CFSet.h

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