You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
693 lines
33 KiB
693 lines
33 KiB
5 years ago
|
/* CFDictionary.h
|
||
|
|
Copyright (c) 1998-2003, 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 have two subflavors,
|
||
|
|
fixed-capacity, for which there is a maximum number set at creation
|
||
|
|
time of values which can be put into the dictionary, and variable
|
||
|
|
capacity, which can have an unlimited number of values (or rather,
|
||
|
|
limited only by constraints external to CFDictionary, like the
|
||
|
|
amount of available memory). Fixed-capacity dictionaries can be
|
||
|
|
somewhat higher performing, if you can put a definate upper limit
|
||
|
|
on the number of values that might be put into the dictionary.
|
||
|
|
|
||
|
|
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>
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@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.
|
||
|
|
*/
|
||
|
|
#if TARGET_OS_WIN32
|
||
|
|
#define kCFTypeDictionaryKeyCallBacks (*((const CFDictionaryKeyCallBacks *)QTGetCFConstant("kCFTypeDictionaryKeyCallBacks")))
|
||
|
|
#else
|
||
|
|
CF_EXPORT
|
||
|
|
const CFDictionaryKeyCallBacks kCFTypeDictionaryKeyCallBacks;
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@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.
|
||
|
|
*/
|
||
|
|
#if TARGET_OS_WIN32
|
||
|
|
#define kCFCopyStringDictionaryKeyCallBacks (*((const CFDictionaryKeyCallBacks *)QTGetCFConstant("kCFCopyStringDictionaryKeyCallBacks")))
|
||
|
|
#else
|
||
|
|
CF_EXPORT
|
||
|
|
const CFDictionaryKeyCallBacks kCFCopyStringDictionaryKeyCallBacks;
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@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.
|
||
|
|
*/
|
||
|
|
#if TARGET_OS_WIN32
|
||
|
|
#define kCFTypeDictionaryValueCallBacks (*((const CFDictionaryValueCallBacks *)QTGetCFConstant("kCFTypeDictionaryValueCallBacks")))
|
||
|
|
#else
|
||
|
|
CF_EXPORT
|
||
|
|
const CFDictionaryValueCallBacks kCFTypeDictionaryValueCallBacks;
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/*!
|
||
|
|
@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 The maximum number of values that can be contained by
|
||
|
|
the CFDictionary. The dictionary starts empty, and can grow
|
||
|
|
to this number of values (and it can have less). If this
|
||
|
|
parameter is 0, the dictionary's maximum capacity is unlimited
|
||
|
|
(or rather, 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 The maximum number of values that can be contained
|
||
|
|
by the CFDictionary. The dictionary starts empty, and can grow
|
||
|
|
to this number of values (and it can have less). If this
|
||
|
|
parameter is 0, the dictionary's maximum capacity is unlimited
|
||
|
|
(or rather, 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. If the dictionary is a fixed-capacity dictionary and
|
||
|
|
it is full before this operation, 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. If the dictionary is a fixed-capacity dictionary and
|
||
|
|
it is full before this operation, and the key does not exist in
|
||
|
|
the dictionary, 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);
|
||
|
|
|
||
|
|
#if defined(__cplusplus)
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* ! __COREFOUNDATION_CFDICTIONARY__ */
|
||
|
|
|