CFBag Reference

Overview

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 by Task

Creating a Bag

• CFBagCreate
• CFBagCreateCopy

Examining a Bag

• CFBagContainsValue
• CFBagGetCount
• CFBagGetCountOfValue
• CFBagGetValue
• CFBagGetValueIfPresent
• CFBagGetValues

Applying a Function to the Contents of a Bag

• CFBagApplyFunction

Getting the CFBag Type ID

• CFBagGetTypeID

Functions

CFBagApplyFunction

Calls a function once for each value in a bag.

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

CFBagContainsValue

Reports whether or not a value is in a bag.

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

CFBagCreate

Creates an immutable bag containing specified values.

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

CFBagCreateCopy

Creates an immutable bag with the values of another bag.

CFBagRef CFBagCreateCopy (
   CFAllocatorRef allocator,
   CFBagRef theBag
);

CFBagGetCount

Returns the number of values currently in a bag.

CFIndex CFBagGetCount (
   CFBagRef theBag
);

CFBagGetCountOfValue

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

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

CFBagGetTypeID

Returns the type identifier for the CFBag opaque type.

CFTypeID CFBagGetTypeID (
   void
);

CFBagGetValue

Returns a requested value from a bag.

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

CFBagGetValueIfPresent

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

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

CFBagGetValues

Fills a buffer with values from a bag.

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

Callbacks

CFBagApplierFunction

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

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

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

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

CFBagCopyDescriptionCallBack

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

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

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

CFStringRef MyCallBack (
   const void *value
);

CFBagEqualCallBack

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

typedef Boolean (*CFBagEqualCallBack) (
   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
);

CFBagHashCallBack

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.

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

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

CFHashCode CFBagHashCallBack (
   const void *value
);

CFBagReleaseCallBack

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

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

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

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

CFBagRetainCallBack

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

typedef const void *(*CFBagRetainCallBack) (
   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

CFBagCallBacks

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

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.

CFBagRef

A reference to an immutable bag object.

typedef const struct __CFBag *CFBagRef;

Constants

Predefined Callback Structures

CFBag provides some predefined callbacks for your convenience.

const CFBagCallBacks kCFTypeBagCallBacks;
const CFBagCallBacks kCFCopyStringBagCallBacks;

Constants

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 iOS 2.0 and later.

Declared in CFBag.h.

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 iOS 2.0 and later.

Declared in CFBag.h.