CFSet.h

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