1/*
2 * Copyright (c) 2014 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24/*	CFSet.h
25	Copyright (c) 1998-2013, Apple Inc. All rights reserved.
26*/
27/*!
28        @header CFSet
29        CFSet implements a container which stores unique values.
30*/
31
32#if !defined(__COREFOUNDATION_CFSET__)
33#define __COREFOUNDATION_CFSET__ 1
34
35#include <CoreFoundation/CFBase.h>
36
37CF_IMPLICIT_BRIDGING_ENABLED
38CF_EXTERN_C_BEGIN
39
40/*!
41	@typedef CFSetRetainCallBack
42	Type of the callback function used by CFSets for retaining values.
43        @param allocator The allocator of the CFSet.
44	@param value The value to retain.
45        @result The value to store in the set, which is usually the value
46		parameter passed to this callback, but may be a different
47		value if a different value should be stored in the set.
48*/
49typedef const void *	(*CFSetRetainCallBack)(CFAllocatorRef allocator, const void *value);
50
51/*!
52	@typedef CFSetReleaseCallBack
53	Type of the callback function used by CFSets for releasing a retain on values.
54        @param allocator The allocator of the CFSet.
55	@param value The value to release.
56*/
57typedef void		(*CFSetReleaseCallBack)(CFAllocatorRef allocator, const void *value);
58
59/*!
60	@typedef CFSetCopyDescriptionCallBack
61	Type of the callback function used by CFSets for describing values.
62	@param value The value to describe.
63        @result A description of the specified value.
64*/
65typedef CFStringRef	(*CFSetCopyDescriptionCallBack)(const void *value);
66
67/*!
68	@typedef CFSetEqualCallBack
69	Type of the callback function used by CFSets for comparing values.
70	@param value1 The first value to compare.
71	@param value2 The second value to compare.
72        @result True if the values are equal, otherwise false.
73*/
74typedef Boolean		(*CFSetEqualCallBack)(const void *value1, const void *value2);
75
76/*!
77	@typedef CFSetHashCallBack
78	Type of the callback function used by CFSets for hashing values.
79	@param value The value to hash.
80        @result The hash of the value.
81*/
82typedef CFHashCode	(*CFSetHashCallBack)(const void *value);
83
84/*!
85	@typedef CFSetCallBacks
86	Structure containing the callbacks of a CFSet.
87	@field version The version number of the structure type being passed
88		in as a parameter to the CFSet creation functions. This
89		structure is version 0.
90	@field retain The callback used to add a retain for the set on
91		values as they are put into the set. This callback returns
92		the value to store in the set, which is usually the value
93		parameter passed to this callback, but may be a different
94		value if a different value should be stored in the set.
95		The set's allocator is passed as the first argument.
96	@field release The callback used to remove a retain previously added
97		for the set from values as they are removed from the
98		set. The set's allocator is passed as the first
99		argument.
100	@field copyDescription The callback used to create a descriptive
101		string representation of each value in the set. This is
102		used by the CFCopyDescription() function.
103	@field equal The callback used to compare values in the set for
104		equality for some operations.
105	@field hash The callback used to compare values in the set for
106		uniqueness for some operations.
107*/
108typedef struct {
109    CFIndex				version;
110    CFSetRetainCallBack			retain;
111    CFSetReleaseCallBack		release;
112    CFSetCopyDescriptionCallBack	copyDescription;
113    CFSetEqualCallBack			equal;
114    CFSetHashCallBack			hash;
115} CFSetCallBacks;
116
117/*!
118	@constant kCFTypeSetCallBacks
119	Predefined CFSetCallBacks structure containing a set of callbacks
120	appropriate for use when the values in a CFSet are all CFTypes.
121*/
122CF_EXPORT
123const CFSetCallBacks kCFTypeSetCallBacks;
124
125/*!
126	@constant kCFCopyStringSetCallBacks
127	Predefined CFSetCallBacks structure containing a set of callbacks
128	appropriate for use when the values in a CFSet should be copies
129        of a CFString.
130*/
131CF_EXPORT
132const CFSetCallBacks kCFCopyStringSetCallBacks;
133
134/*!
135	@typedef CFSetApplierFunction
136	Type of the callback function used by the apply functions of
137		CFSets.
138	@param value The current value from the set.
139	@param context The user-defined context parameter given to the apply
140		function.
141*/
142typedef void (*CFSetApplierFunction)(const void *value, void *context);
143
144/*!
145        @typedef CFSetRef
146	This is the type of a reference to immutable CFSets.
147*/
148typedef const struct __CFSet * CFSetRef;
149
150/*!
151        @typedef CFMutableSetRef
152	This is the type of a reference to mutable CFSets.
153*/
154typedef struct __CFSet * CFMutableSetRef;
155
156/*!
157        @function CFSetGetTypeID
158        Returns the type identifier of all CFSet instances.
159*/
160CF_EXPORT
161CFTypeID CFSetGetTypeID(void);
162
163/*!
164        @function CFSetCreate
165        Creates a new immutable set with the given values.
166	@param allocator The CFAllocator which should be used to allocate
167		memory for the set and its storage for values. This
168		parameter may be NULL in which case the current default
169		CFAllocator is used. If this reference is not a valid
170		CFAllocator, the behavior is undefined.
171	@param values A C array of the pointer-sized values to be in the
172		set.  This C array is not changed or freed by this function.
173                If this parameter is not a valid pointer to a C array of at
174                least numValues pointers, the behavior is undefined.
175	@param numValues The number of values to copy from the values C
176		array into the CFSet. This number will be the count of the
177		set.  If this parameter is zero, negative, or greater than
178                the number of values actually in the values C array, the
179                behavior is undefined.
180	@param callBacks A C pointer to a CFSetCallBacks structure
181		initialized with the callbacks for the set to use on each
182		value in the set. A copy of the contents of the
183		callbacks structure is made, so that a pointer to a
184		structure on the stack can be passed in, or can be reused
185		for multiple set creations. If the version field of this
186		callbacks structure is not one of the defined ones for
187		CFSet, the behavior is undefined. The retain field may be
188		NULL, in which case the CFSet will do nothing to add a
189		retain to the contained values for the set. The release
190		field may be NULL, in which case the CFSet will do nothing
191		to remove the set's retain (if any) on the values when the
192		set is destroyed. If the copyDescription field is NULL,
193		the set will create a simple description for the value. If
194		the equal field is NULL, the set will use pointer equality
195		to test for equality of values. The hash field may be NULL,
196                in which case the CFSet will determine uniqueness by pointer
197                equality. This callbacks parameter
198		itself may be NULL, which is treated as if a valid structure
199		of version 0 with all fields NULL had been passed in.
200		Otherwise, if any of the fields are not valid pointers to
201		functions of the correct type, or this parameter is not a
202		valid pointer to a  CFSetCallBacks callbacks structure,
203		the behavior is undefined. If any of the values put into the
204		set is not one understood by one of the callback functions
205		the behavior when that callback function is used is
206		undefined.
207	@result A reference to the new immutable CFSet.
208*/
209CF_EXPORT
210CFSetRef CFSetCreate(CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFSetCallBacks *callBacks);
211
212/*!
213	@function CFSetCreateCopy
214	Creates a new immutable set with the values from the given set.
215	@param allocator The CFAllocator which should be used to allocate
216		memory for the set and its storage for values. This
217		parameter may be NULL in which case the current default
218		CFAllocator is used. If this reference is not a valid
219		CFAllocator, the behavior is undefined.
220	@param theSet The set which is to be copied. The values from the
221		set are copied as pointers into the new set (that is,
222		the values themselves are copied, not that which the values
223		point to, if anything). However, the values are also
224		retained by the new set. The count of the new set will
225		be the same as the copied set. The new set uses the same
226		callbacks as the set to be copied. If this parameter is
227		not a valid CFSet, the behavior is undefined.
228	@result A reference to the new immutable CFSet.
229*/
230CF_EXPORT
231CFSetRef CFSetCreateCopy(CFAllocatorRef allocator, CFSetRef theSet);
232
233/*!
234	@function CFSetCreateMutable
235	Creates a new empty mutable set.
236	@param allocator The CFAllocator which should be used to allocate
237		memory for the set and its storage for values. This
238		parameter may be NULL in which case the current default
239		CFAllocator is used. If this reference is not a valid
240		CFAllocator, the behavior is undefined.
241        @param capacity A hint about the number of values that will be held
242                by the CFSet. Pass 0 for no hint. The implementation may
243                ignore this hint, or may use it to optimize various
244                operations. A set's actual capacity is only limited by
245                address space and available memory constraints). If this
246                parameter is negative, the behavior is undefined.
247	@param callBacks A C pointer to a CFSetCallBacks structure
248		initialized with the callbacks for the set to use on each
249		value in the set. A copy of the contents of the
250		callbacks structure is made, so that a pointer to a
251		structure on the stack can be passed in, or can be reused
252		for multiple set creations. If the version field of this
253		callbacks structure is not one of the defined ones for
254		CFSet, the behavior is undefined. The retain field may be
255		NULL, in which case the CFSet will do nothing to add a
256		retain to the contained values for the set. The release
257		field may be NULL, in which case the CFSet will do nothing
258		to remove the set's retain (if any) on the values when the
259		set is destroyed. If the copyDescription field is NULL,
260		the set will create a simple description for the value. If
261		the equal field is NULL, the set will use pointer equality
262		to test for equality of values. The hash field may be NULL,
263                in which case the CFSet will determine uniqueness by pointer
264                equality. This callbacks parameter
265		itself may be NULL, which is treated as if a valid structure
266		of version 0 with all fields NULL had been passed in.
267		Otherwise, if any of the fields are not valid pointers to
268		functions of the correct type, or this parameter is not a
269		valid pointer to a  CFSetCallBacks callbacks structure,
270		the behavior is undefined. If any of the values put into the
271		set is not one understood by one of the callback functions
272		the behavior when that callback function is used is
273		undefined.
274	@result A reference to the new mutable CFSet.
275*/
276CF_EXPORT
277CFMutableSetRef CFSetCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFSetCallBacks *callBacks);
278
279/*!
280	@function CFSetCreateMutableCopy
281	Creates a new immutable set with the values from the given set.
282	@param allocator The CFAllocator which should be used to allocate
283		memory for the set and its storage for values. This
284		parameter may be NULL in which case the current default
285		CFAllocator is used. If this reference is not a valid
286		CFAllocator, the behavior is undefined.
287        @param capacity A hint about the number of values that will be held
288                by the CFSet. Pass 0 for no hint. The implementation may
289                ignore this hint, or may use it to optimize various
290                operations. A set's actual capacity is only limited by
291                address space and available memory constraints).
292                This parameter must be greater than or equal
293                to the count of the set which is to be copied, or the
294                behavior is undefined. If this parameter is negative, the
295                behavior is undefined.
296	@param theSet The set which is to be copied. The values from the
297		set are copied as pointers into the new set (that is,
298		the values themselves are copied, not that which the values
299		point to, if anything). However, the values are also
300		retained by the new set. The count of the new set will
301		be the same as the copied set. The new set uses the same
302		callbacks as the set to be copied. If this parameter is
303		not a valid CFSet, the behavior is undefined.
304	@result A reference to the new mutable CFSet.
305*/
306CF_EXPORT
307CFMutableSetRef CFSetCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFSetRef theSet);
308
309/*!
310	@function CFSetGetCount
311	Returns the number of values currently in the set.
312	@param theSet The set to be queried. If this parameter is not a valid
313		CFSet, the behavior is undefined.
314	@result The number of values in the set.
315*/
316CF_EXPORT
317CFIndex CFSetGetCount(CFSetRef theSet);
318
319/*!
320	@function CFSetGetCountOfValue
321	Counts the number of times the given value occurs in the set. Since
322        sets by definition contain only one instance of a value, this function
323        is synonymous to CFSetContainsValue.
324	@param theSet The set to be searched. If this parameter is not a
325		valid CFSet, the behavior is undefined.
326	@param value The value for which to find matches in the set. The
327		equal() callback provided when the set was created is
328		used to compare. If the equal() callback was NULL, pointer
329		equality (in C, ==) is used. If value, or any of the values
330		in the set, are not understood by the equal() callback,
331		the behavior is undefined.
332	@result The number of times the given value occurs in the set.
333*/
334CF_EXPORT
335CFIndex CFSetGetCountOfValue(CFSetRef theSet, const void *value);
336
337/*!
338	@function CFSetContainsValue
339	Reports whether or not the value is in the set.
340	@param theSet The set to be searched. If this parameter is not a
341		valid CFSet, the behavior is undefined.
342	@param value The value for which to find matches in the set. The
343		equal() callback provided when the set was created is
344		used to compare. If the equal() callback was NULL, pointer
345		equality (in C, ==) is used. If value, or any of the values
346		in the set, are not understood by the equal() callback,
347		the behavior is undefined.
348	@result true, if the value is in the set, otherwise false.
349*/
350CF_EXPORT
351Boolean CFSetContainsValue(CFSetRef theSet, const void *value);
352
353/*!
354	@function CFSetGetValue
355	Retrieves a value in the set which hashes the same as the specified value.
356	@param theSet The set to be queried. If this parameter is not a
357		valid CFSet, the behavior is undefined.
358	@param value The value to retrieve. The equal() callback provided when
359                the set was created is used to compare. If the equal() callback
360                was NULL, pointer equality (in C, ==) is used. If a value, or
361                any of the values in the set, are not understood by the equal()
362                callback, the behavior is undefined.
363        @result The value in the set with the given hash.
364*/
365CF_EXPORT
366const void *CFSetGetValue(CFSetRef theSet, const void *value);
367
368/*!
369	@function CFSetGetValueIfPresent
370	Retrieves a value in the set which hashes the same as the specified value,
371        if present.
372	@param theSet The set to be queried. If this parameter is not a
373		valid CFSet, the behavior is undefined.
374	@param candidate This value is hashed and compared with values in the
375                set to determine which value to retrieve. The equal() callback provided when
376                the set was created is used to compare. If the equal() callback
377                was NULL, pointer equality (in C, ==) is used. If a value, or
378                any of the values in the set, are not understood by the equal()
379                callback, the behavior is undefined.
380	@param value A pointer to memory which should be filled with the
381		pointer-sized value if a matching value is found. If no
382		match is found, the contents of the storage pointed to by
383		this parameter are undefined. This parameter may be NULL,
384		in which case the value from the dictionary is not returned
385		(but the return value of this function still indicates
386		whether or not the value was present).
387        @result True if the value was present in the set, otherwise false.
388*/
389CF_EXPORT
390Boolean CFSetGetValueIfPresent(CFSetRef theSet, const void *candidate, const void **value);
391
392/*!
393	@function CFSetGetValues
394	Fills the buffer with values from the set.
395	@param theSet The set to be queried. If this parameter is not a
396		valid CFSet, the behavior is undefined.
397	@param values A C array of pointer-sized values to be filled with
398		values from the set. The values in the C array are ordered
399		in the same order in which they appear in the set. If this
400		parameter is not a valid pointer to a C array of at least
401		CFSetGetCount() pointers, the behavior is undefined.
402*/
403CF_EXPORT
404void CFSetGetValues(CFSetRef theSet, const void **values);
405
406/*!
407	@function CFSetApplyFunction
408	Calls a function once for each value in the set.
409	@param theSet The set to be operated upon. If this parameter is not
410		a valid CFSet, the behavior is undefined.
411	@param applier The callback function to call once for each value in
412		the given set. If this parameter is not a
413		pointer to a function of the correct prototype, the behavior
414		is undefined. If there are values in the set which the
415		applier function does not expect or cannot properly apply
416		to, the behavior is undefined.
417	@param context A pointer-sized user-defined value, which is passed
418		as the second parameter to the applier function, but is
419		otherwise unused by this function. If the context is not
420		what is expected by the applier function, the behavior is
421		undefined.
422*/
423CF_EXPORT
424void CFSetApplyFunction(CFSetRef theSet, CFSetApplierFunction applier, void *context);
425
426/*!
427	@function CFSetAddValue
428	Adds the value to the set if it is not already present.
429	@param theSet The set to which the value is to be added. If this
430		parameter is not a valid mutable CFSet, the behavior is
431		undefined.
432	@param value The value to add to the set. The value is retained by
433		the set using the retain callback provided when the set
434		was created. If the value is not of the sort expected by the
435		retain callback, the behavior is undefined. The count of the
436                set is increased by one.
437*/
438CF_EXPORT
439void CFSetAddValue(CFMutableSetRef theSet, const void *value);
440
441/*!
442	@function CFSetReplaceValue
443	Replaces the value in the set if it is present.
444	@param theSet The set to which the value is to be replaced. If this
445		parameter is not a valid mutable CFSet, the behavior is
446		undefined.
447        @param value The value to replace in the set. The equal() callback provided when
448                the set was created is used to compare. If the equal() callback
449                was NULL, pointer equality (in C, ==) is used. If a value, or
450                any of the values in the set, are not understood by the equal()
451                callback, the behavior is undefined. The value is retained by
452		the set using the retain callback provided when the set
453		was created. If the value is not of the sort expected by the
454		retain callback, the behavior is undefined. The count of the
455                set is increased by one.
456*/
457CF_EXPORT
458void CFSetReplaceValue(CFMutableSetRef theSet, const void *value);
459
460/*!
461	@function CFSetSetValue
462	Replaces the value in the set if it is present, or adds the value to
463        the set if it is absent.
464	@param theSet The set to which the value is to be replaced. If this
465		parameter is not a valid mutable CFSet, the behavior is
466		undefined.
467        @param value The value to set in the CFSet. The equal() callback provided when
468                the set was created is used to compare. If the equal() callback
469                was NULL, pointer equality (in C, ==) is used. If a value, or
470                any of the values in the set, are not understood by the equal()
471                callback, the behavior is undefined. The value is retained by
472		the set using the retain callback provided when the set
473		was created. If the value is not of the sort expected by the
474		retain callback, the behavior is undefined. The count of the
475                set is increased by one.
476*/
477CF_EXPORT
478void CFSetSetValue(CFMutableSetRef theSet, const void *value);
479
480/*!
481	@function CFSetRemoveValue
482	Removes the specified value from the set.
483	@param theSet The set from which the value is to be removed.
484                If this parameter is not a valid mutable CFSet,
485		the behavior is undefined.
486        @param value The value to remove. The equal() callback provided when
487                the set was created is used to compare. If the equal() callback
488                was NULL, pointer equality (in C, ==) is used. If a value, or
489                any of the values in the set, are not understood by the equal()
490                callback, the behavior is undefined.
491*/
492CF_EXPORT
493void CFSetRemoveValue(CFMutableSetRef theSet, const void *value);
494
495/*!
496	@function CFSetRemoveAllValues
497	Removes all the values from the set, making it empty.
498	@param theSet The set from which all of the values are to be
499		removed. If this parameter is not a valid mutable CFSet,
500		the behavior is undefined.
501*/
502CF_EXPORT
503void CFSetRemoveAllValues(CFMutableSetRef theSet);
504
505CF_EXTERN_C_END
506CF_IMPLICIT_BRIDGING_DISABLED
507
508#endif /* ! __COREFOUNDATION_CFSET__ */
509
510