/*

* Copyright (c) 2008-2009 Brent Fulgham <[email protected]>. All rights reserved.

*

* This source code is a modified version of the CoreFoundation sources released by Apple Inc. under

* the terms of the APSL version 2.0 (see below).

*

* For information about changes from the original Apple source release can be found by reviewing the

* source control system for the project at https://sourceforge.net/svn/?group_id=246198.

*

* The original license information is as follows:

*

* Copyright (c) 2008 Apple Inc. All rights reserved.

*

* @APPLE_LICENSE_HEADER_START@

*

* This file contains Original Code and/or Modifications of Original Code

* as defined in and that are subject to the Apple Public Source License

* Version 2.0 (the 'License'). You may not use this file except in

* compliance with the License. Please obtain a copy of the License at

* http://www.opensource.apple.com/apsl/ and read it before using this

* file.

*

* The Original Code and all software distributed under the License are

* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER

* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,

* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,

* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.

* Please see the License for the specific language governing rights and

* limitations under the License.

*

* @APPLE_LICENSE_HEADER_END@

*/

/* CFSet.h

Copyright (c) 1998-2007, Apple Inc. All rights reserved.

*/

/*!

@header CFSet

CFSet implements a container which stores unique values.

*/

#if !defined(__COREFOUNDATION_CFSET__)

#define __COREFOUNDATION_CFSET__ 1

#include <CoreFoundation/CFBase.h>

CF_EXTERN_C_BEGIN

/*!

@typedef CFSetRetainCallBack

Type of the callback function used by CFSets for retaining values.

@param allocator The allocator of the CFSet.

@param value The value to retain.

@result The value to store in the set, which is usually the value

parameter passed to this callback, but may be a different

value if a different value should be stored in the set.

*/

typedef const void * (*CFSetRetainCallBack)(CFAllocatorRef allocator, const void *value);

/*!

@typedef CFSetReleaseCallBack

Type of the callback function used by CFSets for releasing a retain on values.

@param allocator The allocator of the CFSet.

@param value The value to release.

*/

typedef void (*CFSetReleaseCallBack)(CFAllocatorRef allocator, const void *value);

/*!

@typedef CFSetCopyDescriptionCallBack

Type of the callback function used by CFSets for describing values.

@param value The value to describe.

@result A description of the specified value.

*/

typedef CFStringRef (*CFSetCopyDescriptionCallBack)(const void *value);

/*!

@typedef CFSetEqualCallBack

Type of the callback function used by CFSets for comparing values.

@param value1 The first value to compare.

@param value2 The second value to compare.

@result True if the values are equal, otherwise false.

*/

typedef Boolean (*CFSetEqualCallBack)(const void *value1, const void *value2);

/*!

@typedef CFSetHashCallBack

Type of the callback function used by CFSets for hashing values.

@param value The value to hash.

@result The hash of the value.

*/

typedef CFHashCode (*CFSetHashCallBack)(const void *value);

/*!

@typedef CFSetCallBacks

Structure containing the callbacks of a CFSet.

@field version The version number of the structure type being passed

in as a parameter to the CFSet creation functions. This

structure is version 0.

@field retain The callback used to add a retain for the set on

values as they are put into the set. This callback returns

the value to store in the set, which is usually the value

parameter passed to this callback, but may be a different

value if a different value should be stored in the set.

The set's allocator is passed as the first argument.

@field release The callback used to remove a retain previously added

for the set from values as they are removed from the

set. The set's allocator is passed as the first

argument.

@field copyDescription The callback used to create a descriptive

string representation of each value in the set. This is

used by the CFCopyDescription() function.

@field equal The callback used to compare values in the set for

equality for some operations.

@field hash The callback used to compare values in the set for

uniqueness for some operations.

*/

typedef struct {

CFIndex version;

CFSetRetainCallBack retain;

CFSetReleaseCallBack release;

CFSetCopyDescriptionCallBack copyDescription;

CFSetEqualCallBack equal;

CFSetHashCallBack hash;

} CFSetCallBacks;

