[apple/cf.git] / CFBinaryHeap.h

/*
 * Copyright (c) 2011 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * 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@
 */

/*	CFBinaryHeap.h
	Copyright (c) 1998-2011, Apple Inc. All rights reserved.
*/
/*!
        @header CFBinaryHeap
        CFBinaryHeap implements a container which stores values sorted using
        a binary search algorithm.  CFBinaryHeaps can be useful as priority
	queues.
*/

#if !defined(__COREFOUNDATION_CFBINARYHEAP__)
#define __COREFOUNDATION_CFBINARYHEAP__ 1

#include <CoreFoundation/CFBase.h>

CF_EXTERN_C_BEGIN

typedef struct {
    CFIndex	version;
    void *	info;
    const void *(*retain)(const void *info);
    void	(*release)(const void *info);
    CFStringRef	(*copyDescription)(const void *info);
} CFBinaryHeapCompareContext;

/*!
        @typedef CFBinaryHeapCallBacks
	Structure containing the callbacks for values of a CFBinaryHeap.
        @field version The version number of the structure type being passed
                in as a parameter to the CFBinaryHeap creation functions.
                This structure is version 0.
	@field retain The callback used to add a retain for the binary heap
		on values as they are put into the binary heap.
		This callback returns the value to use as the value in the
		binary heap, which is usually the value parameter passed to
		this callback, but may be a different value if a different
		value should be added to the binary heap. The binary heap's
		allocator is passed as the first argument.
	@field release The callback used to remove a retain previously added
		for the binary heap from values as they are removed from
		the binary heap. The binary heap's allocator is passed as the
		first argument.
	@field copyDescription The callback used to create a descriptive
		string representation of each value in the binary heap. This
		is used by the CFCopyDescription() function.
	@field compare The callback used to compare values in the binary heap for
		equality in some operations.
*/
typedef struct {
    CFIndex	version;
    const void *(*retain)(CFAllocatorRef allocator, const void *ptr);
    void	(*release)(CFAllocatorRef allocator, const void *ptr);
    CFStringRef	(*copyDescription)(const void *ptr);
    CFComparisonResult	(*compare)(const void *ptr1, const void *ptr2, void *context);
} CFBinaryHeapCallBacks;

/*!
	@constant kCFStringBinaryHeapCallBacks
	Predefined CFBinaryHeapCallBacks structure containing a set
	of callbacks appropriate for use when the values in a CFBinaryHeap
	are all CFString types.
*/
CF_EXPORT const CFBinaryHeapCallBacks kCFStringBinaryHeapCallBacks;

/*!
	@typedef CFBinaryHeapApplierFunction
	Type of the callback function used by the apply functions of
		CFBinaryHeap.
	@param value The current value from the binary heap.
	@param context The user-defined context parameter given to the apply
		function.
*/
typedef void (*CFBinaryHeapApplierFunction)(const void *val, void *context);

/*!
	@typedef CFBinaryHeapRef
	This is the type of a reference to CFBinaryHeaps.
*/
typedef struct __CFBinaryHeap * CFBinaryHeapRef;

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

/*!
	@function CFBinaryHeapCreate
	Creates a new mutable binary heap with the given values.
	@param allocator The CFAllocator which should be used to allocate
		memory for the binary heap and its storage for values. 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 capacity A hint about the number of values that will be held
                by the CFBinaryHeap. Pass 0 for no hint. The implementation may
                ignore this hint, or may use it to optimize various
                operations. A heap's actual capacity is only limited by 
                address space and available memory constraints). If this 
                parameter is negative, the behavior is undefined.
	@param callBacks A pointer to a CFBinaryHeapCallBacks structure
		initialized with the callbacks for the binary heap to use on
		each value in the binary heap. 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
		binary heap creations. If the version field of this callbacks
		structure is not one of the defined ones for CFBinaryHeap, the
		behavior is undefined. The retain field may be NULL, in which
		case the CFBinaryHeap will do nothing to add a retain to values
		as they are put into the binary heap. The release field may be
		NULL, in which case the CFBinaryHeap will do nothing to remove
		the binary heap's retain (if any) on the values when the
		heap is destroyed or a key-value pair is removed. If the
		copyDescription field is NULL, the binary heap will create a
		simple description for a value. If the equal field is NULL, the
		binary heap will use pointer equality to test for equality of
		values. This callbacks parameter itself 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 CFBinaryHeapCallBacks callbacks structure,
		the behavior is undefined. If any of the values put into the
		binary heap is not one understood by one of the callback functions
		the behavior when that callback function is used is undefined.
        @param compareContext A pointer to a CFBinaryHeapCompareContext structure.
	@result A reference to the new CFBinaryHeap.
*/
CF_EXPORT CFBinaryHeapRef	CFBinaryHeapCreate(CFAllocatorRef allocator, CFIndex capacity, const CFBinaryHeapCallBacks *callBacks, const CFBinaryHeapCompareContext *compareContext);

