net.wotonomy.foundation
Class NSArray

java.lang.Object
  net.wotonomy.foundation.NSArray

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable, java.util.Collection, java.util.List

Direct Known Subclasses:

NSMutableArray

public class NSArray
extends java.lang.Object
implements java.util.List, java.io.Serializable

NSArray is an unmodifiable List. Calling the mutator methods of the List interface (add, addAll, set, etc.) on an instance of NSArray will throw an Unsupported Operation exception: use a NSMutableArray instead. This is to simulate Objective-C's pattern of exposing mutator methods only on mutable subinterface, which is wonderful for communicating via interface the contract on returned collections (whether you may modify return values) as well as implementing array faults.

Version:

$Revision: 929 $

Author:

michael@mpowers.net, $Author: cgruber $

See Also:

Serialized Form

Field Summary

static NSArray	EmptyArray A constant representing an empty array.
static int	NotFound Return value when array index is not found.

Constructor Summary

NSArray()
Default constructor returns an empty array.

NSArray(java.util.Collection aCollection)
Produces an array containing the objects in the specified collection.

NSArray(java.lang.Object anObject)
Produces an array containing only the specified object.

NSArray(java.lang.Object[] anArray)
Produces an array containing the specified objects.

Method Summary

void	add(int index, java.lang.Object element)
boolean	add(java.lang.Object o)
boolean	addAll(java.util.Collection coll)
boolean	addAll(int index, java.util.Collection c)
static NSArray	arrayBackedByList(java.util.List aList) Returns an NSArray backed by the specified List.
NSArray	arrayByAddingObject(java.lang.Object anObject) Returns an array containing all objects in this array plus the specified object.
NSArray	arrayByAddingObjectsFromArray(java.util.Collection aCollection) Returns an array containing all objects in this array plus all objects in the specified list.
void	clear()
java.lang.Object	clone()
java.lang.String	componentsJoinedByString(java.lang.String separator) Returns a string containing the string representations of each element in this array, with each element separated from each neighboring element by the specified string.
static NSArray	componentsSeparatedByString(java.lang.String aString, java.lang.String aSeparator) Returns an array consisting of strings within the specified string as delimited by the specified separator characters.
boolean	contains(java.lang.Object o)
boolean	containsAll(java.util.Collection c)
boolean	containsObject(java.lang.Object anObject) Returns whether an equivalent object is contained in this array.
int	count() Returns the number of items in this array.
boolean	equals(java.lang.Object o)
java.lang.Object	firstObjectCommonWithArray(java.util.Collection aCollection) Returns the first object in this array that is equivalent to an object in the specified list, or null if no objects are in common.
java.lang.Object	get(int index)
void	getObjects(java.lang.Object[] anArray) Copies the elements of this array into the specified object array as the array's capacity permits.
void	getObjects(java.lang.Object[] array, NSRange range) Copies the elements of this array that fall within the specified range into the specified object array as the array's capacity permits.
int	hashCode()
NSArray	immutableClone()
int	indexOf(java.lang.Object o)
int	indexOfIdenticalObject(java.lang.Object anObject) Returns the index of the specified object if it exists in the array, comparing by reference.
int	indexOfIdenticalObject(java.lang.Object anObject, NSRange aRange) Returns the index of the first object in the array within the specified range equivalent to the specified object.
int	indexOfObject(java.lang.Object anObject) Returns the index of the first object in the array equivalent to the specified object.
int	indexOfObject(java.lang.Object anObject, NSRange aRange) Returns the index of the first object in the array within the specified range equivalent to the specified object.
boolean	isEmpty()
boolean	isEqualToArray(java.util.List aList) Returns whether the specified list contains elements equivalent to those in this array in the same order.
java.util.Iterator	iterator()
int	lastIndexOf(java.lang.Object o)
java.lang.Object	lastObject() Returns the last object in this array, or null if the array is empty.
java.util.ListIterator	listIterator()
java.util.ListIterator	listIterator(int index)
NSMutableArray	mutableClone()
java.lang.Object	objectAtIndex(int anIndex) Returns the object at the specified index.
java.util.Enumeration	objectEnumerator() Returns an enumeration over the the elements of the array.
protected boolean	protectedAdd(java.lang.Object o) Provided for the use of subclasses like ArrayFault.
protected boolean	protectedAddAll(java.util.Collection coll) Provided for the use of subclasses like ArrayFault.
java.lang.Object	remove(int index)
boolean	remove(java.lang.Object o)
boolean	removeAll(java.util.Collection coll)
boolean	retainAll(java.util.Collection coll)
java.util.Enumeration	reverseObjectEnumerator() Returns an enumeration over the elements of the array in reverse order.
java.lang.Object	set(int index, java.lang.Object element)
int	size()
NSArray	subarrayWithRange(NSRange aRange) Returns an array comprised of only those elements whose indices fall within the specified range.
java.util.List	subList(int fromIndex, int toIndex)
java.lang.Object[]	toArray()
java.lang.Object[]	toArray(java.lang.Object[] a)
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

