CFArray.h

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