iOS Developer Library

Developer

CoreFoundation Framework Reference CFMutableArray Reference

Options
Deployment Target:

On This Page
Language:

CFMutableArray Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreFoundation

Objective-C

@import CoreFoundation;

CFMutableArray manages dynamic arrays. The basic interface for managing arrays is provided by CFArray Reference. CFMutableArray adds functions to modify the contents of an array.

You create a mutable array object using either the CFArrayCreateMutable or CFArrayCreateMutableCopy function.

CFMutableArray provides several functions for changing the contents of an array, for example the CFArrayAppendValue and CFArrayInsertValueAtIndex functions add values to an array and CFArrayRemoveValueAtIndex removes values from an array. You can also reorder the contents of an array using CFArrayExchangeValuesAtIndices and CFArraySortValues.

CFMutableArray is “toll-free bridged” with its Cocoa Foundation counterpart, NSMutableArray. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSMutableArray * parameter, you can pass in a CFMutableArrayRef, and in a function where you see a CFMutableArrayRef parameter, you can pass in an NSMutableArray instance. This fact also applies to concrete subclasses of NSMutableArray. See Toll-Free Bridged Types for more information on toll-free bridging.

Functions

  • Adds the values from one array to another array.

    Declaration

    Swift

    func CFArrayAppendArray(_ theArray: CFMutableArray!, _ otherArray: CFArray!, _ otherRange: CFRange)

    Objective-C

    void CFArrayAppendArray ( CFMutableArrayRef theArray, CFArrayRef otherArray, CFRange otherRange );

    Parameters

    theArray

    The array to which values from otherArray are added. If theArray is a limited-capacity array, adding otherRange.length values from otherArray must not cause the capacity limit of theArray to be exceeded.

    otherArray

    An array providing the values to be added to theArray.

    otherRange

    The range within otherArray from which to add the values to theArray. The range must not exceed the index space of otherArray.

    Discussion

    The new values are retained by theArray using the retain callback provided when theArray was created. If the values are not of the type expected by the retain callback, the behavior is undefined. The values are assigned to the indices one larger than the previous largest index in theArray, and beyond, and the count of theArray is increased by otherRange.length. The values are assigned new indices in theArray from smallest to largest index in the order in which they appear in otherArray.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Adds a value to an array giving it the new largest index.

    Declaration

    Swift

    func CFArrayAppendValue(_ theArray: CFMutableArray!, _ value: UnsafePointer<Void>)

    Objective-C

    void CFArrayAppendValue ( CFMutableArrayRef theArray, const void *value );

    Parameters

    theArray

    The array to which value is to be added. If theArray is a limited-capacity array and it is full before this operation, the behavior is undefined.

    value

    A CFType object or a pointer value to add to theArray.

    Discussion

    The value parameter is retained by theArray using the retain callback provided when theArray was created. If value is not of the type expected by the retain callback, the behavior is undefined. The value parameter is assigned to the index one larger than the previous largest index and the count of theArray is increased by one.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates a new empty mutable array.

    Declaration

    Swift

    func CFArrayCreateMutable(_ allocator: CFAllocator!, _ capacity: CFIndex, _ callBacks: UnsafePointer<CFArrayCallBacks>) -> CFMutableArray!

    Objective-C

    CFMutableArrayRef CFArrayCreateMutable ( CFAllocatorRef allocator, CFIndex capacity, const CFArrayCallBacks *callBacks );

    Parameters

    allocator

    The allocator to use to allocate memory for the new array and its storage for values. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    capacity

    The maximum number of values that can be contained by the new array. The array starts empty and can grow to this number of values (and it can have less).

    Pass 0 to specify that the maximum capacity is not limited. The value must not be negative.

    callBacks

    A pointer to a CFArrayCallBacks structure initialized with the callbacks for the array to use on each value in the array. A copy of the contents of the callbacks structure is made, so that a pointer to a structure on the stack can be passed in or can be reused for multiple array creations.

    If the array contains CFType objects only, then pass kCFTypeArrayCallBacks to use the default callback functions.

    This parameter may be NULL, which is treated as if a valid structure of version 0 with all fields NULL had been passed in.

    If any of the fields are not valid pointers to functions of the correct type, or this parameter is not a valid pointer to a CFArrayCallBacks structure, the behavior is undefined. If any value put into the array is not one understood by one of the callback functions, the behavior when that callback function is used is undefined.

    Return Value

    A new mutable array, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Creates a new mutable array with the values from another array.

    Declaration

    Swift

    func CFArrayCreateMutableCopy(_ allocator: CFAllocator!, _ capacity: CFIndex, _ theArray: CFArray!) -> CFMutableArray!

    Objective-C

    CFMutableArrayRef CFArrayCreateMutableCopy ( CFAllocatorRef allocator, CFIndex capacity, CFArrayRef theArray );

    Parameters

    allocator

    The allocator to use to allocate memory for the new array and its storage for values. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    capacity

    The maximum number of values that can be contained by the new array. The array starts with the same number of values as theArray and can grow to this number of values (and it can have less).

    Pass 0 to specify that the maximum capacity is not limited. If non-0, capacity must be greater than or equal to the count of theArray.

    theArray

    The array to copy. The pointer values from the array are copied into the new array. However, the values are also retained by the new array.

    Return Value

    A new mutable array that contains the same values as theArray. The new array has the same count as the theArray and uses the same callbacks. Ownership follows the Create Rule.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Exchanges the values at two indices of an array.

    Declaration

    Swift

    func CFArrayExchangeValuesAtIndices(_ theArray: CFMutableArray!, _ idx1: CFIndex, _ idx2: CFIndex)

    Objective-C

    void CFArrayExchangeValuesAtIndices ( CFMutableArrayRef theArray, CFIndex idx1, CFIndex idx2 );

    Parameters

    theArray

    The array that contains the values to be swapped.

    idx1

    The index of the value to swap with the value at idx2. The index must not exceed the index space of theArray (0 to N-1 inclusive, where N is the count of theArray before the operation).

    idx2

    The index of the value to swap with the value at idx1. The index must not exceed the index space of theArray (0 to N-1 inclusive, where N is the count of theArray before the operation).

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Inserts a value into an array at a given index.

    Declaration

    Swift

    func CFArrayInsertValueAtIndex(_ theArray: CFMutableArray!, _ idx: CFIndex, _ value: UnsafePointer<Void>)

    Objective-C

    void CFArrayInsertValueAtIndex ( CFMutableArrayRef theArray, CFIndex idx, const void *value );

    Parameters

    theArray

    The array into which value is inserted. If theArray is a fixed-capacity array and it is full before this operation, the behavior is undefined.

    idx

    The index at which to insert value. The index must be in the range 0 to N inclusive, where N is the count of theArray before the operation. If the index is the same as the count of theArray, this function has the same effect as CFArrayAppendValue.

    value

    The value to insert into theArray. The value is retained by theArray using the retain callback provided when theArray was created. If value is not of the type expected by the retain callback, the behavior is undefined.

    Discussion

    The value parameter is assigned to the index idx, and all values in theArray with equal and larger indices have their indices increased by one.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Removes all the values from an array, making it empty.

    Declaration

    Swift

    func CFArrayRemoveAllValues(_ theArray: CFMutableArray!)

    Objective-C

    void CFArrayRemoveAllValues ( CFMutableArrayRef theArray );

    Parameters

    theArray

    The array from which all of the values are removed.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Removes the value at a given index from an array.

    Declaration

    Swift

    func CFArrayRemoveValueAtIndex(_ theArray: CFMutableArray!, _ idx: CFIndex)

    Objective-C

    void CFArrayRemoveValueAtIndex ( CFMutableArrayRef theArray, CFIndex idx );

    Parameters

    theArray

    The array from which the value is to be removed.

    idx

    The index of the value to remove. The value not lie outside the index space of theArray (0 to N-1 inclusive, where N is the count of theArray before the operation).

    Discussion

    All values in theArray with indices larger than idx have their indices decreased by one.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Replaces a range of values in an array.

    Declaration

    Swift

    func CFArrayReplaceValues(_ theArray: CFMutableArray!, _ range: CFRange, _ newValues: UnsafeMutablePointer<UnsafePointer<Void>>, _ newCount: CFIndex)

    Objective-C

    void CFArrayReplaceValues ( CFMutableArrayRef theArray, CFRange range, const void **newValues, CFIndex newCount );

    Parameters

    theArray

    The array in which some values are to be replaced. If this parameter is not a valid CFMutableArray object, the behavior is undefined.

    range

    The range of values within theArray to replace. The range location or end point (defined by the location plus length minus 1) must not lie outside the index space of theArray (0 to N-1 inclusive, where N is the count of theArray). The range length must not be negative. The range may be empty (length 0), in which case the new values are merely inserted at the range location.

    newValues

    A C array of the pointer-sized values to be placed into theArray. The new values in theArray are ordered in the same order in which they appear in this C array. This parameter may be NULL if the newCount parameter is 0. This C array is not changed or freed by this function. If this parameter is not a valid pointer to a C array of at least newCount pointers, the behavior is undefined.

    newCount

    The number of values to copy from the newValues C array into theArray. If this parameter is different from the range length, the excess newCount values are inserted after the range or the excess range values are deleted. This parameter may be 0, in which case no new values are replaced into theArray and the values in the range are simply removed. If this parameter is negative or greater than the number of values actually in the newValues C array, the behavior is undefined.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Changes the value at a given index in an array.

    Declaration

    Swift

    func CFArraySetValueAtIndex(_ theArray: CFMutableArray!, _ idx: CFIndex, _ value: UnsafePointer<Void>)

    Objective-C

    void CFArraySetValueAtIndex ( CFMutableArrayRef theArray, CFIndex idx, const void *value );

    Parameters

    theArray

    The array in which the value is to be changed.

    idx

    The index at which to set the new value. The value must not lie outside the index space of theArray (0 to N-1 inclusive, where N is the count of the array before the operation).

    value

    The value to set in theArray. The value is retained by theArray using the retain callback provided when theArray was created and the previous value at idx is released. If the value is not of the type expected by the retain callback, the behavior is undefined. The indices of other values are not affected.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Sorts the values in an array using a given comparison function.

    Declaration

    Swift

    func CFArraySortValues(_ theArray: CFMutableArray!, _ range: CFRange, _ comparator: CFComparatorFunction, _ context: UnsafeMutablePointer<Void>)

    Objective-C

    void CFArraySortValues ( CFMutableArrayRef theArray, CFRange range, CFComparatorFunction comparator, void *context );

    Parameters

    theArray

    The array whose values are sorted.

    range

    The range of values within theArray to sort. The range location or end point (defined by the location plus length minus 1) must not lie outside the index space of theArray (0 to N-1 inclusive, where N is the count of theArray). The range length must not be negative. The range may be empty (length 0).

    comparator

    The function with the comparator function type signature that is used in the sort operation to compare the values in theArray. If this parameter is not a pointer to a function of the correct prototype, the behavior is undefined. If there are values in theArray that the comparator function does not expect or cannot properly compare, the behavior is undefined. The values in the range are sorted from least to greatest according to this function.

    context

    A pointer-sized program-defined value, which is passed as the third parameter to the comparator function, but is otherwise unused by this function. If the context is not what is expected by the comparator function, the behavior is undefined.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Data Types

Miscellaneous

  • A reference to a mutable array object.

    Declaration

    Swift

    typealias CFMutableArrayRef = CFMutableArray

    Objective-C

    typedef struct __CFArray *CFMutableArrayRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.