CFDictionary.h

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