Collections.subproj/CFSet.h

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