/*!

@constant kCFTypeSetCallBacks

Predefined CFSetCallBacks structure containing a set of callbacks

appropriate for use when the values in a CFSet are all CFTypes.

*/

CF_EXPORT

const CFSetCallBacks kCFTypeSetCallBacks;

/*!

@constant kCFCopyStringSetCallBacks

Predefined CFSetCallBacks structure containing a set of callbacks

appropriate for use when the values in a CFSet should be copies

of a CFString.

*/

CF_EXPORT

const CFSetCallBacks kCFCopyStringSetCallBacks;

/*!

@typedef CFSetApplierFunction

Type of the callback function used by the apply functions of

CFSets.

@param value The current value from the set.

@param context The user-defined context parameter given to the apply

function.

*/

typedef void (*CFSetApplierFunction)(const void *value, void *context);

/*!

@typedef CFSetRef

This is the type of a reference to immutable CFSets.

*/

typedef const struct __CFSet * CFSetRef;

/*!

@typedef CFMutableSetRef

This is the type of a reference to mutable CFSets.

*/

typedef struct __CFSet * CFMutableSetRef;

/*!

@function CFSetGetTypeID

Returns the type identifier of all CFSet instances.

*/

CF_EXPORT

CFTypeID CFSetGetTypeID(void);

/*!

@function CFSetCreate

Creates a new immutable set with the given values.

@param allocator The CFAllocator which should be used to allocate

memory for the set 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 values A C array of the pointer-sized values to be in the

set. 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 values C

array into the CFSet. This number will be the count of the

set. If this parameter is zero, negative, or greater than

the number of values actually in the values C array, the

behavior is undefined.

@param callBacks A C pointer to a CFSetCallBacks structure

initialized with the callbacks for the set to use on each

value in the set. 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 set creations. If the version field of this

callbacks structure is not one of the defined ones for

CFSet, the behavior is undefined. The retain field may be

NULL, in which case the CFSet will do nothing to add a

retain to the contained values for the set. The release

field may be NULL, in which case the CFSet will do nothing

to remove the set's retain (if any) on the values when the

set is destroyed. If the copyDescription field is NULL,

the set will create a simple description for the value. If

the equal field is NULL, the set will use pointer equality

to test for equality of values. The hash field may be NULL,

in which case the CFSet will determine uniqueness by pointer

equality. 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 CFSetCallBacks callbacks structure,

the behavior is undefined. If any of the values put into the

set 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 CFSet.

*/

CF_EXPORT

CFSetRef CFSetCreate(CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFSetCallBacks *callBacks);

/*!

@function CFSetCreateCopy

Creates a new immutable set with the values from the given set.

@param allocator The CFAllocator which should be used to allocate

memory for the set 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 theSet The set which is to be copied. The values from the

set are copied as pointers into the new set (that is,

the values themselves are copied, not that which the values

point to, if anything). However, the values are also

retained by the new set. The count of the new set will

be the same as the copied set. The new set uses the same

callbacks as the set to be copied. If this parameter is

not a valid CFSet, the behavior is undefined.

@result A reference to the new immutable CFSet.

*/

CF_EXPORT

CFSetRef CFSetCreateCopy(CFAllocatorRef allocator, CFSetRef theSet);

/*!

@function CFSetCreateMutable

Creates a new empty mutable set.

@param allocator The CFAllocator which should be used to allocate

memory for the set 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 CFSet. Pass 0 for no hint. The implementation may

ignore this hint, or may use it to optimize various

operations. A set's actual capacity is only limited by

address space and available memory constraints). If this

parameter is negative, the behavior is undefined.

@param callBacks A C pointer to a CFSetCallBacks structure

initialized with the callbacks for the set to use on each

value in the set. 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 set creations. If the version field of this

callbacks structure is not one of the defined ones for

CFSet, the behavior is undefined. The retain field may be

NULL, in which case the CFSet will do nothing to add a

retain to the contained values for the set. The release

field may be NULL, in which case the CFSet will do nothing

to remove the set's retain (if any) on the values when the

set is destroyed. If the copyDescription field is NULL,

the set will create a simple description for the value. If

the equal field is NULL, the set will use pointer equality

to test for equality of values. The hash field may be NULL,

in which case the CFSet will determine uniqueness by pointer

equality. 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 CFSetCallBacks callbacks structure,

the behavior is undefined. If any of the values put into the

set 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 CFSet.

*/