/*!
	@function CFBinaryHeapCreateCopy
	Creates a new mutable binary heap with the values from the given binary heap.
	@param allocator The CFAllocator which should be used to allocate
		memory for the binary heap and its storage for values. 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 capacity A hint about the number of values that will be held
                by the CFBinaryHeap. Pass 0 for no hint. The implementation may
                ignore this hint, or may use it to optimize various
                operations. A heap's actual capacity is only limited by
                address space and available memory constraints). 
                This parameter must be greater than or equal
                to the count of the heap which is to be copied, or the
                behavior is undefined. If this parameter is negative, the
                behavior is undefined.
	@param heap The binary heap which is to be copied. The values from the
		binary heap are copied as pointers into the new binary heap (that is,
		the values themselves are copied, not that which the values
		point to, if anything). However, the values are also
		retained by the new binary heap. The count of the new binary will
		be the same as the given binary heap. The new binary heap uses the same
		callbacks as the binary heap to be copied. If this parameter is
		not a valid CFBinaryHeap, the behavior is undefined.
	@result A reference to the new mutable binary heap.
*/
CF_EXPORT CFBinaryHeapRef	CFBinaryHeapCreateCopy(CFAllocatorRef allocator, CFIndex capacity, CFBinaryHeapRef heap);

/*!
	@function CFBinaryHeapGetCount
	Returns the number of values currently in the binary heap.
	@param heap The binary heap to be queried. If this parameter is not a valid
		CFBinaryHeap, the behavior is undefined.
	@result The number of values in the binary heap.
*/
CF_EXPORT CFIndex	CFBinaryHeapGetCount(CFBinaryHeapRef heap);

/*!
	@function CFBinaryHeapGetCountOfValue
	Counts the number of times the given value occurs in the binary heap.
	@param heap The binary heap to be searched. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
	@param value The value for which to find matches in the binary heap. The
		compare() callback provided when the binary heap was created is
		used to compare. If the compare() callback was NULL, pointer
		equality (in C, ==) is used. If value, or any of the values
		in the binary heap, are not understood by the compare() callback,
		the behavior is undefined.
	@result The number of times the given value occurs in the binary heap.
*/
CF_EXPORT CFIndex	CFBinaryHeapGetCountOfValue(CFBinaryHeapRef heap, const void *value);

/*!
	@function CFBinaryHeapContainsValue
	Reports whether or not the value is in the binary heap.
	@param heap The binary heap to be searched. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
	@param value The value for which to find matches in the binary heap. The
		compare() callback provided when the binary heap was created is
		used to compare. If the compare() callback was NULL, pointer
		equality (in C, ==) is used. If value, or any of the values
		in the binary heap, are not understood by the compare() callback,
		the behavior is undefined.
	@result true, if the value is in the specified binary heap, otherwise false.
*/
CF_EXPORT Boolean	CFBinaryHeapContainsValue(CFBinaryHeapRef heap, const void *value);

/*!
	@function CFBinaryHeapGetMinimum
	Returns the minimum value is in the binary heap.  If the heap contains several equal
                minimum values, any one may be returned.
	@param heap The binary heap to be searched. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
	@result A reference to the minimum value in the binary heap, or NULL if the
                binary heap contains no values.
*/
CF_EXPORT const void *	CFBinaryHeapGetMinimum(CFBinaryHeapRef heap);

/*!
	@function CFBinaryHeapGetMinimumIfPresent
	Returns the minimum value is in the binary heap, if present.  If the heap contains several equal
                minimum values, any one may be returned.
	@param heap The binary heap to be searched. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
        @param value A C pointer to pointer-sized storage to be filled with the minimum value in 
                the binary heap.  If this value is not a valid C pointer to a pointer-sized block
                of storage, the result is undefined.  If the result of the function is false, the value
                stored at this address is undefined.
	@result true, if a minimum value was found in the specified binary heap, otherwise false.
*/
CF_EXPORT Boolean	CFBinaryHeapGetMinimumIfPresent(CFBinaryHeapRef heap, const void **value);

