PATH |
NSArray
- Inherits from:
- Object
- Implements:
- Cloneable
- java.io.Serializable
- NSCoding
- NSKeyValueCoding
- NSKeyValueCodingAdditions
- Package:
- com.webobjects.foundation
Class Description
NSArray and its subclass NSMutableArray manage collections of objects called arrays. NSArray creates static arrays and NSMutableArray creates dynamic arrays.
Table 0-1 describes the NSArray methods that provide the basis for all NSArray's other methods; that is, all other methods are implemented in terms of these three. If you create a subclass of NSArray, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.
Method | Description |
count | Returns the number of elements in the array. |
objectAtIndex | Provides access to the array elements by index. |
objectsNoCopy | Returns a natural language array containing the NSArray's objects. |
The methods objectEnumerator and reverseObjectEnumerator 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. 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 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 its the exact same instance as 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.
Operators
An NSArray works with NSArray.Operators to perform operations on the array's elements. By default, an array has operators defined for the following keys:
Key | Operator Description |
count |
Returns the number of elements in an array. |
max |
Returns the element in the array with the highest value. |
min |
Returns the element in the array with the lowest value. |
avg |
Returns the average of the array's elements' values. |
sum |
Returns the sum of the array's element's values. |
To compute an operation on an array's elements, you use key-value coding methods with a specially formatted key. The character "@" introduces the name of the operator you want to perform. For example, to compute the average salary of an array's elements, you could use the method valueForKeyPath with "@avg.salary" as the key path. For more information, see the NSArray.Operator interface specification.
If you write your own operator class, you can make it available for use with NSArrays with the method setOperatorForKey. The operatorNames method returns the keys for the operators that NSArray knows about, and operatorForKey returns the operator for a specified key.
Constants
NSArray defines the following constants:
Constant | Type | Description |
AverageOperatorName | String |
A key representing the operator (an NSArray.Operator) that computes the average of the elements in an array. |
CountOperatorName | String |
A key representing the operator (an NSArray.Operator) that computes the number of elements in an array. |
NotFound | int |
Returned in the place of an index when an object is not found in an array. For example, indexOfObject returns NotFound if none of the receiver's objects are equal to the specified object. |
MaximumOperatorName | String |
A key representing the operator (an NSArray.Operator) that computes the largest element in an array. |
MinimumOperatorName | String |
A key representing the operator (an NSArray.Operator) that computes the smallest element in an array. |
EmptyArray | NSArray |
An empty array, which can be shared to save memory. |
SumOperatorName | String |
A key representing the operator (an NSArray.Operator) that computes the sum of the elements in an array. |
Interfaces Implemented
- Cloneable
- clone
- java.io.Serializable
- NSCoding
- decodeObject
- classForCoder
- encodeWithCoder
- NSKeyValueCoding
- takeValueForKey
- valueForKey
- NSKeyValueCodingAdditions
- takeValueForKeyPath
- valueForKeyPath
Method Types
- Creating arrays
- NSArray
- immutableClone
- mutableClone
- arrayByAddingObject
- arrayByAddingObjectsFromArray
- sortedArrayUsingComparator
- subarrayWithRange
- Querying the array
- containsObject
- count
- getObjects
- indexOfObject
- indexOfIdenticalObject
- lastObject
- objectAtIndex
- objects
- objectsNoCopy
- objectEnumerator
- reverseObjectEnumerator
- vector
- Comparing arrays
- firstObjectCommonWithArray
- isEqualToArray
- Working with string elements
- componentsJoinedByString
- componentsSeparatedByString
- Operations
- operatorForKey
- operatorNames
- setOperatorForKey
- removeOperatorForKey
- Methods inherited from Object
- equals
- hashCode
- toString
- Sending messages to elements
- makeObjectsPerformSelector
Constructors
NSArray
public NSArray()
Creates an empty, immutable array. After an immutable array has been initialized in this way, it can't be modified. If you need an empty, immutable array, use EmptyArray instead. This method is used by mutable subclasses of NSArray.
public NSArray(NSArray anArray)
public NSArray(Object anObject)
public NSArray(Object[] objects)
null
values it encounters in objects. After an immutable array has been initialized in this way, it can't be modified.
public NSArray( Object[] objects, NSRange aRange)
null
values it encounters in objects. After an immutable array has been initialized in this way, it can't be modified.
public NSArray( java.util.Vector aVector, NSRange aRange, boolean checkForNull)
null
value in the vector: if checkForNull is true
, the null
value is simply ignored. If checkForNull is false, the method raises an IllegalArgumentException.
Static Methods
componentsSeparatedByString
public static NSArray componentsSeparatedByString( String string, String separator)
String list = "wrenches, hammers, saws"; NSArray listItems = NSArray.componentsSeparatedByString (", ");
produces an array with these contents:
Index | Substring |
0 | wrenches |
1 | hammers |
2 | saws |
If list begins with a comma and space the array has these contents:
Index | Substring |
0 | (empty string) |
1 | wrenches |
2 | hammers |
3 | saws |
If list has no separators-for example, "wrenches"-the array contains the string itself, in this case "wrenches".
See Also: componentsJoinedByString
decodeObject
public static Object decodeObject(NSCoder coder)
See Also: NSCoding Interface Description
operatorForKey
public static NSArray.Operator operatorForKey(String operatorName)
See Also: "Operators" (page 4)
operatorNames
public static NSArray operatorNames()
count
, max
, min
, avg
, and sum
.
See Also: "Operators" (page 4)
removeOperatorForKey
public static void removeOperatorForKey(String operatorName)
See Also: "Operators" (page 4)
setOperatorForKey
public static void setOperatorForKey( String key, NSArray.Operator operator)
See Also: "Operators" (page 4)
Instance Methods
arrayByAddingObject
public NSArray arrayByAddingObject(Object anObject)
null
, an IllegalArgumentException is thrown.
See Also: addObject (NSMutableArray)
arrayByAddingObjectsFromArray
public NSArray arrayByAddingObjectsFromArray(NSArray otherArray)
See Also: addObjectsFromArray (NSMutableArray)
classForCoder
public Class classForCoder()
See Also: classForCoder (NSCoding)
clone
public Object clone()
componentsJoinedByString
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 the empty string is returned.
See Also: componentsSeparatedByString
containsObject
public boolean containsObject(Object anObject)
count
public int count()
encodeWithCoder
public void encodeWithCoder(NSCoder coder)
equals
public boolean equals(Object anObject)
true
if anObject is an NSArray and its contents are equal to the receiver's or false
otherwise. If you know that anObject is an NSArray, use the more efficient method isEqualToArray instead.
firstObjectCommonWithArray
public Object firstObjectCommonWithArray(NSArray otherArray)
null
if no such object is found. This method uses equals to check for object equality.
getObjects
public void getObjects(Object[] buffer[])
public void getObjects( Object[] buffer[], NSRange aRange)
hashCode
public int hashCode()
immutableClone
public NSArray immutableClone()
indexOfIdenticalObject
public int indexOfIdenticalObject(Object anObject)
public int indexOfIdenticalObject( Object anObject, NSRange aRange)
indexOfObject
public int indexOfObject(Object anObject)
true
. If none of the specified objects are equal to anObject, returns NotFound.
public int indexOfObject( Object anObject, NSRange aRange)
true
. If none of the specified objects are equal to anObject, returns NotFound. Throws an IllegalArgumentException if aRange is out of bounds.
isEqualToArray
public boolean isEqualToArray(NSArray otherArray)
true
if the contents of otherArray are equal to the contents of the receiver, false
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 equals test.
lastObject
public Object lastObject()
null
.
makeObjectsPerformSelector
public void makeObjectsPerformSelector( NSSelector selector, Object[] anObject[])
mutableClone
public NSMutableArray mutableClone()
objectAtIndex
public Object objectAtIndex(int index)
See Also: count
objectEnumerator
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
objects
public Object[] objects()
public Object[] objects(NSRange aRange)
objectsNoCopy
protected Object[] objectsNoCopy()
reverseObjectEnumerator
public java.util.Enumeration reverseObjectEnumerator()
java.util.Enumeration enumerator = myArray.reverseObjectEnumerator(); 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: objectEnumerator
sortedArrayUsingComparator
public NSArray sortedArrayUsingComparator(NSComparator comparator) throws NSComparator.ComparisonException
sortedArrayUsingSelector
public NSArray sortedArrayUsingSelector(NSSelector selector) throws NSComparator.ComparisonException
subarrayWithRange
public NSArray subarrayWithRange(NSRange aRange)
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);
takeValueForKey
public void takeValueForKey( Object value, String key)
takeValueForKeyPath
public void takeValueForKeyPath( Object value, String key)
toString
public String toString()
valueForKey
public Object valueForKey(String key)
- If key indicates an operation that doesn't require an argument (such as returning the array's count), valueForKey performs the operation and returns the result. key indicates an operation if its first character is "@". For example, if key is "@count", valueForKey invokes compute on the "count" operator. This has the effect of computing and returning the number of elements in the receiver. Don't use valueForKey for operations that take arguments; instead use valueForKeyPath.
- For any other key, valueForKey creates an array with the same number of elements as the receiver. For each element in the receiver, the corresponding element in the new array is the value for key of the receiver's element. For example, if key is "firstName", this method returns an array containing the firstName values for the receiver's elements. The key argument can be a key path of the form relationship.property; for example, "department.name". valueForKey replaces null values with an instance of NSKeyValueCoding.Null.
See Also: "Operators" (page 4)
valueForKeyPath
public Object valueForKeyPath(String keyPath)
- If key indicates an operation takes an argument (such as computing an average), valueForKeyPath performs the operation and returns the result. key indicates an aggregate operation if its first character is "@". For example, if key is "@avg.salary", valueForKey invokes compute on the "avg" operator specifying the receiver and "salary" as arguments. This has the effect of computing and returning the average salary of the receiver's elements.
- Otherwise, valueForKeyPath invokes the default implementation of valueForKeyPath. For more information see the method description for valueForKeyPath in the NSKeyValueCodingAdditions interface specification.
See Also: "Operators" (page 4)
vector
public java.util.Vector vector()
© 2001 Apple Computer, Inc. (Last Published April 17, 2001)