com.webobjects.foundation
Class NSArray

java.lang.Object
  com.webobjects.foundation.NSArray

All Implemented Interfaces:

NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Serializable, Cloneable, Iterable, Collection, List

Direct Known Subclasses:

NSMutableArray

public class NSArray
extends Object
implements Cloneable, Serializable, NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, List

NSArray and its subclass NSMutableArray manage ordered collections of objects. NSArray creates immutable arrays and NSMutableArray creates mutable arrays.

The following table 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.

NSArray's Base API

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 in the Foundation framework, 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 if it is 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 equals 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.

See Also:

List, ArrayList, Vector, NSArray.count(), NSArray.objectAtIndex(int), indexOfObject, NSArray.arrayByAddingObjectsFromArray(com.webobjects.foundation.NSArray), NSArray.componentsJoinedByString(java.lang.String), NSArray.objectEnumerator(), Serialized Form

Nested Class Summary

static interface

NSArray.Operator Objects implementing NSArray.Operator are used to perform operations on an array's elements.

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding

NSCoding.Support

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Field Summary

static String	AverageOperatorName A key representing the operator (NSArray.Operator) that computes the average of the elements in an array.
static boolean	CheckForNull Convenience for the constructor methods
static String	CountOperatorName A key representing the operator (NSArray.Operator) that computes the number of elements in an array.
static NSArray	EmptyArray A constant representation of an empty array.
static boolean	IgnoreNull Convenience for the constructor methods
static String	MaximumOperatorName A key representing the operator (NSArray.Operator) that computes the largest element in an array.
static String	MinimumOperatorName A key representing the operator (NSArray.Operator) that computes the smallest element in an array.
static int	NotFound This constant is returned by several search methods, indicating that no matching object was found.
static String	SumOperatorName A key representing the operator (NSArray.Operator) that computes the sum of the elements in an array.

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

	NSArray() Creates an empty, immutable array.
	NSArray(Collection collection) Creates a NSArray from objects that implement the java.util.Collection interface.
	NSArray(Collection collection, boolean checkForNull) Creates a NSArray from objects that implement the java.util.Collection interface.
	NSArray(Object object) Creates an array containing the single element object.
	NSArray(Object[] objects) Creates an array containing the elements from objects.
	NSArray(Object[] objects, NSRange range) Creates an array containing the objects from objects in the range specified by range.
	NSArray(List list, NSRange range, boolean ignoreNull) Creates an array containing the objects from list in the range specified by range.
	NSArray(NSArray otherArray) One should use immutableClone instead.
protected	NSArray(Object[] objects, int rangeLocation, int rangeLength, boolean checkForNull, boolean ignoreNull)

Method Summary