CF_EXPORT

CFMutableSetRef CFSetCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFSetCallBacks *callBacks);

/*!

@function CFSetCreateMutableCopy

Creates a new immutable set with the values from the given set.

@param allocator The CFAllocator which should be used to allocate

memory for the set 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 CFSet. Pass 0 for no hint. The implementation may

ignore this hint, or may use it to optimize various

operations. A set'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 set which is to be copied, or the

behavior is undefined. If this parameter is negative, the

behavior is undefined.

@param theSet The set which is to be copied. The values from the

set are copied as pointers into the new set (that is,

the values themselves are copied, not that which the values

point to, if anything). However, the values are also

retained by the new set. The count of the new set will

be the same as the copied set. The new set uses the same

callbacks as the set to be copied. If this parameter is

not a valid CFSet, the behavior is undefined.

@result A reference to the new mutable CFSet.

*/

CF_EXPORT

CFMutableSetRef CFSetCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFSetRef theSet);

/*!

@function CFSetGetCount

Returns the number of values currently in the set.

@param theSet The set to be queried. If this parameter is not a valid

CFSet, the behavior is undefined.

@result The number of values in the set.

*/

CF_EXPORT

CFIndex CFSetGetCount(CFSetRef theSet);

/*!

@function CFSetGetCountOfValue

Counts the number of times the given value occurs in the set. Since

sets by definition contain only one instance of a value, this function

is synomous to SFSetContainsValue.

@param theSet The set to be searched. If this parameter is not a

valid CFSet, the behavior is undefined.

@param value The value for which to find matches in the set. The

equal() callback provided when the set 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 set, are not understood by the equal() callback,

the behavior is undefined.

@result The number of times the given value occurs in the set.

*/

CF_EXPORT

CFIndex CFSetGetCountOfValue(CFSetRef theSet, const void *value);

/*!

@function CFSetContainsValue

Reports whether or not the value is in the set.

@param theSet The set to be searched. If this parameter is not a

valid CFSet, the behavior is undefined.

@param value The value for which to find matches in the set. The

equal() callback provided when the set 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 set, are not understood by the equal() callback,

the behavior is undefined.

@result true, if the value is in the set, otherwise false.

*/

CF_EXPORT

Boolean CFSetContainsValue(CFSetRef theSet, const void *value);

/*!

@function CFSetGetValue

Retrieves a value in the set which hashes the same as the specified value.

@param theSet The set to be queried. If this parameter is not a

valid CFSet, the behavior is undefined.

@param value The value to retrieve. The equal() callback provided when

the set was created is used to compare. If the equal() callback

was NULL, pointer equality (in C, ==) is used. If a value, or

any of the values in the set, are not understood by the equal()

callback, the behavior is undefined.

@result The value in the set with the given hash.

*/

CF_EXPORT

const void *CFSetGetValue(CFSetRef theSet, const void *value);

/*!

@function CFSetGetValue

Retrieves a value in the set which hashes the same as the specified value,

if present.

@param theSet The set to be queried. If this parameter is not a

valid CFSet, the behavior is undefined.

@param candidate This value is hashed and compared with values in the

set to determine which value to retrieve. The equal() callback provided when

the set was created is used to compare. If the equal() callback

was NULL, pointer equality (in C, ==) is used. If a value, or

any of the values in the set, 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 value is found. If no

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 value was present).

@result True if the value was present in the set, otherwise false.

*/

CF_EXPORT