/*!
	@function CFBinaryHeapGetValues
	Fills the buffer with values from the binary heap.
	@param heap The binary heap to be queried. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
	@param values A C array of pointer-sized values to be filled with
		values from the binary heap. The values in the C array are ordered
		from least to greatest. If this parameter is not a valid pointer to a 
                C array of at least CFBinaryHeapGetCount() pointers, the behavior is undefined.
*/
CF_EXPORT void		CFBinaryHeapGetValues(CFBinaryHeapRef heap, const void **values);

/*!
	@function CFBinaryHeapApplyFunction
	Calls a function once for each value in the binary heap.
	@param heap The binary heap to be operated upon. If this parameter is not a
		valid CFBinaryHeap, the behavior is undefined.
	@param applier The callback function to call once for each value in
		the given binary heap. If this parameter is not a
		pointer to a function of the correct prototype, the behavior
		is undefined. If there are values in the binary heap 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		CFBinaryHeapApplyFunction(CFBinaryHeapRef heap, CFBinaryHeapApplierFunction applier, void *context);

/*!
	@function CFBinaryHeapAddValue
	Adds the value to the binary heap.
	@param heap The binary heap to which the value is to be added. If this parameter is not a
		valid mutable CFBinaryHeap, the behavior is undefined.
	@param value The value to add to the binary heap. The value is retained by
		the binary heap using the retain callback provided when the binary heap
		was created. If the value is not of the sort expected by the
		retain callback, the behavior is undefined.
*/
CF_EXPORT void		CFBinaryHeapAddValue(CFBinaryHeapRef heap, const void *value);

/*!
	@function CFBinaryHeapRemoveMinimumValue
	Removes the minimum value from the binary heap.
	@param heap The binary heap from which the minimum value is to be removed. If this 
                parameter is not a valid mutable CFBinaryHeap, the behavior is undefined.
*/
CF_EXPORT void		CFBinaryHeapRemoveMinimumValue(CFBinaryHeapRef heap);

/*!
	@function CFBinaryHeapRemoveAllValues
	Removes all the values from the binary heap, making it empty.
	@param heap The binary heap from which all of the values are to be
		removed. If this parameter is not a valid mutable CFBinaryHeap,
		the behavior is undefined.
*/
CF_EXPORT void		CFBinaryHeapRemoveAllValues(CFBinaryHeapRef heap);

CF_EXTERN_C_END

#endif /* ! __COREFOUNDATION_CFBINARYHEAP__ */
Commit	Line	Data
9ce05555	1	/*
8ca704e1	2	* Copyright (c) 2011 Apple Inc. All rights reserved.
9ce05555 A	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
9ce05555 A	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
f64f9b69	23
9ce05555	24	/* CFBinaryHeap.h
8ca704e1	25	Copyright (c) 1998-2011, Apple Inc. All rights reserved.
9ce05555 A	26	*/
	27	/*!
	28	@header CFBinaryHeap
	29	CFBinaryHeap implements a container which stores values sorted using
	30	a binary search algorithm. CFBinaryHeaps can be useful as priority
	31	queues.
	32	*/
	33
	34	#if !defined(__COREFOUNDATION_CFBINARYHEAP__)
	35	#define __COREFOUNDATION_CFBINARYHEAP__ 1
	36
	37	#include <CoreFoundation/CFBase.h>
	38
