WebObjects 5.4.2

com.webobjects.foundation
Class NSArray

java.lang.Object
  extended by 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:

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:

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)

Last updated June 2008

Copyright © 2000-2008 Apple Inc.