Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

NSArray Class Reference

Overview

NSArray and its subclass NSMutableArray manage collections of objects called arrays. NSArray creates static arrays, and NSMutableArray creates dynamic arrays.

NSArray and NSMutableArray are part of a class cluster, so arrays are not actual instances of the NSArray or NSMutableArray classes but of one of their private subclasses. Although an array’s class is private, its interface is public, as declared by these abstract superclasses, NSArray and NSMutableArray.

Generally, you instantiate an array by sending one of the array... messages to either the NSArray or NSMutableArray class object. These methods return an array containing the elements you pass in as arguments. (Note that arrays can’t contain nil.) In general, objects that you add to an array aren’t copied; rather, each object receives a retain message before its id is added to the array. When an object is removed from an array, it’s sent a release message.

The NSArray and NSMutableArray classes adopt the NSCopying and NSMutableCopying protocols, making it convenient to convert an array of one type to the other.

NSArray’s two primitive methods—count and objectAtIndex:—provide the basis for all other methods in its interface. The count method returns the number of elements in the array; objectAtIndex: gives you access to the array elements by index, with index values starting at 0.

The methods objectEnumerator and reverseObjectEnumerator also grant sequential access to the elements of the array, differing only in the direction of travel through the elements. These methods are provided so that arrays can be traversed in a manner similar to that used for objects of other collection classes, such as NSDictionary. See the objectEnumerator method description for a code excerpt that shows how to use these methods to access the elements of an array. In Mac OS X v10.5 and later, it is more efficient to use the fast enumeration protocol (see NSFastEnumeration).

NSArray provides methods for querying the elements of the array. The indexOfObject: method searches the array for the object that matches its argument. To determine whether the search is successful, each element of the array is sent an isEqual: message, as declared in the NSObject protocol. Another method, indexOfObjectIdenticalTo:, is provided for the less common case of determining whether a specific object is present in the array. The indexOfObjectIdenticalTo: method tests each element in the array to see whether its id matches that of the argument.

NSArray’s filteredArrayUsingPredicate: method allows you to create a new array from an existing array filtered using a predicate (see Predicate Programming Guide).

NSArray’s makeObjectsPerformSelector: and makeObjectsPerformSelector:withObject: methods let you send messages to all objects in the array. To act on the array as a whole, a variety of other methods are defined. You can create a sorted version of the array (sortedArrayUsingSelector: and sortedArrayUsingFunction:context:, extract a subset of the array (subarrayWithRange:), or concatenate the elements of an array of NSString objects into a single string (componentsJoinedByString:). In addition, you can compare two arrays using the isEqualToArray: and firstObjectCommonWithArray: methods. Finally, you can create new arrays that contain the objects in an existing array and one or more additional objects with arrayByAddingObject: and arrayByAddingObjectsFromArray:.

NSArray is “toll-free bridged” with its Core Foundation counterpart, CFArray. What this means is that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object, providing you cast one type to the other. Therefore, in an API where you see an NSArray * parameter, you can pass in a CFArrayRef, and in an API where you see a CFArrayRef parameter, you can pass in an NSArray instance. This arrangement also applies to your concrete subclasses of NSArray. See Carbon-Cocoa Integration Guide for more information on toll-free bridging.

Subclassing Notes

Most developers would not have any 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.

• Changing how NSArray retains and releases its elements.

• 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. The NSArray class does not have a designated initializer, so your initializer need only invoke the init method of super. 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. The primitive methods of NSArray do not include any designated initializers. This means that you must provide the storage for your subclass and implement the primitive methods that directly act on that storage.

Special Considerations

In most cases your custom NSArray class should conform to Cocoa’s object-ownership conventions. Thus you must send retain to each object that you add to your collection and release to each object that you remove from the collection. Of course, if the reason for subclassing NSArray is to implement object-retention behavior different from the norm (for example, a non-retaining array), then you can ignore this requirement.

Alternatives to Subclassing

Before making a custom class of NSArray, investigate the corresponding Core Foundation type, CFArray. 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.

Adopted Protocols

• – encodeWithCoder:

• – initWithCoder:

• – copyWithZone:

• – mutableCopyWithZone:

Tasks

Creating an Array

• + array
• + arrayWithArray:
• + arrayWithContentsOfFile:
• + arrayWithContentsOfURL:
• + arrayWithObject:
• + arrayWithObjects:
• + arrayWithObjects:count:

Initializing an Array

• – initWithArray:
• – initWithArray:copyItems:
• – initWithContentsOfFile:
• – initWithContentsOfURL:
• – initWithObjects:
• – initWithObjects:count:

Querying an Array

• – containsObject:
• – count
• – getObjects:
• – getObjects:range:
• – indexOfObject:
• – indexOfObject:inRange:
• – indexOfObjectIdenticalTo:
• – indexOfObjectIdenticalTo:inRange:
• – lastObject
• – objectAtIndex:
• – objectsAtIndexes:
• – objectEnumerator
• – reverseObjectEnumerator

Sending Messages to Elements

• – makeObjectsPerformSelector:
• – makeObjectsPerformSelector:withObject:

Comparing Arrays

• – firstObjectCommonWithArray:
• – isEqualToArray:

Deriving New Arrays

• – arrayByAddingObject:
• – arrayByAddingObjectsFromArray:
• – filteredArrayUsingPredicate:
• – subarrayWithRange:

Sorting

• – sortedArrayHint
• – sortedArrayUsingFunction:context:
• – sortedArrayUsingFunction:context:hint:
• – sortedArrayUsingDescriptors:
• – sortedArrayUsingSelector:

Working with String Elements

• – componentsJoinedByString:

Creating a Description

• – description
• – descriptionWithLocale:
• – descriptionWithLocale:indent:
• – writeToFile:atomically:
• – writeToURL:atomically:

Collecting Paths

• – pathsMatchingExtensions:

Key-Value Observing

• – addObserver:forKeyPath:options:context:
• – removeObserver:forKeyPath:
• – addObserver:toObjectsAtIndexes:forKeyPath:options:context:
• – removeObserver:fromObjectsAtIndexes:forKeyPath:

Key-Value Coding

• – setValue:forKey:
• – valueForKey:

Class Methods

array

Creates and returns an empty array.

+ (id)array

Return Value

An empty array.

Discussion

This method is used by mutable subclasses of NSArray.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithObject:
• + arrayWithObjects:

Declared In

arrayWithArray:

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

+ (id)arrayWithArray:(NSArray *)anArray

Parameters

anArray

An array.

Return Value

An array containing the objects in anArray.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithObjects:
• – initWithObjects:

Declared In

arrayWithContentsOfFile:

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

+ (id)arrayWithContentsOfFile:(NSString *)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, NSArray, or NSDictionary objects).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – writeToFile:atomically:

Declared In

arrayWithContentsOfURL:

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

+ (id)arrayWithContentsOfURL:(NSURL *)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).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – writeToURL:atomically:

Declared In

arrayWithObject:

Creates and returns an array containing a given object.

+ (id)arrayWithObject:(id)anObject

Parameters

anObject

An object.

Return Value

An array containing the single element anObject.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + array
• + arrayWithObjects:

Declared In

arrayWithObjects:

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

+ (id)arrayWithObjects:(id)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:

NSArray *myArray;

NSDate *aDate = [NSDate distantFuture];

NSValue *aValue = [NSNumber numberWithInt:5];

NSString *aString = @"a string";

myArray = [NSArray arrayWithObjects:aDate, aValue, aString, nil];

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + array
• + arrayWithObject:

Declared In

arrayWithObjects:count:

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

+ (id)arrayWithObjects:(const id *)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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getObjects:
• – getObjects:range:

Declared In

Instance Methods

addObserver:forKeyPath:options:context:

Raises an exception.

- (void)addObserver:(NSObject *)observerforKeyPath:(NSString *)keyPathoptions:(NSKeyValueObservingOptions)optionscontext:(void *)context

Parameters

observer

The object to register for KVO notifications. The observer must implement the key-value observing method observeValueForKeyPath:ofObject:change:context:.

keyPath

The key path, relative to the receiver, of the property to observe. This value must not be nil.

options

A combination of the NSKeyValueObservingOptions values that specifies what is included in observation notifications. For possible values, see NSKeyValueObservingOptions.

context

Arbitrary data that is passed to observer in observeValueForKeyPath:ofObject:change:context:.

Special Considerations

NSArray objects are not observable, so this method raises an exception when invoked on an NSArray object. Instead of observing an array, observe the to-many relationship for which the array is the collection of related objects.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – removeObserver:forKeyPath:
• – addObserver:toObjectsAtIndexes:forKeyPath:options:context:

Declared In

addObserver:toObjectsAtIndexes:forKeyPath:options:context:

Registers anObserver to receive key value observer notifications for the specified keypath relative to the objects at indexes.

- (void)addObserver:(NSObject *)anObserver toObjectsAtIndexes:(NSIndexSet *)indexes forKeyPath:(NSString *)keyPath options:(NSKeyValueObservingOptions)options context:(void *)context

Discussion

The options determine what is included in the notifications, and the context is passed in the notifications.

This is not merely a convenience method; invoking this method is potentially much faster than repeatedly invoking addObserver:forKeyPath:options:context:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeObserver:fromObjectsAtIndexes:forKeyPath:

Declared In

arrayByAddingObject:

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

- (NSArray *)arrayByAddingObject:(id)anObject

Parameters

anObject

An object.

Return Value

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

Discussion

If anObject is nil, an NSInvalidArgumentException is raised.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addObject: (NSMutableArray)

Declared In

arrayByAddingObjectsFromArray:

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

- (NSArray *)arrayByAddingObjectsFromArray:(NSArray *)otherArray

Parameters

otherArray

An array.

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addObjectsFromArray: (NSMutableArray)

Declared In

componentsJoinedByString:

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

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

Parameters

separator

The string to interpose between the elements of the receiver’s array.

Return Value

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

Discussion

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

NSArray *pathArray = [NSArray arrayWithObjects:@"here",

    @"be", @"dragons", nil];

NSLog(@"%@",

    [pathArray componentsJoinedByString:@" "]);

Special Considerations

Each element in the receiver’s array must handle description.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – componentsSeparatedByString: (NSString)

Declared In

containsObject:

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

- (BOOL)containsObject:(id)anObject

Parameters

anObject

An object.

Return Value

YES if anObject is present in the receiver, otherwise NO.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfObject:
• – indexOfObjectIdenticalTo:

Declared In

count

Returns the number of objects currently in the receiver.

- (NSUInteger)count

Return Value

The number of objects currently in the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectAtIndex:

Declared In

description

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

- (NSString *)description

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – descriptionWithLocale:
• – descriptionWithLocale:indent:

Declared In

descriptionWithLocale:

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

- (NSString *)descriptionWithLocale:(id)locale

Parameters

locale

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

Return Value

A string that represents the contents of the receiver, 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 Mac OS X v10.0 and later.

See Also

• – description
• – descriptionWithLocale:indent:

Declared In

descriptionWithLocale:indent:

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

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

Parameters

locale

An NSLocale object or an NSDictionary object that specifies options used for formatting each of the receiver’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 receiver, formatted as a property list.

Discussion

The returned NSString object contains the string representations of each of the receiver’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 Mac OS X v10.0 and later.

See Also

• – description
• – descriptionWithLocale:

Declared In

filteredArrayUsingPredicate:

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

- (NSArray *)filteredArrayUsingPredicate:(NSPredicate *)predicate

Parameters

predicate

The predicate against which to evaluate the receiver’s elements.

Return Value

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

Discussion

For more details, see Predicate Programming Guide.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

firstObjectCommonWithArray:

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

- (id)firstObjectCommonWithArray:(NSArray *)otherArray

Parameters

otherArray

An array.

Return Value

Returns the first object contained in the receiver 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 Mac OS X v10.0 and later.

See Also

• – containsObject:

Declared In

getObjects:

Copies all the objects contained in the receiver to aBuffer.

- (void)getObjects:(id *)aBuffer

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithObjects:count:

Declared In

getObjects:range:

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

- (void)getObjects:(id *)aBuffer range:(NSRange)aRange

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithObjects:count:

Declared In

indexOfObject:

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

- (NSUInteger)indexOfObject:(id)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 receiver is equal to anObject, returns NSNotFound.

Discussion

Objects are considered equal if isEqual: returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containsObject:
• – indexOfObjectIdenticalTo:

Declared In

indexOfObject:inRange:

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

- (NSUInteger)indexOfObject:(id)anObject inRange:(NSRange)range

Parameters

anObject

An object.

range

The range of indexes in the receiver 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

Objects are considered equal if isEqual: returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containsObject:
• – indexOfObjectIdenticalTo:inRange:

Declared In

indexOfObjectIdenticalTo:

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

- (NSUInteger)indexOfObjectIdenticalTo:(id)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 receiver is identical to anObject, returns NSNotFound.

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – containsObject:
• – indexOfObject:

Declared In

indexOfObjectIdenticalTo:inRange:

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

- (NSUInteger)indexOfObjectIdenticalTo:(id)anObject inRange:(NSRange)range

Parameters

anObject

An object.

range

The range of indexes in the receiver 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 Mac OS X v10.0 and later.

See Also

• – containsObject:
• – indexOfObject:inRange:

Declared In

initWithArray:

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

- (id)initWithArray:(NSArray *)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

In a managed memory environment, each object in anArray receives a retain message as it’s added to the array. After an immutable array has been initialized in this way, it cannot be modified.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithObject:
• – initWithObjects:

Declared In

initWithArray:copyItems:

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

- (id)initWithArray:(NSArray *)array copyItems:(BOOL)flag

Parameters

array

An array.

flag

If YES, each object in array receives a copyWithZone message to create a copy of the object. The object copy is then added to the returned array. If NO, then in a managed memory environment each object in array receives a retain message as it’s added to the returned array.

