[apple/cf.git] / Collections.subproj / CFTree.h

/*
 * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*	CFTree.h
	Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
*/
/*!
        @header CFTree
        CFTree implements a container which stores references to other CFTrees.
        Each tree may have a parent, and a variable number of children.
*/

#if !defined(__COREFOUNDATION_CFTREE__)
#define __COREFOUNDATION_CFTREE__ 1

#include <CoreFoundation/CFBase.h>

#if defined(__cplusplus)
extern "C" {
#endif

/*!
        @typedef CFTreeRetainCallBack
        Type of the callback function used to add a retain to the user-specified
        info parameter.  This callback may returns the value to use whenever the
        info parameter is retained, which is usually the value parameter passed
        to this callback, but may be a different value if a different value
        should be used.
        @param info A user-supplied info parameter provided in a CFTreeContext.
        @result The retained info parameter.
*/
typedef const void *	(*CFTreeRetainCallBack)(const void *info);

/*!
        @typedef CFTreeReleaseCallBack
        Type of the callback function used to remove a retain previously
        added to the user-specified info parameter.
        @param info A user-supplied info parameter provided in a CFTreeContext.
*/
typedef void		(*CFTreeReleaseCallBack)(const void *info);

/*!
        @typedef CFTreeCopyDescriptionCallBack
        Type of the callback function used to provide a description of the
        user-specified info parameter.
        @param info A user-supplied info parameter provided in a CFTreeContext.
        @result A description of the info parameter.
*/
typedef CFStringRef	(*CFTreeCopyDescriptionCallBack)(const void *info);

/*!
        @typedef CFTreeContext
        Structure containing user-specified data and callbacks for a CFTree.
        @field version The version number of the structure type being passed
                in as a parameter to the CFTree creation function.
                This structure is version 0.
        @field info A C pointer to a user-specified block of data.
        @field retain The callback used to add a retain for the info field.
                If this parameter is not a pointer to a function of the correct
                prototype, the behavior is undefined.  The value may be NULL.
        @field release The calllback used to remove a retain previously added
                for the info field.  If this parameter is not a pointer to a 
                function of the correct prototype, the behavior is undefined.
                The value may be NULL.
        @field copyDescription The callback used to provide a description of
                the info field.
*/
typedef struct {
    CFIndex				version;
    void *				info;
    CFTreeRetainCallBack		retain;
    CFTreeReleaseCallBack		release;	
    CFTreeCopyDescriptionCallBack	copyDescription;
} CFTreeContext;

/*!
        @typedef CFTreeApplierFunction
        Type of the callback function used by the apply functions of
                CFTree.
        @param value The current value from the CFTree
        @param context The user-defined context parameter give to the apply
                function.
*/
typedef void (*CFTreeApplierFunction)(const void *value, void *context);

/*!
        @typedef CFTreeRef
        This is the type of a reference to CFTrees.
*/
typedef struct __CFTree * CFTreeRef;

/*!
        @function CFTreeGetTypeID
        Returns the type identifier of all CFTree instances.
*/
CF_EXPORT
CFTypeID CFTreeGetTypeID(void);

/*!
        @function CFTreeCreate
        Creates a new mutable tree.
        @param allocator The CFAllocator which should be used to allocate
                memory for the tree and storage for its children.  This
                parameter may be NULL in which case the current default
                CFAllocator is used.  If this reference is not a valid
                CFAllocator, the behavior is undefined.
        @param context A C pointer to a CFTreeContext structure to be copied 
                and used as the context of the new tree.  The info parameter
                will be retained by the tree if a retain function is provided.
                If this value is not a valid C pointer to a CFTreeContext 
                structure-sized block of storage, the result is undefined. 
                If the version number of the storage is not a valid CFTreeContext
                version number, the result is undefined.
        @result A reference to the new CFTree.
*/
CF_EXPORT
CFTreeRef CFTreeCreate(CFAllocatorRef allocator, const CFTreeContext *context);

/*!
        @function CFTreeGetParent
        Returns the parent of the specified tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @result The parent of the tree.
*/
CF_EXPORT
CFTreeRef CFTreeGetParent(CFTreeRef tree);

/*!
        @function CFTreeGetNextSibling
        Returns the sibling after the specified tree in the parent tree's list.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @result The next sibling of the tree.
*/
CF_EXPORT
CFTreeRef CFTreeGetNextSibling(CFTreeRef tree);

/*!
        @function CFTreeGetFirstChild
        Returns the first child of the tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @result The first child of the tree.
*/
CF_EXPORT
CFTreeRef CFTreeGetFirstChild(CFTreeRef tree);

/*!
        @function CFTreeGetContext
        Returns the context of the specified tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @param context A C pointer to a CFTreeContext structure to be filled in with
                the context of the specified tree.  If this value is not a valid C
                pointer to a CFTreeContext structure-sized block of storage, the
                result is undefined.  If the version number of the storage is not
                a valid CFTreeContext version number, the result is undefined.
*/
CF_EXPORT
void CFTreeGetContext(CFTreeRef tree, CFTreeContext *context);

/*!
        @function CFTreeGetChildCount
        Returns the number of children of the specified tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @result The number of children.
*/
CF_EXPORT
CFIndex CFTreeGetChildCount(CFTreeRef tree);

/*!
        @function CFTreeGetChildAtIndex
        Returns the nth child of the specified tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @param idx The index of the child tree to be returned.  If this parameter
                is less than zero or greater than the number of children of the
                tree, the result is undefined.
        @result A reference to the specified child tree.
*/
CF_EXPORT
CFTreeRef CFTreeGetChildAtIndex(CFTreeRef tree, CFIndex idx);

/*!
        @function CFTreeGetChildren
        Fills the buffer with children from the tree.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
	@param children A C array of pointer-sized values to be filled with
		children from the tree.  If this parameter is not a valid pointer to a 
                C array of at least CFTreeGetChildCount() pointers, the behavior is undefined.
        @result A reference to the specified child tree.
*/
CF_EXPORT
void CFTreeGetChildren(CFTreeRef tree, CFTreeRef *children);

/*!
	@function CFTreeApplyFunctionToChildren
	Calls a function once for each child of the tree.  Note that the applier
        only operates one level deep, and does not operate on descendents further
        removed than the immediate children of the tree.
        @param heap The tree to be operated upon.  If this parameter is not a
		valid CFTree, the behavior is undefined.
	@param applier The callback function to call once for each child of
		the given tree.  If this parameter is not a pointer to a 
                function of the correct prototype, the behavior is undefined.
                If there are values in the tree which the applier function does
                not expect or cannot properly apply to, the behavior is undefined.
	@param context A pointer-sized user-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.
*/
CF_EXPORT
void CFTreeApplyFunctionToChildren(CFTreeRef tree, CFTreeApplierFunction applier, void *context);

/*!
        @function CFTreeFindRoot
        Returns the root tree of which the specified tree is a descendent.
        @param tree The tree to be queried.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @result A reference to the root of the tree.
*/
CF_EXPORT
CFTreeRef CFTreeFindRoot(CFTreeRef tree);

/*!
        @function CFTreeSetContext
        Replaces the context of a tree.  The tree releases its retain on the
        info of the previous context, and retains the info of the new context.
        @param tree The tree to be operated on.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @param context A C pointer to a CFTreeContext structure to be copied 
                and used as the context of the new tree.  The info parameter
                will be retained by the tree if a retain function is provided.
                If this value is not a valid C pointer to a CFTreeContext 
                structure-sized block of storage, the result is undefined. 
                If the version number of the storage is not a valid CFTreeContext
                version number, the result is undefined.
*/
CF_EXPORT
void CFTreeSetContext(CFTreeRef tree, const CFTreeContext *context);

/*!
        @function CFTreePrependChild
        Adds the newChild to the specified tree as the first in its list of children.
        @param tree The tree to be operated on.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @param newChild The child to be added.
                If this parameter is not a valid CFTree, the behavior is undefined.
                If this parameter is a tree which is already a child of any tree,
                the behavior is undefined.
*/
CF_EXPORT
void CFTreePrependChild(CFTreeRef tree, CFTreeRef newChild);

/*!
        @function CFTreeAppendChild
        Adds the newChild to the specified tree as the last in its list of children.
        @param tree The tree to be operated on.  If this parameter is not a valid
                CFTree, the behavior is undefined.
        @param newChild The child to be added.
                If this parameter is not a valid CFTree, the behavior is undefined.
                If this parameter is a tree which is already a child of any tree,
                the behavior is undefined.
*/
CF_EXPORT
void CFTreeAppendChild(CFTreeRef tree, CFTreeRef newChild);

/*!
        @function CFTreeInsertSibling
        Inserts newSibling into the the parent tree's linked list of children after
        tree.  The newSibling will have the same parent as tree.
        @param tree The tree to insert newSibling after.  If this parameter is not a valid
                CFTree, the behavior is undefined.  If the tree does not have a
                parent, the behavior is undefined.
        @param newSibling The sibling to be added.
                If this parameter is not a valid CFTree, the behavior is undefined.
                If this parameter is a tree which is already a child of any tree,
                the behavior is undefined.  
*/
CF_EXPORT
void CFTreeInsertSibling(CFTreeRef tree, CFTreeRef newSibling);

/*!
        @function CFTreeRemove
        Removes the tree from its parent.
        @param tree The tree to be removed.  If this parameter is not a valid
                CFTree, the behavior is undefined.
*/
CF_EXPORT
void CFTreeRemove(CFTreeRef tree);

/*!
        @function CFTreeRemoveAllChildren
        Removes all the children of the tree.
        @param tree The tree to remove all children from.  If this parameter is not a valid
                CFTree, the behavior is undefined.
*/
CF_EXPORT
void CFTreeRemoveAllChildren(CFTreeRef tree);

/*!
        @function CFTreeSortChildren
        Sorts the children of the specified tree using the specified comparator function.
        @param tree The tree to be operated on.  If this parameter is not a valid
                CFTree, the behavior is undefined.
	@param comparator The function with the comparator function type
		signature which is used in the sort operation to compare
		children of the tree with the given value. If this parameter
		is not a pointer to a function of the correct prototype, the
		the behavior is undefined. The children of the tree are sorted 
                from least to greatest according to this function.
	@param context A pointer-sized user-defined value, which is passed
		as the third parameter to the comparator function, but is
		otherwise unused by this function. If the context is not
		what is expected by the comparator function, the behavior is
		undefined.
*/
CF_EXPORT
void CFTreeSortChildren(CFTreeRef tree, CFComparatorFunction comparator, void *context);

#if defined(__cplusplus)
}
#endif

