iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSArray Class Reference

Options
Deployment Target:

On This Page
Language:

NSArray

NSArray and its subclass NSMutableArray manage ordered collections of objects called arrays. NSArray creates static arrays, and NSMutableArray creates dynamic arrays. You can use arrays when you need an ordered collection of objects.

NSArray is “toll-free bridged” with its Core Foundation counterpart, CFArrayRef. See Toll-Free Bridging for more information on toll-free bridging.

Subclassing Notes

There is typically little reason to subclass NSArray. The class does well what it is designed to do—maintain an ordered collection of objects. But there are situations where a custom NSArray object might come in handy. Here are a few possibilities:

  • Changing how NSArray stores the elements of its collection. You might do this for performance reasons or for better compatibility with legacy code.

  • Acquiring more information about what is happening to the collection (for example, statistics gathering).

Methods to Override

Any subclass of NSArray must override the primitive instance methods count and objectAtIndex:. These methods must operate on the backing store that you provide for the elements of the collection. For this backing store you can use a static array, a standard NSArray object, or some other data type or mechanism. You may also choose to override, partially or fully, any other NSArray method for which you want to provide an alternative implementation.

You might want to implement an initializer for your subclass that is suited to the backing store that the subclass is managing. If you do, your initializer must invoke one of the designated initializers of the NSArray class, either init or initWithObjects:count:. The NSArray class adopts the NSCopying, NSMutableCopying, and NSCoding protocols; if you want instances of your own custom subclass created from copying or coding, override the methods in these protocols.

Remember that NSArray is the public interface for a class cluster and what this entails for your subclass. You must provide the storage for your subclass and implement the primitive methods that directly act on that storage.

Alternatives to Subclassing

Before making a custom class of NSArray, investigate NSPointerArray and the corresponding Core Foundation type, CFArray Reference. Because NSArray and CFArray are “toll-free bridged,” you can substitute a CFArray object for a NSArray object in your code (with appropriate casting). Although they are corresponding types, CFArray and NSArray do not have identical interfaces or implementations, and you can sometimes do things with CFArray that you cannot easily do with NSArray. For example, CFArray provides a set of callbacks, some of which are for implementing custom retain-release behavior. If you specify NULL implementations for these callbacks, you can easily get a non-retaining array.