Return Value

An array initialized to contain the objects—or if flag is YES, 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.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – initWithArray:
• + arrayWithObject:
• – initWithObjects:

Declared In

initWithContentsOfFile:

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

- (id)initWithContentsOfFile:(NSString *)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 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).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithContentsOfFile:
• – writeToFile:atomically:

Declared In

initWithContentsOfURL:

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

- (id)initWithContentsOfURL:(NSURL *)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).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + arrayWithContentsOfURL:
• – writeToURL:atomically:

Declared In

initWithObjects:

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

- (id)initWithObjects:(id)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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – initWithObjects:count:
• + arrayWithObjects:
• – initWithArray:

Declared In

initWithObjects:count:

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

- (id)initWithObjects:(const id *)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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – initWithObjects:
• + arrayWithObjects:
• – initWithArray:

Declared In

isEqualToArray:

Compares the receiving array to another array.

- (BOOL)isEqualToArray:(NSArray *)otherArray

Parameters

otherArray

An array.

Return Value

YES if the contents of otherArray are equal to the contents of the receiver, otherwise NO.

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 Mac OS X v10.0 and later.

Declared In

lastObject

Returns the object in the array with the highest index value.

- (id)lastObject

Return Value

The object in the array with the highest index value. If the array is empty, returns nil.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – removeLastObject (NSMutableArray)

Declared In

makeObjectsPerformSelector:

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

- (void)makeObjectsPerformSelector:(SEL)aSelector

Parameters

aSelector

A selector that identifies the message to send to the objects in the receiver. 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 Mac OS X v10.0 and later.

See Also

• – makeObjectsPerformSelector:withObject:

Declared In

makeObjectsPerformSelector:withObject:

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

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

Parameters

aSelector

A selector that identifies the message to send to the objects in the receiver. 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 Mac OS X v10.0 and later.

See Also

• – makeObjectsPerformSelector:

Declared In

objectAtIndex:

Returns the object located at index.

- (id)objectAtIndex:(NSUInteger)index

Parameters

index

An index within the bounds of the receiver.

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 Mac OS X v10.0 and later.

See Also

• – count
• – objectsAtIndexes:

Declared In

objectEnumerator

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

- (NSEnumerator *)objectEnumerator

Return Value

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

Discussion

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

NSEnumerator *enumerator = [myArray objectEnumerator];

id anObject;

while (anObject = [enumerator nextObject]) {

    /* code to act on each element as it is returned */

}

Special Considerations

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

On Mac OS X v10.5 and later, it is more efficient to use the fast enumeration protocol (see NSFastEnumeration).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – reverseObjectEnumerator
• – nextObject (NSEnumerator)

Declared In

objectsAtIndexes:

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

- (NSArray *)objectsAtIndexes:(NSIndexSet *)indexes

Return Value

An array containing the objects in the receiver 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 exception if any location in indexes exceeds the bounds of the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – count
• – objectAtIndex:

Declared In

pathsMatchingExtensions:

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

- (NSArray *)pathsMatchingExtensions:(NSArray *)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 receiver that have filename extensions from the filterTypes array.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

removeObserver:forKeyPath:

Raises an exception.

- (void)removeObserver:(NSObject *)observerforKeyPath:(NSString *)keyPath

Parameters

observer

The object to remove as an observer.

keyPath

A key-path, relative to the receiver, for which observer is registered to receive KVO change notifications. This value must not be nil.

Special Considerations

NSArray objects are not observable, so this method raises an exception when invoked on an NSArray object. Instead of observing an array, observe the to-many relationship for which the array is the collection of related objects.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – addObserver:forKeyPath:options:context:
• – removeObserver:fromObjectsAtIndexes:forKeyPath:

Declared In

removeObserver:fromObjectsAtIndexes:forKeyPath:

Removes anObserver from all key value observer notifications associated with the specified keyPath relative to the receiver’s objects at indexes.

- (void)removeObserver:(NSObject *)anObserver fromObjectsAtIndexes:(NSIndexSet *)indexes forKeyPath:(NSString *)keyPath

Discussion

This is not merely a convenience method; invoking this method is potentially much faster than repeatedly invoking removeObserver:forKeyPath:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – addObserver:toObjectsAtIndexes:forKeyPath:options:context:

Declared In

reverseObjectEnumerator

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

- (NSEnumerator *)reverseObjectEnumerator

Return Value

An enumerator object that lets you access each object in the receiver, 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.

On Mac OS X v10.5 and later, it is more efficient to use the fast enumeration protocol (see NSFastEnumeration).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectEnumerator
• – nextObject (NSEnumerator)

Declared In

setValue:forKey:

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