Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 methodsÐcount 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

Querying the 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.

Sending Messages to Elements

- (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.

Comparing Arrays

- (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. 

Deriving New Arrays

- (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.

Joining String Elements

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

Creating a String Description of the 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.