NotFound

public static final int NotFound

Return value when array index is not found.

See Also:

Constant Field Values

EmptyArray

public static final NSArray EmptyArray

A constant representing an empty array.

Constructor Detail

NSArray

public NSArray()

Default constructor returns an empty array.

NSArray

public NSArray(java.lang.Object anObject)

Produces an array containing only the specified object.

NSArray

public NSArray(java.lang.Object[] anArray)

Produces an array containing the specified objects.

NSArray

public NSArray(java.util.Collection aCollection)

Produces an array containing the objects in the specified collection.

Method Detail

arrayBackedByList

public static NSArray arrayBackedByList(java.util.List aList)

Returns an NSArray backed by the specified List. This is useful to "protect" an internal representation that is returned by a method of return type NSArray.

count

public int count()

Returns the number of items in this array.

arrayByAddingObject

public NSArray arrayByAddingObject(java.lang.Object anObject)

Returns an array containing all objects in this array plus the specified object.

arrayByAddingObjectsFromArray

public NSArray arrayByAddingObjectsFromArray(java.util.Collection aCollection)

Returns an array containing all objects in this array plus all objects in the specified list.

componentsJoinedByString

public java.lang.String componentsJoinedByString(java.lang.String separator)

Returns a string containing the string representations of each element in this array, with each element separated from each neighboring element by the specified string.

containsObject

public boolean containsObject(java.lang.Object anObject)

Returns whether an equivalent object is contained in this array.

firstObjectCommonWithArray

public java.lang.Object firstObjectCommonWithArray(java.util.Collection aCollection)

Returns the first object in this array that is equivalent to an object in the specified list, or null if no objects are in common.

isEqualToArray

public boolean isEqualToArray(java.util.List aList)

Returns whether the specified list contains elements equivalent to those in this array in the same order.

lastObject

public java.lang.Object lastObject()

Returns the last object in this array, or null if the array is empty.

subarrayWithRange

public NSArray subarrayWithRange(NSRange aRange)

Returns an array comprised of only those elements whose indices fall within the specified range.

objectEnumerator

public java.util.Enumeration objectEnumerator()

Returns an enumeration over the the elements of the array.

reverseObjectEnumerator

public java.util.Enumeration reverseObjectEnumerator()

Returns an enumeration over the elements of the array in reverse order.

getObjects

public void getObjects(java.lang.Object[] anArray)

Copies the elements of this array into the specified object array as the array's capacity permits.

getObjects

public void getObjects(java.lang.Object[] array,
                       NSRange range)

Copies the elements of this array that fall within the specified range into the specified object array as the array's capacity permits. This method must not overflow, even in the face of a null range, an over or under-sized array, or a bad range. It may underflow and fail to entirely populate the array, if the array is larger than the data to be copied. TODO: Check whether in WebObjects the range supposed to be measured against the parameter or the NSArray itself??? -ceg

Parameters:

anArray - An object array to be filled by this method.

range - An NSRange object representing the range of data in the NSArray to be copied.

indexOfObject

public int indexOfObject(java.lang.Object anObject)

Returns the index of the first object in the array equivalent to the specified object. Returns NotFound if the item is not found.