bd5b749c	39	CF_EXTERN_C_BEGIN
9ce05555 A	40
	41	typedef struct {
	42	CFIndex version;
	43	void * info;
	44	const void (retain)(const void *info);
	45	void (release)(const void info);
	46	CFStringRef (copyDescription)(const void info);
	47	} CFBinaryHeapCompareContext;
	48
	49	/*!
	50	@typedef CFBinaryHeapCallBacks
	51	Structure containing the callbacks for values of a CFBinaryHeap.
	52	@field version The version number of the structure type being passed
	53	in as a parameter to the CFBinaryHeap creation functions.
	54	This structure is version 0.
	55	@field retain The callback used to add a retain for the binary heap
	56	on values as they are put into the binary heap.
	57	This callback returns the value to use as the value in the
	58	binary heap, which is usually the value parameter passed to
	59	this callback, but may be a different value if a different
	60	value should be added to the binary heap. The binary heap's
	61	allocator is passed as the first argument.
	62	@field release The callback used to remove a retain previously added
	63	for the binary heap from values as they are removed from
	64	the binary heap. The binary heap's allocator is passed as the
	65	first argument.
	66	@field copyDescription The callback used to create a descriptive
	67	string representation of each value in the binary heap. This
	68	is used by the CFCopyDescription() function.
	69	@field compare The callback used to compare values in the binary heap for
	70	equality in some operations.
	71	*/
	72	typedef struct {
	73	CFIndex version;
	74	const void (retain)(CFAllocatorRef allocator, const void *ptr);
	75	void (release)(CFAllocatorRef allocator, const void ptr);
	76	CFStringRef (copyDescription)(const void ptr);
	77	CFComparisonResult (compare)(const void ptr1, const void ptr2, void context);
	78	} CFBinaryHeapCallBacks;
	79
	80	/*!
	81	@constant kCFStringBinaryHeapCallBacks
	82	Predefined CFBinaryHeapCallBacks structure containing a set
	83	of callbacks appropriate for use when the values in a CFBinaryHeap
	84	are all CFString types.
	85	*/
	86	CF_EXPORT const CFBinaryHeapCallBacks kCFStringBinaryHeapCallBacks;
	87
	88	/*!
	89	@typedef CFBinaryHeapApplierFunction
	90	Type of the callback function used by the apply functions of
	91	CFBinaryHeap.
	92	@param value The current value from the binary heap.
	93	@param context The user-defined context parameter given to the apply
	94	function.
	95	*/
	96	typedef void (CFBinaryHeapApplierFunction)(const void val, void *context);
	97
	98	/*!
	99	@typedef CFBinaryHeapRef
	100	This is the type of a reference to CFBinaryHeaps.
	101	*/
	102	typedef struct __CFBinaryHeap * CFBinaryHeapRef;
	103
