CFArray.h

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