Mac Developer Library

Developer

CoreFoundation Framework Reference CFSet Reference

Options
Deployment Target:

On This Page
Language:

CFSet Reference

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

  • Creates an immutable CFSet object containing supplied values.

    Declaration

    Swift

    func CFSetCreate(_ allocator: CFAllocator!, _ values: UnsafeMutablePointer<UnsafePointer<Void>>, _ numValues: CFIndex, _ callBacks: UnsafePointer<CFSetCallBacks>) -> CFSet!

    Objective-C

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

    Parameters

    allocator

    The allocator to use to to allocate memory for the new set and its storage for values. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    values

    A C array of the pointer-sized values to be in the new set. This parameter may be NULL if the numValues parameter is 0. The C array is not changed or freed by this function. values must be a pointer to a C array of at least numValues elements.

    numValues

    The number of values to copy from the values C array in the new set.

    callBacks

    A pointer to a CFSetCallBacks structure initialized with the callbacks to use to retain, release, describe, and compare values in the collection. 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 collection creations.

    This value may be NULL, which is treated as a valid structure of version 0 with all fields NULL. If the collection contains only CFType objects, then pass kCFTypeSetCallBacks to use the default callback functions.

    Return Value

    A new immutable set, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Discussion

    If any value put into the collection is not one understood by one of the callback functions, the behavior when that callback function is used is undefined.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFSetCreateCopy(_ allocator: CFAllocator!, _ theSet: CFSet!) -> CFSet!

    Objective-C

    CFSetRef CFSetCreateCopy ( CFAllocatorRef allocator, CFSetRef theSet );

    Parameters

    allocator

    The allocator to use to allocate memory for the new set and its storage for values. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    theSet

    The set to copy.

    Return Value

    A new set that contains the same values as theSet, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Discussion

    The pointer values from theSet are copied into the new set, and the values are retained by the new set. The count of the new set is the same as the count of theSet. The new set uses the same callbacks as theSet.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFSetContainsValue(_ theSet: CFSet!, _ value: UnsafePointer<Void>) -> Boolean

    Objective-C

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

    Parameters

    theSet

    The set to search.

    value

    The value to match in theSet. Comparisons are made using the equal callback provided when theSet was created. If the equal callback was NULL, pointer equality (in C, ==) is used.

    Return Value

    true if value is contained in theSet, otherwise false.

    Discussion

    This function uses the equal callback. value and all elements in the set must be understood by the equal callback.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of values currently in a set.

    Declaration

    Swift

    func CFSetGetCount(_ theSet: CFSet!) -> CFIndex

    Objective-C

    CFIndex CFSetGetCount ( CFSetRef theSet );

    Parameters

    theSet

    The set to examine.

    Return Value

    The number of values in theSet.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFSetGetCountOfValue(_ theSet: CFSet!, _ value: UnsafePointer<Void>) -> CFIndex

    Objective-C

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

    Parameters

    theSet

    The set to examine.

    value

    The value for which to search in theSet. Comparisons are made using the equal callback provided when theSet was created. If the equal callback was NULL, pointer equality (in C, ==) is used.

    Return Value

    The number of times value occurs in theSet. By definition, sets can not contain duplicate values, so returns 1 if value is contained in theSet, otherwise 0.

    Discussion

    This function uses the equal callback. value and all elements in the set must be understood by the equal callback.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Obtains a specified value from a set.

    Declaration

    Swift

    func CFSetGetValue(_ theSet: CFSet!, _ value: UnsafePointer<Void>) -> UnsafePointer<Void>

    Objective-C

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

    Parameters

    theSet

    The set to examine.

    value

    The value for which to search in theSet. Comparisons are made using the equal callback provided when theSet was created. If the equal callback was NULL, pointer equality (in C, ==) is used.

    Return Value

    A pointer to the requested value, or NULL if the value is not in theSet. If the value is a Core Foundation object, Ownership follows the Get Rule.

    Discussion

    Since this function uses the equal callback, value all elements in the set must be understood by the equal callback. Depending on the implementation of the equal callback specified when creating theSet, the value returned may not have the same pointer equality as value.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CFSetGetValueIfPresent(_ theSet: CFSet!, _ candidate: UnsafePointer<Void>, _ value: UnsafeMutablePointer<UnsafePointer<Void>>) -> Boolean

    Objective-C

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

    Parameters

    theSet

    The set to examine.

    candidate

    The value for which to search in theSet. Comparisons are made using the equal callback provided when theSet was created. If the equal callback was NULL, pointer equality (in C, ==) is used.

    value

    Upon return contains the matching value if it exists in theSet, otherwise NULL. If the value is a Core Foundation object, ownership follows the Get Rule.

    Return Value

    true if value exists in theSet, otherwise false.

    Discussion

    This function uses the equal callback. candidate and all elements in the set must be understood by the equal callback. Depending on the implementation of the equal callback specified when creating theSet, the value returned in value may not have the same pointer equality as candidate.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Obtains all values in a set.

    Declaration

    Swift

    func CFSetGetValues(_ theSet: CFSet!, _ values: UnsafeMutablePointer<UnsafePointer<Void>>)

    Objective-C

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

    Parameters

    theSet

    The set to examine.

    values

    A C array of pointer-sized values to be filled with values from theSet. The value must be a valid C array of the appropriate type and of a size at least equal to the count of theSet). If the values are Core Foundation objects, ownership follows the Get Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Calls a function once for each value in a set.

    Declaration

    Swift

    func CFSetApplyFunction(_ theSet: CFSet!, _ applier: CFSetApplierFunction, _ context: UnsafeMutablePointer<Void>)

    Objective-C

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

    Parameters

    theSet

    The set to operate upon.

    applier

    The callback function to call once for each value in the theSet. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. The applier function must be able to work with all values in theSet.

    context

    A pointer-sized program-defined value, which is passed as the second parameter to the applier function, but is otherwise unused by this function.

    Discussion

    If theSet is mutable, it is unsafe for the applier function to change the contents of the collection.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the type identifier for the CFSet type.

    Declaration

    Swift

    func CFSetGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFSetGetTypeID ( void );

    Return Value

    The type identifier for the CFSet type.

    Discussion

    CFMutableSet has the same type identifier as CFSet.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Callbacks

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

    Declaration

    Swift

    typealias CFSetApplierFunction = CFunctionPointer<((UnsafePointer<Void>, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

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

    Parameters

    value

    The current value in a set.

    context

    The program-defined context parameter given to the apply function.

    Discussion

    This callback is passed to the CFSetApplyFunction function which iterates over the values in a set and applies the behavior defined in the applier function to each value in a set.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CFSetCopyDescriptionCallBack = CFunctionPointer<((UnsafePointer<Void>) -> Unmanaged<CFString>!)>

    Objective-C

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

    Parameters

    value

    The value to be described.

    Return Value

    A textual description of value. The caller is responsible for releasing this object.

    Discussion

    This callback is passed to CFSetCreate in a CFSetCallBacks structure. This callback is used by the CFCopyDescription function.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CFSetEqualCallBack = CFunctionPointer<((UnsafePointer<Void>, UnsafePointer<Void>) -> Boolean)>

    Objective-C

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

    Parameters

    value1

    A value in the set.

    value2

    Another value in the set.

    Return Value

    true if value1 and value2 are equal, false otherwise.

    Discussion

    This callback is passed to CFSetCreate in a CFSetCallBacks structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • 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.

    Declaration

    Swift

    typealias CFSetHashCallBack = CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)>

    Objective-C

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

    Parameters

    value

    The value used to compute the hash code.

    Return Value

    An integer that can be used as a table address in a hash table structure.

    Discussion

    This callback is passed to CFSetCreate in a CFSetCallBacks structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CFSetReleaseCallBack = CFunctionPointer<((CFAllocator!, UnsafePointer<Void>) -> Void)>

    Objective-C

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

    Parameters

    allocator

    The set’s allocator.

    value

    The value being removed from the set.

    Discussion

    This callback is passed to CFSetCreate in a CFSetCallBacks structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CFSetRetainCallBack = CFunctionPointer<((CFAllocator!, UnsafePointer<Void>) -> UnsafePointer<Void>)>

    Objective-C

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

    Parameters

    allocator

    The set’s allocator.

    value

    The value being added to the set.

    Return Value

    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 collection.

    Discussion

    This callback is passed to CFSetCreate in a CFSetCallBacks structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Data Types

Miscellaneous

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

    Declaration

    Swift

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

    Objective-C

    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.

    Availability

    Available in OS X v10.0 and later.

  • A reference to an immutable set object.

    Declaration

    Swift

    typealias CFSetRef = CFSet

    Objective-C

    typedef const struct __CFSet *CFSetRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • CFSet provides some predefined callbacks for your convenience.

    Declaration

    Swift

    let kCFTypeSetCallBacks: CFSetCallBacks let kCFCopyStringSetCallBacks: CFSetCallBacks

    Objective-C

    const CFSetCallBacks kCFTypeSetCallBacks; const CFSetCallBacks kCFCopyStringSetCallBacks;

    Constants

    • kCFTypeSetCallBacks

      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.

    • kCFCopyStringSetCallBacks

      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.