-
Notifications
You must be signed in to change notification settings - Fork 109
/
CFDictionary.h
692 lines (653 loc) · 33.3 KB
/
CFDictionary.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
/*
* Copyright (c) 2015 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-2014, 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(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*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_IMPLICIT_BRIDGING_ENABLED
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 CF_BRIDGED_TYPE(NSDictionary) __CFDictionary * CFDictionaryRef;
/*!
@typedef CFMutableDictionaryRef
This is the type of a reference to mutable CFDictionarys.
*/
typedef struct CF_BRIDGED_MUTABLE_TYPE(NSMutableDictionary) __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
CF_IMPLICIT_BRIDGING_DISABLED
#endif /* ! __COREFOUNDATION_CFDICTIONARY__ */