Collections.subproj/CFSet.h

   1 /*
   2  * Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*      CFSet.h
  24         Copyright (c) 1998-2005, Apple, Inc. All rights reserved.
  25 */
  26 /*!
  27         @header CFSet
  28         CFSet implements a container which stores unique values.
  29 */
  30
  31 #if !defined(__COREFOUNDATION_CFSET__)
  32 #define __COREFOUNDATION_CFSET__ 1
  33
  34 #include <CoreFoundation/CFBase.h>
  35
  36 #if defined(__cplusplus)
  37 extern "C" {
  38 #endif
  39
  40 /*!
  41         @typedef CFSetRetainCallBack
  42         Type of the callback function used by CFSets for retaining values.
  43         @param allocator The allocator of the CFSet.
  44         @param value The value to retain.
  45         @result The value to store in the set, which is usually the value
  46                 parameter passed to this callback, but may be a different
  47                 value if a different value should be stored in the set.
  48 */
  49 typedef const void *    (*CFSetRetainCallBack)(CFAllocatorRef allocator, const void *value);
  50
  51 /*!
  52         @typedef CFSetReleaseCallBack
  53         Type of the callback function used by CFSets for releasing a retain on values.
  54         @param allocator The allocator of the CFSet.
  55         @param value The value to release.
  56 */
  57 typedef void            (*CFSetReleaseCallBack)(CFAllocatorRef allocator, const void *value);
  58
  59 /*!
  60         @typedef CFSetCopyDescriptionCallBack
  61         Type of the callback function used by CFSets for describing values.
  62         @param value The value to describe.
  63         @result A description of the specified value.
  64 */
  65 typedef CFStringRef     (*CFSetCopyDescriptionCallBack)(const void *value);
  66
  67 /*!
  68         @typedef CFSetEqualCallBack
  69         Type of the callback function used by CFSets for comparing values.
  70         @param value1 The first value to compare.
  71         @param value2 The second value to compare.
  72         @result True if the values are equal, otherwise false.
  73 */
  74 typedef Boolean         (*CFSetEqualCallBack)(const void *value1, const void *value2);
  75
  76 /*!
  77         @typedef CFSetHashCallBack
  78         Type of the callback function used by CFSets for hashing values.
  79         @param value The value to hash.
  80         @result The hash of the value.
  81 */
  82 typedef CFHashCode      (*CFSetHashCallBack)(const void *value);
  83
  84 /*!
  85         @typedef CFSetCallBacks
  86         Structure containing the callbacks of a CFSet.
  87         @field version The version number of the structure type being passed
  88                 in as a parameter to the CFSet creation functions. This
  89                 structure is version 0.
  90         @field retain The callback used to add a retain for the set on
  91                 values as they are put into the set. This callback returns
  92                 the value to store in the set, which is usually the value
  93                 parameter passed to this callback, but may be a different
  94                 value if a different value should be stored in the set.
  95                 The set's allocator is passed as the first argument.
  96         @field release The callback used to remove a retain previously added
  97                 for the set from values as they are removed from the
  98                 set. The set's allocator is passed as the first
  99                 argument.
 100         @field copyDescription The callback used to create a descriptive
 101                 string representation of each value in the set. This is
 102                 used by the CFCopyDescription() function.
 103         @field equal The callback used to compare values in the set for
 104                 equality for some operations.
 105         @field hash The callback used to compare values in the set for
 106                 uniqueness for some operations.
 107 */
 108 typedef struct {
 109     CFIndex                             version;
 110     CFSetRetainCallBack                 retain;
 111     CFSetReleaseCallBack                release;
 112     CFSetCopyDescriptionCallBack        copyDescription;
 113     CFSetEqualCallBack                  equal;
 114     CFSetHashCallBack                   hash;
 115 } CFSetCallBacks;
 116
 117 /*!
 118         @constant kCFTypeSetCallBacks
 119         Predefined CFSetCallBacks structure containing a set of callbacks
 120         appropriate for use when the values in a CFSet are all CFTypes.
 121 */
 122 CF_EXPORT
 123 const CFSetCallBacks kCFTypeSetCallBacks;
 124
 125 /*!
 126         @constant kCFCopyStringSetCallBacks
 127         Predefined CFSetCallBacks structure containing a set of callbacks
 128         appropriate for use when the values in a CFSet should be copies
 129         of a CFString.
 130 */
 131 CF_EXPORT
 132 const CFSetCallBacks kCFCopyStringSetCallBacks;
 133
 134 /*!
 135         @typedef CFSetApplierFunction
 136         Type of the callback function used by the apply functions of
 137                 CFSets.
 138         @param value The current value from the set.
 139         @param context The user-defined context parameter given to the apply
 140                 function.
 141 */
 142 typedef void (*CFSetApplierFunction)(const void *value, void *context);
 143
 144 /*!
 145         @typedef CFSetRef
 146         This is the type of a reference to immutable CFSets.
 147 */
 148 typedef const struct __CFSet * CFSetRef;
 149
 150 /*!
 151         @typedef CFMutableSetRef
 152         This is the type of a reference to mutable CFSets.
 153 */
 154 typedef struct __CFSet * CFMutableSetRef;
 155
 156 /*!
 157         @function CFSetGetTypeID
 158         Returns the type identifier of all CFSet instances.
 159 */
 160 CF_EXPORT
 161 CFTypeID CFSetGetTypeID(void);
 162
 163 /*!
 164         @function CFSetCreate
 165         Creates a new immutable set with the given values.
 166         @param allocator The CFAllocator which should be used to allocate
 167                 memory for the set and its storage for values. This
 168                 parameter may be NULL in which case the current default
 169                 CFAllocator is used. If this reference is not a valid
 170                 CFAllocator, the behavior is undefined.
 171         @param values A C array of the pointer-sized values to be in the
 172                 set.  This C array is not changed or freed by this function.
 173                 If this parameter is not a valid pointer to a C array of at
 174                 least numValues pointers, the behavior is undefined.
 175         @param numValues The number of values to copy from the values C
 176                 array into the CFSet. This number will be the count of the
 177                 set.  If this parameter is zero, negative, or greater than
 178                 the number of values actually in the values C array, the
 179                 behavior is undefined.
 180         @param callBacks A C pointer to a CFSetCallBacks structure
 181                 initialized with the callbacks for the set to use on each
 182                 value in the set. A copy of the contents of the
 183                 callbacks structure is made, so that a pointer to a
 184                 structure on the stack can be passed in, or can be reused
 185                 for multiple set creations. If the version field of this
 186                 callbacks structure is not one of the defined ones for
 187                 CFSet, the behavior is undefined. The retain field may be
 188                 NULL, in which case the CFSet will do nothing to add a
 189                 retain to the contained values for the set. The release
 190                 field may be NULL, in which case the CFSet will do nothing
 191                 to remove the set's retain (if any) on the values when the
 192                 set is destroyed. If the copyDescription field is NULL,
 193                 the set will create a simple description for the value. If
 194                 the equal field is NULL, the set will use pointer equality
 195                 to test for equality of values. The hash field may be NULL,
 196                 in which case the CFSet will determine uniqueness by pointer
 197                 equality. This callbacks parameter
 198                 itself may be NULL, which is treated as if a valid structure
 199                 of version 0 with all fields NULL had been passed in.
 200                 Otherwise, if any of the fields are not valid pointers to
 201                 functions of the correct type, or this parameter is not a
 202                 valid pointer to a  CFSetCallBacks callbacks structure,
 203                 the behavior is undefined. If any of the values put into the
 204                 set is not one understood by one of the callback functions
 205                 the behavior when that callback function is used is
 206                 undefined.
 207         @result A reference to the new immutable CFSet.
 208 */
 209 CF_EXPORT
 210 CFSetRef CFSetCreate(CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFSetCallBacks *callBacks);
 211
 212 /*!
 213         @function CFSetCreateCopy
 214         Creates a new immutable set with the values from the given set.
 215         @param allocator The CFAllocator which should be used to allocate
 216                 memory for the set and its storage for values. This
 217                 parameter may be NULL in which case the current default
 218                 CFAllocator is used. If this reference is not a valid
 219                 CFAllocator, the behavior is undefined.
 220         @param theSet The set which is to be copied. The values from the
 221                 set are copied as pointers into the new set (that is,
 222                 the values themselves are copied, not that which the values
 223                 point to, if anything). However, the values are also
 224                 retained by the new set. The count of the new set will
 225                 be the same as the copied set. The new set uses the same
 226                 callbacks as the set to be copied. If this parameter is
 227                 not a valid CFSet, the behavior is undefined.
 228         @result A reference to the new immutable CFSet.
 229 */
 230 CF_EXPORT
 231 CFSetRef CFSetCreateCopy(CFAllocatorRef allocator, CFSetRef theSet);
 232
 233 /*!
 234         @function CFSetCreateMutable
 235         Creates a new empty mutable set.
 236         @param allocator The CFAllocator which should be used to allocate
 237                 memory for the set and its storage for values. This
 238                 parameter may be NULL in which case the current default
 239                 CFAllocator is used. If this reference is not a valid
 240                 CFAllocator, the behavior is undefined.
 241         @param capacity The maximum number of values that can be contained
 242                 by the CFSet. The set starts empty, and can grow to this
 243                 number of values (and it can have less). If this parameter
 244                 is 0, the set's maximum capacity is unlimited (or rather,
 245                 only limited by address space and available memory
 246                 constraints). If this parameter is negative, the behavior is
 247                 undefined.
 248         @param callBacks A C pointer to a CFSetCallBacks structure
 249                 initialized with the callbacks for the set to use on each
 250                 value in the set. A copy of the contents of the
 251                 callbacks structure is made, so that a pointer to a
 252                 structure on the stack can be passed in, or can be reused
 253                 for multiple set creations. If the version field of this
 254                 callbacks structure is not one of the defined ones for
 255                 CFSet, the behavior is undefined. The retain field may be
 256                 NULL, in which case the CFSet will do nothing to add a
 257                 retain to the contained values for the set. The release
 258                 field may be NULL, in which case the CFSet will do nothing
 259                 to remove the set's retain (if any) on the values when the
 260                 set is destroyed. If the copyDescription field is NULL,
 261                 the set will create a simple description for the value. If
 262                 the equal field is NULL, the set will use pointer equality
 263                 to test for equality of values. The hash field may be NULL,
 264                 in which case the CFSet will determine uniqueness by pointer
 265                 equality. This callbacks parameter
 266                 itself may be NULL, which is treated as if a valid structure
 267                 of version 0 with all fields NULL had been passed in.
 268                 Otherwise, if any of the fields are not valid pointers to
 269                 functions of the correct type, or this parameter is not a
 270                 valid pointer to a  CFSetCallBacks callbacks structure,
 271                 the behavior is undefined. If any of the values put into the
 272                 set is not one understood by one of the callback functions
 273                 the behavior when that callback function is used is
 274                 undefined.
 275         @result A reference to the new mutable CFSet.
 276 */
 277 CF_EXPORT
 278 CFMutableSetRef CFSetCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFSetCallBacks *callBacks);
 279
 280 /*!
 281         @function CFSetCreateMutableCopy
 282         Creates a new immutable set with the values from the given set.
 283         @param allocator The CFAllocator which should be used to allocate
 284                 memory for the set and its storage for values. This
 285                 parameter may be NULL in which case the current default
 286                 CFAllocator is used. If this reference is not a valid
 287                 CFAllocator, the behavior is undefined.
 288         @param capacity The maximum number of values that can be contained
 289                 by the CFSet. The set starts with the same values as the
 290                 set to be copied, and can grow to this number of values.
 291                 If this parameter is 0, the set's maximum capacity is
 292                 unlimited (or rather, only limited by address space and
 293                 available memory constraints). This parameter must be
 294                 greater than or equal to the count of the set which is to
 295                 be copied, or the behavior is undefined.
 296         @param theSet The set which is to be copied. The values from the
 297                 set are copied as pointers into the new set (that is,
 298                 the values themselves are copied, not that which the values
 299                 point to, if anything). However, the values are also
 300                 retained by the new set. The count of the new set will
 301                 be the same as the copied set. The new set uses the same
 302                 callbacks as the set to be copied. If this parameter is
 303                 not a valid CFSet, the behavior is undefined.
 304         @result A reference to the new mutable CFSet.
 305 */
 306 CF_EXPORT
 307 CFMutableSetRef CFSetCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFSetRef theSet);
 308
 309 /*!
 310         @function CFSetGetCount
 311         Returns the number of values currently in the set.
 312         @param theSet The set to be queried. If this parameter is not a valid
 313                 CFSet, the behavior is undefined.
 314         @result The number of values in the set.
 315 */
 316 CF_EXPORT
 317 CFIndex CFSetGetCount(CFSetRef theSet);
 318
 319 /*!
 320         @function CFSetGetCountOfValue
 321         Counts the number of times the given value occurs in the set. Since
 322         sets by definition contain only one instance of a value, this function
 323         is synomous to SFSetContainsValue.
 324         @param theSet The set to be searched. If this parameter is not a
 325                 valid CFSet, the behavior is undefined.
 326         @param value The value for which to find matches in the set. The
 327                 equal() callback provided when the set was created is
 328                 used to compare. If the equal() callback was NULL, pointer
 329                 equality (in C, ==) is used. If value, or any of the values
 330                 in the set, are not understood by the equal() callback,
 331                 the behavior is undefined.
 332         @result The number of times the given value occurs in the set.
 333 */
 334 CF_EXPORT
 335 CFIndex CFSetGetCountOfValue(CFSetRef theSet, const void *value);
 336
 337 /*!
 338         @function CFSetContainsValue
 339         Reports whether or not the value is in the set.
 340         @param theSet The set to be searched. If this parameter is not a
 341                 valid CFSet, the behavior is undefined.
 342         @param value The value for which to find matches in the set. The
 343                 equal() callback provided when the set was created is
 344                 used to compare. If the equal() callback was NULL, pointer
 345                 equality (in C, ==) is used. If value, or any of the values
 346                 in the set, are not understood by the equal() callback,
 347                 the behavior is undefined.
 348         @result true, if the value is in the set, otherwise false.
 349 */
 350 CF_EXPORT
 351 Boolean CFSetContainsValue(CFSetRef theSet, const void *value);
 352
 353 /*!
 354         @function CFSetGetValue
 355         Retrieves a value in the set which hashes the same as the specified value.
 356         @param theSet The set to be queried. If this parameter is not a
 357                 valid CFSet, the behavior is undefined.
 358         @param value The value to retrieve. The equal() callback provided when
 359                 the set was created is used to compare. If the equal() callback
 360                 was NULL, pointer equality (in C, ==) is used. If a value, or
 361                 any of the values in the set, are not understood by the equal()
 362                 callback, the behavior is undefined.
 363         @result The value in the set with the given hash.
 364 */
 365 CF_EXPORT
 366 const void *CFSetGetValue(CFSetRef theSet, const void *value);
 367
 368 /*!
 369         @function CFSetGetValue
 370         Retrieves a value in the set which hashes the same as the specified value,
 371         if present.
 372         @param theSet The set to be queried. If this parameter is not a
 373                 valid CFSet, the behavior is undefined.
 374         @param candidate This value is hashed and compared with values in the
 375                 set to determine which value to retrieve. The equal() callback provided when
 376                 the set was created is used to compare. If the equal() callback
 377                 was NULL, pointer equality (in C, ==) is used. If a value, or
 378                 any of the values in the set, are not understood by the equal()
 379                 callback, the behavior is undefined.
 380         @param value A pointer to memory which should be filled with the
 381                 pointer-sized value if a matching value is found. If no
 382                 match is found, the contents of the storage pointed to by
 383                 this parameter are undefined. This parameter may be NULL,
 384                 in which case the value from the dictionary is not returned
 385                 (but the return value of this function still indicates
 386                 whether or not the value was present).
 387         @result True if the value was present in the set, otherwise false.
 388 */
 389 CF_EXPORT
 390 Boolean CFSetGetValueIfPresent(CFSetRef theSet, const void *candidate, const void **value);
 391
 392 /*!
 393         @function CFSetGetValues
 394         Fills the buffer with values from the set.
 395         @param theSet The set to be queried. If this parameter is not a
 396                 valid CFSet, the behavior is undefined.
 397         @param values A C array of pointer-sized values to be filled with
 398                 values from the set. The values in the C array are ordered
 399                 in the same order in which they appear in the set. If this
 400                 parameter is not a valid pointer to a C array of at least
 401                 CFSetGetCount() pointers, the behavior is undefined.
 402 */
 403 CF_EXPORT
 404 void CFSetGetValues(CFSetRef theSet, const void **values);
 405
 406 /*!
 407         @function CFSetApplyFunction
 408         Calls a function once for each value in the set.
 409         @param theSet The set to be operated upon. If this parameter is not
 410                 a valid CFSet, the behavior is undefined.
 411         @param applier The callback function to call once for each value in
 412                 the given set. If this parameter is not a
 413                 pointer to a function of the correct prototype, the behavior
 414                 is undefined. If there are values in the set which the
 415                 applier function does not expect or cannot properly apply
 416                 to, the behavior is undefined.
 417         @param context A pointer-sized user-defined value, which is passed
 418                 as the second parameter to the applier function, but is
 419                 otherwise unused by this function. If the context is not
 420                 what is expected by the applier function, the behavior is
 421                 undefined.
 422 */
 423 CF_EXPORT
 424 void CFSetApplyFunction(CFSetRef theSet, CFSetApplierFunction applier, void *context);
 425
 426 /*!
 427         @function CFSetAddValue
 428         Adds the value to the set if it is not already present.
 429         @param theSet The set to which the value is to be added. If this
 430                 parameter is not a valid mutable CFSet, the behavior is
 431                 undefined. If the set is a fixed-capacity set and it
 432                 is full before this operation, the behavior is undefined.
 433         @param value The value to add to the set. The value is retained by
 434                 the set using the retain callback provided when the set
 435                 was created. If the value is not of the sort expected by the
 436                 retain callback, the behavior is undefined. The count of the
 437                 set is increased by one.
 438 */
 439 CF_EXPORT
 440 void CFSetAddValue(CFMutableSetRef theSet, const void *value);
 441
 442 /*!
 443         @function CFSetReplaceValue
 444         Replaces the value in the set if it is present.
 445         @param theSet The set to which the value is to be replaced. If this
 446                 parameter is not a valid mutable CFSet, the behavior is
 447                 undefined.
 448         @param value The value to replace in the set. The equal() callback provided when
 449                 the set was created is used to compare. If the equal() callback
 450                 was NULL, pointer equality (in C, ==) is used. If a value, or
 451                 any of the values in the set, are not understood by the equal()
 452                 callback, the behavior is undefined. The value is retained by
 453                 the set using the retain callback provided when the set
 454                 was created. If the value is not of the sort expected by the
 455                 retain callback, the behavior is undefined. The count of the
 456                 set is increased by one.
 457 */
 458 CF_EXPORT
 459 void CFSetReplaceValue(CFMutableSetRef theSet, const void *value);
 460
 461 /*!
 462         @function CFSetSetValue
 463         Replaces the value in the set if it is present, or adds the value to
 464         the set if it is absent.
 465         @param theSet The set to which the value is to be replaced. If this
 466                 parameter is not a valid mutable CFSet, the behavior is
 467                 undefined.
 468         @param value The value to set in the CFSet. The equal() callback provided when
 469                 the set was created is used to compare. If the equal() callback
 470                 was NULL, pointer equality (in C, ==) is used. If a value, or
 471                 any of the values in the set, are not understood by the equal()
 472                 callback, the behavior is undefined. The value is retained by
 473                 the set using the retain callback provided when the set
 474                 was created. If the value is not of the sort expected by the
 475                 retain callback, the behavior is undefined. The count of the
 476                 set is increased by one.
 477 */
 478 CF_EXPORT
 479 void CFSetSetValue(CFMutableSetRef theSet, const void *value);
 480
 481 /*!
 482         @function CFSetRemoveValue
 483         Removes the specified value from the set.
 484         @param theSet The set from which the value is to be removed.
 485                 If this parameter is not a valid mutable CFSet,
 486                 the behavior is undefined.
 487         @param value The value to remove. The equal() callback provided when
 488                 the set was created is used to compare. If the equal() callback
 489                 was NULL, pointer equality (in C, ==) is used. If a value, or
 490                 any of the values in the set, are not understood by the equal()
 491                 callback, the behavior is undefined.
 492 */
 493 CF_EXPORT
 494 void CFSetRemoveValue(CFMutableSetRef theSet, const void *value);
 495
 496 /*!
 497         @function CFSetRemoveAllValues
 498         Removes all the values from the set, making it empty.
 499         @param theSet The set from which all of the values are to be
 500                 removed. If this parameter is not a valid mutable CFSet,
 501                 the behavior is undefined.
 502 */
 503 CF_EXPORT
 504 void CFSetRemoveAllValues(CFMutableSetRef theSet);
 505
 506 #if defined(__cplusplus)
 507 }
 508 #endif
 509
 510 #endif /* ! __COREFOUNDATION_CFSET__ */
 511