Collections.subproj/CFDictionary.h

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