CFDictionary.h

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