CFSet Reference

Overview

CFSet and its derived mutable type, CFMutableSet Reference, provide support for the mathematical concept of a set. A set, both in its mathematical sense and in the implementation of CFSet, is an unordered collection of distinct elements. CFSet creates static sets and CFMutableSet creates dynamic sets.

Use bags or sets as an alternative to arrays when the order of elements isn't important and performance in testing whether a value is contained in the collection is a consideration—while arrays are ordered, testing for membership is slower than with bags or sets. Use bags over sets if you want to allow duplicate values in your collections.

You create a static set object using either the CFSetCreate or CFSetCreateCopy function. These functions return a set containing the values you pass in as arguments. (Note that sets can't contain NULL pointers; in most cases, though, you can use the kCFNull constant instead.) Values are not copied but retained using the retain callback provided when the set was created. Similarly, when a value is removed from a set, it is released using the release callback.

CFSet provides functions for querying the values of a set. The CFSetGetCount returns the number of values in a set, the CFSetContainsValue function checks if a value is in a set, and CFSetGetValues returns a C array containing all the values in a set.

CFSet is “toll-free bridged” with its Cocoa Foundation counterpart, NSSet. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSSet * parameter, you can pass in a CFSetRef, and in a function where you see a CFSetRef parameter, you can pass in an NSSet instance. This also applies to concrete subclasses of NSSet. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating Sets

• CFSetCreate
• CFSetCreateCopy

Examining a Set

• CFSetContainsValue
• CFSetGetCount
• CFSetGetCountOfValue
• CFSetGetValue
• CFSetGetValueIfPresent
• CFSetGetValues

Applying a Function to Set Members

• CFSetApplyFunction

Getting the CFSet Type ID

• CFSetGetTypeID

Functions

CFSetApplyFunction

Calls a function once for each value in a set.

void CFSetApplyFunction (
   CFSetRef theSet,
   CFSetApplierFunction applier,
   void *context
);

CFSetContainsValue

Returns a Boolean that indicates whether a set contains a given value.

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

CFSetCreate

Creates an immutable CFSet object containing supplied values.

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

CFSetCreateCopy

Creates an immutable set containing the values of an existing set.

CFSetRef CFSetCreateCopy (
   CFAllocatorRef allocator,
   CFSetRef theSet
);

CFSetGetCount

Returns the number of values currently in a set.

CFIndex CFSetGetCount (
   CFSetRef theSet
);

CFSetGetCountOfValue

Returns the number of values in a set that match a given value.

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

CFSetGetTypeID

Returns the type identifier for the CFSet type.

CFTypeID CFSetGetTypeID (
   void
);

CFSetGetValue

Obtains a specified value from a set.

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

CFSetGetValueIfPresent

Reports whether or not a value is in a set, and if it exists returns the value indirectly.

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

CFSetGetValues

Obtains all values in a set.

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

Callbacks

CFSetApplierFunction

Prototype of a callback function that may be applied to every value in a set.

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   const void *value,
   void *context
);

CFSetCopyDescriptionCallBack

Prototype of a callback function used to get a description of a value in a set.

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

If you name your function MyCallBack, you would declare it like this:

CFStringRef MyCallBack (
   const void *value
);

CFSetEqualCallBack

Prototype of a callback function used to determine if two values in a set are equal.

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

If you name your function MyCallBack, you would declare it like this:

Boolean MyCallBack (
   const void *value1,
   const void *value2
);

CFSetHashCallBack

Prototype of a callback function called to compute a hash code for a value. Hash codes are used when values are accessed, added, or removed from a collection.

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

If you name your function MyCallBack, you would declare it like this:

CFHashCode MyCallBack (
   const void *value
);

CFSetReleaseCallBack

Prototype of a callback function used to release a value before it’s removed from a set.

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

If you name your function MyCallBack, you would declare it like this:

void MyCallBack (
   CFAllocatorRef allocator,
   const void *value
);

CFSetRetainCallBack

Prototype of a callback function used to retain a value being added to a set.

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

If you name your function MyCallBack, you would declare it like this:

const void *MyCallBack (
   CFAllocatorRef allocator,
   const void *value
);

Data Types

CFSetCallBacks

This structure contains the callbacks used to retain, release, describe, and compare the values of a CFSet object.

struct CFSetCallBacks {
   CFIndex version;
   CFSetRetainCallBack retain;
   CFSetReleaseCallBack release;
   CFSetCopyDescriptionCallBack copyDescription;
   CFSetEqualCallBack equal;
   CFSetHashCallBack hash;
};
typedef struct CFSetCallBacks CFSetCallBacks;

Fields

version

The version number of this structure. If not one of the defined version numbers for this opaque type, the behavior is undefined. The current version of this structure is 0.

retain

The callback used to retain each value as they are added to the collection. If NULL, values are not retained. See CFSetRetainCallBack for a descriptions of this function’s parameters.

release

The callback used to release values as they are removed from the collection. If NULL, values are not released. See CFSetReleaseCallBack for a description of this callback.

copyDescription

The callback used to create a descriptive string representation of each value in the collection. If NULL, the collection will create a simple description of each value. See CFSetCopyDescriptionCallBack for a description of this callback.

equal

The callback used to compare values in the collection for equality for some operations. If NULL, the collection will use pointer equality to compare values in the collection. See CFSetEqualCallBack for a description of this callback.

hash

The callback used to compute a hash code for values in a collection. If NULL, the collection computes a hash code by converting the pointer value to an integer. See CFSetHashCallBack for a description of this callback.

CFSetRef

A reference to an immutable set object.

typedef const struct __CFSet *CFSetRef;

Constants

Predefined Callback Structures

CFSet provides some predefined callbacks for your convenience.

const CFSetCallBacks kCFTypeSetCallBacks;
const CFSetCallBacks kCFCopyStringSetCallBacks;

Constants

kCFTypeSetCallBacks

Predefined CFSetCallBacks structure containing a set of callbacks appropriate for use when the values in a CFSet are all CFType-derived objects. The retain callback is CFRetain, the release callback is CFRelease, the copy callback is CFCopyDescription, the equal callback is CFEqual, and the hash callback is CFHash. Therefore, if you use this constant when creating the collection, items are automatically retained when added to the collection, and released when removed from the collection.

Available in OS X v10.0 and later.

Declared in CFSet.h.

kCFCopyStringSetCallBacks

Predefined CFSetCallBacks structure containing a set of callbacks appropriate for use when the values in a set are all CFString objects. The retain callback makes an immutable copy of strings added to the set.

Available in OS X v10.0 and later.

Declared in CFSet.h.