Commonly Used Array Methods

The following sections list the most commonly used NSArray and NSMutableArray methods. The methods covered are grouped in the following categories:

Creating Arrays

The methods in this section are class methods, as denoted by the plus sign (+). You use class methods to send messages to a class-in this case, NSArray and NSMutableArray. For more information on class methods, see "Messaging in WebScript" in the "Using WebScript" chapter.

+ array

Returns an empty array. Usually used to create NSMutableArrays. NSArrays created with this method are permanently empty.

// Most common use
id mutableArray = [NSMutableArray array];

// May not be what you want
id array = [NSArray array];

+ arrayWithObject:

Returns an array containing the single specified object.

+ arrayWithObjects:

Returns an array containing the objects in the argument list. The argument list is a comma-separated list of objects ending with nil.

id array = [NSMutableArray arrayWithObjects:
		@"Plates", @"Plasticware", @"Napkins", nil];

+ arrayWithArray:

Returns an array containing the contents of a specified array. Usually used to create an NSMutableArray from an immutable NSArray. For example, the following statement:

id mutableArray = [NSMutableArray arrayWithArray:@("A", "B", "C")];

creates an NSMutableArray from a constant NSArray object.

+ arrayWithContentsOfFile:

Returns an array initialized from the contents of a specified file. The specified file can be a full or relative pathname; the file that it names must contain a string representation of an array, such as that produced by the writeToFile:atomically: method. See also description.

Querying Arrays

- count: Returns the number of objects in the array.
- isEqual:: Returns YES if the specified object is an array and has contents equivalent to the receiver, NO otherwise. 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.
- objectAtIndex:: Returns the object located at a specified index. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. It is an error to specify an index that is out of bounds (greater than or equal to the array's count).
- indexOfObject:: Returns the index of the first object in the array that is equivalent to a specified object. To determine equality, each element of the array is sent an isEqual: message.
- indexOfObjectIdenticalTo:: Returns the index of the first occurrence of the a specified object. To determine equality, the ids of the two objects are compared.

Sorting Arrays

- sortedArrayUsingSelector:

Returns an NSArray that lists the receiver's elements in ascending order, as determined by a specified method. This method is used to sort arrays containing strings and/or numbers. For example, the following code excerpt:

id guestArray = @("Suzy", "Alice", "John", "Peggy", "David");
id sortedArray = [guestArray sortedArrayUsingSelector:@"compare:"];

creates the NSArray sortedArray containing the string "Alice" at index 0, "David" at index 1, and so on.

Adding and Removing Objects

Warning: The following methods are not supported by NSArray. They are only available to NSMutableArray objects.

- addObject:: Adds a specified object at the end of the receiver. It is an error to specify nil as an argument to this method. You can not add nil to an array.
- insertObject:atIndex:: Inserts an object at a specified index. If the specified index is already occupied, the objects at that index and beyond are shifted down one slot to make room. The specified index can't be greater than the receiver's count, and the specified object cannot be nil.; Array objects have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. You can only insert new objects in ascending order-with no gaps. Once you add two objects, the array's size is 2, so you can insert objects at indexes 0, 1, or 2. Index 3 is illegal and out of bounds.; It is an error to specify nil as an argument to this method. You cannot add nil to an array. It is also an error to specify an index that is greater than the array's count.
- removeObject:: Removes all objects in the array equivalent to a specified object, and moves elements up as necessary to fill any gaps. Equivalency is determined using the isEqual: method.
- removeObjectIdenticalTo:: Removes all occurrences of a specified object and moves elements up as necessary to fill any gaps.
- removeObjectAtIndex:: Removes the object at a specified index and moves all elements beyond the index up one slot to fill the gap. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on.; It is an error to specify an index that is out of bounds (greater than or equal to the array's count).
- removeAllObjects: Empties the receiver of all of its elements.
- setArray:: Empties the receiver of all its elements, then adds the contents of a specified array.

Storing Arrays

- writeToFile:atomically:

Writes the array's string representation to a specified file using the description method. Returns YES on success and NO on failure. If YES is specified for atomically:, this method attempts to write the file safely so that an existing file with the specified path is not overwritten, and it does not create a new file at the specified path unless the write is successful. The resulting file is suitable for use with arrayWithContentsOfFile:. For example, the following code excerpt:

id guestArray = [NSMutableArray arrayWithContentsOfFile:path];
[guestArray addObject:newGuest];
[guestArray writeToFile:path atomically:YES];

creates guestArray with the contents of the specified file, adds a new guest, and saves the changes to the same file.

Representing Arrays as Strings

- description

Returns a string that represents the contents of the receiver. For example, the following code excerpt:

id array = [NSMutableArray arrayWithObjects:
		@"Plates", @"Plasticware", @"Napkins", nil];
id description = [array description];

produces the string "(Plates, Plasticware, Napkins)".

- componentsJoinedByString:

Returns an NSString created by interposing a specified string between the elements of the receiver's objects. Each element of the array must be a string. If the receiver has no elements, an empty string is returned. See also componentsSeparatedByString: (NSString and NSMutableString). For example, the following code excerpt:

id commaString = @"A, B, C";
id array = [string componentsSeparatedByString:@","];
id dashString = [array componentsJoinedByString:@"-"];

creates the NSString dashString with the contents "A-B-C".

Table of Contents Next Section