boolean	add(Object element) add is not a supported operation in NSArray
void	add(int index, Object element) add is not a supported operation in NSArray
boolean	addAll(Collection collection) addAll is not a supported operation in NSArray
boolean	addAll(int index, Collection collection) addAll is not a supported operation in NSArray
NSArray	arrayByAddingObject(Object object) Returns a new NSArray which contains the values from this array, and appends the object argument.
NSArray	arrayByAddingObjectsFromArray(NSArray otherArray) Returns a new NSArray which contains the values from this array, and appends values from the otherArray argument.
ArrayList	arrayList() Creates a java.util.ArrayList with the same contents as this object.
Class	classForCoder() Conformance to the NSCoding interface.
void	clear() Operation not supported
Object	clone() Clones this array Object Since NSArrays are immutable, there's no need to make an actual clone.
String	componentsJoinedByString(String separator) This method concatenates the String representation of each element in this array together in order from lowest index to highest.
static NSArray	componentsSeparatedByString(String string, String separator) This static method tokenizes the string argument into a series of substrings according to separator It creates a new NSArray which contains the substrings in the order they appeared in string.
boolean	contains(Object element) Returns true if NSArray contains the specified element.
boolean	containsAll(Collection c)
boolean	containsObject(Object object) This method determines whether object is present in this array by comparing it to each of the array's objects using equals
int	count()
static Object	decodeObject(NSCoder coder) Creates a new NSArray from the data in coder.
static NSArray	emptyArray() Returns the empty NSArray (immutable).
void	encodeWithCoder(NSCoder coder) Encodes the receiver using coder.
boolean	equals(Object object) Compares this array to object, returning true if object satisfies instanceof NSArray and its elements are equal to the elements of this array, otherwise it returns false.
Object	firstObjectCommonWithArray(NSArray otherArray) This method searches for the first object in this array which is contained within otherArray.
Object	get(int index)
void	getObjects(Object[] objects) Deprecated. use public Object[] objects() instead
void	getObjects(Object[] objects, NSRange range) Deprecated. use public Object[] objects() in NSRange instead
int	hashCode()
NSArray	immutableClone() Since an NSArray is immutable, NSArray's implementation simply returns this.
int	indexOf(Object element)
int	indexOfIdenticalObject(Object object) Searches all objects in this array for object.
int	indexOfIdenticalObject(Object object, NSRange range) Searches the specified subset within this array for object (testing for equality by directly comparing Object references with ==) and returns the first (lowest) index whose corresponding element is identical to object.
int	indexOfObject(Object object) Searches this array for object and returns the first (lowest) index whose corresponding element is equal to object.
int	indexOfObject(Object object, NSRange range) Searches the specified subset within this array for object and returns the first (lowest) index whose corresponding element is equal to object.
boolean	isEmpty() Returns true if this list contains no elements.
boolean	isEqualToArray(NSArray otherArray) Included for backward compatibility.
Iterator	iterator()
int	lastIndexOf(Object element)
Object	lastObject()
ListIterator	listIterator()
ListIterator	listIterator(int index)
void	makeObjectsPerformSelector(NSSelector selector, Object[] parameters) Invokes the method specified by selector on each object in this array.
NSMutableArray	mutableClone() NSArray's implementation creates a new NSMutableArray with this array's elements, not copies.
Object	objectAtIndex(int index) Returns the Object reference stored at index within this NSArray.
Enumeration	objectEnumerator() This method creates a java.util.Enumeration which can used to iterate through the array's elements.
Object[]	objects()
Object[]	objects(NSRange range) Copies a subset of this array into a Java array.
protected Object[]	objectsNoCopy() This method should only be used by subclasses.
static NSArray.Operator	operatorForKey(String operatorName)
static NSArray	operatorNames() Returns the names of the operations that can be performed on array elements.
Object	remove(int index) Operation not supported
boolean	remove(Object element) Operation not supported
boolean	removeAll(Collection collection) Operation not supported
static void	removeOperatorForKey(String operatorName) Removes the operator identified by operatorName from the list of operators that can be performed on array elements.
boolean	retainAll(Collection collection) Operation not supported
Enumeration	reverseObjectEnumerator() This method creates a java.util.Enumeration which can used to iterate through the array's elements in reverse.
Object	set(int index, Object element)
static void	setOperatorForKey(String operatorName, NSArray.Operator arrayOperator) Registers an operator with a String.
int	size()
NSArray	sortedArrayUsingComparator(NSComparator comparator) This method creates a new array with this array's element which have been sorted in an order based on the comparator operation.
NSArray	sortedArrayUsingSelector(NSSelector selector) Deprecated. use sortedArrayUsingComparator instead
NSArray	subarrayWithRange(NSRange range) This method creates a new array from a subset of this array.
List	subList(int fromIndex, int toIndex)
void	takeValueForKey(Object value, String key) Conformance to the NSKeyValueCoding interface.
void	takeValueForKeyPath(Object value, String keyPath) Sets the value for the property identified by keyPath to value.
Object[]	toArray()
Object[]	toArray(Object[] objects)
String	toString()
Object	valueForKey(String key) Conformance to the NSKeyValueCoding interface.
Object	valueForKeyPath(String keyPath) Conformance to the NSKeyValueCodingAdditions interface.
Vector	vector() Creates a java.util.Vector with the same contents as this object.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NotFound

public static final int NotFound

This constant is returned by several search methods, indicating that no matching object was found.

See Also:

Constant Field Values

EmptyArray

public static final NSArray EmptyArray

