1/* 2 * Copyright (c) 2014 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-2013, 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 37CF_IMPLICIT_BRIDGING_ENABLED 38CF_EXTERN_C_BEGIN 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*/ 49typedef 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*/ 57typedef 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*/ 65typedef 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*/ 74typedef 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*/ 82typedef 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*/ 108typedef 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*/ 122CF_EXPORT 123const 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*/ 131CF_EXPORT 132const 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*/ 142typedef void (*CFSetApplierFunction)(const void *value, void *context); 143 144/*! 145 @typedef CFSetRef 146 This is the type of a reference to immutable CFSets. 147*/ 148typedef const struct __CFSet * CFSetRef; 149 150/*! 151 @typedef CFMutableSetRef 152 This is the type of a reference to mutable CFSets. 153*/ 154typedef struct __CFSet * CFMutableSetRef; 155 156/*! 157 @function CFSetGetTypeID 158 Returns the type identifier of all CFSet instances. 159*/ 160CF_EXPORT 161CFTypeID 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*/ 209CF_EXPORT 210CFSetRef 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*/ 230CF_EXPORT 231CFSetRef 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 A hint about the number of values that will be held 242 by the CFSet. Pass 0 for no hint. The implementation may 243 ignore this hint, or may use it to optimize various 244 operations. A set's actual capacity is only limited by 245 address space and available memory constraints). If this 246 parameter is negative, the behavior is undefined. 247 @param callBacks A C pointer to a CFSetCallBacks structure 248 initialized with the callbacks for the set to use on each 249 value in the set. A copy of the contents of the 250 callbacks structure is made, so that a pointer to a 251 structure on the stack can be passed in, or can be reused 252 for multiple set creations. If the version field of this 253 callbacks structure is not one of the defined ones for 254 CFSet, the behavior is undefined. The retain field may be 255 NULL, in which case the CFSet will do nothing to add a 256 retain to the contained values for the set. The release 257 field may be NULL, in which case the CFSet will do nothing 258 to remove the set's retain (if any) on the values when the 259 set is destroyed. If the copyDescription field is NULL, 260 the set will create a simple description for the value. If 261 the equal field is NULL, the set will use pointer equality 262 to test for equality of values. The hash field may be NULL, 263 in which case the CFSet will determine uniqueness by pointer 264 equality. This callbacks parameter 265 itself may be NULL, which is treated as if a valid structure 266 of version 0 with all fields NULL had been passed in. 267 Otherwise, if any of the fields are not valid pointers to 268 functions of the correct type, or this parameter is not a 269 valid pointer to a CFSetCallBacks callbacks structure, 270 the behavior is undefined. If any of the values put into the 271 set is not one understood by one of the callback functions 272 the behavior when that callback function is used is 273 undefined. 274 @result A reference to the new mutable CFSet. 275*/ 276CF_EXPORT 277CFMutableSetRef CFSetCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFSetCallBacks *callBacks); 278 279/*! 280 @function CFSetCreateMutableCopy 281 Creates a new immutable set with the values from the given set. 282 @param allocator The CFAllocator which should be used to allocate 283 memory for the set and its storage for values. This 284 parameter may be NULL in which case the current default 285 CFAllocator is used. If this reference is not a valid 286 CFAllocator, the behavior is undefined. 287 @param capacity A hint about the number of values that will be held 288 by the CFSet. Pass 0 for no hint. The implementation may 289 ignore this hint, or may use it to optimize various 290 operations. A set's actual capacity is only limited by 291 address space and available memory constraints). 292 This parameter must be greater than or equal 293 to the count of the set which is to be copied, or the 294 behavior is undefined. If this parameter is negative, the 295 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*/ 306CF_EXPORT 307CFMutableSetRef 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*/ 316CF_EXPORT 317CFIndex 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 synonymous to CFSetContainsValue. 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*/ 334CF_EXPORT 335CFIndex 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*/ 350CF_EXPORT 351Boolean 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*/ 365CF_EXPORT 366const void *CFSetGetValue(CFSetRef theSet, const void *value); 367 368/*! 369 @function CFSetGetValueIfPresent 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*/ 389CF_EXPORT 390Boolean 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*/ 403CF_EXPORT 404void 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*/ 423CF_EXPORT 424void 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. 432 @param value The value to add to the set. The value is retained by 433 the set using the retain callback provided when the set 434 was created. If the value is not of the sort expected by the 435 retain callback, the behavior is undefined. The count of the 436 set is increased by one. 437*/ 438CF_EXPORT 439void CFSetAddValue(CFMutableSetRef theSet, const void *value); 440 441/*! 442 @function CFSetReplaceValue 443 Replaces the value in the set if it is present. 444 @param theSet The set to which the value is to be replaced. If this 445 parameter is not a valid mutable CFSet, the behavior is 446 undefined. 447 @param value The value to replace in the set. The equal() callback provided when 448 the set was created is used to compare. If the equal() callback 449 was NULL, pointer equality (in C, ==) is used. If a value, or 450 any of the values in the set, are not understood by the equal() 451 callback, the behavior is undefined. The value is retained by 452 the set using the retain callback provided when the set 453 was created. If the value is not of the sort expected by the 454 retain callback, the behavior is undefined. The count of the 455 set is increased by one. 456*/ 457CF_EXPORT 458void CFSetReplaceValue(CFMutableSetRef theSet, const void *value); 459 460/*! 461 @function CFSetSetValue 462 Replaces the value in the set if it is present, or adds the value to 463 the set if it is absent. 464 @param theSet The set to which the value is to be replaced. If this 465 parameter is not a valid mutable CFSet, the behavior is 466 undefined. 467 @param value The value to set in the CFSet. The equal() callback provided when 468 the set was created is used to compare. If the equal() callback 469 was NULL, pointer equality (in C, ==) is used. If a value, or 470 any of the values in the set, are not understood by the equal() 471 callback, the behavior is undefined. The value is retained by 472 the set using the retain callback provided when the set 473 was created. If the value is not of the sort expected by the 474 retain callback, the behavior is undefined. The count of the 475 set is increased by one. 476*/ 477CF_EXPORT 478void CFSetSetValue(CFMutableSetRef theSet, const void *value); 479 480/*! 481 @function CFSetRemoveValue 482 Removes the specified value from the set. 483 @param theSet The set from which the value is to be removed. 484 If this parameter is not a valid mutable CFSet, 485 the behavior is undefined. 486 @param value The value to remove. The equal() callback provided when 487 the set was created is used to compare. If the equal() callback 488 was NULL, pointer equality (in C, ==) is used. If a value, or 489 any of the values in the set, are not understood by the equal() 490 callback, the behavior is undefined. 491*/ 492CF_EXPORT 493void CFSetRemoveValue(CFMutableSetRef theSet, const void *value); 494 495/*! 496 @function CFSetRemoveAllValues 497 Removes all the values from the set, making it empty. 498 @param theSet The set from which all of the values are to be 499 removed. If this parameter is not a valid mutable CFSet, 500 the behavior is undefined. 501*/ 502CF_EXPORT 503void CFSetRemoveAllValues(CFMutableSetRef theSet); 504 505CF_EXTERN_C_END 506CF_IMPLICIT_BRIDGING_DISABLED 507 508#endif /* ! __COREFOUNDATION_CFSET__ */ 509 510