indexOfObject

public int indexOfObject(java.lang.Object anObject,
                         NSRange aRange)

Returns the index of the first object in the array within the specified range equivalent to the specified object. Returns NotFound if the item is not found.

indexOfIdenticalObject

public int indexOfIdenticalObject(java.lang.Object anObject)

Returns the index of the specified object if it exists in the array, comparing by reference. Returns NotFound if the item is not found.

indexOfIdenticalObject

public int indexOfIdenticalObject(java.lang.Object anObject,
                                  NSRange aRange)

Returns the index of the first object in the array within the specified range equivalent to the specified object.

objectAtIndex

public java.lang.Object objectAtIndex(int anIndex)

Returns the object at the specified index. Throws an IndexOutOfRange exception if the index is out of range.

componentsSeparatedByString

public static NSArray componentsSeparatedByString(java.lang.String aString,
                                                  java.lang.String aSeparator)

Returns an array consisting of strings within the specified string as delimited by the specified separator characters.

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

immutableClone

public NSArray immutableClone()

mutableClone

public NSMutableArray mutableClone()

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

contains

public boolean contains(java.lang.Object o)

Specified by:

contains in interface java.util.Collection

Specified by:

contains in interface java.util.List

containsAll

public boolean containsAll(java.util.Collection c)

Specified by:

containsAll in interface java.util.Collection

Specified by:

containsAll in interface java.util.List

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Collection

Specified by:

equals in interface java.util.List

Overrides:

equals in class java.lang.Object

get

public java.lang.Object get(int index)

Specified by:

get in interface java.util.List

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Collection

Specified by:

hashCode in interface java.util.List

Overrides:

hashCode in class java.lang.Object

indexOf

public int indexOf(java.lang.Object o)

Specified by:

indexOf in interface java.util.List

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection

Specified by:

isEmpty in interface java.util.List

lastIndexOf

public int lastIndexOf(java.lang.Object o)

Specified by:

lastIndexOf in interface java.util.List

size

public int size()

Specified by:

size in interface java.util.Collection

Specified by:

size in interface java.util.List

toArray

public java.lang.Object[] toArray()

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.List

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.List

add

public void add(int index,
                java.lang.Object element)

Specified by:

add in interface java.util.List

add

public boolean add(java.lang.Object o)

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.List

addAll

public boolean addAll(java.util.Collection coll)

Specified by:

addAll in interface java.util.Collection

Specified by:

addAll in interface java.util.List

addAll

public boolean addAll(int index,
                      java.util.Collection c)

Specified by:

addAll in interface java.util.List

clear

public void clear()

Specified by:

clear in interface java.util.Collection

Specified by:

clear in interface java.util.List

iterator

public java.util.Iterator iterator()

Specified by:

iterator in interface java.lang.Iterable

Specified by:

iterator in interface java.util.Collection

Specified by:

iterator in interface java.util.List

listIterator

public java.util.ListIterator listIterator()

Specified by:

listIterator in interface java.util.List

listIterator

public java.util.ListIterator listIterator(int index)

Specified by:

listIterator in interface java.util.List

remove

public java.lang.Object remove(int index)

Specified by:

remove in interface java.util.List

remove

public boolean remove(java.lang.Object o)

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.List

removeAll

public boolean removeAll(java.util.Collection coll)

Specified by:

removeAll in interface java.util.Collection

Specified by:

removeAll in interface java.util.List

retainAll

public boolean retainAll(java.util.Collection coll)

Specified by:

retainAll in interface java.util.Collection

Specified by:

retainAll in interface java.util.List

set

public java.lang.Object set(int index,
                            java.lang.Object element)

Specified by:

set in interface java.util.List

subList

public java.util.List subList(int fromIndex,
                              int toIndex)

Specified by:

subList in interface java.util.List

protectedAdd

protected boolean protectedAdd(java.lang.Object o)

Provided for the use of subclasses like ArrayFault.

protectedAddAll

protected boolean protectedAddAll(java.util.Collection coll)

Provided for the use of subclasses like ArrayFault.