PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSArray


Inherits from:
NSObject
Package:
com.apple.yellow.foundation

Class at a Glance


An NSArray stores an immutable array of objects.

Principal Attributes


Creation



NSArray Constructors Returns an array.

Commonly Used Methods



count Returns the number of objects currently in the array.
objectAtIndex Returns the object located at the specified index.


Class Description


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

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 in both the Java API and the Foundation Kit, such as java.util.Hashtable or NSDictionary. See the objectEnumerator method description for a code excerpt that shows how to use these methods to access the elements of an array.

NSArray provides methods for querying the elements of the array. indexOfObjectsearches the array for the object that matches its argument. To determine whether the search is successful, each element of the array is sent an equals message. Another method, indexOfIdenticalObject, is provided for the less common case of determining whether a specific object is present in the array. indexOfIdenticalObject tests each element in the array to see whether its id matches that of the argument.

To act on the array as a whole, a variety of other methods are defined. You can extract a subset of the array ( subarrayWithRange) or concatenate the elements of an array of Strings 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.




Constants


NSArray provides the following constant as a convenience; you can use it to compare to values returned by some NSArray methods:


Constant Type Description
NotFound int Returned when an object is not found in an NSArray



Method Types


Constructors
NSArray
Querying the array
containsObject
count
getObjects
indexOfObject
indexOfIdenticalObject
lastObject
objectAtIndex
objectEnumerator
reverseObjectEnumerator
Comparing arrays
firstObjectCommonWithArray
isEqualToArray
Deriving new arrays
arrayByAddingObject
arrayByAddingObjectsFromArray
sortedArrayUsingSelector
subarrayWithRange
Working with string elements
componentsJoinedByString
componentsSeparatedByString


Constructors



NSArray

public NSArray()

Creates an empty array. This method is used by mutable subclasses of NSArray.

public NSArray(Object anObject)

Creates an array containing the single element anObject. After an immutable array has been initialized in this way, it can't be modified.

public NSArray(Object[] objects)

Creates an array containing objects. After an immutable array has been initialized in this way, it can't be modified.

public NSArray(NSArray anArray)

Creates an array containing the objects in anArray. After an immutable array has been initialized in this way, it can't be modified.




Static Methods



componentsSeparatedByString

public static NSArray componentsSeparatedByString( String aString, String separator)

Description forthcoming.


Instance Methods



arrayByAddingObject

public NSArray arrayByAddingObject(Object anObject)

Returns a new array that is a copy of the receiver with anObject added to the end. If anObject is null, an InvalidArgumentException is thrown.

See Also: addObject (NSMutableArray)



arrayByAddingObjectsFromArray

public NSArray arrayByAddingObjectsFromArray(NSArray otherArray)

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

See Also: addObjectsFromArray (NSMutableArray)



componentsJoinedByString

public String componentsJoinedByString(String separator)

Constructs and returns a String that is the result of interposing separator between the elements of the receiver's array. For example, this code excerpt writes the path System/Developer to the console:
NSArray pathArray = new NSArray(new Object[] {"System", 
    "Developer"});
System.out.println("The path is " + 
    pathArray.componentsJoinedByString("/") + ".");

Each element in the receiver's array must handle either description, or if it is not implemented, toString. If the receiver has no elements, a String representing an empty string is returned.

See Also: componentsSeparatedByString (NSStringReference)



containsObject

public boolean containsObject(Object anObject)

Returns true if anObject is present in the array. This method determines whether an object is present in the array by sending an equals message to each of the array's objects (and passing anObject as the parameter to each equals message).

See Also: indexOfObject, indexOfIdenticalObject, equals(NSObject)



count

public int count()

Returns the number of objects currently in the array.

See Also: objectAtIndex



firstObjectCommonWithArray

public Object firstObjectCommonWithArray(NSArray otherArray)

Returns the first object contained in the receiver that's equal to an object in otherArray. If no such object is found, this method returns null. This method uses equals to check for object equality.

See Also: containsObject, equals (NSObject)



getObjects

public void getObjects(Object[] aBuffer)

Copies all objects contained in the receiver to aBuffer.

public void getObjects( Object[] aBuffer, NSRange aRange)

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

See Also: "Constructors"



indexOfIdenticalObject

public int indexOfIdenticalObject(Object anObject)

Searches all objects in the receiver for anObject (testing for equality by comparing object addresses) and returns the lowest index whose corresponding array value is identical to anObject. If none of the objects in the receiver are identical to anObject, this method returns NSArray.NotFound.

public int indexOfIdenticalObject( Object anObject, NSRange aRange)

Searches the specified range within the receiver for anObject (testing for equality by comparing object addresses) and returns the lowest index whose corresponding array value is identical to anObject. If none of the objects in the range are identical to anObject, this method returns NSArray.NotFound.

See Also: containsObject, indexOfObject



indexOfObject

public int indexOfObject(Object anObject)

Searches all objects in the receiver for anObject and returns the lowest index whose corresponding array value is equal to anObject. Objects are considered equal if equals returns true. If none of the specified objects are equal to anObject, returns NSArray.NotFound.

public int indexOfObject( Object anObject, NSRange aRange)

Searches the specified range within the receiver for anObject and returns the lowest index whose corresponding array value is equal to anObject. Objects are considered equal if equals returns true. If none of the specified objects are equal to anObject, returns NSArray.NotFound.

See Also: containsObject, indexOfIdenticalObject



isEqualToArray

public boolean isEqualToArray(NSArray otherArray)

Compares the receiving array to otherArray. If the contents of otherArray are equal to the contents of the receiver, this method returns true. If not, it returns false.

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 equals test.

See Also: equals(NSObject)



lastObject

public Object lastObject()

Returns the object in the array with the highest index value. If the array is empty, lastObject returns null.

See Also: removeLastObject (NSMutableArray)



objectAtIndex

public Object objectAtIndex(int index)

Returns the object located at index. If index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), a RangeException is thrown.

See Also: count



objectEnumerator

public java.util.Enumeration objectEnumerator()

Returns an enumerator object that lets you access each object in the array, in order, starting with the element at index 0, as in:
java.util.Enumeration enumerator = myArray.objectEnumerator();

while (enumerator.hasMoreElements()) {{
    Object anObject = enumerator.nextElement(); 
    /* code to act on each element */
}

When this method is used with mutable subclasses of NSArray, your code shouldn't modify the array during enumeration.

See Also: reverseObjectEnumerator, nextElement (NSEnumerator)



reverseObjectEnumerator

public java.util.Enumeration reverseObjectEnumerator()

Returns 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. Your code shouldn't modify the array during enumeration.

See Also: objectEnumerator, nextElement (NSEnumerator)



sortedArrayUsingSelector

public NSArray sortedArrayUsingSelector(NSSelector selector)

Returns an array that lists the receiver's elements in ascending order, as determined by the comparison method specified by the selector selector. The new array contains references to the receiver's elements, not copies of them. The retain count is incremented for each element in the receiving array.

The selector message is sent to each object in the array, and has as its single argument another object in the array. The selector method is used to compare two elements at a time and should return OrderedAscending if the receiver is smaller than the argument, OrderedDescending if the receiver is larger than the argument, and OrderedSame if they are equal.



subarrayWithRange

public NSArray subarrayWithRange(NSRange range)

Returns a new array containing the receiver's elements that fall within the limits specified by range. If range isn't within the receiver's range of elements, a RangeException is thrown.

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

NSRange theRange = new NSRange(0, wholeArray.count()/2);
NSArray halfArray = wholeArray.subarrayWithRange(theRange);




Table of Contents