mirror of
https://github.com/nillerusr/source-engine.git
synced 2026-08-14 12:46:58 +00:00
1
This commit is contained in:
FluorescentCIAAfricanAmerican
@@ -0,0 +1,692 @@
|
||||
/* 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__ */
|
||||
|
||||
Reference in New Issue
Block a user