104	/*!
105	@function CFBinaryHeapGetTypeID
106	Returns the type identifier of all CFBinaryHeap instances.
107	*/
108	CF_EXPORT CFTypeID CFBinaryHeapGetTypeID(void);
109
110	/*!
111	@function CFBinaryHeapCreate
bd5b749c	112	Creates a new mutable binary heap with the given values.
9ce05555 A	113	@param allocator The CFAllocator which should be used to allocate
	114	memory for the binary heap and its storage for values. This
	115	parameter may be NULL in which case the current default
	116	CFAllocator is used. If this reference is not a valid
	117	CFAllocator, the behavior is undefined.
bd5b749c A	118	@param capacity A hint about the number of values that will be held
	119	by the CFBinaryHeap. Pass 0 for no hint. The implementation may
	120	ignore this hint, or may use it to optimize various
	121	operations. A heap's actual capacity is only limited by
	122	address space and available memory constraints). If this
	123	parameter is negative, the behavior is undefined.
9ce05555 A	124	@param callBacks A pointer to a CFBinaryHeapCallBacks structure
	125	initialized with the callbacks for the binary heap to use on
	126	each value in the binary heap. A copy of the contents of the
	127	callbacks structure is made, so that a pointer to a structure
	128	on the stack can be passed in, or can be reused for multiple
	129	binary heap creations. If the version field of this callbacks
	130	structure is not one of the defined ones for CFBinaryHeap, the
	131	behavior is undefined. The retain field may be NULL, in which
	132	case the CFBinaryHeap will do nothing to add a retain to values
	133	as they are put into the binary heap. The release field may be
	134	NULL, in which case the CFBinaryHeap will do nothing to remove
	135	the binary heap's retain (if any) on the values when the
	136	heap is destroyed or a key-value pair is removed. If the
	137	copyDescription field is NULL, the binary heap will create a
	138	simple description for a value. If the equal field is NULL, the
	139	binary heap will use pointer equality to test for equality of
	140	values. This callbacks parameter itself may be NULL, which is
	141	treated as if a valid structure of version 0 with all fields
	142	NULL had been passed in. Otherwise,
	143	if any of the fields are not valid pointers to functions
	144	of the correct type, or this parameter is not a valid
	145	pointer to a CFBinaryHeapCallBacks callbacks structure,
	146	the behavior is undefined. If any of the values put into the
	147	binary heap is not one understood by one of the callback functions
	148	the behavior when that callback function is used is undefined.
	149	@param compareContext A pointer to a CFBinaryHeapCompareContext structure.
	150	@result A reference to the new CFBinaryHeap.
	151	*/
	152	CF_EXPORT CFBinaryHeapRef CFBinaryHeapCreate(CFAllocatorRef allocator, CFIndex capacity, const CFBinaryHeapCallBacks callBacks, const CFBinaryHeapCompareContext compareContext);
	153
	154	/*!
	155	@function CFBinaryHeapCreateCopy
bd5b749c	156	Creates a new mutable binary heap with the values from the given binary heap.
9ce05555 A	157	@param allocator The CFAllocator which should be used to allocate
	158	memory for the binary heap and its storage for values. This
	159	parameter may be NULL in which case the current default
	160	CFAllocator is used. If this reference is not a valid
	161	CFAllocator, the behavior is undefined.
bd5b749c A	162	@param capacity A hint about the number of values that will be held
	163	by the CFBinaryHeap. Pass 0 for no hint. The implementation may
	164	ignore this hint, or may use it to optimize various
	165	operations. A heap's actual capacity is only limited by
	166	address space and available memory constraints).
	167	This parameter must be greater than or equal
	168	to the count of the heap which is to be copied, or the
	169	behavior is undefined. If this parameter is negative, the
	170	behavior is undefined.
9ce05555 A	171	@param heap The binary heap which is to be copied. The values from the
	172	binary heap are copied as pointers into the new binary heap (that is,
	173	the values themselves are copied, not that which the values
	174	point to, if anything). However, the values are also
	175	retained by the new binary heap. The count of the new binary will
	176	be the same as the given binary heap. The new binary heap uses the same
	177	callbacks as the binary heap to be copied. If this parameter is
	178	not a valid CFBinaryHeap, the behavior is undefined.
bd5b749c	179	@result A reference to the new mutable binary heap.
9ce05555 A	180	*/
	181	CF_EXPORT CFBinaryHeapRef CFBinaryHeapCreateCopy(CFAllocatorRef allocator, CFIndex capacity, CFBinaryHeapRef heap);
	182
	183	/*!
	184	@function CFBinaryHeapGetCount
	185	Returns the number of values currently in the binary heap.
	186	@param heap The binary heap to be queried. If this parameter is not a valid
	187	CFBinaryHeap, the behavior is undefined.
	188	@result The number of values in the binary heap.
	189	*/
	190	CF_EXPORT CFIndex CFBinaryHeapGetCount(CFBinaryHeapRef heap);
	191
	192	/*!
	193	@function CFBinaryHeapGetCountOfValue
	194	Counts the number of times the given value occurs in the binary heap.
	195	@param heap The binary heap to be searched. If this parameter is not a
	196	valid CFBinaryHeap, the behavior is undefined.
	197	@param value The value for which to find matches in the binary heap. The
	198	compare() callback provided when the binary heap was created is
	199	used to compare. If the compare() callback was NULL, pointer
	200	equality (in C, ==) is used. If value, or any of the values
	201	in the binary heap, are not understood by the compare() callback,
	202	the behavior is undefined.
	203	@result The number of times the given value occurs in the binary heap.
	204	*/
	205	CF_EXPORT CFIndex CFBinaryHeapGetCountOfValue(CFBinaryHeapRef heap, const void *value);
	206
	207	/*!
	208	@function CFBinaryHeapContainsValue
	209	Reports whether or not the value is in the binary heap.
	210	@param heap The binary heap to be searched. If this parameter is not a
	211	valid CFBinaryHeap, the behavior is undefined.
	212	@param value The value for which to find matches in the binary heap. The
	213	compare() callback provided when the binary heap was created is
	214	used to compare. If the compare() callback was NULL, pointer
	215	equality (in C, ==) is used. If value, or any of the values
	216	in the binary heap, are not understood by the compare() callback,
	217	the behavior is undefined.
	218	@result true, if the value is in the specified binary heap, otherwise false.
	219	*/
	220	CF_EXPORT Boolean CFBinaryHeapContainsValue(CFBinaryHeapRef heap, const void *value);
	221
	222	/*!
	223	@function CFBinaryHeapGetMinimum
	224	Returns the minimum value is in the binary heap. If the heap contains several equal
	225	minimum values, any one may be returned.
	226	@param heap The binary heap to be searched. If this parameter is not a
	227	valid CFBinaryHeap, the behavior is undefined.
	228	@result A reference to the minimum value in the binary heap, or NULL if the
	229	binary heap contains no values.
	230	*/
	231	CF_EXPORT const void * CFBinaryHeapGetMinimum(CFBinaryHeapRef heap);
	232
	233	/*!
	234	@function CFBinaryHeapGetMinimumIfPresent
	235	Returns the minimum value is in the binary heap, if present. If the heap contains several equal
	236	minimum values, any one may be returned.
	237	@param heap The binary heap to be searched. If this parameter is not a
	238	valid CFBinaryHeap, the behavior is undefined.
	239	@param value A C pointer to pointer-sized storage to be filled with the minimum value in
	240	the binary heap. If this value is not a valid C pointer to a pointer-sized block
	241	of storage, the result is undefined. If the result of the function is false, the value
	242	stored at this address is undefined.
	243	@result true, if a minimum value was found in the specified binary heap, otherwise false.
244	*/
245	CF_EXPORT Boolean CFBinaryHeapGetMinimumIfPresent(CFBinaryHeapRef heap, const void **value);
246
247	/*!
248	@function CFBinaryHeapGetValues
249	Fills the buffer with values from the binary heap.
250	@param heap The binary heap to be queried. If this parameter is not a
251	valid CFBinaryHeap, the behavior is undefined.
252	@param values A C array of pointer-sized values to be filled with
253	values from the binary heap. The values in the C array are ordered
254	from least to greatest. If this parameter is not a valid pointer to a
255	C array of at least CFBinaryHeapGetCount() pointers, the behavior is undefined.
256	*/
257	CF_EXPORT void CFBinaryHeapGetValues(CFBinaryHeapRef heap, const void **values);
258
259	/*!
260	@function CFBinaryHeapApplyFunction
261	Calls a function once for each value in the binary heap.
262	@param heap The binary heap to be operated upon. If this parameter is not a
263	valid CFBinaryHeap, the behavior is undefined.
264	@param applier The callback function to call once for each value in
265	the given binary heap. If this parameter is not a
266	pointer to a function of the correct prototype, the behavior
267	is undefined. If there are values in the binary heap which the
268	applier function does not expect or cannot properly apply
269	to, the behavior is undefined.
270	@param context A pointer-sized user-defined value, which is passed
271	as the second parameter to the applier function, but is
272	otherwise unused by this function. If the context is not
273	what is expected by the applier function, the behavior is
274	undefined.
275	*/
276	CF_EXPORT void CFBinaryHeapApplyFunction(CFBinaryHeapRef heap, CFBinaryHeapApplierFunction applier, void *context);
277
278	/*!
279	@function CFBinaryHeapAddValue
280	Adds the value to the binary heap.
281	@param heap The binary heap to which the value is to be added. If this parameter is not a
282	valid mutable CFBinaryHeap, the behavior is undefined.
9ce05555 A	283	@param value The value to add to the binary heap. The value is retained by
	284	the binary heap using the retain callback provided when the binary heap
	285	was created. If the value is not of the sort expected by the
	286	retain callback, the behavior is undefined.
	287	*/
	288	CF_EXPORT void CFBinaryHeapAddValue(CFBinaryHeapRef heap, const void *value);
	289
	290	/*!
	291	@function CFBinaryHeapRemoveMinimumValue
	292	Removes the minimum value from the binary heap.
	293	@param heap The binary heap from which the minimum value is to be removed. If this
	294	parameter is not a valid mutable CFBinaryHeap, the behavior is undefined.
	295	*/
	296	CF_EXPORT void CFBinaryHeapRemoveMinimumValue(CFBinaryHeapRef heap);
	297
	298	/*!
	299	@function CFBinaryHeapRemoveAllValues
	300	Removes all the values from the binary heap, making it empty.
	301	@param heap The binary heap from which all of the values are to be
	302	removed. If this parameter is not a valid mutable CFBinaryHeap,
	303	the behavior is undefined.
	304	*/
	305	CF_EXPORT void CFBinaryHeapRemoveAllValues(CFBinaryHeapRef heap);
	306
bd5b749c	307	CF_EXTERN_C_END
9ce05555 A	308
	309	#endif /* ! __COREFOUNDATION_CFBINARYHEAP__ */
	310