#endif /* ! __COREFOUNDATION_CFTREE__ */
Commit	Line	Data
9ce05555 A	1	/*
	2	* Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
	7	*
	8	* This file contains Original Code and/or Modifications of Original Code
	9	* as defined in and that are subject to the Apple Public Source License
	10	* Version 2.0 (the 'License'). You may not use this file except in
	11	* compliance with the License. Please obtain a copy of the License at
	12	* http://www.opensource.apple.com/apsl/ and read it before using this
	13	* file.
	14	*
	15	* The Original Code and all software distributed under the License are
	16	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	17	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	18	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	19	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	20	* Please see the License for the specific language governing rights and
	21	* limitations under the License.
	22	*
	23	* @APPLE_LICENSE_HEADER_END@
	24	*/
	25	/* CFTree.h
	26	Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
	27	*/
	28	/*!
	29	@header CFTree
	30	CFTree implements a container which stores references to other CFTrees.
	31	Each tree may have a parent, and a variable number of children.
	32	*/
	33
	34	#if !defined(__COREFOUNDATION_CFTREE__)
	35	#define __COREFOUNDATION_CFTREE__ 1
	36
	37	#include <CoreFoundation/CFBase.h>
	38
	39	#if defined(__cplusplus)
	40	extern "C" {
	41	#endif
	42
	43	/*!
	44	@typedef CFTreeRetainCallBack
	45	Type of the callback function used to add a retain to the user-specified
	46	info parameter. This callback may returns the value to use whenever the
	47	info parameter is retained, which is usually the value parameter passed
	48	to this callback, but may be a different value if a different value
	49	should be used.
	50	@param info A user-supplied info parameter provided in a CFTreeContext.
	51	@result The retained info parameter.
	52	*/
	53	typedef const void * (CFTreeRetainCallBack)(const void info);
	54
	55	/*!
	56	@typedef CFTreeReleaseCallBack
	57	Type of the callback function used to remove a retain previously
	58	added to the user-specified info parameter.
	59	@param info A user-supplied info parameter provided in a CFTreeContext.
	60	*/
	61	typedef void (CFTreeReleaseCallBack)(const void info);
	62
	63	/*!
	64	@typedef CFTreeCopyDescriptionCallBack
65	Type of the callback function used to provide a description of the
66	user-specified info parameter.
67	@param info A user-supplied info parameter provided in a CFTreeContext.
68	@result A description of the info parameter.
69	*/
70	typedef CFStringRef (CFTreeCopyDescriptionCallBack)(const void info);
71
72	/*!
73	@typedef CFTreeContext
74	Structure containing user-specified data and callbacks for a CFTree.
75	@field version The version number of the structure type being passed
76	in as a parameter to the CFTree creation function.
77	This structure is version 0.
78	@field info A C pointer to a user-specified block of data.
79	@field retain The callback used to add a retain for the info field.
80	If this parameter is not a pointer to a function of the correct
81	prototype, the behavior is undefined. The value may be NULL.
82	@field release The calllback used to remove a retain previously added
83	for the info field. If this parameter is not a pointer to a
84	function of the correct prototype, the behavior is undefined.
85	The value may be NULL.
86	@field copyDescription The callback used to provide a description of
87	the info field.
88	*/
89	typedef struct {
90	CFIndex version;
91	void * info;
92	CFTreeRetainCallBack retain;
93	CFTreeReleaseCallBack release;
94	CFTreeCopyDescriptionCallBack copyDescription;
95	} CFTreeContext;
96
97	/*!
98	@typedef CFTreeApplierFunction
99	Type of the callback function used by the apply functions of
100	CFTree.
101	@param value The current value from the CFTree
102	@param context The user-defined context parameter give to the apply
103	function.
104	*/
105	typedef void (CFTreeApplierFunction)(const void value, void *context);
106
107	/*!
108	@typedef CFTreeRef
109	This is the type of a reference to CFTrees.
110	*/
111	typedef struct __CFTree * CFTreeRef;
112
113	/*!
114	@function CFTreeGetTypeID
115	Returns the type identifier of all CFTree instances.
116	*/
117	CF_EXPORT
118	CFTypeID CFTreeGetTypeID(void);
119
120	/*!
121	@function CFTreeCreate
122	Creates a new mutable tree.
123	@param allocator The CFAllocator which should be used to allocate
124	memory for the tree and storage for its children. This
125	parameter may be NULL in which case the current default
126	CFAllocator is used. If this reference is not a valid
127	CFAllocator, the behavior is undefined.
128	@param context A C pointer to a CFTreeContext structure to be copied
129	and used as the context of the new tree. The info parameter
130	will be retained by the tree if a retain function is provided.
131	If this value is not a valid C pointer to a CFTreeContext
132	structure-sized block of storage, the result is undefined.
133	If the version number of the storage is not a valid CFTreeContext
134	version number, the result is undefined.
135	@result A reference to the new CFTree.
136	*/
137	CF_EXPORT
138	CFTreeRef CFTreeCreate(CFAllocatorRef allocator, const CFTreeContext *context);
139
140	/*!
141	@function CFTreeGetParent
142	Returns the parent of the specified tree.
143	@param tree The tree to be queried. If this parameter is not a valid
144	CFTree, the behavior is undefined.
145	@result The parent of the tree.
146	*/
147	CF_EXPORT
148	CFTreeRef CFTreeGetParent(CFTreeRef tree);
149
150	/*!
151	@function CFTreeGetNextSibling
152	Returns the sibling after the specified tree in the parent tree's list.
153	@param tree The tree to be queried. If this parameter is not a valid
154	CFTree, the behavior is undefined.
155	@result The next sibling of the tree.
156	*/
157	CF_EXPORT
158	CFTreeRef CFTreeGetNextSibling(CFTreeRef tree);
159
160	/*!
161	@function CFTreeGetFirstChild
162	Returns the first child of the tree.
163	@param tree The tree to be queried. If this parameter is not a valid
164	CFTree, the behavior is undefined.
165	@result The first child of the tree.
166	*/
167	CF_EXPORT
168	CFTreeRef CFTreeGetFirstChild(CFTreeRef tree);
169
170	/*!
171	@function CFTreeGetContext
172	Returns the context of the specified tree.
173	@param tree The tree to be queried. If this parameter is not a valid
174	CFTree, the behavior is undefined.
175	@param context A C pointer to a CFTreeContext structure to be filled in with
176	the context of the specified tree. If this value is not a valid C
177	pointer to a CFTreeContext structure-sized block of storage, the
178	result is undefined. If the version number of the storage is not
179	a valid CFTreeContext version number, the result is undefined.
180	*/
181	CF_EXPORT
182	void CFTreeGetContext(CFTreeRef tree, CFTreeContext *context);
183
184	/*!
185	@function CFTreeGetChildCount
186	Returns the number of children of the specified tree.
187	@param tree The tree to be queried. If this parameter is not a valid
188	CFTree, the behavior is undefined.
189	@result The number of children.
190	*/
191	CF_EXPORT
192	CFIndex CFTreeGetChildCount(CFTreeRef tree);
193
194	/*!
195	@function CFTreeGetChildAtIndex
196	Returns the nth child of the specified tree.
197	@param tree The tree to be queried. If this parameter is not a valid
198	CFTree, the behavior is undefined.
199	@param idx The index of the child tree to be returned. If this parameter
200	is less than zero or greater than the number of children of the
201	tree, the result is undefined.
202	@result A reference to the specified child tree.
203	*/
204	CF_EXPORT
205	CFTreeRef CFTreeGetChildAtIndex(CFTreeRef tree, CFIndex idx);
206
207	/*!
208	@function CFTreeGetChildren
209	Fills the buffer with children from the tree.
210	@param tree The tree to be queried. If this parameter is not a valid
211	CFTree, the behavior is undefined.
212	@param children A C array of pointer-sized values to be filled with
213	children from the tree. If this parameter is not a valid pointer to a
214	C array of at least CFTreeGetChildCount() pointers, the behavior is undefined.
215	@result A reference to the specified child tree.
216	*/
217	CF_EXPORT
218	void CFTreeGetChildren(CFTreeRef tree, CFTreeRef *children);
219
220	/*!
221	@function CFTreeApplyFunctionToChildren
222	Calls a function once for each child of the tree. Note that the applier
223	only operates one level deep, and does not operate on descendents further
224	removed than the immediate children of the tree.
225	@param heap The tree to be operated upon. If this parameter is not a
226	valid CFTree, the behavior is undefined.
227	@param applier The callback function to call once for each child of
228	the given tree. If this parameter is not a pointer to a
229	function of the correct prototype, the behavior is undefined.
230	If there are values in the tree which the applier function does
231	not expect or cannot properly apply to, the behavior is undefined.
232	@param context A pointer-sized user-defined value, which is passed
233	as the second parameter to the applier function, but is
234	otherwise unused by this function. If the context is not
235	what is expected by the applier function, the behavior is
236	undefined.
237	*/
238	CF_EXPORT
239	void CFTreeApplyFunctionToChildren(CFTreeRef tree, CFTreeApplierFunction applier, void *context);
240
241	/*!
242	@function CFTreeFindRoot
243	Returns the root tree of which the specified tree is a descendent.
244	@param tree The tree to be queried. If this parameter is not a valid
245	CFTree, the behavior is undefined.
246	@result A reference to the root of the tree.
247	*/
248	CF_EXPORT
249	CFTreeRef CFTreeFindRoot(CFTreeRef tree);
250
251	/*!
252	@function CFTreeSetContext
253	Replaces the context of a tree. The tree releases its retain on the
254	info of the previous context, and retains the info of the new context.
255	@param tree The tree to be operated on. If this parameter is not a valid
256	CFTree, the behavior is undefined.
257	@param context A C pointer to a CFTreeContext structure to be copied
258	and used as the context of the new tree. The info parameter
259	will be retained by the tree if a retain function is provided.
260	If this value is not a valid C pointer to a CFTreeContext
261	structure-sized block of storage, the result is undefined.
262	If the version number of the storage is not a valid CFTreeContext
263	version number, the result is undefined.
264	*/
265	CF_EXPORT
266	void CFTreeSetContext(CFTreeRef tree, const CFTreeContext *context);
267
268	/*!
269	@function CFTreePrependChild
270	Adds the newChild to the specified tree as the first in its list of children.
271	@param tree The tree to be operated on. If this parameter is not a valid
272	CFTree, the behavior is undefined.
273	@param newChild The child to be added.
274	If this parameter is not a valid CFTree, the behavior is undefined.
275	If this parameter is a tree which is already a child of any tree,
276	the behavior is undefined.
277	*/
278	CF_EXPORT
279	void CFTreePrependChild(CFTreeRef tree, CFTreeRef newChild);
280
281	/*!
282	@function CFTreeAppendChild
283	Adds the newChild to the specified tree as the last in its list of children.
284	@param tree The tree to be operated on. If this parameter is not a valid
285	CFTree, the behavior is undefined.
286	@param newChild The child to be added.
287	If this parameter is not a valid CFTree, the behavior is undefined.
288	If this parameter is a tree which is already a child of any tree,
289	the behavior is undefined.
290	*/
291	CF_EXPORT
292	void CFTreeAppendChild(CFTreeRef tree, CFTreeRef newChild);
293
294	/*!
295	@function CFTreeInsertSibling
296	Inserts newSibling into the the parent tree's linked list of children after
297	tree. The newSibling will have the same parent as tree.
298	@param tree The tree to insert newSibling after. If this parameter is not a valid
299	CFTree, the behavior is undefined. If the tree does not have a
300	parent, the behavior is undefined.
301	@param newSibling The sibling to be added.
302	If this parameter is not a valid CFTree, the behavior is undefined.
303	If this parameter is a tree which is already a child of any tree,
304	the behavior is undefined.
305	*/
306	CF_EXPORT
307	void CFTreeInsertSibling(CFTreeRef tree, CFTreeRef newSibling);
308
309	/*!
310	@function CFTreeRemove
311	Removes the tree from its parent.
312	@param tree The tree to be removed. If this parameter is not a valid
313	CFTree, the behavior is undefined.
314	*/
315	CF_EXPORT
316	void CFTreeRemove(CFTreeRef tree);
317
318	/*!
319	@function CFTreeRemoveAllChildren
320	Removes all the children of the tree.
321	@param tree The tree to remove all children from. If this parameter is not a valid
322	CFTree, the behavior is undefined.
323	*/
324	CF_EXPORT
325	void CFTreeRemoveAllChildren(CFTreeRef tree);
326
327	/*!
328	@function CFTreeSortChildren
329	Sorts the children of the specified tree using the specified comparator function.
330	@param tree The tree to be operated on. If this parameter is not a valid
331	CFTree, the behavior is undefined.
332	@param comparator The function with the comparator function type
333	signature which is used in the sort operation to compare
334	children of the tree with the given value. If this parameter
335	is not a pointer to a function of the correct prototype, the
336	the behavior is undefined. The children of the tree are sorted
337	from least to greatest according to this function.
338	@param context A pointer-sized user-defined value, which is passed
339	as the third parameter to the comparator function, but is
340	otherwise unused by this function. If the context is not
341	what is expected by the comparator function, the behavior is
342	undefined.
343	*/
344	CF_EXPORT
345	void CFTreeSortChildren(CFTreeRef tree, CFComparatorFunction comparator, void *context);
346
347	#if defined(__cplusplus)
348	}
349	#endif
350
351	#endif /* ! __COREFOUNDATION_CFTREE__ */
352