A constant representation of an empty array. It is used to avoid unnecessary object creation.

CountOperatorName

public static final String CountOperatorName

A key representing the operator (NSArray.Operator) that computes the number of elements in an array.

See Also:

Constant Field Values

MaximumOperatorName

public static final String MaximumOperatorName

A key representing the operator (NSArray.Operator) that computes the largest element in an array.

See Also:

Constant Field Values

MinimumOperatorName

public static final String MinimumOperatorName

A key representing the operator (NSArray.Operator) that computes the smallest element in an array.

See Also:

Constant Field Values

SumOperatorName

public static final String SumOperatorName

A key representing the operator (NSArray.Operator) that computes the sum of the elements in an array.

See Also:

Constant Field Values

AverageOperatorName

public static final String AverageOperatorName

A key representing the operator (NSArray.Operator) that computes the average of the elements in an array.

See Also:

Constant Field Values

CheckForNull

public static final boolean CheckForNull

Convenience for the constructor methods

See Also:

Constant Field Values

IgnoreNull

public static final boolean IgnoreNull

Convenience for the constructor methods

See Also:

Constant Field Values

Constructor Detail

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.

See Also:

NSArray.EmptyArray

NSArray

public NSArray(Object object)

Creates an array containing the single element object. object is not permitted to be null

Parameters:

object - the single element within the new NSArray

Throws:

IllegalArgumentException - java.lang.IllegalArgumentException if object is null

NSArray

protected NSArray(Object[] objects,
                  int rangeLocation,
                  int rangeLength,
                  boolean checkForNull,
                  boolean ignoreNull)

NSArray

public NSArray(Object[] objects)

Creates an array containing the elements from objects. objects must not be null, but this method ignores any null values within objects.

Parameters:

objects - a Java array containing the initial values for the newly created NSArray

NSArray

public NSArray(Object[] objects,
               NSRange range)

Creates an array containing the objects from objects in the range specified by range. Ignores any null values it encounters in objects.

Parameters:

objects - a Java array containing initial values for the newly created NSArray

range - specifies which elements of the objects array are to be added

NSArray

public NSArray(NSArray otherArray)

One should use immutableClone instead. Creates a new array that contains the same object references as otherArray. otherArray must not be null.

Parameters:

otherArray - the array to be duplicated

See Also:

NSArray.immutableClone()

NSArray

public NSArray(Collection collection,
               boolean checkForNull)

Creates a NSArray from objects that implement the java.util.Collection interface.

Parameters:

collection - object that implements the Collection interface

checkForNull - whether to check for null values in List or throw exception

Throws:

IllegalArgumentException - if a null element exists in Collection or java.lang.NullPointerException if the Collection parameter is null.

Since:

5.4

See Also:

List

NSArray

public NSArray(Collection collection)

Creates a NSArray from objects that implement the java.util.Collection interface.

Parameters:

collection - object that implements the Collection interface

Throws:

IllegalArgumentException - if a null element exists in Collection or java.lang.NullPointerException if the Collection parameter is null.

Since:

5.4

See Also:

Collection

NSArray

public NSArray(List list,
               NSRange range,
               boolean ignoreNull)

Creates an array containing the objects from list in the range specified by range. The ignoreNull parameter controls the method's behavior when it encounters a null value in the list. If ignoreNull is true, then null values are simply ignored. If ignoreNull is false, the method raises an IllegalArgumentException when it encounters a null value.

Parameters:

list - object that implements the List interface

range - the range of objects to include

ignoreNull - whether to ignore null values in vector or throw exception

Throws:

IllegalArgumentException - if a null element exists in vector.

See Also:

Vector

Method Detail

operatorNames

public static NSArray operatorNames()

Returns the names of the operations that can be performed on array 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.

Returns:

the names of the operations that can be performed on array elements.

setOperatorForKey

public static void setOperatorForKey(String operatorName,
                                     NSArray.Operator arrayOperator)

Registers an operator with a String. Throws an IllegalArgumentException if either operatorName or arrayOperator are null.

Parameters:

operatorName - the human-readable name for the operator instance

arrayOperator - the operator instance

Throws:

IllegalArgumentException - if either operatorName or arrayOperator are null

operatorForKey

public static NSArray.Operator operatorForKey(String operatorName)

Parameters:

operatorName - the human-readable name for the operator instance

Returns:

the operator object registered as operatorName if one exists, null otherwise

See Also:

NSArray

removeOperatorForKey

public static void removeOperatorForKey(String operatorName)

Removes the operator identified by operatorName from the list of operators that can be performed on array elements.

Parameters:

operatorName - the human-readable name for the operator instance to be removed

objectsNoCopy

protected Object[] objectsNoCopy()

This method should only be used by subclasses. It avoids making unnecessary copies whenever possible, however, this method never returns the actual array reference used by this NSArray.

Returns:

the NSArray's elements in a Java array.

count

public int count()

Returns:

the number of objects currently in the array

objectAtIndex

public Object objectAtIndex(int index)

Returns the Object reference stored at index within this NSArray. If the array is empty or if index is beyond the end of the array (that is, if index is greater than or equal to the value returned by count), an IllegalArgumentException is thrown. Negative index arguments are similarly illegal.

Parameters:

index - the location of the object

Returns:

the object located at index

Throws:

IllegalArgumentException - when index is not greater than or equal to 0 and less than count

See Also:

NSArray._count

arrayByAddingObject

public NSArray arrayByAddingObject(Object object)

Returns a new NSArray which contains the values from this array, and appends the object argument. If object is null, an IllegalArgumentException is thrown.

Parameters:

object - the object to be appended

Returns:

a new array that is a copy of the this one with object appended

Throws:

IllegalArgumentException - IllegalArgumentException if object is null.

See Also:

NSMutableArray#addObject

arrayByAddingObjectsFromArray

public NSArray arrayByAddingObjectsFromArray(NSArray otherArray)

Returns a new NSArray which contains the values from this array, and appends values from the otherArray argument.

Parameters:

otherArray - the array to be appended

Returns:

a new array that is a copy of the this one with the objects contained in otherArray appended.

See Also:

NSMutableArray#addObjectsFromArray

objects

public Object[] objects()

Returns:

A copy of this array into a Java array.

objects

public Object[] objects(NSRange range)

Copies a subset of this array into a Java array. The order of the elements is preserved.

Parameters:

range - the range specifying a subset to copy

Returns:

A copy of this array into a Java array.

vector

public Vector vector()

Creates a java.util.Vector with the same contents as this object. The order of the elements is preserved.

Returns:

a java.util.Vector with the same elements as this array

arrayList

public ArrayList arrayList()

Creates a java.util.ArrayList with the same contents as this object. The order of the elements is preserved.

Returns:

a java.util.ArrayList with the same elements as this array

Since:

5.3

containsObject

public boolean containsObject(Object object)

This method determines whether object is present in this array by comparing it to each of the array's objects using equals

Parameters:

object - the searched for object

Returns:

true if this array contains an object equal to object, otherwise false

firstObjectCommonWithArray

public Object firstObjectCommonWithArray(NSArray otherArray)

This method searches for the first object in this array which is contained within otherArray. It uses equals to check for equality.

Parameters:

otherArray - the input array

Returns:

the first object that is equal to an object in otherArray, or null if no such object is found

getObjects

@Deprecated
public void getObjects(Object[] objects)

Deprecated. use public Object[] objects() instead

Parameters:

objects - the destination buffer to copy this array into. It must be large enough to hold count Object references.

See Also:

NSArray.objects()

getObjects

@Deprecated
public void getObjects(Object[] objects,
                                  NSRange range)

Deprecated. use public Object[] objects() in NSRange instead

Parameters:

objects - the destination buffer to copy a subset of this array into. It must be large enough to hold count Object references.

range - the subset of entries to copy into objects

See Also:

NSArray.objects(NSRange range)

indexOfObject

public int indexOfObject(Object object)

Searches this array for object and returns the first (lowest) index whose corresponding element is equal to object. Objects are considered equal if equals returns true. If none of the specified objects are equal to object, returns NotFound.

Parameters:

object - the search's target

Returns:

the first index whose element is equal to anObject

See Also:

