CFDictionary.h

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