Mac Developer Library

Developer

CoreFoundation Framework Reference CFBag Reference

Options
Deployment Target:

On This Page
Language:

CFBag Reference

CFBag and its derived mutable type, CFMutableBag, manage non-sequential collections of values called bags in which there can be duplicate values. CFBag creates static bags and CFMutableBag creates dynamic bags.

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 bag object using either the CFBagCreate or CFBagCreateCopy function. These functions return a bag containing the values you pass in as arguments. (Note that bags 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 bag was created. Similarly, when a value is removed from a bag, it is released using the release callback.

CFBag provides functions for querying the values of a bag. The CFBagGetCount returns the number of values in a bag, the CFBagContainsValue function checks if a value is in a bag, and CFBagGetValues returns a C array containing all the values in a bag.

The CFBagApplyFunction function lets you apply a function to all values in a bag.

Functions

  • Creates an immutable bag containing specified values.

    Declaration

    Swift

    func CFBagCreate(_ allocator: CFAllocator!, _ values: UnsafeMutablePointer<UnsafePointer<Void>>, _ numValues: CFIndex, _ callBacks: UnsafePointer<CFBagCallBacks>) -> CFBag!

    Objective-C

    CFBagRef CFBagCreate ( CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFBagCallBacks *callBacks );

    Parameters

    allocator

    The allocator to use to allocate memory for the new bag 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 bag. 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 valid 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 CFBag object. If the number is negative or is greater than the actual number of values, the behavior is undefined.

    callBacks

    A pointer to a CFBagCallBacks structure initialized with the callbacks to use to retain, release, describe, and compare values in the bag. 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 parameter 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 CFBagCallBacks structure, the behavior is undefined. 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. If the collection contains CFType objects only, then pass kCFTypeBagCallBacks as this parameter to use the default callback functions.

    Return Value

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

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Creates an immutable bag with the values of another bag.

    Declaration

    Swift

    func CFBagCreateCopy(_ allocator: CFAllocator!, _ theBag: CFBag!) -> CFBag!

    Objective-C

    CFBagRef CFBagCreateCopy ( CFAllocatorRef allocator, CFBagRef theBag );

    Parameters

    allocator

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

    theBag

    The bag to copy. The pointer values from theBag are copied into the new bag. However, the values are also retained by the new bag. The count of the new bag is the same as the count of theBag. The new bag uses the same callbacks as theBag.

    Return Value

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

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

    Declaration

    Swift

    func CFBagContainsValue(_ theBag: CFBag!, _ value: UnsafePointer<Void>) -> Boolean

    Objective-C

    Boolean CFBagContainsValue ( CFBagRef theBag, const void *value );

    Parameters

    theBag

    The bag to examine.

    value

    The value to match in theBag. The equal callback provided when theBag was created is used to compare. If the equal callback was NULL, pointer equality (in C, ==) is used. If value, or any other value in theBag, is not understood by the equal callback, the behavior is undefined.

    Return Value

    true if value is contained in theBag, otherwise false.

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

    Declaration

    Swift

    func CFBagGetCount(_ theBag: CFBag!) -> CFIndex

    Objective-C

    CFIndex CFBagGetCount ( CFBagRef theBag );

    Parameters

    theBag

    The bag to examine.

    Return Value

    The number of values in theBag.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of times a value occurs in a bag.

    Declaration

    Swift

    func CFBagGetCountOfValue(_ theBag: CFBag!, _ value: UnsafePointer<Void>) -> CFIndex

    Objective-C

    CFIndex CFBagGetCountOfValue ( CFBagRef theBag, const void *value );

    Parameters

    theBag

    The bag to examine.

    value

    The value for which to find matches in theBag. The equal callback provided when theBag was created is used to compare. If the equal callback was NULL, pointer equality (in C, ==) is used. If value, or any other value in theBag, is not understood by the equal callback, the behavior is undefined.

    Return Value

    The number of times value occurs in theBag.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a requested value from a bag.

    Declaration

    Swift

    func CFBagGetValue(_ theBag: CFBag!, _ value: UnsafePointer<Void>) -> UnsafePointer<Void>

    Objective-C

    const void * CFBagGetValue ( CFBagRef theBag, const void *value );

    Parameters

    theBag

    The bag to examine.

    value

    The value for which to find matches in theBag. The equal callback provided when theBag was created is used to compare. If the equal callback was NULL, pointer equality (in C, ==) is used. If value, or any other value in theBag, is not understood by the equal callback, the behavior is undefined.

    Return Value

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

    Discussion

    Depending on the implementation of the equal callback specified when creating theBag, 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 bag, and returns that value indirectly if it exists.

    Declaration

    Swift

    func CFBagGetValueIfPresent(_ theBag: CFBag!, _ candidate: UnsafePointer<Void>, _ value: UnsafeMutablePointer<UnsafePointer<Void>>) -> Boolean

    Objective-C

    Boolean CFBagGetValueIfPresent ( CFBagRef theBag, const void *candidate, const void **value );

    Parameters

    theBag

    The bag to be searched.

    candidate

    The value for which to find matches in theBag. The equal callback provided when theBag was created is used to compare. If the equal callback was NULL, pointer equality (in C, ==) is used. If candidate, or any other value in theBag, is not understood by the equal callback, the behavior is undefined.

    value

    A pointer to a value object. Set to the matching value if it exists in the bag, otherwise NULL. If the value is a Core Foundation object, ownership follows the Get Rule.

    Return Value

    true if value is present in theBag, otherwise false.

    Discussion

    Depending on the implementation of the equal callback specified when creating theBag, 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.

  • Fills a buffer with values from a bag.

    Declaration

    Swift

    func CFBagGetValues(_ theBag: CFBag!, _ values: UnsafeMutablePointer<UnsafePointer<Void>>)

    Objective-C

    void CFBagGetValues ( CFBagRef theBag, const void **values );

    Parameters

    theBag

    The bag to examine.

    values

    A C array of pointer-sized values to be filled with values from theBag. The value must be a valid C array of the appropriate type and size (that is, a size equal to the count of theBag).

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

    Declaration

    Swift

    func CFBagApplyFunction(_ theBag: CFBag!, _ applier: CFBagApplierFunction, _ context: UnsafeMutablePointer<Void>)

    Objective-C

    void CFBagApplyFunction ( CFBagRef theBag, CFBagApplierFunction applier, void *context );

    Parameters

    theBag

    The bag to operate upon.

    applier

    The callback function to call once for each value in the theBag. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in the range that the applier function does not expect or cannot properly apply to, the behavior is undefined.

    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. If the context is not what is expected by the applier function, the behavior is undefined.

    Discussion

    While this function iterates over a mutable collection, 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 CFBag opaque type.

    Declaration

    Swift

    func CFBagGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFBagGetTypeID ( void );

    Return Value

    The type identifier for the CFBag opaque type.

    Special Considerations

    CFMutableBag objects have the same type identifier as CFBag objects.

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

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    value

    The current value in a bag.

    context

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

    Discussion

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

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

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    value

    The value to be described.

    Return Value

    A textual description of value. Ownership follows the Create Rule.

    Discussion

    This callback is passed to CFBagCreate in a CFBagCallBacks 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 bag are equal.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    value1

    A value in the bag.

    value2

    Another value in the bag.

    Return Value

    true if value1 and value2 are equal, false otherwise.

    Discussion

    This callback is passed to CFBagCreate in a CFBagCallBacks structure.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

  • Prototype of a callback function invoked 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 CFBagHashCallBack = CFunctionPointer<((UnsafePointer<Void>) -> CFHashCode)>

    Objective-C

    typedef CFHashCode (*CFBagHashCallBack) ( 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 CFBagCreate in a CFBagCallBacks 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 bag.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    allocator

    The bag’s allocator.

    value

    The value being removed from the bag.

    Discussion

    This callback is passed to CFBagCreate in a CFBagCallBacks 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 bag.

    Declaration

    Swift

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

    Objective-C

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

    Parameters

    allocator

    The bag’s allocator.

    value

    The value being added to the bag.

    Return Value

    The value to store in the bag, 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 CFBagCreate in a CFBagCallBacks 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 CFBag object.

    Declaration

    Swift

    struct CFBagCallBacks { var version: CFIndex var retain: CFBagRetainCallBack var release: CFBagReleaseCallBack var copyDescription: CFBagCopyDescriptionCallBack var equal: CFBagEqualCallBack var hash: CFBagHashCallBack }

    Objective-C

    struct CFBagCallBacks { CFIndex version; CFBagRetainCallBack retain; CFBagReleaseCallBack release; CFBagCopyDescriptionCallBack copyDescription; CFBagEqualCallBack equal; CFBagHashCallBack hash; }; typedef struct CFBagCallBacks CFBagCallBacks;

    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 CFBagRetainCallBack 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 CFBagReleaseCallBack 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 CFBagCopyDescriptionCallBack 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 CFBagEqualCallBack 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 CFBagHashCallBack for a description of this callback.

    Availability

    Available in OS X v10.0 and later.

  • A reference to an immutable bag object.

    Declaration

    Swift

    typealias CFBagRef = CFBag

    Objective-C

    typedef const struct __CFBag *CFBagRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.0 and later.

Constants

Miscellaneous

  • CFBag provides some predefined callbacks for your convenience.

    Declaration

    Swift

    let kCFTypeBagCallBacks: CFBagCallBacks let kCFCopyStringBagCallBacks: CFBagCallBacks

    Objective-C

    const CFBagCallBacks kCFTypeBagCallBacks; const CFBagCallBacks kCFCopyStringBagCallBacks;

    Constants

    • kCFTypeBagCallBacks

      kCFTypeBagCallBacks

      Predefined CFBagCallBacks structure containing a set of callbacks appropriate for use when the values in a CFBag 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.

    • kCFCopyStringBagCallBacks

      kCFCopyStringBagCallBacks

      Predefined CFBagCallBacks structure containing a set of callbacks appropriate for use when the values in a CFBag are all CFString objects. The bag makes immutable copies of the strings placed into it.

      Available in OS X v10.0 and later.