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/* CFDictionary.h 25 Copyright (c) 1998-2013, Apple Inc. All rights reserved. 26*/ 27 28/*! 29 @header CFDictionary 30 CFDictionary implements a container which pairs pointer-sized keys 31 with pointer-sized values. Values are accessed via arbitrary 32 user-defined keys. A CFDictionary differs from a CFArray in that 33 the key used to access a particular value in the dictionary remains 34 the same as values are added to or removed from the dictionary, 35 unless a value associated with its particular key is replaced or 36 removed. In a CFArray, the key (or index) used to retrieve a 37 particular value can change over time as values are added to or 38 deleted from the array. Also unlike an array, there is no ordering 39 among values in a dictionary. To enable later retrieval of a value, 40 the key of the key-value pair should be constant (or treated as 41 constant); if the key changes after being used to put a value in 42 the dictionary, the value may not be retrievable. The keys of a 43 dictionary form a set; that is, no two keys which are equal to 44 one another are present in the dictionary at any time. 45 46 Dictionaries come in two flavors, immutable, which cannot have 47 values added to them or removed from them after the dictionary is 48 created, and mutable, to which you can add values or from which 49 remove values. Mutable dictionaries can have an unlimited number 50 of values (or rather, limited only by constraints external to 51 CFDictionary, like the amount of available memory). 52 53 As with all CoreFoundation collection types, dictionaries maintain 54 hard references on the values you put in them, but the retaining and 55 releasing functions are user-defined callbacks that can actually do 56 whatever the user wants (for example, nothing). 57 58 Although a particular implementation of CFDictionary may not use 59 hashing and a hash table for storage of the values, the keys have 60 a hash-code generating function defined for them, and a function 61 to test for equality of two keys. These two functions together 62 must maintain the invariant that if equal(X, Y), then hash(X) == 63 hash(Y). Note that the converse will not generally be true (but 64 the contrapositive, if hash(X) != hash(Y), then !equal(X, Y), 65 will be as required by Boolean logic). If the hash() and equal() 66 key callbacks are NULL, the key is used as a pointer-sized integer, 67 and pointer equality is used. Care should be taken to provide a 68 hash() callback which will compute sufficiently dispersed hash 69 codes for the key set for best performance. 70 71 Computational Complexity 72 The access time for a value in the dictionary is guaranteed to be at 73 worst O(N) for any implementation, current and future, but will 74 often be O(1) (constant time). Insertion or deletion operations 75 will typically be constant time as well, but are O(N*N) in the 76 worst case in some implementations. Access of values through a key 77 is faster than accessing values directly (if there are any such 78 operations). Dictionaries will tend to use significantly more memory 79 than a array with the same number of values. 80*/ 81 82#if !defined(__COREFOUNDATION_CFDICTIONARY__) 83#define __COREFOUNDATION_CFDICTIONARY__ 1 84 85#include <CoreFoundation/CFBase.h> 86 87CF_IMPLICIT_BRIDGING_ENABLED 88CF_EXTERN_C_BEGIN 89 90/*! 91 @typedef CFDictionaryKeyCallBacks 92 Structure containing the callbacks for keys of a CFDictionary. 93 @field version The version number of the structure type being passed 94 in as a parameter to the CFDictionary creation functions. 95 This structure is version 0. 96 @field retain The callback used to add a retain for the dictionary 97 on keys as they are used to put values into the dictionary. 98 This callback returns the value to use as the key in the 99 dictionary, which is usually the value parameter passed to 100 this callback, but may be a different value if a different 101 value should be used as the key. The dictionary's allocator 102 is passed as the first argument. 103 @field release The callback used to remove a retain previously added 104 for the dictionary from keys as their values are removed from 105 the dictionary. The dictionary's allocator is passed as the 106 first argument. 107 @field copyDescription The callback used to create a descriptive 108 string representation of each key in the dictionary. This 109 is used by the CFCopyDescription() function. 110 @field equal The callback used to compare keys in the dictionary for 111 equality. 112 @field hash The callback used to compute a hash code for keys as they 113 are used to access, add, or remove values in the dictionary. 114*/ 115typedef const void * (*CFDictionaryRetainCallBack)(CFAllocatorRef allocator, const void *value); 116typedef void (*CFDictionaryReleaseCallBack)(CFAllocatorRef allocator, const void *value); 117typedef CFStringRef (*CFDictionaryCopyDescriptionCallBack)(const void *value); 118typedef Boolean (*CFDictionaryEqualCallBack)(const void *value1, const void *value2); 119typedef CFHashCode (*CFDictionaryHashCallBack)(const void *value); 120typedef struct { 121 CFIndex version; 122 CFDictionaryRetainCallBack retain; 123 CFDictionaryReleaseCallBack release; 124 CFDictionaryCopyDescriptionCallBack copyDescription; 125 CFDictionaryEqualCallBack equal; 126 CFDictionaryHashCallBack hash; 127} CFDictionaryKeyCallBacks; 128 129/*! 130 @constant kCFTypeDictionaryKeyCallBacks 131 Predefined CFDictionaryKeyCallBacks structure containing a 132 set of callbacks appropriate for use when the keys of a 133 CFDictionary are all CFTypes. 134*/ 135CF_EXPORT 136const CFDictionaryKeyCallBacks kCFTypeDictionaryKeyCallBacks; 137 138/*! 139 @constant kCFCopyStringDictionaryKeyCallBacks 140 Predefined CFDictionaryKeyCallBacks structure containing a 141 set of callbacks appropriate for use when the keys of a 142 CFDictionary are all CFStrings, which may be mutable and 143 need to be copied in order to serve as constant keys for 144 the values in the dictionary. 145*/ 146CF_EXPORT 147const CFDictionaryKeyCallBacks kCFCopyStringDictionaryKeyCallBacks; 148 149/*! 150 @typedef CFDictionaryValueCallBacks 151 Structure containing the callbacks for values of a CFDictionary. 152 @field version The version number of the structure type being passed 153 in as a parameter to the CFDictionary creation functions. 154 This structure is version 0. 155 @field retain The callback used to add a retain for the dictionary 156 on values as they are put into the dictionary. 157 This callback returns the value to use as the value in the 158 dictionary, which is usually the value parameter passed to 159 this callback, but may be a different value if a different 160 value should be added to the dictionary. The dictionary's 161 allocator is passed as the first argument. 162 @field release The callback used to remove a retain previously added 163 for the dictionary from values as they are removed from 164 the dictionary. The dictionary's allocator is passed as the 165 first argument. 166 @field copyDescription The callback used to create a descriptive 167 string representation of each value in the dictionary. This 168 is used by the CFCopyDescription() function. 169 @field equal The callback used to compare values in the dictionary for 170 equality in some operations. 171*/ 172typedef struct { 173 CFIndex version; 174 CFDictionaryRetainCallBack retain; 175 CFDictionaryReleaseCallBack release; 176 CFDictionaryCopyDescriptionCallBack copyDescription; 177 CFDictionaryEqualCallBack equal; 178} CFDictionaryValueCallBacks; 179 180/*! 181 @constant kCFTypeDictionaryValueCallBacks 182 Predefined CFDictionaryValueCallBacks structure containing a set 183 of callbacks appropriate for use when the values in a CFDictionary 184 are all CFTypes. 185*/ 186CF_EXPORT 187const CFDictionaryValueCallBacks kCFTypeDictionaryValueCallBacks; 188 189/*! 190 @typedef CFDictionaryApplierFunction 191 Type of the callback function used by the apply functions of 192 CFDictionarys. 193 @param key The current key for the value. 194 @param value The current value from the dictionary. 195 @param context The user-defined context parameter given to the apply 196 function. 197*/ 198typedef void (*CFDictionaryApplierFunction)(const void *key, const void *value, void *context); 199 200/*! 201 @typedef CFDictionaryRef 202 This is the type of a reference to immutable CFDictionarys. 203*/ 204typedef const struct __CFDictionary * CFDictionaryRef; 205 206/*! 207 @typedef CFMutableDictionaryRef 208 This is the type of a reference to mutable CFDictionarys. 209*/ 210typedef struct __CFDictionary * CFMutableDictionaryRef; 211 212/*! 213 @function CFDictionaryGetTypeID 214 Returns the type identifier of all CFDictionary instances. 215*/ 216CF_EXPORT 217CFTypeID CFDictionaryGetTypeID(void); 218 219/*! 220 @function CFDictionaryCreate 221 Creates a new immutable dictionary with the given values. 222 @param allocator The CFAllocator which should be used to allocate 223 memory for the dictionary and its storage for values. This 224 parameter may be NULL in which case the current default 225 CFAllocator is used. If this reference is not a valid 226 CFAllocator, the behavior is undefined. 227 @param keys A C array of the pointer-sized keys to be used for 228 the parallel C array of values to be put into the dictionary. 229 This parameter may be NULL if the numValues parameter is 0. 230 This C array is not changed or freed by this function. If 231 this parameter is not a valid pointer to a C array of at 232 least numValues pointers, the behavior is undefined. 233 @param values A C array of the pointer-sized values to be in the 234 dictionary. This parameter may be NULL if the numValues 235 parameter is 0. This C array is not changed or freed by 236 this function. If this parameter is not a valid pointer to 237 a C array of at least numValues pointers, the behavior is 238 undefined. 239 @param numValues The number of values to copy from the keys and 240 values C arrays into the CFDictionary. This number will be 241 the count of the dictionary. If this parameter is 242 negative, or greater than the number of values actually 243 in the keys or values C arrays, the behavior is undefined. 244 @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure 245 initialized with the callbacks for the dictionary to use on 246 each key in the dictionary. The retain callback will be used 247 within this function, for example, to retain all of the new 248 keys from the keys C array. A copy of the contents of the 249 callbacks structure is made, so that a pointer to a structure 250 on the stack can be passed in, or can be reused for multiple 251 dictionary creations. If the version field of this 252 callbacks structure is not one of the defined ones for 253 CFDictionary, the behavior is undefined. The retain field may 254 be NULL, in which case the CFDictionary will do nothing to add 255 a retain to the keys of the contained values. The release field 256 may be NULL, in which case the CFDictionary will do nothing 257 to remove the dictionary's retain (if any) on the keys when the 258 dictionary is destroyed or a key-value pair is removed. If the 259 copyDescription field is NULL, the dictionary will create a 260 simple description for a key. If the equal field is NULL, the 261 dictionary will use pointer equality to test for equality of 262 keys. If the hash field is NULL, a key will be converted from 263 a pointer to an integer to compute the hash code. This callbacks 264 parameter itself may be NULL, which is treated as if a valid 265 structure 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 CFDictionaryKeyCallBacks callbacks structure, 269 the behavior is undefined. If any of the keys put into the 270 dictionary is not one understood by one of the callback functions 271 the behavior when that callback function is used is undefined. 272 @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure 273 initialized with the callbacks for the dictionary to use on 274 each value in the dictionary. The retain callback will be used 275 within this function, for example, to retain all of the new 276 values from the values C array. A copy of the contents of the 277 callbacks structure is made, so that a pointer to a structure 278 on the stack can be passed in, or can be reused for multiple 279 dictionary creations. If the version field of this callbacks 280 structure is not one of the defined ones for CFDictionary, the 281 behavior is undefined. The retain field may be NULL, in which 282 case the CFDictionary will do nothing to add a retain to values 283 as they are put into the dictionary. The release field may be 284 NULL, in which case the CFDictionary will do nothing to remove 285 the dictionary's retain (if any) on the values when the 286 dictionary is destroyed or a key-value pair is removed. If the 287 copyDescription field is NULL, the dictionary will create a 288 simple description for a value. If the equal field is NULL, the 289 dictionary will use pointer equality to test for equality of 290 values. This callbacks parameter itself may be NULL, which is 291 treated as if a valid structure of version 0 with all fields 292 NULL had been passed in. Otherwise, 293 if any of the fields are not valid pointers to functions 294 of the correct type, or this parameter is not a valid 295 pointer to a CFDictionaryValueCallBacks callbacks structure, 296 the behavior is undefined. If any of the values put into the 297 dictionary is not one understood by one of the callback functions 298 the behavior when that callback function is used is undefined. 299 @result A reference to the new immutable CFDictionary. 300*/ 301CF_EXPORT 302CFDictionaryRef CFDictionaryCreate(CFAllocatorRef allocator, const void **keys, const void **values, CFIndex numValues, const CFDictionaryKeyCallBacks *keyCallBacks, const CFDictionaryValueCallBacks *valueCallBacks); 303 304/*! 305 @function CFDictionaryCreateCopy 306 Creates a new immutable dictionary with the key-value pairs from 307 the given dictionary. 308 @param allocator The CFAllocator which should be used to allocate 309 memory for the dictionary and its storage for values. This 310 parameter may be NULL in which case the current default 311 CFAllocator is used. If this reference is not a valid 312 CFAllocator, the behavior is undefined. 313 @param theDict The dictionary which is to be copied. The keys and values 314 from the dictionary are copied as pointers into the new 315 dictionary (that is, the values themselves are copied, not 316 that which the values point to, if anything). However, the 317 keys and values are also retained by the new dictionary using 318 the retain function of the original dictionary. 319 The count of the new dictionary will be the same as the 320 given dictionary. The new dictionary uses the same callbacks 321 as the dictionary to be copied. If this parameter is 322 not a valid CFDictionary, the behavior is undefined. 323 @result A reference to the new immutable CFDictionary. 324*/ 325CF_EXPORT 326CFDictionaryRef CFDictionaryCreateCopy(CFAllocatorRef allocator, CFDictionaryRef theDict); 327 328/*! 329 @function CFDictionaryCreateMutable 330 Creates a new mutable dictionary. 331 @param allocator The CFAllocator which should be used to allocate 332 memory for the dictionary and its storage for values. This 333 parameter may be NULL in which case the current default 334 CFAllocator is used. If this reference is not a valid 335 CFAllocator, the behavior is undefined. 336 @param capacity A hint about the number of values that will be held 337 by the CFDictionary. Pass 0 for no hint. The implementation may 338 ignore this hint, or may use it to optimize various 339 operations. A dictionary's actual capacity is only limited by 340 address space and available memory constraints). If this 341 parameter is negative, the behavior is undefined. 342 @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure 343 initialized with the callbacks for the dictionary to use on 344 each key in the dictionary. A copy of the contents of the 345 callbacks structure is made, so that a pointer to a structure 346 on the stack can be passed in, or can be reused for multiple 347 dictionary creations. If the version field of this 348 callbacks structure is not one of the defined ones for 349 CFDictionary, the behavior is undefined. The retain field may 350 be NULL, in which case the CFDictionary will do nothing to add 351 a retain to the keys of the contained values. The release field 352 may be NULL, in which case the CFDictionary will do nothing 353 to remove the dictionary's retain (if any) on the keys when the 354 dictionary is destroyed or a key-value pair is removed. If the 355 copyDescription field is NULL, the dictionary will create a 356 simple description for a key. If the equal field is NULL, the 357 dictionary will use pointer equality to test for equality of 358 keys. If the hash field is NULL, a key will be converted from 359 a pointer to an integer to compute the hash code. This callbacks 360 parameter itself may be NULL, which is treated as if a valid 361 structure of version 0 with all fields NULL had been passed in. 362 Otherwise, if any of the fields are not valid pointers to 363 functions of the correct type, or this parameter is not a 364 valid pointer to a CFDictionaryKeyCallBacks callbacks structure, 365 the behavior is undefined. If any of the keys put into the 366 dictionary is not one understood by one of the callback functions 367 the behavior when that callback function is used is undefined. 368 @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure 369 initialized with the callbacks for the dictionary to use on 370 each value in the dictionary. The retain callback will be used 371 within this function, for example, to retain all of the new 372 values from the values C array. A copy of the contents of the 373 callbacks structure is made, so that a pointer to a structure 374 on the stack can be passed in, or can be reused for multiple 375 dictionary creations. If the version field of this callbacks 376 structure is not one of the defined ones for CFDictionary, the 377 behavior is undefined. The retain field may be NULL, in which 378 case the CFDictionary will do nothing to add a retain to values 379 as they are put into the dictionary. The release field may be 380 NULL, in which case the CFDictionary will do nothing to remove 381 the dictionary's retain (if any) on the values when the 382 dictionary is destroyed or a key-value pair is removed. If the 383 copyDescription field is NULL, the dictionary will create a 384 simple description for a value. If the equal field is NULL, the 385 dictionary will use pointer equality to test for equality of 386 values. This callbacks parameter itself may be NULL, which is 387 treated as if a valid structure of version 0 with all fields 388 NULL had been passed in. Otherwise, 389 if any of the fields are not valid pointers to functions 390 of the correct type, or this parameter is not a valid 391 pointer to a CFDictionaryValueCallBacks callbacks structure, 392 the behavior is undefined. If any of the values put into the 393 dictionary is not one understood by one of the callback functions 394 the behavior when that callback function is used is undefined. 395 @result A reference to the new mutable CFDictionary. 396*/ 397CF_EXPORT 398CFMutableDictionaryRef CFDictionaryCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFDictionaryKeyCallBacks *keyCallBacks, const CFDictionaryValueCallBacks *valueCallBacks); 399 400/*! 401 @function CFDictionaryCreateMutableCopy 402 Creates a new mutable dictionary with the key-value pairs from 403 the given dictionary. 404 @param allocator The CFAllocator which should be used to allocate 405 memory for the dictionary and its storage for values. This 406 parameter may be NULL in which case the current default 407 CFAllocator is used. If this reference is not a valid 408 CFAllocator, the behavior is undefined. 409 @param capacity A hint about the number of values that will be held 410 by the CFDictionary. Pass 0 for no hint. The implementation may 411 ignore this hint, or may use it to optimize various 412 operations. A dictionary's actual capacity is only limited by 413 address space and available memory constraints). 414 This parameter must be greater than or equal 415 to the count of the dictionary which is to be copied, or the 416 behavior is undefined. If this parameter is negative, the 417 behavior is undefined. 418 @param theDict The dictionary which is to be copied. The keys and values 419 from the dictionary are copied as pointers into the new 420 dictionary (that is, the values themselves are copied, not 421 that which the values point to, if anything). However, the 422 keys and values are also retained by the new dictionary using 423 the retain function of the original dictionary. 424 The count of the new dictionary will be the same as the 425 given dictionary. The new dictionary uses the same callbacks 426 as the dictionary to be copied. If this parameter is 427 not a valid CFDictionary, the behavior is undefined. 428 @result A reference to the new mutable CFDictionary. 429*/ 430CF_EXPORT 431CFMutableDictionaryRef CFDictionaryCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFDictionaryRef theDict); 432 433/*! 434 @function CFDictionaryGetCount 435 Returns the number of values currently in the dictionary. 436 @param theDict The dictionary to be queried. If this parameter is 437 not a valid CFDictionary, the behavior is undefined. 438 @result The number of values in the dictionary. 439*/ 440CF_EXPORT 441CFIndex CFDictionaryGetCount(CFDictionaryRef theDict); 442 443/*! 444 @function CFDictionaryGetCountOfKey 445 Counts the number of times the given key occurs in the dictionary. 446 @param theDict The dictionary to be searched. If this parameter is 447 not a valid CFDictionary, the behavior is undefined. 448 @param key The key for which to find matches in the dictionary. The 449 hash() and equal() key callbacks provided when the dictionary 450 was created are used to compare. If the hash() key callback 451 was NULL, the key is treated as a pointer and converted to 452 an integer. If the equal() key callback was NULL, pointer 453 equality (in C, ==) is used. If key, or any of the keys in 454 the dictionary, are not understood by the equal() callback, 455 the behavior is undefined. 456 @result Returns 1 if a matching key is used by the dictionary, 457 0 otherwise. 458*/ 459CF_EXPORT 460CFIndex CFDictionaryGetCountOfKey(CFDictionaryRef theDict, const void *key); 461 462/*! 463 @function CFDictionaryGetCountOfValue 464 Counts the number of times the given value occurs in the dictionary. 465 @param theDict The dictionary to be searched. If this parameter is 466 not a valid CFDictionary, the behavior is undefined. 467 @param value The value for which to find matches in the dictionary. The 468 equal() callback provided when the dictionary was created is 469 used to compare. If the equal() value callback was NULL, pointer 470 equality (in C, ==) is used. If value, or any of the values in 471 the dictionary, are not understood by the equal() callback, 472 the behavior is undefined. 473 @result The number of times the given value occurs in the dictionary. 474*/ 475CF_EXPORT 476CFIndex CFDictionaryGetCountOfValue(CFDictionaryRef theDict, const void *value); 477 478/*! 479 @function CFDictionaryContainsKey 480 Reports whether or not the key is in the dictionary. 481 @param theDict The dictionary to be searched. If this parameter is 482 not a valid CFDictionary, the behavior is undefined. 483 @param key The key for which to find matches in the dictionary. The 484 hash() and equal() key callbacks provided when the dictionary 485 was created are used to compare. If the hash() key callback 486 was NULL, the key is treated as a pointer and converted to 487 an integer. If the equal() key callback was NULL, pointer 488 equality (in C, ==) is used. If key, or any of the keys in 489 the dictionary, are not understood by the equal() callback, 490 the behavior is undefined. 491 @result true, if the key is in the dictionary, otherwise false. 492*/ 493CF_EXPORT 494Boolean CFDictionaryContainsKey(CFDictionaryRef theDict, const void *key); 495 496/*! 497 @function CFDictionaryContainsValue 498 Reports whether or not the value is in the dictionary. 499 @param theDict The dictionary to be searched. If this parameter is 500 not a valid CFDictionary, the behavior is undefined. 501 @param value The value for which to find matches in the dictionary. The 502 equal() callback provided when the dictionary was created is 503 used to compare. If the equal() callback was NULL, pointer 504 equality (in C, ==) is used. If value, or any of the values 505 in the dictionary, are not understood by the equal() callback, 506 the behavior is undefined. 507 @result true, if the value is in the dictionary, otherwise false. 508*/ 509CF_EXPORT 510Boolean CFDictionaryContainsValue(CFDictionaryRef theDict, const void *value); 511 512/*! 513 @function CFDictionaryGetValue 514 Retrieves the value associated with the given key. 515 @param theDict The dictionary to be queried. If this parameter is 516 not a valid CFDictionary, the behavior is undefined. 517 @param key The key for which to find a match in the dictionary. The 518 hash() and equal() key callbacks provided when the dictionary 519 was created are used to compare. If the hash() key callback 520 was NULL, the key is treated as a pointer and converted to 521 an integer. If the equal() key callback was NULL, pointer 522 equality (in C, ==) is used. If key, or any of the keys in 523 the dictionary, are not understood by the equal() callback, 524 the behavior is undefined. 525 @result The value with the given key in the dictionary, or NULL if 526 no key-value pair with a matching key exists. Since NULL 527 can be a valid value in some dictionaries, the function 528 CFDictionaryGetValueIfPresent() must be used to distinguish 529 NULL-no-found from NULL-is-the-value. 530*/ 531CF_EXPORT 532const void *CFDictionaryGetValue(CFDictionaryRef theDict, const void *key); 533 534/*! 535 @function CFDictionaryGetValueIfPresent 536 Retrieves the value associated with the given key. 537 @param theDict The dictionary to be queried. If this parameter is 538 not a valid CFDictionary, the behavior is undefined. 539 @param key The key for which to find a match in the dictionary. The 540 hash() and equal() key callbacks provided when the dictionary 541 was created are used to compare. If the hash() key callback 542 was NULL, the key is treated as a pointer and converted to 543 an integer. If the equal() key callback was NULL, pointer 544 equality (in C, ==) is used. If key, or any of the keys in 545 the dictionary, are not understood by the equal() callback, 546 the behavior is undefined. 547 @param value A pointer to memory which should be filled with the 548 pointer-sized value if a matching key is found. If no key 549 match is found, the contents of the storage pointed to by 550 this parameter are undefined. This parameter may be NULL, 551 in which case the value from the dictionary is not returned 552 (but the return value of this function still indicates 553 whether or not the key-value pair was present). 554 @result true, if a matching key was found, false otherwise. 555*/ 556CF_EXPORT 557Boolean CFDictionaryGetValueIfPresent(CFDictionaryRef theDict, const void *key, const void **value); 558 559/*! 560 @function CFDictionaryGetKeysAndValues 561 Fills the two buffers with the keys and values from the dictionary. 562 @param theDict The dictionary to be queried. If this parameter is 563 not a valid CFDictionary, the behavior is undefined. 564 @param keys A C array of pointer-sized values to be filled with keys 565 from the dictionary. The keys and values C arrays are parallel 566 to each other (that is, the items at the same indices form a 567 key-value pair from the dictionary). This parameter may be NULL 568 if the keys are not desired. If this parameter is not a valid 569 pointer to a C array of at least CFDictionaryGetCount() pointers, 570 or NULL, the behavior is undefined. 571 @param values A C array of pointer-sized values to be filled with values 572 from the dictionary. The keys and values C arrays are parallel 573 to each other (that is, the items at the same indices form a 574 key-value pair from the dictionary). This parameter may be NULL 575 if the values are not desired. If this parameter is not a valid 576 pointer to a C array of at least CFDictionaryGetCount() pointers, 577 or NULL, the behavior is undefined. 578*/ 579CF_EXPORT 580void CFDictionaryGetKeysAndValues(CFDictionaryRef theDict, const void **keys, const void **values); 581 582/*! 583 @function CFDictionaryApplyFunction 584 Calls a function once for each value in the dictionary. 585 @param theDict The dictionary to be queried. If this parameter is 586 not a valid CFDictionary, the behavior is undefined. 587 @param applier The callback function to call once for each value in 588 the dictionary. If this parameter is not a 589 pointer to a function of the correct prototype, the behavior 590 is undefined. If there are keys or values which the 591 applier function does not expect or cannot properly apply 592 to, the behavior is undefined. 593 @param context A pointer-sized user-defined value, which is passed 594 as the third parameter to the applier function, but is 595 otherwise unused by this function. If the context is not 596 what is expected by the applier function, the behavior is 597 undefined. 598*/ 599CF_EXPORT 600void CFDictionaryApplyFunction(CFDictionaryRef theDict, CFDictionaryApplierFunction applier, void *context); 601 602/*! 603 @function CFDictionaryAddValue 604 Adds the key-value pair to the dictionary if no such key already exists. 605 @param theDict The dictionary to which the value is to be added. If this 606 parameter is not a valid mutable CFDictionary, the behavior is 607 undefined. 608 @param key The key of the value to add to the dictionary. The key is 609 retained by the dictionary using the retain callback provided 610 when the dictionary was created. If the key is not of the sort 611 expected by the retain callback, the behavior is undefined. If 612 a key which matches this key is already present in the dictionary, 613 this function does nothing ("add if absent"). 614 @param value The value to add to the dictionary. The value is retained 615 by the dictionary using the retain callback provided when the 616 dictionary was created. If the value is not of the sort expected 617 by the retain callback, the behavior is undefined. 618*/ 619CF_EXPORT 620void CFDictionaryAddValue(CFMutableDictionaryRef theDict, const void *key, const void *value); 621 622/*! 623 @function CFDictionarySetValue 624 Sets the value of the key in the dictionary. 625 @param theDict The dictionary to which the value is to be set. If this 626 parameter is not a valid mutable CFDictionary, the behavior is 627 undefined. 628 @param key The key of the value to set into the dictionary. If a key 629 which matches this key is already present in the dictionary, only 630 the value is changed ("add if absent, replace if present"). If 631 no key matches the given key, the key-value pair is added to the 632 dictionary. If added, the key is retained by the dictionary, 633 using the retain callback provided 634 when the dictionary was created. If the key is not of the sort 635 expected by the key retain callback, the behavior is undefined. 636 @param value The value to add to or replace into the dictionary. The value 637 is retained by the dictionary using the retain callback provided 638 when the dictionary was created, and the previous value if any is 639 released. If the value is not of the sort expected by the 640 retain or release callbacks, the behavior is undefined. 641*/ 642CF_EXPORT 643void CFDictionarySetValue(CFMutableDictionaryRef theDict, const void *key, const void *value); 644 645/*! 646 @function CFDictionaryReplaceValue 647 Replaces the value of the key in the dictionary. 648 @param theDict The dictionary to which the value is to be replaced. If this 649 parameter is not a valid mutable CFDictionary, the behavior is 650 undefined. 651 @param key The key of the value to replace in the dictionary. If a key 652 which matches this key is present in the dictionary, the value 653 is changed to the given value, otherwise this function does 654 nothing ("replace if present"). 655 @param value The value to replace into the dictionary. The value 656 is retained by the dictionary using the retain callback provided 657 when the dictionary was created, and the previous value is 658 released. If the value is not of the sort expected by the 659 retain or release callbacks, the behavior is undefined. 660*/ 661CF_EXPORT 662void CFDictionaryReplaceValue(CFMutableDictionaryRef theDict, const void *key, const void *value); 663 664/*! 665 @function CFDictionaryRemoveValue 666 Removes the value of the key from the dictionary. 667 @param theDict The dictionary from which the value is to be removed. If this 668 parameter is not a valid mutable CFDictionary, the behavior is 669 undefined. 670 @param key The key of the value to remove from the dictionary. If a key 671 which matches this key is present in the dictionary, the key-value 672 pair is removed from the dictionary, otherwise this function does 673 nothing ("remove if present"). 674*/ 675CF_EXPORT 676void CFDictionaryRemoveValue(CFMutableDictionaryRef theDict, const void *key); 677 678/*! 679 @function CFDictionaryRemoveAllValues 680 Removes all the values from the dictionary, making it empty. 681 @param theDict The dictionary from which all of the values are to be 682 removed. If this parameter is not a valid mutable 683 CFDictionary, the behavior is undefined. 684*/ 685CF_EXPORT 686void CFDictionaryRemoveAllValues(CFMutableDictionaryRef theDict); 687 688CF_EXTERN_C_END 689CF_IMPLICIT_BRIDGING_DISABLED 690 691#endif /* ! __COREFOUNDATION_CFDICTIONARY__ */ 692 693