--- /dev/null
+/*
+ * Copyright (c) 2008 Apple Inc. All rights reserved.
+ *
+ * @APPLE_LICENSE_HEADER_START@
+ *
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this
+ * file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+ * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
+ *
+ * @APPLE_LICENSE_HEADER_END@
+ */
+/* CFDictionary.h
+ Copyright (c) 1998-2007, Apple Inc. All rights reserved.
+*/
+
+/*!
+ @header CFDictionary
+ CFDictionary implements a container which pairs pointer-sized keys
+ with pointer-sized values. Values are accessed via arbitrary
+ user-defined keys. A CFDictionary differs from a CFArray in that
+ the key used to access a particular value in the dictionary remains
+ the same as values are added to or removed from the dictionary,
+ unless a value associated with its particular key is replaced or
+ removed. In a CFArray, the key (or index) used to retrieve a
+ particular value can change over time as values are added to or
+ deleted from the array. Also unlike an array, there is no ordering
+ among values in a dictionary. To enable later retrieval of a value,
+ the key of the key-value pair should be constant (or treated as
+ constant); if the key changes after being used to put a value in
+ the dictionary, the value may not be retrievable. The keys of a
+ dictionary form a set; that is, no two keys which are equal to
+ one another are present in the dictionary at any time.
+
+ Dictionaries come in two flavors, immutable, which cannot have
+ values added to them or removed from them after the dictionary is
+ created, and mutable, to which you can add values or from which
+ remove values. Mutable dictionaries can have an unlimited number
+ of values (or rather, limited only by constraints external to
+ CFDictionary, like the amount of available memory).
+
+ As with all CoreFoundation collection types, dictionaries maintain
+ hard references on the values you put in them, but the retaining and
+ releasing functions are user-defined callbacks that can actually do
+ whatever the user wants (for example, nothing).
+
+ Although a particular implementation of CFDictionary may not use
+ hashing and a hash table for storage of the values, the keys have
+ a hash-code generating function defined for them, and a function
+ to test for equality of two keys. These two functions together
+ must maintain the invariant that if equal(X, Y), then hash(X) ==
+ hash(Y). Note that the converse will not generally be true (but
+ the contrapositive, if hash(X) != hash(Y), then !equal(X, Y),
+ will be as required by Boolean logic). If the hash() and equal()
+ key callbacks are NULL, the key is used as a pointer-sized integer,
+ and pointer equality is used. Care should be taken to provide a
+ hash() callback which will compute sufficiently dispersed hash
+ codes for the key set for best performance.
+
+ Computational Complexity
+ The access time for a value in the dictionary is guaranteed to be at
+ worst O(lg N) for any implementation, current and future, but will
+ often be O(1) (constant time). Insertion or deletion operations
+ will typically be constant time as well, but are O(N*lg N) in the
+ worst case in some implementations. Access of values through a key
+ is faster than accessing values directly (if there are any such
+ operations). Dictionaries will tend to use significantly more memory
+ than a array with the same number of values.
+*/
+
+#if !defined(__COREFOUNDATION_CFDICTIONARY__)
+#define __COREFOUNDATION_CFDICTIONARY__ 1
+
+#include <CoreFoundation/CFBase.h>
+
+CF_EXTERN_C_BEGIN
+
+/*!
+ @typedef CFDictionaryKeyCallBacks
+ Structure containing the callbacks for keys of a CFDictionary.
+ @field version The version number of the structure type being passed
+ in as a parameter to the CFDictionary creation functions.
+ This structure is version 0.
+ @field retain The callback used to add a retain for the dictionary
+ on keys as they are used to put values into the dictionary.
+ This callback returns the value to use as the key in the
+ dictionary, which is usually the value parameter passed to
+ this callback, but may be a different value if a different
+ value should be used as the key. The dictionary's allocator
+ is passed as the first argument.
+ @field release The callback used to remove a retain previously added
+ for the dictionary from keys as their values are removed from
+ the dictionary. The dictionary's allocator is passed as the
+ first argument.
+ @field copyDescription The callback used to create a descriptive
+ string representation of each key in the dictionary. This
+ is used by the CFCopyDescription() function.
+ @field equal The callback used to compare keys in the dictionary for
+ equality.
+ @field hash The callback used to compute a hash code for keys as they
+ are used to access, add, or remove values in the dictionary.
+*/
+typedef const void * (*CFDictionaryRetainCallBack)(CFAllocatorRef allocator, const void *value);
+typedef void (*CFDictionaryReleaseCallBack)(CFAllocatorRef allocator, const void *value);
+typedef CFStringRef (*CFDictionaryCopyDescriptionCallBack)(const void *value);
+typedef Boolean (*CFDictionaryEqualCallBack)(const void *value1, const void *value2);
+typedef CFHashCode (*CFDictionaryHashCallBack)(const void *value);
+typedef struct {
+ CFIndex version;
+ CFDictionaryRetainCallBack retain;
+ CFDictionaryReleaseCallBack release;
+ CFDictionaryCopyDescriptionCallBack copyDescription;
+ CFDictionaryEqualCallBack equal;
+ CFDictionaryHashCallBack hash;
+} CFDictionaryKeyCallBacks;
+
+/*!
+ @constant kCFTypeDictionaryKeyCallBacks
+ Predefined CFDictionaryKeyCallBacks structure containing a
+ set of callbacks appropriate for use when the keys of a
+ CFDictionary are all CFTypes.
+*/
+CF_EXPORT
+const CFDictionaryKeyCallBacks kCFTypeDictionaryKeyCallBacks;
+
+/*!
+ @constant kCFCopyStringDictionaryKeyCallBacks
+ Predefined CFDictionaryKeyCallBacks structure containing a
+ set of callbacks appropriate for use when the keys of a
+ CFDictionary are all CFStrings, which may be mutable and
+ need to be copied in order to serve as constant keys for
+ the values in the dictionary.
+*/
+CF_EXPORT
+const CFDictionaryKeyCallBacks kCFCopyStringDictionaryKeyCallBacks;
+
+/*!
+ @typedef CFDictionaryValueCallBacks
+ Structure containing the callbacks for values of a CFDictionary.
+ @field version The version number of the structure type being passed
+ in as a parameter to the CFDictionary creation functions.
+ This structure is version 0.
+ @field retain The callback used to add a retain for the dictionary
+ on values as they are put into the dictionary.
+ This callback returns the value to use as the value in the
+ dictionary, which is usually the value parameter passed to
+ this callback, but may be a different value if a different
+ value should be added to the dictionary. The dictionary's
+ allocator is passed as the first argument.
+ @field release The callback used to remove a retain previously added
+ for the dictionary from values as they are removed from
+ the dictionary. The dictionary's allocator is passed as the
+ first argument.
+ @field copyDescription The callback used to create a descriptive
+ string representation of each value in the dictionary. This
+ is used by the CFCopyDescription() function.
+ @field equal The callback used to compare values in the dictionary for
+ equality in some operations.
+*/
+typedef struct {
+ CFIndex version;
+ CFDictionaryRetainCallBack retain;
+ CFDictionaryReleaseCallBack release;
+ CFDictionaryCopyDescriptionCallBack copyDescription;
+ CFDictionaryEqualCallBack equal;
+} CFDictionaryValueCallBacks;
+
+/*!
+ @constant kCFTypeDictionaryValueCallBacks
+ Predefined CFDictionaryValueCallBacks structure containing a set
+ of callbacks appropriate for use when the values in a CFDictionary
+ are all CFTypes.
+*/
+CF_EXPORT
+const CFDictionaryValueCallBacks kCFTypeDictionaryValueCallBacks;
+
+/*!
+ @typedef CFDictionaryApplierFunction
+ Type of the callback function used by the apply functions of
+ CFDictionarys.
+ @param key The current key for the value.
+ @param value The current value from the dictionary.
+ @param context The user-defined context parameter given to the apply
+ function.
+*/
+typedef void (*CFDictionaryApplierFunction)(const void *key, const void *value, void *context);
+
+/*!
+ @typedef CFDictionaryRef
+ This is the type of a reference to immutable CFDictionarys.
+*/
+typedef const struct __CFDictionary * CFDictionaryRef;
+
+/*!
+ @typedef CFMutableDictionaryRef
+ This is the type of a reference to mutable CFDictionarys.
+*/
+typedef struct __CFDictionary * CFMutableDictionaryRef;
+
+/*!
+ @function CFDictionaryGetTypeID
+ Returns the type identifier of all CFDictionary instances.
+*/
+CF_EXPORT
+CFTypeID CFDictionaryGetTypeID(void);
+
+/*!
+ @function CFDictionaryCreate
+ Creates a new immutable dictionary with the given values.
+ @param allocator The CFAllocator which should be used to allocate
+ memory for the dictionary and its storage for values. This
+ parameter may be NULL in which case the current default
+ CFAllocator is used. If this reference is not a valid
+ CFAllocator, the behavior is undefined.
+ @param keys A C array of the pointer-sized keys to be used for
+ the parallel C array of values to be put into the dictionary.
+ This parameter may be NULL if the numValues parameter is 0.
+ This C array is not changed or freed by this function. If
+ this parameter is not a valid pointer to a C array of at
+ least numValues pointers, the behavior is undefined.
+ @param values A C array of the pointer-sized values to be in the
+ dictionary. This parameter may be NULL if the numValues
+ parameter is 0. This C array is not changed or freed by
+ this function. If this parameter is not a valid pointer to
+ a C array of at least numValues pointers, the behavior is
+ undefined.
+ @param numValues The number of values to copy from the keys and
+ values C arrays into the CFDictionary. This number will be
+ the count of the dictionary. If this parameter is
+ negative, or greater than the number of values actually
+ in the keys or values C arrays, the behavior is undefined.
+ @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
+ initialized with the callbacks for the dictionary to use on
+ each key in the dictionary. The retain callback will be used
+ within this function, for example, to retain all of the new
+ keys from the keys C array. A copy of the contents of the
+ callbacks structure is made, so that a pointer to a structure
+ on the stack can be passed in, or can be reused for multiple
+ dictionary creations. If the version field of this
+ callbacks structure is not one of the defined ones for
+ CFDictionary, the behavior is undefined. The retain field may
+ be NULL, in which case the CFDictionary will do nothing to add
+ a retain to the keys of the contained values. The release field
+ may be NULL, in which case the CFDictionary will do nothing
+ to remove the dictionary's retain (if any) on the keys when the
+ dictionary is destroyed or a key-value pair is removed. If the
+ copyDescription field is NULL, the dictionary will create a
+ simple description for a key. If the equal field is NULL, the
+ dictionary will use pointer equality to test for equality of
+ keys. If the hash field is NULL, a key will be converted from
+ a pointer to an integer to compute the hash code. This callbacks
+ parameter itself may be NULL, which is treated as if a valid
+ structure of version 0 with all fields NULL had been passed in.
+ Otherwise, if any of the fields are not valid pointers to
+ functions of the correct type, or this parameter is not a
+ valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
+ the behavior is undefined. If any of the keys put into the
+ dictionary is not one understood by one of the callback functions
+ the behavior when that callback function is used is undefined.
+ @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
+ initialized with the callbacks for the dictionary to use on
+ each value in the dictionary. The retain callback will be used
+ within this function, for example, to retain all of the new
+ values from the values C array. A copy of the contents of the
+ callbacks structure is made, so that a pointer to a structure
+ on the stack can be passed in, or can be reused for multiple
+ dictionary creations. If the version field of this callbacks
+ structure is not one of the defined ones for CFDictionary, the
+ behavior is undefined. The retain field may be NULL, in which
+ case the CFDictionary will do nothing to add a retain to values
+ as they are put into the dictionary. The release field may be
+ NULL, in which case the CFDictionary will do nothing to remove
+ the dictionary's retain (if any) on the values when the
+ dictionary is destroyed or a key-value pair is removed. If the
+ copyDescription field is NULL, the dictionary will create a
+ simple description for a value. If the equal field is NULL, the
+ dictionary will use pointer equality to test for equality of
+ values. This callbacks parameter itself may be NULL, which is
+ treated as if a valid structure of version 0 with all fields
+ NULL had been passed in. Otherwise,
+ if any of the fields are not valid pointers to functions
+ of the correct type, or this parameter is not a valid
+ pointer to a CFDictionaryValueCallBacks callbacks structure,
+ the behavior is undefined. If any of the values put into the
+ dictionary is not one understood by one of the callback functions
+ the behavior when that callback function is used is undefined.
+ @result A reference to the new immutable CFDictionary.
+*/
+CF_EXPORT
+CFDictionaryRef CFDictionaryCreate(CFAllocatorRef allocator, const void **keys, const void **values, CFIndex numValues, const CFDictionaryKeyCallBacks *keyCallBacks, const CFDictionaryValueCallBacks *valueCallBacks);
+
+/*!
+ @function CFDictionaryCreateCopy
+ Creates a new immutable dictionary with the key-value pairs from
+ the given dictionary.
+ @param allocator The CFAllocator which should be used to allocate
+ memory for the dictionary and its storage for values. This
+ parameter may be NULL in which case the current default
+ CFAllocator is used. If this reference is not a valid
+ CFAllocator, the behavior is undefined.
+ @param theDict The dictionary which is to be copied. The keys and values
+ from the dictionary are copied as pointers into the new
+ dictionary (that is, the values themselves are copied, not
+ that which the values point to, if anything). However, the
+ keys and values are also retained by the new dictionary using
+ the retain function of the original dictionary.
+ The count of the new dictionary will be the same as the
+ given dictionary. The new dictionary uses the same callbacks
+ as the dictionary to be copied. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @result A reference to the new immutable CFDictionary.
+*/
+CF_EXPORT
+CFDictionaryRef CFDictionaryCreateCopy(CFAllocatorRef allocator, CFDictionaryRef theDict);
+
+/*!
+ @function CFDictionaryCreateMutable
+ Creates a new mutable dictionary.
+ @param allocator The CFAllocator which should be used to allocate
+ memory for the dictionary and its storage for values. This
+ parameter may be NULL in which case the current default
+ CFAllocator is used. If this reference is not a valid
+ CFAllocator, the behavior is undefined.
+ @param capacity A hint about the number of values that will be held
+ by the CFDictionary. Pass 0 for no hint. The implementation may
+ ignore this hint, or may use it to optimize various
+ operations. A dictionary's actual capacity is only limited by
+ address space and available memory constraints). If this
+ parameter is negative, the behavior is undefined.
+ @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
+ initialized with the callbacks for the dictionary to use on
+ each key in the dictionary. A copy of the contents of the
+ callbacks structure is made, so that a pointer to a structure
+ on the stack can be passed in, or can be reused for multiple
+ dictionary creations. If the version field of this
+ callbacks structure is not one of the defined ones for
+ CFDictionary, the behavior is undefined. The retain field may
+ be NULL, in which case the CFDictionary will do nothing to add
+ a retain to the keys of the contained values. The release field
+ may be NULL, in which case the CFDictionary will do nothing
+ to remove the dictionary's retain (if any) on the keys when the
+ dictionary is destroyed or a key-value pair is removed. If the
+ copyDescription field is NULL, the dictionary will create a
+ simple description for a key. If the equal field is NULL, the
+ dictionary will use pointer equality to test for equality of
+ keys. If the hash field is NULL, a key will be converted from
+ a pointer to an integer to compute the hash code. This callbacks
+ parameter itself may be NULL, which is treated as if a valid
+ structure of version 0 with all fields NULL had been passed in.
+ Otherwise, if any of the fields are not valid pointers to
+ functions of the correct type, or this parameter is not a
+ valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
+ the behavior is undefined. If any of the keys put into the
+ dictionary is not one understood by one of the callback functions
+ the behavior when that callback function is used is undefined.
+ @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
+ initialized with the callbacks for the dictionary to use on
+ each value in the dictionary. The retain callback will be used
+ within this function, for example, to retain all of the new
+ values from the values C array. A copy of the contents of the
+ callbacks structure is made, so that a pointer to a structure
+ on the stack can be passed in, or can be reused for multiple
+ dictionary creations. If the version field of this callbacks
+ structure is not one of the defined ones for CFDictionary, the
+ behavior is undefined. The retain field may be NULL, in which
+ case the CFDictionary will do nothing to add a retain to values
+ as they are put into the dictionary. The release field may be
+ NULL, in which case the CFDictionary will do nothing to remove
+ the dictionary's retain (if any) on the values when the
+ dictionary is destroyed or a key-value pair is removed. If the
+ copyDescription field is NULL, the dictionary will create a
+ simple description for a value. If the equal field is NULL, the
+ dictionary will use pointer equality to test for equality of
+ values. This callbacks parameter itself may be NULL, which is
+ treated as if a valid structure of version 0 with all fields
+ NULL had been passed in. Otherwise,
+ if any of the fields are not valid pointers to functions
+ of the correct type, or this parameter is not a valid
+ pointer to a CFDictionaryValueCallBacks callbacks structure,
+ the behavior is undefined. If any of the values put into the
+ dictionary is not one understood by one of the callback functions
+ the behavior when that callback function is used is undefined.
+ @result A reference to the new mutable CFDictionary.
+*/
+CF_EXPORT
+CFMutableDictionaryRef CFDictionaryCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFDictionaryKeyCallBacks *keyCallBacks, const CFDictionaryValueCallBacks *valueCallBacks);
+
+/*!
+ @function CFDictionaryCreateMutableCopy
+ Creates a new mutable dictionary with the key-value pairs from
+ the given dictionary.
+ @param allocator The CFAllocator which should be used to allocate
+ memory for the dictionary and its storage for values. This
+ parameter may be NULL in which case the current default
+ CFAllocator is used. If this reference is not a valid
+ CFAllocator, the behavior is undefined.
+ @param capacity A hint about the number of values that will be held
+ by the CFDictionary. Pass 0 for no hint. The implementation may
+ ignore this hint, or may use it to optimize various
+ operations. A dictionary's actual capacity is only limited by
+ address space and available memory constraints).
+ This parameter must be greater than or equal
+ to the count of the dictionary which is to be copied, or the
+ behavior is undefined. If this parameter is negative, the
+ behavior is undefined.
+ @param theDict The dictionary which is to be copied. The keys and values
+ from the dictionary are copied as pointers into the new
+ dictionary (that is, the values themselves are copied, not
+ that which the values point to, if anything). However, the
+ keys and values are also retained by the new dictionary using
+ the retain function of the original dictionary.
+ The count of the new dictionary will be the same as the
+ given dictionary. The new dictionary uses the same callbacks
+ as the dictionary to be copied. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @result A reference to the new mutable CFDictionary.
+*/
+CF_EXPORT
+CFMutableDictionaryRef CFDictionaryCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFDictionaryRef theDict);
+
+/*!
+ @function CFDictionaryGetCount
+ Returns the number of values currently in the dictionary.
+ @param theDict The dictionary to be queried. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @result The number of values in the dictionary.
+*/
+CF_EXPORT
+CFIndex CFDictionaryGetCount(CFDictionaryRef theDict);
+
+/*!
+ @function CFDictionaryGetCountOfKey
+ Counts the number of times the given key occurs in the dictionary.
+ @param theDict The dictionary to be searched. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param key The key for which to find matches in the dictionary. The
+ hash() and equal() key callbacks provided when the dictionary
+ was created are used to compare. If the hash() key callback
+ was NULL, the key is treated as a pointer and converted to
+ an integer. If the equal() key callback was NULL, pointer
+ equality (in C, ==) is used. If key, or any of the keys in
+ the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @result Returns 1 if a matching key is used by the dictionary,
+ 0 otherwise.
+*/
+CF_EXPORT
+CFIndex CFDictionaryGetCountOfKey(CFDictionaryRef theDict, const void *key);
+
+/*!
+ @function CFDictionaryGetCountOfValue
+ Counts the number of times the given value occurs in the dictionary.
+ @param theDict The dictionary to be searched. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param value The value for which to find matches in the dictionary. The
+ equal() callback provided when the dictionary was created is
+ used to compare. If the equal() value callback was NULL, pointer
+ equality (in C, ==) is used. If value, or any of the values in
+ the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @result The number of times the given value occurs in the dictionary.
+*/
+CF_EXPORT
+CFIndex CFDictionaryGetCountOfValue(CFDictionaryRef theDict, const void *value);
+
+/*!
+ @function CFDictionaryContainsKey
+ Reports whether or not the key is in the dictionary.
+ @param theDict The dictionary to be searched. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param key The key for which to find matches in the dictionary. The
+ hash() and equal() key callbacks provided when the dictionary
+ was created are used to compare. If the hash() key callback
+ was NULL, the key is treated as a pointer and converted to
+ an integer. If the equal() key callback was NULL, pointer
+ equality (in C, ==) is used. If key, or any of the keys in
+ the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @result true, if the key is in the dictionary, otherwise false.
+*/
+CF_EXPORT
+Boolean CFDictionaryContainsKey(CFDictionaryRef theDict, const void *key);
+
+/*!
+ @function CFDictionaryContainsValue
+ Reports whether or not the value is in the dictionary.
+ @param theDict The dictionary to be searched. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param value The value for which to find matches in the dictionary. The
+ equal() callback provided when the dictionary was created is
+ used to compare. If the equal() callback was NULL, pointer
+ equality (in C, ==) is used. If value, or any of the values
+ in the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @result true, if the value is in the dictionary, otherwise false.
+*/
+CF_EXPORT
+Boolean CFDictionaryContainsValue(CFDictionaryRef theDict, const void *value);
+
+/*!
+ @function CFDictionaryGetValue
+ Retrieves the value associated with the given key.
+ @param theDict The dictionary to be queried. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param key The key for which to find a match in the dictionary. The
+ hash() and equal() key callbacks provided when the dictionary
+ was created are used to compare. If the hash() key callback
+ was NULL, the key is treated as a pointer and converted to
+ an integer. If the equal() key callback was NULL, pointer
+ equality (in C, ==) is used. If key, or any of the keys in
+ the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @result The value with the given key in the dictionary, or NULL if
+ no key-value pair with a matching key exists. Since NULL
+ can be a valid value in some dictionaries, the function
+ CFDictionaryGetValueIfPresent() must be used to distinguish
+ NULL-no-found from NULL-is-the-value.
+*/
+CF_EXPORT
+const void *CFDictionaryGetValue(CFDictionaryRef theDict, const void *key);
+
+/*!
+ @function CFDictionaryGetValueIfPresent
+ Retrieves the value associated with the given key.
+ @param theDict The dictionary to be queried. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param key The key for which to find a match in the dictionary. The
+ hash() and equal() key callbacks provided when the dictionary
+ was created are used to compare. If the hash() key callback
+ was NULL, the key is treated as a pointer and converted to
+ an integer. If the equal() key callback was NULL, pointer
+ equality (in C, ==) is used. If key, or any of the keys in
+ the dictionary, are not understood by the equal() callback,
+ the behavior is undefined.
+ @param value A pointer to memory which should be filled with the
+ pointer-sized value if a matching key is found. If no key
+ match is found, the contents of the storage pointed to by
+ this parameter are undefined. This parameter may be NULL,
+ in which case the value from the dictionary is not returned
+ (but the return value of this function still indicates
+ whether or not the key-value pair was present).
+ @result true, if a matching key was found, false otherwise.
+*/
+CF_EXPORT
+Boolean CFDictionaryGetValueIfPresent(CFDictionaryRef theDict, const void *key, const void **value);
+
+/*!
+ @function CFDictionaryGetKeysAndValues
+ Fills the two buffers with the keys and values from the dictionary.
+ @param theDict The dictionary to be queried. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param keys A C array of pointer-sized values to be filled with keys
+ from the dictionary. The keys and values C arrays are parallel
+ to each other (that is, the items at the same indices form a
+ key-value pair from the dictionary). This parameter may be NULL
+ if the keys are not desired. If this parameter is not a valid
+ pointer to a C array of at least CFDictionaryGetCount() pointers,
+ or NULL, the behavior is undefined.
+ @param values A C array of pointer-sized values to be filled with values
+ from the dictionary. The keys and values C arrays are parallel
+ to each other (that is, the items at the same indices form a
+ key-value pair from the dictionary). This parameter may be NULL
+ if the values are not desired. If this parameter is not a valid
+ pointer to a C array of at least CFDictionaryGetCount() pointers,
+ or NULL, the behavior is undefined.
+*/
+CF_EXPORT
+void CFDictionaryGetKeysAndValues(CFDictionaryRef theDict, const void **keys, const void **values);
+
+/*!
+ @function CFDictionaryApplyFunction
+ Calls a function once for each value in the dictionary.
+ @param theDict The dictionary to be queried. If this parameter is
+ not a valid CFDictionary, the behavior is undefined.
+ @param applier The callback function to call once for each value in
+ the dictionary. If this parameter is not a
+ pointer to a function of the correct prototype, the behavior
+ is undefined. If there are keys or values which the
+ applier function does not expect or cannot properly apply
+ to, the behavior is undefined.
+ @param context A pointer-sized user-defined value, which is passed
+ as the third parameter to the applier function, but is
+ otherwise unused by this function. If the context is not
+ what is expected by the applier function, the behavior is
+ undefined.
+*/
+CF_EXPORT
+void CFDictionaryApplyFunction(CFDictionaryRef theDict, CFDictionaryApplierFunction applier, void *context);
+
+/*!
+ @function CFDictionaryAddValue
+ Adds the key-value pair to the dictionary if no such key already exists.
+ @param theDict The dictionary to which the value is to be added. If this
+ parameter is not a valid mutable CFDictionary, the behavior is
+ undefined.
+ @param key The key of the value to add to the dictionary. The key is
+ retained by the dictionary using the retain callback provided
+ when the dictionary was created. If the key is not of the sort
+ expected by the retain callback, the behavior is undefined. If
+ a key which matches this key is already present in the dictionary,
+ this function does nothing ("add if absent").
+ @param value The value to add to the dictionary. The value is retained
+ by the dictionary using the retain callback provided when the
+ dictionary was created. If the value is not of the sort expected
+ by the retain callback, the behavior is undefined.
+*/
+CF_EXPORT
+void CFDictionaryAddValue(CFMutableDictionaryRef theDict, const void *key, const void *value);
+
+/*!
+ @function CFDictionarySetValue
+ Sets the value of the key in the dictionary.
+ @param theDict The dictionary to which the value is to be set. If this
+ parameter is not a valid mutable CFDictionary, the behavior is
+ undefined.
+ @param key The key of the value to set into the dictionary. If a key
+ which matches this key is already present in the dictionary, only
+ the value is changed ("add if absent, replace if present"). If
+ no key matches the given key, the key-value pair is added to the
+ dictionary. If added, the key is retained by the dictionary,
+ using the retain callback provided
+ when the dictionary was created. If the key is not of the sort
+ expected by the key retain callback, the behavior is undefined.
+ @param value The value to add to or replace into the dictionary. The value
+ is retained by the dictionary using the retain callback provided
+ when the dictionary was created, and the previous value if any is
+ released. If the value is not of the sort expected by the
+ retain or release callbacks, the behavior is undefined.
+*/
+CF_EXPORT
+void CFDictionarySetValue(CFMutableDictionaryRef theDict, const void *key, const void *value);
+
+/*!
+ @function CFDictionaryReplaceValue
+ Replaces the value of the key in the dictionary.
+ @param theDict The dictionary to which the value is to be replaced. If this
+ parameter is not a valid mutable CFDictionary, the behavior is
+ undefined.
+ @param key The key of the value to replace in the dictionary. If a key
+ which matches this key is present in the dictionary, the value
+ is changed to the given value, otherwise this function does
+ nothing ("replace if present").
+ @param value The value to replace into the dictionary. The value
+ is retained by the dictionary using the retain callback provided
+ when the dictionary was created, and the previous value is
+ released. If the value is not of the sort expected by the
+ retain or release callbacks, the behavior is undefined.
+*/
+CF_EXPORT
+void CFDictionaryReplaceValue(CFMutableDictionaryRef theDict, const void *key, const void *value);
+
+/*!
+ @function CFDictionaryRemoveValue
+ Removes the value of the key from the dictionary.
+ @param theDict The dictionary from which the value is to be removed. If this
+ parameter is not a valid mutable CFDictionary, the behavior is
+ undefined.
+ @param key The key of the value to remove from the dictionary. If a key
+ which matches this key is present in the dictionary, the key-value
+ pair is removed from the dictionary, otherwise this function does
+ nothing ("remove if present").
+*/
+CF_EXPORT
+void CFDictionaryRemoveValue(CFMutableDictionaryRef theDict, const void *key);
+
+/*!
+ @function CFDictionaryRemoveAllValues
+ Removes all the values from the dictionary, making it empty.
+ @param theDict The dictionary from which all of the values are to be
+ removed. If this parameter is not a valid mutable
+ CFDictionary, the behavior is undefined.
+*/
+CF_EXPORT
+void CFDictionaryRemoveAllValues(CFMutableDictionaryRef theDict);
+
+CF_EXTERN_C_END
+
+#endif /* ! __COREFOUNDATION_CFDICTIONARY__ */
+
projects / apple / cf.git / blobdiff