NSArray.NotFound

indexOfObject

public int indexOfObject(Object object,
                         NSRange range)

Searches the specified subset within this array for object and returns the first (lowest) index whose corresponding element is equal to object. Objects are considered equal if equals returns true. If none of the specified objects are equal to object, returns NotFound. Throws an IllegalArgumentException if aRange is out of bounds.

Parameters:

object - the search's target

range - the subset to search

Returns:

the first index whose element is equals to object

Throws:

IllegalArgumentException - if aRange is out of bounds.

indexOfIdenticalObject

public int indexOfIdenticalObject(Object object)

Searches all objects in this array for object. The method tests for equality by comparing object references directly using the == operator, and not the equals method, and returns the first (lowest) index whose corresponding element is identical to object. If none of the objects in the receiver are identical to object, this method returns NotFound.

Parameters:

object - the search's target

Returns:

the first index whose element is identical to object

See Also:

NSArray.NotFound

indexOfIdenticalObject

public int indexOfIdenticalObject(Object object,
                                  NSRange range)

Searches the specified subset within this array for object (testing for equality by directly comparing Object references with ==) and returns the first (lowest) index whose corresponding element is identical to object. If none of the objects in the range match, then this method returns NotFound. Throws an IllegalArgumentException if range is out of bounds.

Parameters:

object - the search's target

range - the subset to search

Returns:

the first index whose element is == equal to object

Throws:

IllegalArgumentException - java.lang.IllegalArgumentException if range is out of bounds

See Also:

NSArray.NotFound

subarrayWithRange

public NSArray subarrayWithRange(NSRange range)

This method creates a new array from a subset of this array. The elements' ordering is preserved.

Parameters:

range - the subset of elements to be included in the new array

Returns:

a new array with all this array's elements that fall within the limits specified by range

Throws:

IndexOutOfBoundsException - java.lang.IndexOutOfBoundsException when input range is outside the bounds of this array

lastObject

public Object lastObject()

Returns:

the last object in this array or null if the array is empty

isEqualToArray

public boolean isEqualToArray(NSArray otherArray)

Included for backward compatibility. Use equals instead.

Parameters:

otherArray - the array to be compared against

Returns:

true if otherArray and this array are equal else false

See Also:

NSArray.equals(java.lang.Object)

equals

public boolean equals(Object object)

Compares this array to object, returning true if object satisfies instanceof NSArray and its elements are equal to the elements of this array, otherwise it returns false. Two arrays have equal contents if they each hold the same number of objects and objects at corresponding indices in each array satisfy the equals test.

Specified by:

equals in interface Collection

Specified by:

equals in interface List

Overrides:

equals in class Object

Parameters:

object - the object to compare this array against

Returns:

true if object is an NSArray and its contents are equal to this array or false otherwise

See Also:

Object.equals(java.lang.Object)

objectEnumerator

public Enumeration objectEnumerator()

This method creates a java.util.Enumeration which can used to iterate through the array's elements. The following code excerpt can be considered:

         <blockquote>
          java.util.Enumeration enumerator = myArray.objectEnumerator();
          while (enumerator.hasMoreElements()) {
             Object anObject = enumerator.nextElement();
             //code to act on each element
          }
          </blockquote>
 

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

Returns:

a java.util.Enumeration that can access each object in the array in order, starting with the element at index 0

See Also:

NSArray.reverseObjectEnumerator()

reverseObjectEnumerator

public Enumeration reverseObjectEnumerator()

This method creates a java.util.Enumeration which can used to iterate through the array's elements in reverse. For example, the following code can be considered:

         <blockquote>
          java.util.Enumeration enumerator = myArray.reverseObjectEnumerator();
          while (enumerator.hasMoreElements()) {
             Object anObject = enumerator.nextElement();
             //code to act on each element
          }
          </blockquote>
 

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

Returns:

an enumeration that can access each object in the array, in order, from the element at the highest index down to the element at index 0

See Also:

NSArray.objectEnumerator()

sortedArrayUsingSelector

@Deprecated
public NSArray sortedArrayUsingSelector(NSSelector selector)
                                 throws NSComparator.ComparisonException

