net.wotonomy.foundation
Class NSArray

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



Copyright © 2006 null. All Rights Reserved.