NSArray

Inherits From: NSObject

Conforms To: NSCoding, NSCopying, NSMutableCopying NSObject (NSObject)

Declared In: Foundation/NSArray.h

Class Description

The NSArray class declares the programmatic interface to an object that manages an immutable array of objects. (The complementary class NSMutableArray manages modifiable arrays of objects.) NSArray's two primitive methodscount and objectAtIndex:provide the basis for all the 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 permit sequential access of the elements of the array, differing only in the direction of travel through the elements. These methods are provided so that array objects can be traversed in a manner similar to that used for objects of other collection classes, such as NSDictionary.

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

NSArray provides methods for querying the elements of the array. indexOfObject: 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. indexOfObjectIdenticalTo: tests each element in the array to see whether its id matches that of the argument.

NSArray's makeObjectsPerform: and makeObjectsPerform:withObject: methods let you act on the individual objects in the array by sending them messages. To act on the array as a whole, a variety of 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 array objects using the isEqualToArray: and firstObjectCommonWithArray: methods.

Allocating and Initializing an Array

• + (id)allocWithZone:(NSZone *)zone Returns an uninitialized array object in zone.
• + (id)array Returns an empty array object
• + (id)arrayWithObject:(id)anObject Returns an NSArray containing the single element anObject. Raises an NSInvalidArgumentException if anObject is nil.
• + (id)arrayWithObjects:(id)firstObj,... Returns an NSArray containing the objects in the argument list. The object list is comma-separated and ends with nil.
• - (NSArray *)arrayByAddingObject:(id)anObject Returns an NSArray containing the receiver's elements plus anObject.
• - (NSArray *)arrayByAddingObjectsFromArray:(NSArray *)anotherArray Returns an NSArray containing the receiver's elements plus the elements from anotherArray.
• - (id)initWithArray:(NSArray *)anotherArray Initializes a newly allocated array object by placing in it the objects contained in anotherArray.
• - (id)initWithObjects:(id)firstObj,... Initializes a newly allocated array object by placing in it the objects in the argument list. The object list is comma-separated and ends with nil. Raises an NSInvalidArgumentException if any object in the list of objects is nil.
• - (id)initWithObjects:(id *)objects Initializes a newly allocated array object by placing in count:(unsigned int)count it count objects from the objects array

• - (BOOL)containsObject:(id)anObject Returns YES if anObject is present in the array.
• - (unsigned int)count Returns the number of objects currently in the array.
• - (unsigned int)indexOfObject:(id)anObject Returns the index of anObject, if found; otherwise, returns NSNotFound. This method checks the elements in the array from last to first by sending them an isEqual: message.
• - (unsigned int)indexOfObjectIdenticalTo:(id)anObject Returns the index of anObject, if found; otherwise, returns NSNotFound. This method checks the elements in the array from last to first by comparing their ids.
• - (id)lastObject Returns the last object in the array.
• - (id)objectAtIndex:(unsigned int)index Returns the object located at index. An array's index starts at 0. Raises an NSRangeException if index is beyond the end of the array.
• - (NSEnumerator *)objectEnumerator Returns an enumerator object that lets you access each object in the array, starting with the first element.
• - (NSEnumerator *)reverseObjectEnumerator Returns an enumerator object that lets you access each object in the array, from the last element to the first.

• - (void)makeObjectsPerform:(SEL)aSelector Sends an aSelector message to each object in the array.
• - (void)makeObjectsPerform:(SEL)aSelector Sends an aSelector message to each object in the withObject:(id)anObject array, with anObject as an argument.

• - (id)firstObjectCommonWithArray:(NSArray *)otherArray Returns the first object from the receiver's array that's equal to an object in otherArray.
• - (BOOL)isEqualToArray:(NSArray *)otherArray Compares the receiving array object to otherArray.

• - (NSArray *)sortedArrayUsingFunction:(int(*)(id element1, id element2, void *userData))comparator context:(void *)context Returns an array listing the receiver's elements in ascending order as defined by the comparison function comparator. context is passed to the comparator function as its third argument.
• - (NSArray *)sortedArrayUsingSelector:(SEL)comparator Returns an array listing the receiver's elements in ascending order, as determined by the comparison method specified by the selector comparator.
• - (NSArray *)subarrayWithRange:(NSRange)range Returns an array containing the receiver's elements that fall within the limits specified by range.

• - (NSString *)componentsJoinedByString:(NSString *)separator Returns a string that's the result of interposing separator between the elements of the receiver's array.

• - (NSString *)description Returns a string object that represents the contents of the receiver.
• - (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary Returns a string representation of the NSArray object. Included are the key and values that represent the locale data from localeDictionary.
• - (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary indent:(unsigned int)level Returns a string representation of the NSArray object. Included are the key and values that represent the locale data from localeDictionary. Elements of the array are indented from the left margin by level + 1 multiples of four spaces, to make the output more readable.