Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
704 lines (665 sloc) 32.1 KB
/*
* Copyright (c) 2008-2009 Brent Fulgham <bfulgham@gmail.org>. All rights reserved.
*
* This source code is a modified version of the CoreFoundation sources released by Apple Inc. under
* the terms of the APSL version 2.0 (see below).
*
* For information about changes from the original Apple source release can be found by reviewing the
* source control system for the project at https://sourceforge.net/svn/?group_id=246198.
*
* The original license information is as follows:
*
* Copyright (c) 2008 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@
*/
/* CFArray.h
Copyright (c) 1998-2007, Apple Inc. All rights reserved.
*/
/*!
@header CFArray
CFArray implements an ordered, compact container of pointer-sized
values. Values are accessed via integer keys (indices), from the
range 0 to N-1, where N is the number of values in the array when
an operation is performed. The array is said to be "compact" because
deleted or inserted values do not leave a gap in the key space --
the values with higher-numbered indices have their indices
renumbered lower (or higher, in the case of insertion) so that the
set of valid indices is always in the integer range [0, N-1]. Thus,
the index to access a particular value in the array may change over
time as other values are inserted into or deleted from the array.
Arrays come in two flavors, immutable, which cannot have values
added to them or removed from them after the array is created, and
mutable, to which you can add values or from which remove values.
Mutable arrays can have an unlimited number of values (or rather,
limited only by constraints external to CFArray, like the amount
of available memory).
As with all CoreFoundation collection types, arrays maintain hard
references on the values you put in them, but the retaining and
releasing functions are user-defined callbacks that can actually do
whatever the user wants (for example, nothing).
Computational Complexity
The access time for a value in the array is guaranteed to be at
worst O(lg N) for any implementation, current and future, but will
often be O(1) (constant time). Linear search operations similarly
have a worst case complexity of O(N*lg N), though typically the
bounds will be tighter, and so on. Insertion or deletion operations
will typically be linear in the number of values in the array, but
may be O(N*lg N) clearly in the worst case in some implementations.
There are no favored positions within the array for performance;
that is, it is not necessarily faster to access values with low
indices, or to insert or delete values with high indices, or
whatever.
*/
#if !defined(__COREFOUNDATION_CFARRAY__)
#define __COREFOUNDATION_CFARRAY__ 1
#include <CoreFoundation/CFBase.h>
CF_EXTERN_C_BEGIN
/*!
@typedef CFArrayCallBacks
Structure containing the callbacks of a CFArray.
@field version The version number of the structure type being passed
in as a parameter to the CFArray creation functions. This
structure is version 0.
@field retain The callback used to add a retain for the array on
values as they are put into the array. This callback returns
the value to store in the array, 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 array.
The array's allocator is passed as the first argument.
@field release The callback used to remove a retain previously added
for the array from values as they are removed from the
array. The array's allocator is passed as the first
argument.
@field copyDescription The callback used to create a descriptive
string representation of each value in the array. This is
used by the CFCopyDescription() function.
@field equal The callback used to compare values in the array for
equality for some operations.
*/
typedef const void * (*CFArrayRetainCallBack)(CFAllocatorRef allocator, const void *value);
typedef void (*CFArrayReleaseCallBack)(CFAllocatorRef allocator, const void *value);
typedef CFStringRef (*CFArrayCopyDescriptionCallBack)(const void *value);
typedef Boolean (*CFArrayEqualCallBack)(const void *value1, const void *value2);
typedef struct {
CFIndex version;
CFArrayRetainCallBack retain;
CFArrayReleaseCallBack release;
CFArrayCopyDescriptionCallBack copyDescription;
CFArrayEqualCallBack equal;
} CFArrayCallBacks;
/*!
@constant kCFTypeArrayCallBacks
Predefined CFArrayCallBacks structure containing a set of callbacks
appropriate for use when the values in a CFArray are all CFTypes.
*/
CF_EXPORT
const CFArrayCallBacks kCFTypeArrayCallBacks;
/*!
@typedef CFArrayApplierFunction
Type of the callback function used by the apply functions of
CFArrays.
@param value The current value from the array.
@param context The user-defined context parameter given to the apply
function.
*/
typedef void (*CFArrayApplierFunction)(const void *value, void *context);
/*!
@typedef CFArrayRef
This is the type of a reference to immutable CFArrays.
*/
typedef const struct __CFArray * CFArrayRef;
/*!
@typedef CFMutableArrayRef
This is the type of a reference to mutable CFArrays.
*/
typedef struct __CFArray * CFMutableArrayRef;
/*!
@function CFArrayGetTypeID
Returns the type identifier of all CFArray instances.
*/
CF_EXPORT
CFTypeID CFArrayGetTypeID(void);
/*!
@function CFArrayCreate
Creates a new immutable array with the given values.
@param allocator The CFAllocator which should be used to allocate
memory for the array 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 values A C array of the pointer-sized values to be in the
array. The values in the array are ordered in the same order
in which they appear in this C array. This parameter may be
NULL if the numValues parameter is 0. This C array is not
changed or freed by this function. If this parameter is not
a valid pointer to a C array of at least numValues pointers,
the behavior is undefined.
@param numValues The number of values to copy from the values C
array into the CFArray. This number will be the count of the
array.
If this parameter is negative, or greater than the number of
values actually in the value's C array, the behavior is
undefined.
@param callBacks A pointer to a CFArrayCallBacks structure
initialized with the callbacks for the array to use on each
value in the array. The retain callback will be used within
this function, for example, to retain all of the new values
from the values C array. 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 array creations. If the version field of this
callbacks structure is not one of the defined ones for
CFArray, the behavior is undefined. The retain field may be
NULL, in which case the CFArray will do nothing to add a
retain to the contained values for the array. The release
field may be NULL, in which case the CFArray will do nothing
to remove the array's retain (if any) on the values when the
array is destroyed. If the copyDescription field is NULL,
the array will create a simple description for the value. If
the equal field is NULL, the array 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 CFArrayCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
array is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new immutable CFArray.
*/
CF_EXPORT
CFArrayRef CFArrayCreate(CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFArrayCallBacks *callBacks);
/*!
@function CFArrayCreateCopy
Creates a new immutable array with the values from the given array.
@param allocator The CFAllocator which should be used to allocate
memory for the array 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 theArray The array which is to be copied. The values from the
array are copied as pointers into the new array (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 array. The count of the new array will
be the same as the given array. The new array uses the same
callbacks as the array to be copied. If this parameter is
not a valid CFArray, the behavior is undefined.
@result A reference to the new immutable CFArray.
*/
CF_EXPORT
CFArrayRef CFArrayCreateCopy(CFAllocatorRef allocator, CFArrayRef theArray);
/*!
@function CFArrayCreateMutable
Creates a new empty mutable array.
@param allocator The CFAllocator which should be used to allocate
memory for the array 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 CFArray. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. An array'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 CFArrayCallBacks structure
initialized with the callbacks for the array to use on each
value in the array. 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 array creations. If the version field of this
callbacks structure is not one of the defined ones for
CFArray, the behavior is undefined. The retain field may be
NULL, in which case the CFArray will do nothing to add a
retain to the contained values for the array. The release
field may be NULL, in which case the CFArray will do nothing
to remove the array's retain (if any) on the values when the
array is destroyed. If the copyDescription field is NULL,
the array will create a simple description for the value. If
the equal field is NULL, the array 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 CFArrayCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
array is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new mutable CFArray.
*/
CF_EXPORT
CFMutableArrayRef CFArrayCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFArrayCallBacks *callBacks);
/*!
@function CFArrayCreateMutableCopy
Creates a new mutable array with the values from the given array.
@param allocator The CFAllocator which should be used to allocate
memory for the array 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 CFArray. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. An array'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 array which is to be copied, or the
behavior is undefined. If this parameter is negative, the
behavior is undefined.
@param theArray The array which is to be copied. The values from the
array are copied as pointers into the new array (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 array. The count of the new array will
be the same as the given array. The new array uses the same
callbacks as the array to be copied. If this parameter is
not a valid CFArray, the behavior is undefined.
@result A reference to the new mutable CFArray.
*/
CF_EXPORT
CFMutableArrayRef CFArrayCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFArrayRef theArray);
/*!
@function CFArrayGetCount
Returns the number of values currently in the array.
@param theArray The array to be queried. If this parameter is not a valid
CFArray, the behavior is undefined.
@result The number of values in the array.
*/
CF_EXPORT
CFIndex CFArrayGetCount(CFArrayRef theArray);
/*!
@function CFArrayGetCountOfValue
Counts the number of times the given value occurs in the array.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find matches in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The number of times the given value occurs in the array,
within the specified range.
*/
CF_EXPORT
CFIndex CFArrayGetCountOfValue(CFArrayRef theArray, CFRange range, const void *value);
/*!
@function CFArrayContainsValue
Reports whether or not the value is in the array.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find matches in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result true, if the value is in the specified range of the array,
otherwise false.
*/
CF_EXPORT
Boolean CFArrayContainsValue(CFArrayRef theArray, CFRange range, const void *value);
/*!
@function CFArrayGetValueAtIndex
Retrieves the value at the given index.
@param theArray The array to be queried. If this parameter is not a
valid CFArray, the behavior is undefined.
@param idx The index of the value to retrieve. If the index is
outside the index space of the array (0 to N-1 inclusive,
where N is the count of the array), the behavior is
undefined.
@result The value with the given index in the array.
*/
CF_EXPORT
const void *CFArrayGetValueAtIndex(CFArrayRef theArray, CFIndex idx);
/*!
@function CFArrayGetValues
Fills the buffer with values from the array.
@param theArray The array to be queried. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range of values within the array to retrieve. If
the range location or end point (defined by the location
plus length minus 1) is outside the index space of the
array (0 to N-1 inclusive, where N is the count of the
array), the behavior is undefined. If the range length is
negative, the behavior is undefined. The range may be empty
(length 0), in which case no values are put into the buffer.
@param values A C array of pointer-sized values to be filled with
values from the array. The values in the C array are ordered
in the same order in which they appear in the array. If this
parameter is not a valid pointer to a C array of at least
range.length pointers, the behavior is undefined.
*/
CF_EXPORT
void CFArrayGetValues(CFArrayRef theArray, CFRange range, const void **values);
/*!
@function CFArrayApplyFunction
Calls a function once for each value in the array.
@param theArray The array to be operated upon. If this parameter is not
a valid CFArray, the behavior is undefined.
@param range The range of values within the array to which to apply
the function. If the range location or end point (defined by
the location plus length minus 1) is outside the index
space of the array (0 to N-1 inclusive, where N is the count
of the array), the behavior is undefined. If the range
length is negative, the behavior is undefined. The range may
be empty (length 0).
@param applier The callback function to call once for each value in
the given range in the array. 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 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 CFArrayApplyFunction(CFArrayRef theArray, CFRange range, CFArrayApplierFunction applier, void *context);
/*!
@function CFArrayGetFirstIndexOfValue
Searches the array for the value.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
The search progresses from the smallest index defined by
the range to the largest.
@param value The value for which to find a match in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The lowest index of the matching values in the range, or
kCFNotFound if no value in the range matched.
*/
CF_EXPORT
CFIndex CFArrayGetFirstIndexOfValue(CFArrayRef theArray, CFRange range, const void *value);
/*!
@function CFArrayGetLastIndexOfValue
Searches the array for the value.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
The search progresses from the largest index defined by the
range to the smallest.
@param value The value for which to find a match in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The highest index of the matching values in the range, or
kCFNotFound if no value in the range matched.
*/
CF_EXPORT
CFIndex CFArrayGetLastIndexOfValue(CFArrayRef theArray, CFRange range, const void *value);
/*!
@function CFArrayBSearchValues
Searches the array for the value using a binary search algorithm.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined. If the array is
not sorted from least to greatest according to the
comparator function, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find a match in the array. If
value, or any of the values in the array, are not understood
by the comparator callback, the behavior is undefined.
@param comparator The function with the comparator function type
signature which is used in the binary search operation to
compare values in the array with the given value. 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 which the comparator function does not expect
or cannot properly compare, the behavior is undefined.
@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.
@result The return value is either 1) the index of a value that
matched, if the target value matches one or more in the
range, 2) greater than or equal to the end point of the
range, if the value is greater than all the values in the
range, or 3) the index of the value greater than the target
value, if the value lies between two of (or less than all
of) the values in the range.
*/
CF_EXPORT
CFIndex CFArrayBSearchValues(CFArrayRef theArray, CFRange range, const void *value, CFComparatorFunction comparator, void *context);
/*!
@function CFArrayAppendValue
Adds the value to the array giving it a new largest index.
@param theArray The array to which the value is to be added. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param value The value to add to the array. The value is retained by
the array using the retain callback provided when the array
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The value is
assigned to the index one larger than the previous largest
index, and the count of the array is increased by one.
*/
CF_EXPORT
void CFArrayAppendValue(CFMutableArrayRef theArray, const void *value);
/*!
@function CFArrayInsertValueAtIndex
Adds the value to the array, giving it the given index.
@param theArray The array to which the value is to be added. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param idx The index to which to add the new value. If the index is
outside the index space of the array (0 to N inclusive,
where N is the count of the array before the operation), the
behavior is undefined. If the index is the same as N, this
function has the same effect as CFArrayAppendValue().
@param value The value to add to the array. The value is retained by
the array using the retain callback provided when the array
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The value is
assigned to the given index, and all values with equal and
larger indices have their indexes increased by one.
*/
CF_EXPORT
void CFArrayInsertValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void *value);
/*!
@function CFArraySetValueAtIndex
Changes the value with the given index in the array.
@param theArray The array in which the value is to be changed. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param idx The index to which to set the new value. If the index is
outside the index space of the array (0 to N inclusive,
where N is the count of the array before the operation), the
behavior is undefined. If the index is the same as N, this
function has the same effect as CFArrayAppendValue().
@param value The value to set in the array. The value is retained by
the array using the retain callback provided when the array
was created, and the previous value with that index is
released. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The indices of
other values is not affected.
*/
CF_EXPORT
void CFArraySetValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void *value);
/*!
@function CFArrayRemoveValueAtIndex
Removes the value with the given index from the array.
@param theArray The array from which the value is to be removed. If
this parameter is not a valid mutable CFArray, the behavior
is undefined.
@param idx The index from which to remove the value. If the index is
outside the index space of the array (0 to N-1 inclusive,
where N is the count of the array before the operation), the
behavior is undefined.
*/
CF_EXPORT
void CFArrayRemoveValueAtIndex(CFMutableArrayRef theArray, CFIndex idx);
/*!
@function CFArrayRemoveAllValues
Removes all the values from the array, making it empty.
@param theArray The array from which all of the values are to be
removed. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
*/
CF_EXPORT
void CFArrayRemoveAllValues(CFMutableArrayRef theArray);
/*!
@function CFArrayReplaceValues
Replaces a range of values in the array.
@param theArray The array from which all of the values are to be
removed. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
@param range The range of values within the array to replace. If the
range location or end point (defined by the location plus
length minus 1) is outside the index space of the array (0
to N inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0),
in which case the new values are merely inserted at the
range location.
@param newValues A C array of the pointer-sized values to be placed
into the array. The new values in the array are ordered in
the same order in which they appear in this C array. This
parameter may be NULL if the newCount parameter is 0. This
C array is not changed or freed by this function. If this
parameter is not a valid pointer to a C array of at least
newCount pointers, the behavior is undefined.
@param newCount The number of values to copy from the values C
array into the CFArray. If this parameter is different than
the range length, the excess newCount values will be
inserted after the range, or the excess range values will be
deleted. This parameter may be 0, in which case no new
values are replaced into the array and the values in the
range are simply removed. If this parameter is negative, or
greater than the number of values actually in the newValues
C array, the behavior is undefined.
*/
CF_EXPORT
void CFArrayReplaceValues(CFMutableArrayRef theArray, CFRange range, const void **newValues, CFIndex newCount);
/*!
@function CFArrayExchangeValuesAtIndices
Exchanges the values at two indices of the array.
@param theArray The array of which the values are to be swapped. If
this parameter is not a valid mutable CFArray, the behavior
is undefined.
@param idx1 The first index whose values should be swapped. If the
index is outside the index space of the array (0 to N-1
inclusive, where N is the count of the array before the
operation), the behavior is undefined.
@param idx2 The second index whose values should be swapped. If the
index is outside the index space of the array (0 to N-1
inclusive, where N is the count of the array before the
operation), the behavior is undefined.
*/
CF_EXPORT
void CFArrayExchangeValuesAtIndices(CFMutableArrayRef theArray, CFIndex idx1, CFIndex idx2);
/*!
@function CFArraySortValues
Sorts the values in the array using the given comparison function.
@param theArray The array whose values are to be sorted. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param range The range of values within the array to sort. If the
range location or end point (defined by the location plus
length minus 1) is outside the index space of the array (0
to N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param comparator The function with the comparator function type
signature which is used in the sort operation to compare
values in the array with the given value. If this parameter
is not a pointer to a function of the correct prototype, the
the behavior is undefined. If there are values in the array
which the comparator function does not expect or cannot
properly compare, the behavior is undefined. The values in
the range 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 CFArraySortValues(CFMutableArrayRef theArray, CFRange range, CFComparatorFunction comparator, void *context);
/*!
@function CFArrayAppendArray
Adds the values from an array to another array.
@param theArray The array to which values from the otherArray are to
be added. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
@param otherArray The array providing the values to be added to the
array. If this parameter is not a valid CFArray, the
behavior is undefined.
@param otherRange The range within the otherArray from which to add
the values to the array. If the range location or end point
(defined by the location plus length minus 1) is outside
the index space of the otherArray (0 to N-1 inclusive, where
N is the count of the otherArray), the behavior is
undefined. The new values are retained by the array using
the retain callback provided when the array was created. If
the values are not of the sort expected by the retain
callback, the behavior is undefined. The values are assigned
to the indices one larger than the previous largest index
in the array, and beyond, and the count of the array is
increased by range.length. The values are assigned new
indices in the array from smallest to largest index in the
order in which they appear in the otherArray.
*/
CF_EXPORT
void CFArrayAppendArray(CFMutableArrayRef theArray, CFArrayRef otherArray, CFRange otherRange);
CF_EXTERN_C_END
#endif /* ! __COREFOUNDATION_CFARRAY__ */