You use CFTree to create tree structures that represent hierarchical organizations of information. In such structures, each tree node has exactly one parent tree (except for the root tree, which has no parent) and can have multiple children. Each CFTree object in the structure has a context associated with it; this context includes some program-defined data as well as callbacks that operate on that data. The program-defined data is often used as the basis for determining where CFTree objects fit within the structure. All CFTree objects are mutable.

You create a CFTree object using the CFTreeCreate function. This function takes an allocator and pointer to a CFTreeGetContext structure as parameters. The CFTreeContext structure contains the program-defined data and callbacks needed to describe, retain, and release that data. If you do not implement these callbacks, your program-defined data will not be retained or released when trees are added and removed from a parent.

Each CFTree object has a parent and list of children, all of which may be NULL. CFTree provides functions for adding and removing tree objects from the tree structure. Use the CFTreeAppendChild, CFTreeInsertSibling, or CFTreePrependChild functions to add trees to a tree structure, and the CFTreeRemove or CFTreeRemoveAllChildren functions to remove trees.

For the purposes of memory management, CFTree can be thought of as a collection. Typically the only object that retains a child tree is its parent. Usually, therefore, when you remove a child tree from a tree, the child tree is destroyed. If you want to use a child tree after you remove it from its parent, you should retain the child tree first, prior to removing it.

Releasing a tree releases its child trees, and all of their child trees (recursively). Note also that the final release of a tree (when its retain count decreases to zero) causes all of its child trees, and all of their child trees (recursively), to be destroyed, regardless of their retain counts. Releasing a child that is still in a tree is therefore a programming error, and may cause your application to crash.

You can use any of the get functions (functions containing the word “Get”) to obtain the parent, children, or attributes of a tree. For example, use CFTreeGetChildAtIndex to obtain a child of a tree at a specified location. In common with other Core Foundation “Get” functions, these functions do not retain the tree that is returned. If you are making other modifications to the tree, you should either retain or make a deep copy of the child tree returned.

You can apply a function to all children of a tree using the CFTreeApplyFunctionToChildren function, and sort children of a tree using the CFTreeSortChildren function.


Creating Trees


Creates a new CFTree object.

Modifying a Tree


Adds a new child to a tree as the last in its list of children.


Inserts a new sibling after a given tree.


Removes all the children of a tree.


Adds a new child to the specified tree as the first in its list of children.


Removes a tree from its parent.


Replaces the context of a tree by releasing the old information pointer and retaining the new one.

Sorting a Tree


Sorts the immediate children of a tree using a specified comparator function.

Examining a Tree


Returns the root tree of a given tree.


Returns the child of a tree at the specified index.


Returns the number of children in a tree.


Fills a buffer with children from the tree.


Returns the context of the specified tree.


Returns the first child of a tree.


Returns the next sibling, adjacent to a given tree, in the parent's children list.


Returns the parent of a given tree.

Performing an Operation on Tree Elements


Calls a function once for each immediate child of a tree.

Getting the Tree Type ID


Returns the type identifier of the CFTree opaque type.



Type of the callback function used by the CFTree apply function.


Callback function used to provide a description of the program-defined information pointer.


Callback function used to release a previously retained program-defined information pointer.


Callback function used to retain a program-defined information pointer.

Data Types


Structure containing program-defined data and callbacks for a CFTree object.


A reference to a CFTree object.

See Also

Opaque Types


The CFFileDescriptor provides an opaque type to monitor file descriptors for read and write activity via CFRunLoop.


CFStringTokenizer allows you to tokenize strings into words, sentences or paragraphs in a language-neutral way. It supports languages such as Japanese and Chinese that do not delimit words by spaces, as well as de-compounding German compounds. You can obtain Latin transcription for tokens. It also provides language identification API.