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