If the behavior you want to add supplements that of the existing class, you could write a category on NSArray. Keep in mind, however, that this category will be in effect for all instances of NSArray that you use, and this might have unintended consequences. Alternatively, you could use composition to achieve the desired behavior.

  • Creates and returns an empty array.

    Declaration

    Objective-C

    + (instancetype nonnull)array

    Return Value

    An empty array.

    Discussion

    This method is used by mutable subclasses of NSArray.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array containing the objects in another given array.

    Declaration

    Objective-C

    + (instancetype nonnull)arrayWithArray:(NSArray<ObjectType> * nonnull)anArray

    Parameters

    anArray

    An array.

    Return Value

    An array containing the objects in anArray.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array containing the contents of the file specified by a given path.

    Declaration

    Objective-C

    + (NSArray<ObjectType> * nullable)arrayWithContentsOfFile:(NSString * nonnull)aPath

    Parameters

    aPath

    The path to a file containing a string representation of an array produced by the writeToFile:atomically: method.

    Return Value

    An array containing the contents of the file specified by aPath. Returns nil if the file can’t be opened or if the contents of the file can’t be parsed into an array.

    Discussion

    The array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSDate, NSNumber, NSArray, or NSDictionary objects). For more details, see Property List Programming Guide. The objects contained by this array are immutable, even if the array is mutable.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array containing the contents specified by a given URL.

    Declaration

    Objective-C

    + (NSArray<ObjectType> * nullable)arrayWithContentsOfURL:(NSURL * nonnull)aURL

    Parameters

    aURL

    The location of a file containing a string representation of an array produced by the writeToURL:atomically: method.

    Return Value

    An array containing the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into an array.

    Discussion

    The array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array containing a given object.

    Declaration

    Swift

    convenience init(object anObject: AnyObject)

    Objective-C

    + (instancetype nonnull)arrayWithObject:(ObjectType nonnull)anObject

    Parameters

    anObject

    An object.

    Return Value

    An array containing the single element anObject.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array containing the objects in the argument list.

    Declaration

    Objective-C

    + (instancetype nonnull)arrayWithObjects:(ObjectType nonnull)firstObj, ...

    Parameters

    firstObj, ...

    A comma-separated list of objects ending with nil.

    Return Value

    An array containing the objects in the argument list.

    Discussion

    This code example creates an array containing three different types of element:

    1. NSArray *myArray;
    2. NSDate *aDate = [NSDate distantFuture];
    3. NSValue *aValue = [NSNumber numberWithInt:5];
    4. NSString *aString = @"a string";
    5. myArray = [NSArray arrayWithObjects:aDate, aValue, aString, nil];

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns an array that includes a given number of objects from a given C array.

    Declaration

    Objective-C

    + (instancetype nonnull)arrayWithObjects:(const ObjectType nonnull [])objects count:(NSUInteger)count

    Parameters

    objects

    A C array of objects.

    count

    The number of values from the objects C array to include in the new array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

    Return Value

    A new array including the first count objects from objects.

    Discussion

    Elements are added to the new array in the same order they appear in objects, up to but not including index count. For example:

    1. NSString *strings[3];
    2. strings[0] = @"First";
    3. strings[1] = @"Second";
    4. strings[2] = @"Third";
    5. NSArray *stringsArray = [NSArray arrayWithObjects:strings count:2];
    6. // strings array contains { @"First", @"Second" }

    Availability

    Available in iOS 2.0 and later.

  • init() - init Designated Initializer

    Initializes a newly allocated array.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype nonnull)init

    Return Value

    An array.

    Discussion

    After an immutable array has been initialized in this way, it cannot be modified.

    This method is a designated initializer.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array by placing in it the objects contained in a given array.

    Declaration

    Swift

    convenience init(array array: [AnyObject])

    Objective-C

    - (instancetype nonnull)initWithArray:(NSArray<ObjectType> * nonnull)anArray

    Parameters

    anArray

    An array.

    Return Value

    An array initialized to contain the objects in anArray. The returned object might be different than the original receiver.

    Discussion

    After an immutable array has been initialized in this way, it cannot be modified.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array using anArray as the source of data objects for the array.

    Declaration

    Swift

    convenience init(array array: [AnyObject], copyItems flag: Bool)

    Objective-C

    - (instancetype nonnull)initWithArray:(NSArray<ObjectType> * nonnull)array copyItems:(BOOL)flag

    Parameters

    array

    An array containing the objects with which to initialize the new array.

    flag

    If YEStrue, each object in array receives a copyWithZone: message to create a copy of the object—objects must conform to the NSCopying protocol. In a managed memory environment, this is instead of the retain message the object would otherwise receive. The object copy is then added to the returned array.

    If NOfalse, then in a managed memory environment each object in array simply receives a retain message when it is added to the returned array.

    Return Value

    An array initialized to contain the objects—or if flag is YEStrue, copies of the objects—in array. The returned object might be different than the original receiver.

    Discussion

    After an immutable array has been initialized in this way, it cannot be modified.

    The copyWithZone: method performs a shallow copy. If you have a collection of arbitrary depth, passing YEStrue for the flag parameter will perform an immutable copy of the first level below the surface. If you pass NOfalse the mutability of the first level is unaffected. In either case, the mutability of all deeper levels is unaffected.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array with the contents of the file specified by a given path.

    Declaration

    Swift

    convenience init?(contentsOfFile path: String)

    Objective-C

    - (NSArray<ObjectType> * nullable)initWithContentsOfFile:(NSString * nonnull)aPath

    Parameters

    aPath

    The path to a file containing a representation of an array produced by the writeToFile:atomically: method.

    Return Value

    An array initialized to contain the contents of the file specified by aPath or nil if the file can’t be opened or the contents of the file can’t be parsed into an array. The returned object might be different than the original receiver.

    Discussion

    The array representation in the file identified by aPath must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array with the contents of the location specified by a given URL.

    Declaration

    Swift

    convenience init?(contentsOfURL url: NSURL)

    Objective-C

    - (NSArray<ObjectType> * nullable)initWithContentsOfURL:(NSURL * nonnull)aURL

    Parameters

    aURL

    The location of a file containing a string representation of an array produced by the writeToURL:atomically: method.

    Return Value

    An array initialized to contain the contents specified by aURL. Returns nil if the location can’t be opened or if the contents of the location can’t be parsed into an array. The returned object might be different than the original receiver.

    Discussion

    The array representation at the location identified by aURL must contain only property list objects (NSString, NSData, NSArray, or NSDictionary objects). The objects contained by this array are immutable, even if the array is mutable.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array by placing in it the objects in the argument list.

    Declaration

    Objective-C

    - (instancetype nonnull)initWithObjects:(ObjectType nonnull)firstObj, ...

    Parameters

    firstObj, ...

    A comma-separated list of objects ending with nil.

    Return Value

    An array initialized to include the objects in the argument list. The returned object might be different than the original receiver.

    Discussion

    After an immutable array has been initialized in this way, it can’t be modified.

    This method is a designated initializer.

    Availability

    Available in iOS 2.0 and later.

  • Initializes a newly allocated array to include a given number of objects from a given C array.

    Declaration

    Swift

    init(objects objects: UnsafePointer<AnyObject?>, count cnt: Int)

    Objective-C

    - (instancetype nonnull)initWithObjects:(const ObjectType nonnull [])objects count:(NSUInteger)count

    Parameters

    objects

    A C array of objects.

    count

    The number of values from the objects C array to include in the new array. This number will be the count of the new array—it must not be negative or greater than the number of elements in objects.

    Return Value

    A newly allocated array including the first count objects from objects. The returned object might be different than the original receiver.

    Discussion

    Elements are added to the new array in the same order they appear in objects, up to but not including index count.

    After an immutable array has been initialized in this way, it can’t be modified.

    This method is a designated initializer.

    Availability

    Available in iOS 2.0 and later.

  • Returns a Boolean value that indicates whether a given object is present in the array.

    Declaration

    Swift

    func containsObject(_ anObject: AnyObject) -> Bool

    Objective-C

    - (BOOL)containsObject:(ObjectType nonnull)anObject

    Parameters

    anObject

    An object.

    Return Value

    YEStrue if anObject is present in the array, otherwise NOfalse.

    Discussion

    This method determines whether anObject is present in the array by sending an isEqual: message to each of the array’s objects (and passing anObject as the parameter to each isEqual: message).

    Availability

    Available in iOS 2.0 and later.

  • The number of objects in the array.

    Declaration

    Swift

    var count: Int { get }

    Objective-C

    @property(readonly) NSUInteger count

    Availability

    Available in iOS 2.0 and later.

  • Copies all the objects contained in the array to aBuffer.

    Deprecation Statement

    Use getObjects:range: instead.

    Declaration

    Swift

    func getObjects(_ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>)

    Objective-C

    - (void)getObjects:(ObjectType nonnull [])aBuffer

    Parameters

    aBuffer

    A C array of objects of size at least the count of the array.

    Discussion

    The method copies into aBuffer all the objects in the array; the size of the buffer must therefore be at least the count of the array multiplied by the size of an object reference, as shown in the following example (note that this is just an example, you should typically not create a buffer simply to iterate over the contents of an array):

    1. NSArray *mArray = // ...;
    2. id *objects;
    3. NSUInteger count = [mArray count];
    4. objects = malloc(sizeof(id) * count);
    5. [mArray getObjects:objects];
    6. for (i = 0; i < count; i++) {
    7. NSLog(@"object at index %d: %@", i, objects[i]);
    8. }
    9. free(objects);

    Special Considerations

    This deprecated method is unsafe because it could potentially cause buffer overruns.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 4.0.

  • Copies the objects contained in the array that fall within the specified range to aBuffer.

    Declaration

    Swift

    func getObjects(_ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>, range range: NSRange)

    Objective-C

    - (void)getObjects:(ObjectType nonnull [])aBuffer range:(NSRange)aRange

    Parameters

    aBuffer

    A C array of objects of size at least the length of the range specified by aRange.

    aRange

    A range within the bounds of the array.

    If the location plus the length of the range is greater than the count of the array, this method raises an NSRangeException.

    Discussion

    The method copies into aBuffer the objects in the array in the range specified by aRange; the size of the buffer must therefore be at least the length of the range multiplied by the size of an object reference, as shown in the following example (this is solely for illustration—you should typically not create a buffer simply to iterate over the contents of an array):

    1. NSArray *mArray = // an array with at least six elements...;
    2. id *objects;
    3. NSRange range = NSMakeRange(2, 4);
    4. objects = malloc(sizeof(id) * range.length);
    5. [mArray getObjects:objects range:range];
    6. for (i = 0; i < range.length; i++) {
    7. NSLog(@"objects: %@", objects[i]);
    8. }
    9. free(objects);

    Availability

    Available in iOS 2.0 and later.

  • The first object in the array. (read-only)

    Declaration

    Swift

    var firstObject: AnyObject? { get }

    Objective-C

    @property(nonatomic, readonly) ObjectType firstObject

    Discussion

    If the array is empty, returns nil.

    Availability

    Available in iOS 4.0 and later.

  • The last object in the array. (read-only)

    Declaration

    Swift

    var lastObject: AnyObject? { get }

    Objective-C

    @property(nonatomic, readonly) ObjectType lastObject

    Discussion

    If the array is empty, returns nil.

    Availability

    Available in iOS 2.0 and later.

    See Also

    removeLastObject (NSMutableArray)

  • Returns the object located at the specified index.

    Declaration

    Swift

    func objectAtIndex(_ index: Int) -> AnyObject

    Objective-C

    - (ObjectType nonnull)objectAtIndex:(NSUInteger)index

    Parameters

    index

    An index within the bounds of the array.

    Return Value

    The object located at index.

    Discussion

    If index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), an NSRangeException is raised.

    Availability

    Available in iOS 2.0 and later.

  • Returns the object at the specified index.

    Declaration

    Swift

    subscript (_ idx: Int) -> AnyObject { get }

    Objective-C

    - (ObjectType nonnull)objectAtIndexedSubscript:(NSUInteger)idx

    Parameters

    idx

    An index within the bounds of the array.

    Return Value

    The object located at index.

    Discussion

    If index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), an NSRangeException is raised.

    This method is identical to objectAtIndex:.

    Availability

    Available in iOS 6.0 and later.

  • Returns an array containing the objects in the array at the indexes specified by a given index set.

    Declaration

    Swift

    func objectsAtIndexes(_ indexes: NSIndexSet) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)objectsAtIndexes:(NSIndexSet * nonnull)indexes

    Return Value

    An array containing the objects in the array at the indexes specified by indexes.

    Discussion

    The returned objects are in the ascending order of their indexes in indexes, so that object in returned array with higher index in indexes will follow the object with smaller index in indexes.

    Raises an NSRangeException if any location in indexes exceeds the bounds of the array, indexes is nil.

    Availability

    Available in iOS 2.0 and later.

  • Returns an enumerator object that lets you access each object in the array.

    Declaration

    Swift

    func objectEnumerator() -> NSEnumerator

    Objective-C

    - (NSEnumerator<ObjectType> * nonnull)objectEnumerator

    Return Value

    An enumerator object that lets you access each object in the array, in order, from the element at the lowest index upwards.

    Discussion

    Returns an enumerator object that lets you access each object in the array, in order, starting with the element at index 0, as in:

    1. NSEnumerator *enumerator = [myArray objectEnumerator];
    2. id anObject;
    3. while (anObject = [enumerator nextObject]) {
    4. /* code to act on each element as it is returned */
    5. }

    Special Considerations

    When you use this method with mutable subclasses of NSArray, you must not modify the array during enumeration.

    It is more efficient to use the fast enumeration protocol (see NSFastEnumeration). Fast enumeration is available on OS X v10.5 and later and iOS 2.0 and later.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – reverseObjectEnumerator
    nextObject (NSEnumerator)

  • Returns an enumerator object that lets you access each object in the array, in reverse order.

    Declaration

    Swift

    func reverseObjectEnumerator() -> NSEnumerator

    Objective-C

    - (NSEnumerator<ObjectType> * nonnull)reverseObjectEnumerator

    Return Value

    An enumerator object that lets you access each object in the array, in order, from the element at the highest index down to the element at index 0.

    Special Considerations

    When you use this method with mutable subclasses of NSArray, you must not modify the array during enumeration.

    It is more efficient to use the fast enumeration protocol (see NSFastEnumeration). Fast enumeration is available on OS X v10.5 and later and iOS 2.0 and later.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – objectEnumerator
    nextObject (NSEnumerator)

  • Returns the lowest index whose corresponding array value is equal to a given object.

    Declaration

    Swift

    func indexOfObject(_ anObject: AnyObject) -> Int

    Objective-C

    - (NSUInteger)indexOfObject:(ObjectType nonnull)anObject

    Parameters

    anObject

    An object.

    Return Value

    The lowest index whose corresponding array value is equal to anObject. If none of the objects in the array is equal to anObject, returns NSNotFound.

    Discussion

    Starting at index 0, each element of the array is sent an isEqual: message until a match is found or the end of the array is reached. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: (declared in the NSObject protocol) returns YEStrue.

    Availability

    Available in iOS 2.0 and later.

  • Returns the lowest index within a specified range whose corresponding array value is equal to a given object .

    Declaration

    Swift

    func indexOfObject(_ anObject: AnyObject, inRange range: NSRange) -> Int

    Objective-C

    - (NSUInteger)indexOfObject:(ObjectType nonnull)anObject inRange:(NSRange)range

    Parameters

    anObject

    An object.

    range

    The range of indexes in the array within which to search for anObject.

    Return Value

    The lowest index within range whose corresponding array value is equal to anObject. If none of the objects within range is equal to anObject, returns NSNotFound.

    Discussion

    Starting at range.location, each element of the array is sent an isEqual: message until a match is found or the end of the range is reached. This method passes the anObject parameter to each isEqual: message. Objects are considered equal if isEqual: returns YEStrue.

    This method raises an NSRangeException exception if the range parameter represents a range that doesn’t exist in the array.

    Availability

    Available in iOS 2.0 and later.

  • Returns the lowest index whose corresponding array value is identical to a given object.

    Declaration

    Swift

    func indexOfObjectIdenticalTo(_ anObject: AnyObject) -> Int

    Objective-C

    - (NSUInteger)indexOfObjectIdenticalTo:(ObjectType nonnull)anObject

    Parameters

    anObject

    An object.

    Return Value

    The lowest index whose corresponding array value is identical to anObject. If none of the objects in the array is identical to anObject, returns NSNotFound.

    Discussion

    Objects are considered identical if their object addresses are the same.

    Availability

    Available in iOS 2.0 and later.

  • Returns the lowest index within a specified range whose corresponding array value is equal to a given object .

    Declaration

    Swift

    func indexOfObjectIdenticalTo(_ anObject: AnyObject, inRange range: NSRange) -> Int

    Objective-C

    - (NSUInteger)indexOfObjectIdenticalTo:(ObjectType nonnull)anObject inRange:(NSRange)range

    Parameters

    anObject

    An object.

    range

    The range of indexes in the array within which to search for anObject.

    Return Value

    The lowest index within range whose corresponding array value is identical to anObject. If none of the objects within range is identical to anObject, returns NSNotFound.

    Discussion

    Objects are considered identical if their object addresses are the same.

    Availability

    Available in iOS 2.0 and later.

  • Returns the index of the first object in the array that passes a test in a given Block.

    Declaration

    Swift

    func indexOfObjectPassingTest(_ predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> Int

    Objective-C

    - (NSUInteger)indexOfObjectPassingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test. Returning YEStrue will stop further processing of the array.

    Return Value

    The lowest index whose corresponding value in the array passes the test specified by predicate. If no objects in the array pass the test, returns NSNotFound.

    Discussion

    If the Block parameter is nil this method will raise an exception.

    Availability

    Available in iOS 4.0 and later.

  • Returns the index of an object in the array that passes a test in a given Block for a given set of enumeration options.

    Declaration

    Swift

    func indexOfObjectWithOptions(_ opts: NSEnumerationOptions, passingTest predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> Int

    Objective-C

    - (NSUInteger)indexOfObjectWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test.

    Return Value

    The index whose corresponding value in the array passes the test specified by predicate and opts. If the opts bit mask specifies reverse order, then the last item that matches is returned. Otherwise, the index of the first matching object is returned. If no objects in the array pass the test, returns NSNotFound.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    Availability

    Available in iOS 4.0 and later.

  • Returns the index, from a given set of indexes, of the first object in the array that passes a test in a given Block for a given set of enumeration options.

    Declaration

    Swift

    func indexOfObjectAtIndexes(_ s: NSIndexSet, options opts: NSEnumerationOptions, passingTest predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> Int

    Objective-C

    - (NSUInteger)indexOfObjectAtIndexes:(NSIndexSet * nonnull)indexSet options:(NSEnumerationOptions)opts passingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    indexSet

    The indexes of the objects over which to enumerate.

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test.

    Return Value

    The lowest index whose corresponding value in the array passes the test specified by predicate. If no objects in the array pass the test, returns NSNotFound.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    Availability

    Available in iOS 4.0 and later.

  • Returns the indexes of objects in the array that pass a test in a given Block.

    Declaration

    Swift

    func indexesOfObjectsPassingTest(_ predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> NSIndexSet

    Objective-C

    - (NSIndexSet * nonnull)indexesOfObjectsPassingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test.

    Return Value

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

    Availability

    Available in iOS 4.0 and later.

  • Returns the indexes of objects in the array that pass a test in a given Block for a given set of enumeration options.

    Declaration

    Swift

    func indexesOfObjectsWithOptions(_ opts: NSEnumerationOptions, passingTest predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> NSIndexSet

    Objective-C

    - (NSIndexSet * nonnull)indexesOfObjectsWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test.

    Return Value

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    Availability

    Available in iOS 4.0 and later.

  • Returns the indexes, from a given set of indexes, of objects in the array that pass a test in a given Block for a given set of enumeration options.

    Declaration

    Swift

    func indexesOfObjectsAtIndexes(_ s: NSIndexSet, options opts: NSEnumerationOptions, passingTest predicate: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Bool) -> NSIndexSet

    Objective-C

    - (NSIndexSet * nonnull)indexesOfObjectsAtIndexes:(NSIndexSet * nonnull)indexSet options:(NSEnumerationOptions)opts passingTest:(BOOL (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))predicate

    Parameters

    indexSet

    The indexes of the objects over which to enumerate.

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    predicate

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    The Block returns a Boolean value that indicates whether obj passed the test.

    Return Value

    The indexes whose corresponding values in the array pass the test specified by predicate. If no objects in the array pass the test, returns an empty index set.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    Availability

    Available in iOS 4.0 and later.

  • Returns the index, within a specified range, of an object compared with elements in the array using a given NSComparator block.

    Declaration

    Swift

    func indexOfObject(_ obj: AnyObject, inSortedRange r: NSRange, options opts: NSBinarySearchingOptions, usingComparator cmp: NSComparator) -> Int

    Objective-C

    - (NSUInteger)indexOfObject:(ObjectType nonnull)obj inSortedRange:(NSRange)r options:(NSBinarySearchingOptions)opts usingComparator:(NSComparator nonnull)cmp

    Parameters

    obj

    An object for which to search in the array.

    If this value is nil, throws an NSInvalidArgumentException.

    r

    The range within the array to search for obj.

    If r exceeds the bounds of the array (if the location plus length of the range is greater than the count of the array), throws an NSRangeException.

    opts

    Options for the search. For possible values, see NSBinarySearchingOptions.

    If you specify both NSBinarySearchingFirstEqual and NSBinarySearchingLastEqual, throws an NSInvalidArgumentException.

    cmp

    A comparator block used to compare the object obj with elements in the array.

    If this value is NULL, throws an NSInvalidArgumentException.

    Return Value

    If the NSBinarySearchingInsertionIndex option is not specified:

    If the NSBinarySearchingInsertionIndex option is specified, returns the index at which you should insert obj in order to maintain a sorted array:

    • If the obj is found and neither NSBinarySearchingFirstEqual nor NSBinarySearchingLastEqual is specified, returns any equal or one larger index than any matching object’s index.

    • If the NSBinarySearchingFirstEqual option is also specified, returns the lowest index of equal objects.

    • If the NSBinarySearchingLastEqual option is also specified, returns the highest index of equal objects.

    • If the object is not found, returns the index of the least greater object, or the index at the end of the array if the object is larger than all other elements.

    Special Considerations

    The elements in the array must have already been sorted using the comparator cmp. If the array is not sorted, the result is undefined.

    Availability

    Available in iOS 4.0 and later.

  • Sends to each object in the array the message identified by a given selector, starting with the first object and continuing through the array to the last object.

    Declaration

    Objective-C

    - (void)makeObjectsPerformSelector:(SEL nonnull)aSelector

    Parameters

    aSelector

    A selector that identifies the message to send to the objects in the array. The method must not take any arguments, and must not have the side effect of modifying the receiving array.

    Discussion

    This method raises an NSInvalidArgumentException if aSelector is NULL.

    Availability

    Available in iOS 2.0 and later.

  • Sends the aSelector message to each object in the array, starting with the first object and continuing through the array to the last object.

    Declaration

    Objective-C

    - (void)makeObjectsPerformSelector:(SEL nonnull)aSelector withObject:(id nullable)anObject

    Parameters

    aSelector

    A selector that identifies the message to send to the objects in the array. The method must take a single argument of type id, and must not have the side effect of modifying the receiving array.

    anObject

    The object to send as the argument to each invocation of the aSelector method.

    Discussion

    This method raises an NSInvalidArgumentException if aSelector is NULL.

    Availability

    Available in iOS 2.0 and later.

  • Executes a given block using each object in the array, starting with the first object and continuing through the array to the last object.

    Declaration

    Swift

    func enumerateObjectsUsingBlock(_ block: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateObjectsUsingBlock:(void (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))block

    Parameters

    block

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    Discussion

    If the Block parameter is nil this method will raise an exception. Values allocated within the block will be deallocated after the block is executed. Use retain to explicitly maintain those values.

    This method executes synchronously.

    Availability

    Available in iOS 4.0 and later.

  • Executes a given block using each object in the array.

    Declaration

    Swift

    func enumerateObjectsWithOptions(_ opts: NSEnumerationOptions, usingBlock block: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateObjectsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))block

    Parameters

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    block

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last object. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    This method executes synchronously.

    Availability

    Available in iOS 4.0 and later.

  • Executes a given block using the objects in the array at the specified indexes.

    Declaration

    Swift

    func enumerateObjectsAtIndexes(_ s: NSIndexSet, options opts: NSEnumerationOptions, usingBlock block: (AnyObject, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateObjectsAtIndexes:(NSIndexSet * nonnull)indexSet options:(NSEnumerationOptions)opts usingBlock:(void (^ nonnull)(ObjectType nonnull obj, NSUInteger idx, BOOL * nonnull stop))block

    Parameters

    indexSet

    The indexes of the objects over which to enumerate.

    opts

    A bit mask that specifies the options for the enumeration (whether it should be performed concurrently and whether it should be performed in reverse order).

    block

    The block to apply to elements in the array.

    The block takes three arguments:

    obj

    The element in the array.

    idx

    The index of the element in the array.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    Discussion

    By default, the enumeration starts with the first object and continues serially through the array to the last element specified by indexSet. You can specify NSEnumerationConcurrent and/or NSEnumerationReverse as enumeration options to modify this behavior.

    This method executes synchronously.

    Availability

    Available in iOS 4.0 and later.

  • Returns the first object contained in the receiving array that’s equal to an object in another given array.

    Declaration

    Swift

    func firstObjectCommonWithArray(_ otherArray: [AnyObject]) -> AnyObject?

    Objective-C

    - (ObjectType nullable)firstObjectCommonWithArray:(NSArray<ObjectType> * nonnull)otherArray

    Parameters

    otherArray

    An array.

    Return Value

    Returns the first object contained in the receiving array that’s equal to an object in otherArray. If no such object is found, returns nil.

    Discussion

    This method uses isEqual: to check for object equality.

    Availability

    Available in iOS 2.0 and later.

  • Compares the receiving array to another array.

    Declaration

    Swift

    func isEqualToArray(_ otherArray: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)isEqualToArray:(NSArray<ObjectType> * nonnull)otherArray

    Parameters

    otherArray

    An array.

    Return Value

    YEStrue if the contents of otherArray are equal to the contents of the receiving array, otherwise NOfalse.

    Discussion

    Two arrays have equal contents if they each hold the same number of objects and objects at a given index in each array satisfy the isEqual: test.

    Availability

    Available in iOS 2.0 and later.

  • Returns a new array that is a copy of the receiving array with a given object added to the end.

    Declaration

    Swift

    func arrayByAddingObject(_ anObject: AnyObject) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)arrayByAddingObject:(ObjectType nonnull)anObject

    Parameters

    anObject

    An object.

    Return Value

    A new array that is a copy of the receiving array with anObject added to the end.

    Discussion

    If anObject is nil, an NSInvalidArgumentException is raised.

    Availability

    Available in iOS 2.0 and later.

    See Also

    addObject: (NSMutableArray)

  • Returns a new array that is a copy of the receiving array with the objects contained in another array added to the end.

    Declaration

    Swift

    func arrayByAddingObjectsFromArray(_ otherArray: [AnyObject]) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)arrayByAddingObjectsFromArray:(NSArray<ObjectType> * nonnull)otherArray

    Parameters

    otherArray

    An array.

    Return Value

    A new array that is a copy of the receiving array with the objects contained in otherArray added to the end.

    Availability

    Available in iOS 2.0 and later.

    See Also

    addObjectsFromArray: (NSMutableArray)

  • Evaluates a given predicate against each object in the receiving array and returns a new array containing the objects for which the predicate returns true.

    Declaration

    Swift

    func filteredArrayUsingPredicate(_ predicate: NSPredicate) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)filteredArrayUsingPredicate:(NSPredicate * nonnull)predicate

    Parameters

    predicate

    The predicate against which to evaluate the receiving array’s elements.

    Return Value

    A new array containing the objects in the receiving array for which predicate returns true.

    Discussion

    For more details, see Predicate Programming Guide.

    Availability

    Available in iOS 3.0 and later.

  • Returns a new array containing the receiving array’s elements that fall within the limits specified by a given range.

    Declaration

    Swift

    func subarrayWithRange(_ range: NSRange) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)subarrayWithRange:(NSRange)range

    Parameters

    range

    A range within the receiving array’s range of elements.

    Return Value

    A new array containing the receiving array’s elements that fall within the limits specified by range.

    Discussion

    If range isn’t within the receiving array’s range of elements, an NSRangeException is raised.

    For example, the following code example creates an array containing the elements found in the first half of wholeArray (assuming wholeArray exists).

    1. NSArray *halfArray;
    2. NSRange theRange;
    3. theRange.location = 0;
    4. theRange.length = [wholeArray count] / 2;
    5. halfArray = [wholeArray subarrayWithRange:theRange];

    Availability

    Available in iOS 2.0 and later.

  • Analyzes the array and returns a “hint” that speeds the sorting of the array when the hint is supplied to sortedArrayUsingFunction:context:hint:. (read-only)

    Declaration

    Swift

    @NSCopying var sortedArrayHint: NSData { get }

    Objective-C

    @property(readonly, copy) NSData *sortedArrayHint

    Availability

    Available in iOS 2.0 and later.

  • Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator.

    Declaration

    Swift

    func sortedArrayUsingFunction(_ comparator: (AnyObject, AnyObject, UnsafeMutablePointer<Void>) -> Int, context context: UnsafeMutablePointer<Void>) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayUsingFunction:(NSInteger (* nonnull)(ObjectType nonnull, ObjectType nonnull, void * nullable))comparator context:(void * nullable)context

    Discussion

    The new array contains references to the receiving array’s elements, not copies of them.

    The comparison function is used to compare two elements at a time and should return NSOrderedAscending if the first element is smaller than the second, NSOrderedDescending if the first element is larger than the second, and NSOrderedSame if the elements are equal. Each time the comparison function is called, it’s passed context as its third argument. This allows the comparison to be based on some outside parameter, such as whether character sorting is case-sensitive or case-insensitive.

    Given anArray (an array of NSNumber objects) and a comparison function of this type:

    1. NSInteger intSort(id num1, id num2, void *context)
    2. {
    3. int v1 = [num1 intValue];
    4. int v2 = [num2 intValue];
    5. if (v1 < v2)
    6. return NSOrderedAscending;
    7. else if (v1 > v2)
    8. return NSOrderedDescending;
    9. else
    10. return NSOrderedSame;
    11. }

    A sorted version of anArray is created in this way:

    1. NSArray *sortedArray; sortedArray = [anArray sortedArrayUsingFunction:intSort context:NULL];

    Availability

    Available in iOS 2.0 and later.

  • Returns a new array that lists the receiving array’s elements in ascending order as defined by the comparison function comparator.

    Declaration

    Swift

    func sortedArrayUsingFunction(_ comparator: (AnyObject, AnyObject, UnsafeMutablePointer<Void>) -> Int, context context: UnsafeMutablePointer<Void>, hint hint: NSData?) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayUsingFunction:(NSInteger (* nonnull)(ObjectType nonnull, ObjectType nonnull, void * nullable))comparator context:(void * nullable)context hint:(NSData * nullable)hint

    Discussion

    The new array contains references to the receiving array’s elements, not copies of them.

    This method is similar to sortedArrayUsingFunction:context:, except that it uses the supplied hint to speed the sorting process. When you know the array is nearly sorted, this method is faster than sortedArrayUsingFunction:context:. If you sorted a large array (N entries) once, and you don’t change it much (P additions and deletions, where P is much smaller than N), then you can reuse the work you did in the original sort by conceptually doing a merge sort between the N “old” items and the P “new” items.

    To obtain an appropriate hint, use sortedArrayHint. You should obtain this hint when the original array has been sorted, and keep hold of it until you need it, after the array has been modified. The hint is computed by sortedArrayHint in O(N) (where N is the number of items). This assumes that items in the array implement a -hash method. Given a suitable hint, and assuming that the hash function is a “good” hash function, -sortedArrayUsingFunction:context:hint: sorts the array in O(P*LOG(P)+N) where P is the number of adds or deletes. This is an improvement over the un-hinted sort, O(N*LOG(N)), when P is small.

    The hint is simply an array of size N containing the N hashes. To re-sort you need internally to create a map table mapping a hash to the index. Using this map table on the new array, you can get a first guess for the indices, and then sort that. For example, a sorted array {A, B, D, E, F} with corresponding hash values {25, 96, 78, 32, 17}, may be subject to small changes that result in contents {E, A, C, B, F}. The mapping table maps the hashes {25, 96, 78, 32, 17} to the indices {#0, #1, #2, #3, #4}. If the hashes for {E, A, C, B, F} are {32, 25, 99, 96, 17}, then by using the mapping table you can get a first order sort {#3, #0, ?, #1, #4}, so therefore create an initial semi-sorted array {A, B, E, F}, and then perform a cheap merge sort with {C} that yields {A, B, C, E, F}.

    Availability

    Available in iOS 2.0 and later.

  • Returns a copy of the receiving array sorted as specified by a given array of sort descriptors.

    Declaration

    Swift

    func sortedArrayUsingDescriptors(_ sortDescriptors: [NSSortDescriptor]) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayUsingDescriptors:(NSArray<NSSortDescriptor *> * nonnull)sortDescriptors

    Parameters

    sortDescriptors

    An array of NSSortDescriptor objects.

    Return Value

    A copy of the receiving array sorted as specified by sortDescriptors.

    Discussion

    The first descriptor specifies the primary key path to be used in sorting the receiving array’s contents. Any subsequent descriptors are used to further refine sorting of objects with duplicate values. See NSSortDescriptor for additional information.

    Availability

    Available in iOS 2.0 and later.

  • Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given selector.

    Declaration

    Swift

    func sortedArrayUsingSelector(_ comparator: Selector) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayUsingSelector:(SEL nonnull)comparator

    Parameters

    comparator

    A selector that identifies the method to use to compare two elements at a time. The method should return NSOrderedAscending if the receiving array is smaller than the argument, NSOrderedDescending if the receiving array is larger than the argument, and NSOrderedSame if they are equal.

    Return Value

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by the selector comparator.

    Discussion

    The new array contains references to the receiving array’s elements, not copies of them.

    The comparator message is sent to each object in the array and has as its single argument another object in the array.

    For example, an array of NSString objects can be sorted by using the caseInsensitiveCompare: method declared in the NSString class. Assuming anArray exists, a sorted version of the array can be created in this way:

    1. NSArray *sortedArray =
    2. [anArray sortedArrayUsingSelector:@selector(caseInsensitiveCompare:)];

    Availability

    Available in iOS 2.0 and later.

  • Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator Block.

    Declaration

    Swift

    func sortedArrayUsingComparator(_ cmptr: NSComparator) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayUsingComparator:(NSComparator nonnull)cmptr

    Parameters

    cmptr

    A comparator block.

    Return Value

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified cmptr.

    Availability

    Available in iOS 4.0 and later.

  • Returns an array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified by a given NSComparator Block.

    Declaration

    Swift

    func sortedArrayWithOptions(_ opts: NSSortOptions, usingComparator cmptr: NSComparator) -> [AnyObject]

    Objective-C

    - (NSArray<ObjectType> * nonnull)sortedArrayWithOptions:(NSSortOptions)opts usingComparator:(NSComparator nonnull)cmptr

    Parameters

    opts

    A bit mask that specifies the options for the sort (whether it should be performed concurrently and whether it should be performed stably).

    cmptr

    A comparator block.

    Return Value

    An array that lists the receiving array’s elements in ascending order, as determined by the comparison method specified cmptr.

    Availability

    Available in iOS 4.0 and later.

  • Constructs and returns an NSString object that is the result of interposing a given separator between the elements of the array.

    Declaration

    Swift

    func componentsJoinedByString(_ separator: String) -> String

    Objective-C

    - (NSString * nonnull)componentsJoinedByString:(NSString * nonnull)separator

    Parameters

    separator

    The string to interpose between the elements of the array.

    Return Value

    An NSString object that is the result of interposing separator between the elements of the array. If the array has no elements, returns an NSString object representing an empty string.

    Discussion

    For example, this code excerpt writes "here be dragons" to the console:

    1. NSArray *pathArray = [NSArray arrayWithObjects:@"here", @"be", @"dragons", nil];
    2. NSLog(@"%@",[pathArray componentsJoinedByString:@" "]);

    Special Considerations

    Each element in the array must handle description.

    Availability

    Available in iOS 2.0 and later.

    See Also

    componentsSeparatedByString: (NSString)

  • A string that represents the contents of the array, formatted as a property list. (read-only)

    Declaration

    Swift

    var description: String { get }

    Objective-C

    @property(readonly, copy) NSString *description

    Availability

    Available in iOS 2.0 and later.

  • Returns a string that represents the contents of the array, formatted as a property list.

    Declaration

    Swift

    func descriptionWithLocale(_ locale: AnyObject?) -> String

    Objective-C

    - (NSString * nonnull)descriptionWithLocale:(id nullable)locale

    Parameters

    locale

    An NSLocale object or an NSDictionary object that specifies options used for formatting each of the array’s elements (where recognized). Specify nil if you don’t want the elements formatted.

    Return Value

    A string that represents the contents of the array, formatted as a property list.

    Discussion

    For a description of how locale is applied to each element in the receiving array, see descriptionWithLocale:indent:.

    Availability

    Available in iOS 2.0 and later.

  • Returns a string that represents the contents of the array, formatted as a property list.

    Declaration

    Swift

    func descriptionWithLocale(_ locale: AnyObject?, indent level: Int) -> String

    Objective-C

    - (NSString * nonnull)descriptionWithLocale:(id nullable)locale indent:(NSUInteger)level

    Parameters

    locale

    An NSLocale object or an NSDictionary object that specifies options used for formatting each of the array’s elements (where recognized). Specify nil if you don’t want the elements formatted.

    level

    A level of indent, to make the output more readable: set level to 0 to use four spaces to indent, or 1 to indent the output with a tab character.

    Return Value

    A string that represents the contents of the array, formatted as a property list.

    Discussion

    The returned NSString object contains the string representations of each of the array’s elements, in order, from first to last. To obtain the string representation of a given element, descriptionWithLocale:indent: proceeds as follows:

    • If the element is an NSString object, it is used as is.

    • If the element responds to descriptionWithLocale:indent:, that method is invoked to obtain the element’s string representation.

    • If the element responds to descriptionWithLocale:, that method is invoked to obtain the element’s string representation.

    • If none of the above conditions is met, the element’s string representation is obtained by invoking its description method.

    Availability

    Available in iOS 2.0 and later.

  • Writes the contents of the array to a file at a given path.

    Declaration

    Swift

    func writeToFile(_ path: String, atomically useAuxiliaryFile: Bool) -> Bool

    Objective-C

    - (BOOL)writeToFile:(NSString * nonnull)path atomically:(BOOL)flag

    Parameters

    path

    The path at which to write the contents of the array.

    If path contains a tilde (~) character, you must expand it with stringByExpandingTildeInPath before invoking this method.

    flag

    If YEStrue, the array is written to an auxiliary file, and then the auxiliary file is renamed to path. If NOfalse, the array is written directly to path. The YEStrue option guarantees that path, if it exists at all, won’t be corrupted even if the system should crash during writing.

    Return Value

    YEStrue if the file is written successfully, otherwise NOfalse.

    Discussion

    If the array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the file written by this method can be used to initialize a new array with the class method arrayWithContentsOfFile: or the instance method initWithContentsOfFile:. This method recursively validates that all the contained objects are property list objects before writing out the file, and returns NOfalse if all the objects are not property list objects, since the resultant file would not be a valid property list.

    Availability

    Available in iOS 2.0 and later.

  • Writes the contents of the array to the location specified by a given URL.

    Declaration

    Swift

    func writeToURL(_ url: NSURL, atomically atomically: Bool) -> Bool

    Objective-C

    - (BOOL)writeToURL:(NSURL * nonnull)aURL atomically:(BOOL)flag

    Parameters

    aURL

    The location at which to write the array.

    flag

    If YEStrue, the array is written to an auxiliary location, and then the auxiliary location is renamed to aURL. If NOfalse, the array is written directly to aURL. The YEStrue option guarantees that aURL, if it exists at all, won’t be corrupted even if the system should crash during writing.

    Return Value

    YEStrue if the location is written successfully, otherwise NOfalse.

    Discussion

    If the array’s contents are all property list objects (NSString, NSData, NSArray, or NSDictionary objects), the location written by this method can be used to initialize a new array with the class method arrayWithContentsOfURL: or the instance method initWithContentsOfURL:.

    Availability

    Available in iOS 2.0 and later.

  • Returns an array containing all the pathname elements in the receiving array that have filename extensions from a given array.

    Declaration

    Swift

    func pathsMatchingExtensions(_ filterTypes: [String]) -> [String]

    Objective-C

    - (NSArray<NSString *> * nonnull)pathsMatchingExtensions:(NSArray<NSString *> * nonnull)filterTypes

    Parameters

    filterTypes

    An array of NSString objects containing filename extensions. The extensions should not include the dot (“.”) character.

    Return Value

    An array containing all the pathname elements in the receiving array that have filename extensions from the filterTypes array.

    Availability

    Available in iOS 2.0 and later.

  • Invokes setValue:forKey: on each of the array's items using the specified value and key.

    Declaration

    Swift

    func setValue(_ value: AnyObject?, forKey key: String)

    Objective-C

    - (void)setValue:(id nullable)value forKey:(NSString * nonnull)key

    Parameters

    value

    The object value.

    key

    The key to store the value.

    Availability

    Available in iOS 2.0 and later.

  • Returns an array containing the results of invoking valueForKey: using key on each of the array's objects.

    Declaration

    Swift

    func valueForKey(_ key: String) -> AnyObject

    Objective-C

    - (id nonnull)valueForKey:(NSString * nonnull)key

    Parameters

    key

    The key to retrieve.

    Return Value

    The value of the retrieved key.

    Discussion

    The returned array contains NSNull elements for each object that returns nil.

    Availability

    Available in iOS 2.0 and later.

  • Options for searches and insertions using indexOfObject:inSortedRange:options:usingComparator:.

    Declaration

    Swift

    struct NSBinarySearchingOptions : OptionSetType { init(rawValue rawValue: UInt) static var FirstEqual: NSBinarySearchingOptions { get } static var LastEqual: NSBinarySearchingOptions { get } static var InsertionIndex: NSBinarySearchingOptions { get } }

    Objective-C

    enum { NSBinarySearchingFirstEqual = (1 << 8), NSBinarySearchingLastEqual = (1 << 9), NSBinarySearchingInsertionIndex = (1 << 10), }; typedef NSUInteger NSBinarySearchingOptions;

    Constants

    • FirstEqual

      NSBinarySearchingFirstEqual

      Specifies that the search should return the first object in the range that is equal to the given object.

      Available in iOS 4.0 and later.

    • LastEqual

      NSBinarySearchingLastEqual

      Specifies that the search should return the last object in the range that is equal to the given object.

      Available in iOS 4.0 and later.

    • InsertionIndex

      NSBinarySearchingInsertionIndex

      Returns the index at which you should insert the object in order to maintain a sorted array.

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 4.0 and later.