Deprecated. use sortedArrayUsingComparator instead

Parameters:

selector - an NSSelector for the method to compare the elements during the sort

Returns:

a new and sorted NSArray with this array's elements

Throws:

NSComparator.ComparisonException

See Also:

NSArray.sortedArrayUsingComparator(com.webobjects.foundation.NSComparator)

sortedArrayUsingComparator

public NSArray sortedArrayUsingComparator(NSComparator comparator)
                                   throws NSComparator.ComparisonException

This method creates a new array with this array's element which have been sorted in an order based on the comparator operation.

Parameters:

comparator - It determines the ordering in the new sorted array by comparing two elements at a time and returning one of OrderedAscending, OrderedSame or OrderedDescending

Returns:

a new sorted array that lists this array's elements in an order determined by comparator

Throws:

NSComparator.ComparisonException - if the comparator's compare method throws for any reason

See Also:

NSComparator.compare(java.lang.Object, java.lang.Object)

componentsJoinedByString

public String componentsJoinedByString(String separator)

This method concatenates the String representation of each element in this array together in order from lowest index to highest. The separator String is placed in between each element. This is in all aspects the inverse function of componentsSeparatedByString For example, this code excerpt writes the path System/Developer to the console:

         <blockquote>
          NSArray pathArray = new NSArray(new Object [] {{"System ","Developer "});
          System.out.println("The path is "+pathArray.componentsJoinedByString("/")+".");
          </blockquote>
 

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.

Parameters:

separator - the string to be inserted in between each element. It may be any String object, including null or an empty String

Returns:

String that is the result of interposing separator between the elements of this array

See Also:

NSArray.componentsSeparatedByString(java.lang.String, java.lang.String)

componentsSeparatedByString

public static NSArray componentsSeparatedByString(String string,
                                                  String separator)

This static method tokenizes the string argument into a series of substrings according to separator It creates a new NSArray which contains the substrings in the order they appeared in string. If string begins or ends with separator, then the first or last substring, respectively, is an empty String. If string is null, or an empty String, then this method returns an NSArray with 0 elements. If separator is null, or an empty String, then it returns an NSArray with 1 element, the string Object. This method is in all aspects the inverse function of componentsJoinedByString A code excerpt:

         <blockquote>
          String list ="wrenches, hammers, saws";
          NSArray listItems = NSArray.componentsSeparatedByString (list, ", ");
          </blockquote>
 

produces an array with these contents:

Index	Substring
0	wrenches
1	hammers
2	saws

If list is instead

         <blockquote>
          String list =", wrenches, hammers, saws";
          </blockquote>
 

then the result is:

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

Parameters:

string - the input string to be parsed

separator - the string that is to separate the substrings

Returns:

an array containing substrings from string that have been divided by separator

See Also:

NSArray.componentsJoinedByString(java.lang.String)

valueForKey

public Object valueForKey(String key)

Conformance to the NSKeyValueCoding interface. NSArray's implementation is more complex than the default:

• If key indicates an operation that doesn't require an argument, 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 keys which do not begin with "@", valueForKey creates a new array with the same number of elements as this array. For each element, the corresponding element in the new array is the result of invoking valueForKeyPath with key as the key path on the element. For example, if key is "firstName", this method returns an array containing the firstName values for each of the array'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.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - the input key

Returns:

The result of an operation or a new array of values corresponding to the results of valueForKeyPath on each element of this array

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSArray.operatorNames(), NSArray.valueForKeyPath(java.lang.String), NSKeyValueCoding.Null

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Conformance to the NSKeyValueCoding interface. This method invokes takeValueForKeyPath on each element in this array with the arguments value and key For example, if key is "firstName" and value is "Unknown", this method sets the firstName property of each element to "Unknown".

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

value - each element's new value for the keypath

key - the keypath for the property to set on each element

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String)

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Conformance to the NSKeyValueCodingAdditions interface. NSArray's implementation is more complex than the default:

• If keyPath 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 array and "salary" as arguments. This has the effect of computing and returning the average salary of the array's elements.
• Otherwise, valueForKeyPath behaves similarly to valueForKey and produces a new NSArray whose elements correspond to the results of invoking valueForKeyPath on each element of this array.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - the keypath to the elements in the input array

