- Inherits from:
- NSObject
- Package:
- com.apple.yellow.foundation
An NSArray stores an immutable array of objects.
NSArray Constructors | Returns an array. |
count | Returns the number of objects currently in the array. |
objectAtIndex | Returns the object located at the specified index. |
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.
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 |
- 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
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.
public static NSArray componentsSeparatedByString(
String aString,
String separator)
public NSArray arrayByAddingObject(Object anObject)
null
,
an InvalidArgumentException is thrown.See Also: addObject (NSMutableArray)
public NSArray arrayByAddingObjectsFromArray(NSArray otherArray)
See Also: addObjectsFromArray (NSMutableArray)
public String componentsJoinedByString(String separator)
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)
public boolean containsObject(Object anObject)
See Also: indexOfObject, indexOfIdenticalObject, equals(NSObject)
public int count()
See Also: objectAtIndex
public Object firstObjectCommonWithArray(NSArray otherArray)
null
.
This method uses equals to check for object equality. See Also: containsObject, equals (NSObject)
public void getObjects(Object[] aBuffer)
public void getObjects(
Object[] aBuffer,
NSRange aRange)
See Also: "Constructors"
public int indexOfIdenticalObject(Object anObject)
NSArray.NotFound
.
public int indexOfIdenticalObject(
Object anObject,
NSRange aRange)
NSArray.NotFound
.See Also: containsObject, indexOfObject
public int indexOfObject(Object anObject)
true
.
If none of the specified objects are equal to anObject,
returns NSArray.NotFound.
public int indexOfObject(
Object anObject,
NSRange aRange)
true
.
If none of the specified objects are equal to anObject,
returns NSArray.NotFound
.See Also: containsObject, indexOfIdenticalObject
public boolean isEqualToArray(NSArray otherArray)
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)
public Object lastObject()
null
. See Also: removeLastObject (NSMutableArray)
public Object objectAtIndex(int index)
See Also: count
public java.util.Enumeration objectEnumerator()
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)
public java.util.Enumeration reverseObjectEnumerator()
See Also: objectEnumerator, nextElement (NSEnumerator)
public NSArray sortedArrayUsingSelector(NSSelector selector)
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.
public NSArray subarrayWithRange(NSRange range)
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);