Boolean CFSetGetValueIfPresent(CFSetRef theSet, const void *candidate, const void **value);

/*!

@function CFSetGetValues

Fills the buffer with values from the set.

@param theSet The set to be queried. If this parameter is not a

valid CFSet, the behavior is undefined.

@param values A C array of pointer-sized values to be filled with

values from the set. The values in the C array are ordered

in the same order in which they appear in the set. If this

parameter is not a valid pointer to a C array of at least

CFSetGetCount() pointers, the behavior is undefined.

*/

CF_EXPORT

void CFSetGetValues(CFSetRef theSet, const void **values);

/*!

@function CFSetApplyFunction

Calls a function once for each value in the set.

@param theSet The set to be operated upon. If this parameter is not

a valid CFSet, the behavior is undefined.

@param applier The callback function to call once for each value in

the given set. If this parameter is not a

pointer to a function of the correct prototype, the behavior

is undefined. If there are values in the set 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 second 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 CFSetApplyFunction(CFSetRef theSet, CFSetApplierFunction applier, void *context);

/*!

@function CFSetAddValue

Adds the value to the set if it is not already present.

@param theSet The set to which the value is to be added. If this

parameter is not a valid mutable CFSet, the behavior is

undefined.

@param value The value to add to the set. The value is retained by

the set using the retain callback provided when the set

was created. If the value is not of the sort expected by the

retain callback, the behavior is undefined. The count of the

set is increased by one.

*/

CF_EXPORT

void CFSetAddValue(CFMutableSetRef theSet, const void *value);

/*!

@function CFSetReplaceValue

Replaces the value in the set if it is present.

@param theSet The set to which the value is to be replaced. If this

parameter is not a valid mutable CFSet, the behavior is

undefined.

@param value The value to replace in the set. The equal() callback provided when

the set was created is used to compare. If the equal() callback

was NULL, pointer equality (in C, ==) is used. If a value, or

any of the values in the set, are not understood by the equal()

callback, the behavior is undefined. The value is retained by

the set using the retain callback provided when the set

was created. If the value is not of the sort expected by the

retain callback, the behavior is undefined. The count of the

set is increased by one.

*/

CF_EXPORT

void CFSetReplaceValue(CFMutableSetRef theSet, const void *value);

/*!

@function CFSetSetValue

Replaces the value in the set if it is present, or adds the value to

the set if it is absent.

@param theSet The set to which the value is to be replaced. If this

parameter is not a valid mutable CFSet, the behavior is

undefined.

@param value The value to set in the CFSet. The equal() callback provided when

the set was created is used to compare. If the equal() callback

was NULL, pointer equality (in C, ==) is used. If a value, or

any of the values in the set, are not understood by the equal()

callback, the behavior is undefined. The value is retained by

the set using the retain callback provided when the set

was created. If the value is not of the sort expected by the

retain callback, the behavior is undefined. The count of the

set is increased by one.

*/

CF_EXPORT

void CFSetSetValue(CFMutableSetRef theSet, const void *value);

/*!

@function CFSetRemoveValue

Removes the specified value from the set.

@param theSet The set from which the value is to be removed.

If this parameter is not a valid mutable CFSet,

the behavior is undefined.

@param value The value to remove. The equal() callback provided when

the set was created is used to compare. If the equal() callback

was NULL, pointer equality (in C, ==) is used. If a value, or

any of the values in the set, are not understood by the equal()

callback, the behavior is undefined.

*/

CF_EXPORT

void CFSetRemoveValue(CFMutableSetRef theSet, const void *value);

/*!

@function CFSetRemoveAllValues

Removes all the values from the set, making it empty.

@param theSet The set from which all of the values are to be

removed. If this parameter is not a valid mutable CFSet,

the behavior is undefined.

*/

CF_EXPORT

void CFSetRemoveAllValues(CFMutableSetRef theSet);

CF_EXTERN_C_END

#endif /* ! __COREFOUNDATION_CFSET__ */