Returns:

The result of an operation or a new array of values corresponding to the results of valueForKeyPath on each element of this array

See Also:

NSArray.valueForKey(java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSArray.operatorNames()

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Description copied from interface: NSKeyValueCodingAdditions

Sets the value for the property identified by keyPath to value. A key path has the form relationship.property (with one or more relationships); for example "movieRole.roleName" or "movieRole.talent.lastName". The default implementation of this method (provided by NSKeyValueCodingAdditions.DefaultImplementation) gets the destination object for each relationship using valueForKey, and sends the final object a takeValueForKey message with value and property.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

value - the property identified by keyPath is set to this

keyPath - identifies the property of an object

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCodingAdditions.DefaultImplementation

classForCoder

public Class classForCoder()

Conformance to the NSCoding interface. NSArray's implementation returns the class NSArray, so subclasses that don't override this method (such as NSMutableArray) are encoded as instances of NSArray.

Specified by:

classForCoder in interface NSCoding

Returns:

NSArray.class

See Also:

NSCoding.Support.classForCoder(java.lang.Object), NSCoding, NSMutableArray

decodeObject

public static Object decodeObject(NSCoder coder)

Creates a new NSArray from the data in coder. This is the inverse function of encodeWithCoder

Parameters:

coder - the coder from which to retrieve the array's data

Returns:

an NSArray from the data in coder

See Also:

NSCoding

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Description copied from interface: NSCoding

Encodes the receiver using coder. Object type information along with an object's data is stored.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - an NSCoder object that will be used to encode object of classes that implement this interface

See Also:

NSCoder

makeObjectsPerformSelector

public void makeObjectsPerformSelector(NSSelector selector,
                                       Object[] parameters)

Invokes the method specified by selector on each object in this array. The method is invoked each time with the values in parametersas the method's arguments. The method should not, as a side effect, modify this array or its elements.

Parameters:

selector - the method to invoke. selector must not be null

parameters - the arguments to that method

See Also:

NSSelector.invoke( Object target, Object[] arguments)

hashCode

public int hashCode()

Specified by:

hashCode in interface Collection

Specified by:

hashCode in interface List

Overrides:

hashCode in class Object

Returns:

the hash code for this array

See Also:

Object.hashCode()

clone

public Object clone()

Clones this array Object Since NSArrays are immutable, there's no need to make an actual clone. Subclasses should override as appropriate.

Overrides:

clone in class Object

Returns:

this

See Also:

NSMutableArray, NSArray.immutableClone(), NSArray.mutableClone(), Object.clone()

immutableClone

public NSArray immutableClone()

Since an NSArray is immutable, NSArray's implementation simply returns this. Subclasses such as NSMutableArray should override this method to create an immutable copy of this array.

Returns:

an immutable copy of the receiver

See Also:

NSMutableArray, NSArray.mutableClone(), NSArray.clone()

mutableClone

public NSMutableArray mutableClone()

NSArray's implementation creates a new NSMutableArray with this array's elements, not copies.

Returns:

a mutable copy of this receiver

See Also:

NSMutableArray, NSArray.immutableClone(), NSArray.clone()

toString

public String toString()

Overrides:

toString in class Object

Returns:

a String representation of this array

emptyArray

public static final NSArray emptyArray()

Returns the empty NSArray (immutable). This list is serializable.

This example illustrates the type-safe way to obtain an empty list:

 List<String>     s       = NSArray.emptyArray();
 

Implementation note: Implementations of this method need not create a separate NSArray object for each call. Using this method is likely to have comparable cost to using the like-named field. (Unlike this method, the field does not provide type safety.)

Since:

5.4

See Also:

NSArray.EmptyArray

add

public void add(int index,
                Object element)

add is not a supported operation in NSArray

Specified by:

add in interface List

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.add(int, Object)

add

public boolean add(Object element)

add is not a supported operation in NSArray

Specified by:

add in interface Collection

Specified by:

add in interface List

Parameters:

element - - object to add

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.add(Object)

addAll

public boolean addAll(Collection collection)

addAll is not a supported operation in NSArray

Specified by:

addAll in interface Collection

Specified by:

addAll in interface List

Parameters:

collection - - collection to add

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.addAll(Collection)

addAll

public boolean addAll(int index,
                      Collection collection)

addAll is not a supported operation in NSArray

Specified by:

addAll in interface List

Parameters:

index - - index of element to add

collection - - collection to add

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.addAll(int, Collection)

contains

public boolean contains(Object element)

Returns true if NSArray contains the specified element. NSArrays do not support null valued lookups and will throw a NullPointerException.

Specified by:

contains in interface Collection

Specified by:

contains in interface List

Returns:

true if NSArray contains specified element

Throws:

NullPointerException - if specified element is null

Since:

5.3

See Also:

List.contains(java.lang.Object)

iterator

public Iterator iterator()

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in interface List

Since:

5.3

See Also:

List.iterator()

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection

Specified by:

toArray in interface List

Returns:

Returns a copy of array containing all of the elements in this list in proper sequence

Since:

5.3

See Also:

List.toArray()

toArray

public Object[] toArray(Object[] objects)

Specified by:

toArray in interface Collection

Specified by:

toArray in interface List

Since:

5.3

See Also:

List.toArray(Object[])

containsAll

public boolean containsAll(Collection c)

Specified by:

containsAll in interface Collection

Specified by:

containsAll in interface List

Since:

5.3

See Also:

List#containsAll

listIterator

public ListIterator listIterator()

Specified by:

listIterator in interface List

Since:

5.3

See Also:

listIterator()

listIterator

public ListIterator listIterator(int index)

Specified by:

listIterator in interface List

Parameters:

index - of first element to be returned from the list iterator (by a call to the next method).

Since:

5.3

See Also:

listIterator(int)

get

public Object get(int index)

Specified by:

get in interface List

Parameters:

index - - index of element to lookup

Throws:

IndexOutOfBoundsException - if (index < 0 || index >= size())

Since:

5.3

See Also:

List.get(int)

set

public Object set(int index,
                  Object element)

Specified by:

set in interface List

Throws:

IndexOutOfBoundsException - if (index < 0 || index >= size())

UnsupportedOperationException

Since:

5.3

See Also:

List.set(int, E)

indexOf

public int indexOf(Object element)

Specified by:

indexOf in interface List

Throws:

NullPointerException - if specified element is null

Since:

5.3

See Also:

List.indexOf(java.lang.Object)

lastIndexOf

public int lastIndexOf(Object element)

Specified by:

lastIndexOf in interface List

Throws:

NullPointerException - if specified element is null

Since:

5.3

See Also:

List.lastIndexOf(java.lang.Object)

isEmpty

public boolean isEmpty()

Returns true if this list contains no elements.

Specified by:

isEmpty in interface Collection

Specified by:

isEmpty in interface List

Returns:

Returns true if this list contains no elements.

Since:

5.3

See Also:

List.isEmpty()

size

public int size()

Specified by:

size in interface Collection

Specified by:

size in interface List

Since:

5.3

See Also:

List.size()

remove

public Object remove(int index)

Operation not supported

Specified by:

remove in interface List

Parameters:

index - of the element to removed.

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

remove(int)

remove

public boolean remove(Object element)

Operation not supported

Specified by:

remove in interface Collection

Specified by:

remove in interface List

Parameters:

element - to be removed from this list, if present.

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

remove(Object)

clear

public void clear()

Operation not supported

Specified by:

clear in interface Collection

Specified by:

clear in interface List

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.clear()

retainAll

public boolean retainAll(Collection collection)

Operation not supported

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface List

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.retainAll(java.util.Collection)

removeAll

public boolean removeAll(Collection collection)

Operation not supported

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface List

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

List.removeAll(java.util.Collection)

subList

public List subList(int fromIndex,
                    int toIndex)

Specified by:

subList in interface List

Throws:

IndexOutOfBoundsException - if index values fail the condition (fromIndex < 0 || toIndex > size || fromIndex > toIndex)

Since:

5.3

See Also:

List.subList(int, int)