Collections.subproj/CFArray.h

   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 /*      CFArray.h
  26         Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
  27 */
  28
  29 /*!
  30         @header CFArray
  31         CFArray implements an ordered, compact container of pointer-sized
  32         values. Values are accessed via integer keys (indices), from the
  33         range 0 to N-1, where N is the number of values in the array when
  34         an operation is performed. The array is said to be "compact" because
  35         deleted or inserted values do not leave a gap in the key space --
  36         the values with higher-numbered indices have their indices
  37         renumbered lower (or higher, in the case of insertion) so that the
  38         set of valid indices is always in the integer range [0, N-1]. Thus,
  39         the index to access a particular value in the array may change over
  40         time as other values are inserted into or deleted from the array.
  41
  42         Arrays come in two flavors, immutable, which cannot have values
  43         added to them or removed from them after the array is created, and
  44         mutable, to which you can add values or from which remove values.
  45         Mutable arrays have two subflavors, fixed-capacity, for which there
  46         is a maximum number set at creation time of values which can be put
  47         into the array, and variable capacity, which can have an unlimited
  48         number of values (or rather, limited only by constraints external
  49         to CFArray, like the amount of available memory). Fixed-capacity
  50         arrays can be somewhat higher performing, if you can put a definite
  51         upper limit on the number of values that might be put into the
  52         array.
  53
  54         As with all CoreFoundation collection types, arrays maintain hard
  55         references on the values you put in them, but the retaining and
  56         releasing functions are user-defined callbacks that can actually do
  57         whatever the user wants (for example, nothing).
  58
  59         Computational Complexity
  60         The access time for a value in the array is guaranteed to be at
  61         worst O(lg N) for any implementation, current and future, but will
  62         often be O(1) (constant time). Linear search operations similarly
  63         have a worst case complexity of O(N*lg N), though typically the
  64         bounds will be tighter, and so on. Insertion or deletion operations
  65         will typically be linear in the number of values in the array, but
  66         may be O(N*lg N) clearly in the worst case in some implementations.
  67         There are no favored positions within the array for performance;
  68         that is, it is not necessarily faster to access values with low
  69         indices, or to insert or delete values with high indices, or
  70         whatever.
  71 */
  72
  73 #if !defined(__COREFOUNDATION_CFARRAY__)
  74 #define __COREFOUNDATION_CFARRAY__ 1
  75
  76 #include <CoreFoundation/CFBase.h>
  77
  78 #if defined(__cplusplus)
  79 extern "C" {
  80 #endif
  81
  82 /*!
  83         @typedef CFArrayCallBacks
  84         Structure containing the callbacks of a CFArray.
  85         @field version The version number of the structure type being passed
  86                 in as a parameter to the CFArray creation functions. This
  87                 structure is version 0.
  88         @field retain The callback used to add a retain for the array on
  89                 values as they are put into the array. This callback returns
  90                 the value to store in the array, which is usually the value
  91                 parameter passed to this callback, but may be a different
  92                 value if a different value should be stored in the array.
  93                 The array's allocator is passed as the first argument.
  94         @field release The callback used to remove a retain previously added
  95                 for the array from values as they are removed from the
  96                 array. The array's allocator is passed as the first
  97                 argument.
  98         @field copyDescription The callback used to create a descriptive
  99                 string representation of each value in the array. This is
 100                 used by the CFCopyDescription() function.
 101         @field equal The callback used to compare values in the array for
 102                 equality for some operations.
 103 */
 104 typedef const void *    (*CFArrayRetainCallBack)(CFAllocatorRef allocator, const void *value);
 105 typedef void            (*CFArrayReleaseCallBack)(CFAllocatorRef allocator, const void *value);
 106 typedef CFStringRef     (*CFArrayCopyDescriptionCallBack)(const void *value);
 107 typedef Boolean         (*CFArrayEqualCallBack)(const void *value1, const void *value2);
 108 typedef struct {
 109     CFIndex                             version;
 110     CFArrayRetainCallBack               retain;
 111     CFArrayReleaseCallBack              release;
 112     CFArrayCopyDescriptionCallBack      copyDescription;
 113     CFArrayEqualCallBack                equal;
 114 } CFArrayCallBacks;
 115
 116 /*!
 117         @constant kCFTypeArrayCallBacks
 118         Predefined CFArrayCallBacks structure containing a set of callbacks
 119         appropriate for use when the values in a CFArray are all CFTypes.
 120 */
 121 CF_EXPORT
 122 const CFArrayCallBacks kCFTypeArrayCallBacks;
 123
 124 /*!
 125         @typedef CFArrayApplierFunction
 126         Type of the callback function used by the apply functions of
 127                 CFArrays.
 128         @param value The current value from the array.
 129         @param context The user-defined context parameter given to the apply
 130                 function.
 131 */
 132 typedef void (*CFArrayApplierFunction)(const void *value, void *context);
 133
 134 /*!
 135         @typedef CFArrayRef
 136         This is the type of a reference to immutable CFArrays.
 137 */
 138 typedef const struct __CFArray * CFArrayRef;
 139
 140 /*!
 141         @typedef CFMutableArrayRef
 142         This is the type of a reference to mutable CFArrays.
 143 */
 144 typedef struct __CFArray * CFMutableArrayRef;
 145
 146 /*!
 147         @function CFArrayGetTypeID
 148         Returns the type identifier of all CFArray instances.
 149 */
 150 CF_EXPORT
 151 CFTypeID CFArrayGetTypeID(void);
 152
 153 /*!
 154         @function CFArrayCreate
 155         Creates a new immutable array with the given values.
 156         @param allocator The CFAllocator which should be used to allocate
 157                 memory for the array and its storage for values. This
 158                 parameter may be NULL in which case the current default
 159                 CFAllocator is used. If this reference is not a valid
 160                 CFAllocator, the behavior is undefined.
 161         @param values A C array of the pointer-sized values to be in the
 162                 array. The values in the array are ordered in the same order
 163                 in which they appear in this C array. This parameter may be
 164                 NULL if the numValues parameter is 0. This C array is not
 165                 changed or freed by this function. If this parameter is not
 166                 a valid pointer to a C array of at least numValues pointers,
 167                 the behavior is undefined.
 168         @param numValues The number of values to copy from the values C
 169                 array into the CFArray. This number will be the count of the
 170                 array.
 171                 If this parameter is negative, or greater than the number of
 172                 values actually in the value's C array, the behavior is
 173                 undefined.
 174         @param callBacks A pointer to a CFArrayCallBacks structure
 175                 initialized with the callbacks for the array to use on each
 176                 value in the array. The retain callback will be used within
 177                 this function, for example, to retain all of the new values
 178                 from the values C array. A copy of the contents of the
 179                 callbacks structure is made, so that a pointer to a
 180                 structure on the stack can be passed in, or can be reused
 181                 for multiple array creations. If the version field of this
 182                 callbacks structure is not one of the defined ones for
 183                 CFArray, the behavior is undefined. The retain field may be
 184                 NULL, in which case the CFArray will do nothing to add a
 185                 retain to the contained values for the array. The release
 186                 field may be NULL, in which case the CFArray will do nothing
 187                 to remove the array's retain (if any) on the values when the
 188                 array is destroyed. If the copyDescription field is NULL,
 189                 the array will create a simple description for the value. If
 190                 the equal field is NULL, the array will use pointer equality
 191                 to test for equality of values. This callbacks parameter
 192                 itself may be NULL, which is treated as if a valid structure
 193                 of version 0 with all fields NULL had been passed in.
 194                 Otherwise, if any of the fields are not valid pointers to
 195                 functions of the correct type, or this parameter is not a
 196                 valid pointer to a  CFArrayCallBacks callbacks structure,
 197                 the behavior is undefined. If any of the values put into the
 198                 array is not one understood by one of the callback functions
 199                 the behavior when that callback function is used is
 200                 undefined.
 201         @result A reference to the new immutable CFArray.
 202 */
 203 CF_EXPORT
 204 CFArrayRef CFArrayCreate(CFAllocatorRef allocator, const void **values, CFIndex numValues, const CFArrayCallBacks *callBacks);
 205
 206 /*!
 207         @function CFArrayCreateCopy
 208         Creates a new immutable array with the values from the given array.
 209         @param allocator The CFAllocator which should be used to allocate
 210                 memory for the array and its storage for values. This
 211                 parameter may be NULL in which case the current default
 212                 CFAllocator is used. If this reference is not a valid
 213                 CFAllocator, the behavior is undefined.
 214         @param theArray The array which is to be copied. The values from the
 215                 array are copied as pointers into the new array (that is,
 216                 the values themselves are copied, not that which the values
 217                 point to, if anything). However, the values are also
 218                 retained by the new array. The count of the new array will
 219                 be the same as the given array. The new array uses the same
 220                 callbacks as the array to be copied. If this parameter is
 221                 not a valid CFArray, the behavior is undefined.
 222         @result A reference to the new immutable CFArray.
 223 */
 224 CF_EXPORT
 225 CFArrayRef CFArrayCreateCopy(CFAllocatorRef allocator, CFArrayRef theArray);
 226
 227 /*!
 228         @function CFArrayCreateMutable
 229         Creates a new empty mutable array.
 230         @param allocator The CFAllocator which should be used to allocate
 231                 memory for the array and its storage for values. This
 232                 parameter may be NULL in which case the current default
 233                 CFAllocator is used. If this reference is not a valid
 234                 CFAllocator, the behavior is undefined.
 235         @param capacity The maximum number of values that can be contained
 236                 by the CFArray. The array starts empty, and can grow to this
 237                 number of values (and it can have less). If this parameter
 238                 is 0, the array's maximum capacity is unlimited (or rather,
 239                 only limited by address space and available memory
 240                 constraints). If this parameter is negative, the behavior is
 241                 undefined.
 242         @param callBacks A pointer to a CFArrayCallBacks structure
 243                 initialized with the callbacks for the array to use on each
 244                 value in the array. A copy of the contents of the
 245                 callbacks structure is made, so that a pointer to a
 246                 structure on the stack can be passed in, or can be reused
 247                 for multiple array creations. If the version field of this
 248                 callbacks structure is not one of the defined ones for
 249                 CFArray, the behavior is undefined. The retain field may be
 250                 NULL, in which case the CFArray will do nothing to add a
 251                 retain to the contained values for the array. The release
 252                 field may be NULL, in which case the CFArray will do nothing
 253                 to remove the arrays retain (if any) on the values when the
 254                 array is destroyed. If the copyDescription field is NULL,
 255                 the array will create a simple description for the value. If
 256                 the equal field is NULL, the array will use pointer equality
 257                 to test for equality of values. This callbacks parameter
 258                 itself may be NULL, which is treated as if a valid structure
 259                 of version 0 with all fields NULL had been passed in.
 260                 Otherwise, if any of the fields are not valid pointers to
 261                 functions of the correct type, or this parameter is not a
 262                 valid pointer to a  CFArrayCallBacks callbacks structure,
 263                 the behavior is undefined. If any of the values put into the
 264                 array is not one understood by one of the callback functions
 265                 the behavior when that callback function is used is
 266                 undefined.
 267         @result A reference to the new mutable CFArray.
 268 */
 269 CF_EXPORT
 270 CFMutableArrayRef CFArrayCreateMutable(CFAllocatorRef allocator, CFIndex capacity, const CFArrayCallBacks *callBacks);
 271
 272 /*!
 273         @function CFArrayCreateMutableCopy
 274         Creates a new mutable array with the values from the given array.
 275         @param allocator The CFAllocator which should be used to allocate
 276                 memory for the array and its storage for values. This
 277                 parameter may be NULL in which case the current default
 278                 CFAllocator is used. If this reference is not a valid
 279                 CFAllocator, the behavior is undefined.
 280         @param capacity The maximum number of values that can be contained
 281                 by the CFArray. The array starts empty, and can grow to this
 282                 number of values (and it can have less). If this parameter
 283                 is 0, the array's maximum capacity is unlimited (or rather,
 284                 only limited by address space and available memory
 285                 constraints). This parameter must be greater than or equal
 286                 to the count of the array which is to be copied, or the
 287                 behavior is undefined. If this parameter is negative, the
 288                 behavior is undefined.
 289         @param theArray The array which is to be copied. The values from the
 290                 array are copied as pointers into the new array (that is,
 291                 the values themselves are copied, not that which the values
 292                 point to, if anything). However, the values are also
 293                 retained by the new array. The count of the new array will
 294                 be the same as the given array. The new array uses the same
 295                 callbacks as the array to be copied. If this parameter is
 296                 not a valid CFArray, the behavior is undefined.
 297         @result A reference to the new mutable CFArray.
 298 */
 299 CF_EXPORT
 300 CFMutableArrayRef CFArrayCreateMutableCopy(CFAllocatorRef allocator, CFIndex capacity, CFArrayRef theArray);
 301
 302 /*!
 303         @function CFArrayGetCount
 304         Returns the number of values currently in the array.
 305         @param theArray The array to be queried. If this parameter is not a valid
 306                 CFArray, the behavior is undefined.
 307         @result The number of values in the array.
 308 */
 309 CF_EXPORT
 310 CFIndex CFArrayGetCount(CFArrayRef theArray);
 311
 312 /*!
 313         @function CFArrayGetCountOfValue
 314         Counts the number of times the given value occurs in the array.
 315         @param theArray The array to be searched. If this parameter is not a
 316                 valid CFArray, the behavior is undefined.
 317         @param range The range within the array to search. If the range
 318                 location or end point (defined by the location plus length
 319                 minus 1) is outside the index space of the array (0 to
 320                 N-1 inclusive, where N is the count of the array), the
 321                 behavior is undefined. If the range length is negative, the
 322                 behavior is undefined. The range may be empty (length 0).
 323         @param value The value for which to find matches in the array. The
 324                 equal() callback provided when the array was created is
 325                 used to compare. If the equal() callback was NULL, pointer
 326                 equality (in C, ==) is used. If value, or any of the values
 327                 in the array, are not understood by the equal() callback,
 328                 the behavior is undefined.
 329         @result The number of times the given value occurs in the array,
 330                 within the specified range.
 331 */
 332 CF_EXPORT
 333 CFIndex CFArrayGetCountOfValue(CFArrayRef theArray, CFRange range, const void *value);
 334
 335 /*!
 336         @function CFArrayContainsValue
 337         Reports whether or not the value is in the array.
 338         @param theArray The array to be searched. If this parameter is not a
 339                 valid CFArray, the behavior is undefined.
 340         @param range The range within the array to search. If the range
 341                 location or end point (defined by the location plus length
 342                 minus 1) is outside the index space of the array (0 to
 343                 N-1 inclusive, where N is the count of the array), the
 344                 behavior is undefined. If the range length is negative, the
 345                 behavior is undefined. The range may be empty (length 0).
 346         @param value The value for which to find matches in the array. The
 347                 equal() callback provided when the array was created is
 348                 used to compare. If the equal() callback was NULL, pointer
 349                 equality (in C, ==) is used. If value, or any of the values
 350                 in the array, are not understood by the equal() callback,
 351                 the behavior is undefined.
 352         @result true, if the value is in the specified range of the array,
 353                 otherwise false.
 354 */
 355 CF_EXPORT
 356 Boolean CFArrayContainsValue(CFArrayRef theArray, CFRange range, const void *value);
 357
 358 /*!
 359         @function CFArrayGetValueAtIndex
 360         Retrieves the value at the given index.
 361         @param theArray The array to be queried. If this parameter is not a
 362                 valid CFArray, the behavior is undefined.
 363         @param idx The index of the value to retrieve. If the index is
 364                 outside the index space of the array (0 to N-1 inclusive,
 365                 where N is the count of the array), the behavior is
 366                 undefined.
 367         @result The value with the given index in the array.
 368 */
 369 CF_EXPORT
 370 const void *CFArrayGetValueAtIndex(CFArrayRef theArray, CFIndex idx);
 371
 372 /*!
 373         @function CFArrayGetValues
 374         Fills the buffer with values from the array.
 375         @param theArray The array to be queried. If this parameter is not a
 376                 valid CFArray, the behavior is undefined.
 377         @param range The range of values within the array to retrieve. If
 378                 the range location or end point (defined by the location
 379                 plus length minus 1) is outside the index space of the
 380                 array (0 to N-1 inclusive, where N is the count of the
 381                 array), the behavior is undefined. If the range length is
 382                 negative, the behavior is undefined. The range may be empty
 383                 (length 0), in which case no values are put into the buffer.
 384         @param values A C array of pointer-sized values to be filled with
 385                 values from the array. The values in the C array are ordered
 386                 in the same order in which they appear in the array. If this
 387                 parameter is not a valid pointer to a C array of at least
 388                 range.length pointers, the behavior is undefined.
 389 */
 390 CF_EXPORT
 391 void CFArrayGetValues(CFArrayRef theArray, CFRange range, const void **values);
 392
 393 /*!
 394         @function CFArrayApplyFunction
 395         Calls a function once for each value in the array.
 396         @param theArray The array to be operated upon. If this parameter is not
 397                 a valid CFArray, the behavior is undefined.
 398         @param range The range of values within the array to which to apply
 399                 the function. If the range location or end point (defined by
 400                 the location plus length minus 1) is outside the index
 401                 space of the array (0 to N-1 inclusive, where N is the count
 402                 of the array), the behavior is undefined. If the range
 403                 length is negative, the behavior is undefined. The range may
 404                 be empty (length 0).
 405         @param applier The callback function to call once for each value in
 406                 the given range in the array. If this parameter is not a
 407                 pointer to a function of the correct prototype, the behavior
 408                 is undefined. If there are values in the range which the
 409                 applier function does not expect or cannot properly apply
 410                 to, the behavior is undefined.
 411         @param context A pointer-sized user-defined value, which is passed
 412                 as the second parameter to the applier function, but is
 413                 otherwise unused by this function. If the context is not
 414                 what is expected by the applier function, the behavior is
 415                 undefined.
 416 */
 417 CF_EXPORT
 418 void CFArrayApplyFunction(CFArrayRef theArray, CFRange range, CFArrayApplierFunction applier, void *context);
 419
 420 /*!
 421         @function CFArrayGetFirstIndexOfValue
 422         Searches the array for the value.
 423         @param theArray The array to be searched. If this parameter is not a
 424                 valid CFArray, the behavior is undefined.
 425         @param range The range within the array to search. If the range
 426                 location or end point (defined by the location plus length
 427                 minus 1) is outside the index space of the array (0 to
 428                 N-1 inclusive, where N is the count of the array), the
 429                 behavior is undefined. If the range length is negative, the
 430                 behavior is undefined. The range may be empty (length 0).
 431                 The search progresses from the smallest index defined by
 432                 the range to the largest.
 433         @param value The value for which to find a match in the array. The
 434                 equal() callback provided when the array was created is
 435                 used to compare. If the equal() callback was NULL, pointer
 436                 equality (in C, ==) is used. If value, or any of the values
 437                 in the array, are not understood by the equal() callback,
 438                 the behavior is undefined.
 439         @result The lowest index of the matching values in the range, or
 440                 kCFNotFound if no value in the range matched.
 441 */
 442 CF_EXPORT
 443 CFIndex CFArrayGetFirstIndexOfValue(CFArrayRef theArray, CFRange range, const void *value);
 444
 445 /*!
 446         @function CFArrayGetLastIndexOfValue
 447         Searches the array for the value.
 448         @param theArray The array to be searched. If this parameter is not a
 449                 valid CFArray, the behavior is undefined.
 450         @param range The range within the array to search. If the range
 451                 location or end point (defined by the location plus length
 452                 minus 1) is outside the index space of the array (0 to
 453                 N-1 inclusive, where N is the count of the array), the
 454                 behavior is undefined. If the range length is negative, the
 455                 behavior is undefined. The range may be empty (length 0).
 456                 The search progresses from the largest index defined by the
 457                 range to the smallest.
 458         @param value The value for which to find a match in the array. The
 459                 equal() callback provided when the array was created is
 460                 used to compare. If the equal() callback was NULL, pointer
 461                 equality (in C, ==) is used. If value, or any of the values
 462                 in the array, are not understood by the equal() callback,
 463                 the behavior is undefined.
 464         @result The highest index of the matching values in the range, or
 465                 kCFNotFound if no value in the range matched.
 466 */
 467 CF_EXPORT
 468 CFIndex CFArrayGetLastIndexOfValue(CFArrayRef theArray, CFRange range, const void *value);
 469
 470 /*!
 471         @function CFArrayBSearchValues
 472         Searches the array for the value using a binary search algorithm.
 473         @param theArray The array to be searched. If this parameter is not a
 474                 valid CFArray, the behavior is undefined. If the array is
 475                 not sorted from least to greatest according to the
 476                 comparator function, the behavior is undefined.
 477         @param range The range within the array to search. If the range
 478                 location or end point (defined by the location plus length
 479                 minus 1) is outside the index space of the array (0 to
 480                 N-1 inclusive, where N is the count of the array), the
 481                 behavior is undefined. If the range length is negative, the
 482                 behavior is undefined. The range may be empty (length 0).
 483         @param value The value for which to find a match in the array. If
 484                 value, or any of the values in the array, are not understood
 485                 by the comparator callback, the behavior is undefined.
 486         @param comparator The function with the comparator function type
 487                 signature which is used in the binary search operation to
 488                 compare values in the array with the given value. If this
 489                 parameter is not a pointer to a function of the correct
 490                 prototype, the behavior is undefined. If there are values
 491                 in the range which the comparator function does not expect
 492                 or cannot properly compare, the behavior is undefined.
 493         @param context A pointer-sized user-defined value, which is passed
 494                 as the third parameter to the comparator function, but is
 495                 otherwise unused by this function. If the context is not
 496                 what is expected by the comparator function, the behavior is
 497                 undefined.
 498         @result The return value is either 1) the index of a value that
 499                 matched, if the target value matches one or more in the
 500                 range, 2) greater than or equal to the end point of the
 501                 range, if the value is greater than all the values in the
 502                 range, or 3) the index of the value greater than the target
 503                 value, if the value lies between two of (or less than all
 504                 of) the values in the range.
 505 */
 506 CF_EXPORT
 507 CFIndex CFArrayBSearchValues(CFArrayRef theArray, CFRange range, const void *value, CFComparatorFunction comparator, void *context);
 508
 509 /*!
 510         @function CFArrayAppendValue
 511         Adds the value to the array giving it a new largest index.
 512         @param theArray The array to which the value is to be added. If this
 513                 parameter is not a valid mutable CFArray, the behavior is
 514                 undefined. If the array is a fixed-capacity array and it
 515                 is full before this operation, the behavior is undefined.
 516         @param value The value to add to the array. The value is retained by
 517                 the array using the retain callback provided when the array
 518                 was created. If the value is not of the sort expected by the
 519                 retain callback, the behavior is undefined. The value is
 520                 assigned to the index one larger than the previous largest
 521                 index, and the count of the array is increased by one.
 522 */
 523 CF_EXPORT
 524 void CFArrayAppendValue(CFMutableArrayRef theArray, const void *value);
 525
 526 /*!
 527         @function CFArrayInsertValueAtIndex
 528         Adds the value to the array, giving it the given index.
 529         @param theArray The array to which the value is to be added. If this
 530                 parameter is not a valid mutable CFArray, the behavior is
 531                 undefined. If the array is a fixed-capacity array and it
 532                 is full before this operation, the behavior is undefined.
 533         @param idx The index to which to add the new value. If the index is
 534                 outside the index space of the array (0 to N inclusive,
 535                 where N is the count of the array before the operation), the
 536                 behavior is undefined. If the index is the same as N, this
 537                 function has the same effect as CFArrayAppendValue().
 538         @param value The value to add to the array. The value is retained by
 539                 the array using the retain callback provided when the array
 540                 was created. If the value is not of the sort expected by the
 541                 retain callback, the behavior is undefined. The value is
 542                 assigned to the given index, and all values with equal and
 543                 larger indices have their indexes increased by one.
 544 */
 545 CF_EXPORT
 546 void CFArrayInsertValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void *value);
 547
 548 /*!
 549         @function CFArraySetValueAtIndex
 550         Changes the value with the given index in the array.
 551         @param theArray The array in which the value is to be changed. If this
 552                 parameter is not a valid mutable CFArray, the behavior is
 553                 undefined. If the array is a fixed-capacity array and it
 554                 is full before this operation and the index is the same as
 555                 N, the behavior is undefined.
 556         @param idx The index to which to set the new value. If the index is
 557                 outside the index space of the array (0 to N inclusive,
 558                 where N is the count of the array before the operation), the
 559                 behavior is undefined. If the index is the same as N, this
 560                 function has the same effect as CFArrayAppendValue().
 561         @param value The value to set in the array. The value is retained by
 562                 the array using the retain callback provided when the array
 563                 was created, and the previous value with that index is
 564                 released. If the value is not of the sort expected by the
 565                 retain callback, the behavior is undefined. The indices of
 566                 other values is not affected.
 567 */
 568 CF_EXPORT
 569 void CFArraySetValueAtIndex(CFMutableArrayRef theArray, CFIndex idx, const void *value);
 570
 571 /*!
 572         @function CFArrayRemoveValueAtIndex
 573         Removes the value with the given index from the array.
 574         @param theArray The array from which the value is to be removed. If
 575                 this parameter is not a valid mutable CFArray, the behavior
 576                 is undefined.
 577         @param idx The index from which to remove the value. If the index is
 578                 outside the index space of the array (0 to N-1 inclusive,
 579                 where N is the count of the array before the operation), the
 580                 behavior is undefined.
 581 */
 582 CF_EXPORT
 583 void CFArrayRemoveValueAtIndex(CFMutableArrayRef theArray, CFIndex idx);
 584
 585 /*!
 586         @function CFArrayRemoveAllValues
 587         Removes all the values from the array, making it empty.
 588         @param theArray The array from which all of the values are to be
 589                 removed. If this parameter is not a valid mutable CFArray,
 590                 the behavior is undefined.
 591 */
 592 CF_EXPORT
 593 void CFArrayRemoveAllValues(CFMutableArrayRef theArray);
 594
 595 /*!
 596         @function CFArrayReplaceValues
 597         Replaces a range of values in the array.
 598         @param theArray The array from which all of the values are to be
 599                 removed. If this parameter is not a valid mutable CFArray,
 600                 the behavior is undefined.
 601         @param range The range of values within the array to replace. If the
 602                 range location or end point (defined by the location plus
 603                 length minus 1) is outside the index space of the array (0
 604                 to N inclusive, where N is the count of the array), the
 605                 behavior is undefined. If the range length is negative, the
 606                 behavior is undefined. The range may be empty (length 0),
 607                 in which case the new values are merely inserted at the
 608                 range location.
 609         @param newValues A C array of the pointer-sized values to be placed
 610                 into the array. The new values in the array are ordered in
 611                 the same order in which they appear in this C array. This
 612                 parameter may be NULL if the newCount parameter is 0. This
 613                 C array is not changed or freed by this function. If this
 614                 parameter is not a valid pointer to a C array of at least
 615                 newCount pointers, the behavior is undefined.
 616         @param newCount The number of values to copy from the values C
 617                 array into the CFArray. If this parameter is different than
 618                 the range length, the excess newCount values will be
 619                 inserted after the range, or the excess range values will be
 620                 deleted. This parameter may be 0, in which case no new
 621                 values are replaced into the array and the values in the
 622                 range are simply removed. If this parameter is negative, or
 623                 greater than the number of values actually in the newValues
 624                 C array, the behavior is undefined.
 625 */
 626 CF_EXPORT
 627 void CFArrayReplaceValues(CFMutableArrayRef theArray, CFRange range, const void **newValues, CFIndex newCount);
 628
 629 /*!
 630         @function CFArrayExchangeValuesAtIndices
 631         Exchanges the values at two indices of the array.
 632         @param theArray The array of which the values are to be swapped. If
 633                 this parameter is not a valid mutable CFArray, the behavior
 634                 is undefined.
 635         @param idx1 The first index whose values should be swapped. If the
 636                 index is outside the index space of the array (0 to N-1
 637                 inclusive, where N is the count of the array before the
 638                 operation), the behavior is undefined.
 639         @param idx2 The second index whose values should be swapped. If the
 640                 index is outside the index space of the array (0 to N-1
 641                 inclusive, where N is the count of the array before the
 642                 operation), the behavior is undefined.
 643 */
 644 CF_EXPORT
 645 void CFArrayExchangeValuesAtIndices(CFMutableArrayRef theArray, CFIndex idx1, CFIndex idx2);
 646
 647 /*!
 648         @function CFArraySortValues
 649         Sorts the values in the array using the given comparison function.
 650         @param theArray The array whose values are to be sorted. If this
 651                 parameter is not a valid mutable CFArray, the behavior is
 652                 undefined.
 653         @param range The range of values within the array to sort. If the
 654                 range location or end point (defined by the location plus
 655                 length minus 1) is outside the index space of the array (0
 656                 to N-1 inclusive, where N is the count of the array), the
 657                 behavior is undefined. If the range length is negative, the
 658                 behavior is undefined. The range may be empty (length 0).
 659         @param comparator The function with the comparator function type
 660                 signature which is used in the sort operation to compare
 661                 values in the array with the given value. If this parameter
 662                 is not a pointer to a function of the correct prototype, the
 663                 the behavior is undefined. If there are values in the array
 664                 which the comparator function does not expect or cannot
 665                 properly compare, the behavior is undefined. The values in
 666                 the range are sorted from least to greatest according to
 667                 this function.
 668         @param context A pointer-sized user-defined value, which is passed
 669                 as the third parameter to the comparator function, but is
 670                 otherwise unused by this function. If the context is not
 671                 what is expected by the comparator function, the behavior is
 672                 undefined.
 673 */
 674 CF_EXPORT
 675 void CFArraySortValues(CFMutableArrayRef theArray, CFRange range, CFComparatorFunction comparator, void *context);
 676
 677 /*!
 678         @function CFArrayAppendArray
 679         Adds the values from an array to another array.
 680         @param theArray The array to which values from the otherArray are to
 681                 be added. If this parameter is not a valid mutable CFArray,
 682                 the behavior is undefined. If the array is a fixed-capacity
 683                 array and adding range.length values from the otherArray
 684                 exceeds the capacity of the array, the behavior is
 685                 undefined.
 686         @param otherArray The array providing the values to be added to the
 687                 array. If this parameter is not a valid CFArray, the
 688                 behavior is undefined.
 689         @param otherRange The range within the otherArray from which to add
 690                 the values to the array. If the range location or end point
 691                 (defined by the location plus length minus 1) is outside
 692                 the index space of the otherArray (0 to N-1 inclusive, where
 693                 N is the count of the otherArray), the behavior is
 694                 undefined. The new values are retained by the array using
 695                 the retain callback provided when the array was created. If
 696                 the values are not of the sort expected by the retain
 697                 callback, the behavior is undefined. The values are assigned
 698                 to the indices one larger than the previous largest index
 699                 in the array, and beyond, and the count of the array is
 700                 increased by range.length. The values are assigned new
 701                 indices in the array from smallest to largest index in the
 702                 order in which they appear in the otherArray.
 703 */
 704 CF_EXPORT
 705 void CFArrayAppendArray(CFMutableArrayRef theArray, CFArrayRef otherArray, CFRange otherRange);
 706
 707 #if defined(__cplusplus)
 708 }
 709 #endif
 710
 711 #endif /* ! __COREFOUNDATION_CFARRAY__ */
 712