com.webobjects.foundation
Class NSMutableArray

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

All Implemented Interfaces:

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

public class NSMutableArray
extends NSArray

The NSMutableArray class provides facilities for managing a mutable collection of objects. It adds insertion and deletion operations to the basic array-handling behavior inherited from its superclass, NSArray.

The following table describes the NSMutableArray methods that provide the basis for all NSMutableArray's other methods; that is, all other methods are implemented in terms of these. If you create a subclass of NSMutableArray, you need to ensure that only these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

NSMutableArray's Base API

Method	Description
addObject	Adds an object to the array.
addObjects	Adds multiple objects to the array.
insertObjectAtIndex	Inserts an object into the array at a specified index.
removeAllObjects	Empties the receiver of all its elements.
removeObjectAtIndex	Removes the object at a specified index from the array.
replaceObjectAtIndex(Object, int)	Replaces the object at a specified index with another object.
setArray	Sets an array's elements to the ones in another array.
sortUsingComparator	Sorts the elements of the array.

The other methods provide convenient ways of inserting an object into a specific slot in the array and removing an object based on its identity or position in the array.

See Also:

List, ArrayList, Vector, NSMutableArray.addObject(java.lang.Object), NSMutableArray.addObjects(java.lang.Object[]), NSMutableArray.insertObjectAtIndex(E, int), NSMutableArray.removeAllObjects(), NSMutableArray.removeObjectAtIndex(int), NSMutableArray.replaceObjectAtIndex(Object, int), NSMutableArray.setArray(com.webobjects.foundation.NSArray), NSMutableArray.sortUsingComparator(com.webobjects.foundation.NSComparator), Serialized Form

Nested Class Summary

class

NSMutableArray.MutableArrayListIterator

Nested classes/interfaces inherited from class com.webobjects.foundation.NSArray

NSArray.Operator

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

Fields inherited from class com.webobjects.foundation.NSArray

AverageOperatorName, CheckForNull, CountOperatorName, EmptyArray, IgnoreNull, MaximumOperatorName, MinimumOperatorName, NotFound, SumOperatorName

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

	NSMutableArray() Creates an empty mutable array.
	NSMutableArray(Collection collection) Creates a mutable array from objects that implement the java.util.Collection interface.
	NSMutableArray(Object object) Creates a mutable array containing the single element object.
	NSMutableArray(Object[] objects) Creates a mutable array containing objects.
	NSMutableArray(Object[] objects, NSRange range) Creates a mutable array containing the objects from objects in the range specified by range.
	NSMutableArray(int capacity) Creates an empty mutable array with enough allocated memory to hold the number of objects specified by capacity, a number greater than or equal to 0.
	NSMutableArray(List list, NSRange range, boolean ignoreNull) Creates a mutable array containing the objects from list in the range specified by range.
	NSMutableArray(NSArray otherArray) One should use the mutableClone method instead.
protected	NSMutableArray(Object[] objects, int rangeLocation, int rangeLength, boolean checkForNull, boolean ignoreNull) Creates a new Mutable Array

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
void	addObject(Object object) Inserts object at the end of this array.
void	addObjects(Object[] objects) Adds all the elements of objects to the end of this array.
void	addObjectsFromArray(NSArray otherArray) Adds the objects from otherArray to the end of the this array.
void	clear() Operation not supported
Object	clone() Creates a clone of this array.
NSArray	immutableClone() Creates a new NSArray with the same elements as this array.
void	insertObjectAtIndex(Object object, int index) Inserts object into this array at index.
ListIterator	listIterator()
ListIterator	listIterator(int index)
NSMutableArray	mutableClone() Creates a new NSMutableArray with the same elements as this array.
Object	remove(int index) Removes the element at the specified position in this list.
boolean	remove(Object object) Removes the first occurrence in this list of the specified element.
boolean	removeAll(Collection collection) Operation not supported
void	removeAllObjects() Deletes all of the elements from this array.
boolean	removeIdenticalObject(Object object) Removes all occurrences of object throughout the array.
boolean	removeIdenticalObject(Object object, NSRange range) As removeIdenticalObject(Object object) but it only searchs a subset of this array as specified by range.
Object	removeLastObject() Removes this array's last element (the highest-valued index).
boolean	removeObject(Object object) Removes all occurrences of object throughout this array.
boolean	removeObject(Object object, NSRange range) Same as removeObject(Object object) but only searches a subset of this array as specified by NSRange.
Object	removeObjectAtIndex(int index) Removes the object at index and moves all elements beyond index up one slot to fill the gap.
void	removeObjects(Object[] objects) This method is similar to removeObject, but allows you to efficiently remove all the objects in objects with a single operation.
void	removeObjectsInArray(NSArray otherArray) This method is similar to removeObject, but allows you to efficiently remove the set of objects in otherArray with a single operation.
void	removeObjectsInRange(NSRange range) Removes each of the objects within the specified range from this array using removeObjectAtIndex.
protected void	removeRange(int fromIndex, int toIndex) Removes from this list all of the elements whose index is between fromIndex, inclusive, and toIndex, exclusive.
Object	replaceObjectAtIndex(Object object, int index) Replaces the object at index with object.
void	replaceObjectAtIndex(int index, Object object) Deprecated. This method was provided for backward compatibility only.
void	replaceObjectsInRange(NSRange range, NSArray otherArray, NSRange otherRange) Replaces a subset of the objects in this array as specified by range with a subset of the objects in otherArray as specified by otherRange.
boolean	retainAll(Collection collection) Operation not supported
Object	set(int index, Object element)
void	setArray(NSArray otherArray) Sets this array's elements to those in otherArray.
void	sortUsingComparator(NSComparator comparator) Sorts this array's elements, as determined by comparator.
List	subList(int fromIndex, int toIndex) Create a linked sublist.

Methods inherited from class com.webobjects.foundation.NSArray

arrayByAddingObject, arrayByAddingObjectsFromArray, arrayList, classForCoder, componentsJoinedByString, componentsSeparatedByString, contains, containsAll, containsObject, count, decodeObject, emptyArray, encodeWithCoder, equals, firstObjectCommonWithArray, get, getObjects, getObjects, hashCode, indexOf, indexOfIdenticalObject, indexOfIdenticalObject, indexOfObject, indexOfObject, isEmpty, isEqualToArray, iterator, lastIndexOf, lastObject, makeObjectsPerformSelector, objectAtIndex, objectEnumerator, objects, objects, objectsNoCopy, operatorForKey, operatorNames, removeOperatorForKey, reverseObjectEnumerator, setOperatorForKey, size, sortedArrayUsingComparator, sortedArrayUsingSelector, subarrayWithRange, takeValueForKey, takeValueForKeyPath, toArray, toArray, toString, valueForKey, valueForKeyPath, vector

Methods inherited from class java.lang.Object

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

Constructor Detail

NSMutableArray

public NSMutableArray()

Creates an empty mutable array.

NSMutableArray

public NSMutableArray(int capacity)

Creates an empty mutable array with enough allocated memory to hold the number of objects specified by capacity, a number greater than or equal to 0.

NSMutableArrays expand as needed, so capacity simply establishes the object's initial capacity.

Parameters:

capacity - a size hint for the anticipated upper bound

NSMutableArray

public NSMutableArray(Object object)

Creates a mutable array containing the single element object.

Parameters:

object - the single element contained in the mutable array

NSMutableArray

public NSMutableArray(Object[] objects)

Creates a mutable array containing objects.

Parameters:

objects - the objects contained in the mutable array

NSMutableArray

public NSMutableArray(Object[] objects,
                      NSRange range)

Creates a mutable array containing the objects from objects in the range specified by range.

After an immutable array has been initialized in this way, it can't be modified.

Parameters:

objects - the objects contained in the mutable array

range - the range specified

NSMutableArray

public NSMutableArray(NSArray otherArray)

One should use the mutableClone method instead. Creates a mutable array containing the objects in otherArray.

Parameters:

otherArray - contains the objects

See Also:

NSMutableArray.mutableClone()

NSMutableArray

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

Creates a mutable array containing the objects from list in the range specified by range.

The ignoreNull argument controls the method's behavior when it encounters a null value in the vector: if ignoreNull is true, the null value is simply ignored.

Parameters:

list - object that implements the List interface

range - the specified range

ignoreNull - the null value is ignored

Throws:

IllegalArgumentException - if ignoreNull is false and a null reference exists within the specified range of the vector.

See Also:

Vector

NSMutableArray

public NSMutableArray(Collection collection)

Creates a mutable array 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 List or List parameter is null.

Since:

5.4

See Also:

List

NSMutableArray

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

Creates a new Mutable Array

Parameters:

objects -

rangeLocation -

rangeLength -

checkForNull -

ignoreNull -

Method Detail

setArray

public void setArray(NSArray otherArray)

Sets this array's elements to those in otherArray.

Any existing elements are replaced. It truncates this array, if necessary, so that it contains no more than the number of elements in otherArray. If there are more elements in otherArray than there are in this array, the additional items are added.

Parameters:

otherArray - the elements to replace those in this array

addObject

public void addObject(Object object)

Inserts object at the end of this array.

Parameters:

object - the object to be inserted

Throws:

IllegalArgumentException - if object is null

addObjects

public void addObjects(Object[] objects)

Adds all the elements of objects to the end of this array.

Parameters:

objects - the array of objects to append

Throws:

IllegalArgumentException - if any of the objects in objects are null

replaceObjectAtIndex

public Object replaceObjectAtIndex(Object object,
                                   int index)

Replaces the object at index with object.

Parameters:

object - the new object to be placed at this index

index - the index into the array for the new object

Returns:

the previous object in the array at index which was replaced, or null

Throws:

IllegalArgumentException - if object is null or if index is beyond the end of the array

replaceObjectAtIndex

@Deprecated
public void replaceObjectAtIndex(int index,
                                            Object object)

Deprecated. This method was provided for backward compatibility only.

Use replaceObjectAtIndex(Object, int) instead.

Parameters:

index - position to place the new object

object - the new object to occupy the position at index

See Also:

NSMutableArray.replaceObjectAtIndex(Object, int)

insertObjectAtIndex

public void insertObjectAtIndex(Object object,
                                int index)

Inserts object into this array at index. If index is already occupied, the objects at index and beyond are shifted down one slot to make room. index cannot be greater than the number of elements in the array.

Note that NSArrays are not like C arrays. That is, even though you might specify a size when you create an array, the specified size is regarded as a hint; the actual size of the array is still 0. Because of this, you can only insert new objects in ascending order without gaps. Once you add two objects, the array's size is 2, so you can add objects at indexes 0, 1, or 2. Index 3 is illegal and out of bounds; if you try to add an object at index 3 (when the size of the array is 2), NSMutableArray throws an exception.

Parameters:

object - the object to be inserted

index - the position in this array to place the new object

Throws:

IllegalArgumentException - if object is null or if index is greater than the number of elements in the array

removeObjectAtIndex

public Object removeObjectAtIndex(int index)

Removes the object at index and moves all elements beyond index up one slot to fill the gap.

Parameters:

index - the object at this position is removed

Returns:

the object removed from this array

Throws:

IllegalArgumentException - if the array is empty or if index is beyond the end of the array

removeAllObjects

public void removeAllObjects()

Deletes all of the elements from this array.

sortUsingComparator

public void sortUsingComparator(NSComparator comparator)
                         throws NSComparator.ComparisonException

Sorts this array's elements, as determined by comparator.

Parameters:

comparator - determines sorting behavior

Throws:

NSComparator.ComparisonException - if comparator cannot sort these elements

IllegalArgumentException - if comparator is null

See Also:

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

addObjectsFromArray

public void addObjectsFromArray(NSArray otherArray)

Adds the objects from otherArray to the end of the this array.

Parameters:

otherArray - the objects to be appended to this array

replaceObjectsInRange

public void replaceObjectsInRange(NSRange range,
                                  NSArray otherArray,
                                  NSRange otherRange)

Replaces a subset of the objects in this array as specified by range with a subset of the objects in otherArray as specified by otherRange.

range and otherRange do not have to be equal; if range is greater than otherRange, the extra objects in this array are removed. If otherRange is greater than range, the extra objects from otherArray are inserted into this array.

Parameters:

range - subset of objects in this array to replace

otherArray - the array of new objects

otherRange - range subset of objects in otherArray to use

removeLastObject

public Object removeLastObject()

Removes this array's last element (the highest-valued index). Returns null if the array is empty.

Returns:

the removed object, or null

removeObject

public boolean removeObject(Object object)

Removes all occurrences of object throughout this array. Elements in this array are considered equivalent to object if equals returns true.

Parameters:

object - the object for which all equivalent objects will be deleted from this array

Returns:

true if one or more objects were actually removed

Throws:

IllegalArgumentException - if object is null

See Also:

NSMutableArray.removeObjectAtIndex(int), NSArray.indexOfObject(Object)

removeObject

public boolean removeObject(Object object,
                            NSRange range)

Same as removeObject(Object object) but only searches a subset of this array as specified by NSRange.

Parameters:

object - occurrences of this are removed throughout the subrange of this array

range - the specified subset to search

Returns:

true if one or more objects were actually removed

Throws:

IllegalArgumentException - if anObject is null or if range is out of bounds

See Also:

NSMutableArray.removeObject(Object, NSRange)

removeIdenticalObject

public boolean removeIdenticalObject(Object object)

Removes all occurrences of object throughout the array. Unlike removeObject(Object object) this method uses == to determine equivalence instead of equals.

Parameters:

object - its occurence is removed throughout the array

Returns:

true if one or more objects were actually removed

Throws:

IllegalArgumentException - if object is null

See Also:

NSMutableArray.removeObject(Object)

removeIdenticalObject

public boolean removeIdenticalObject(Object object,
                                     NSRange range)

As removeIdenticalObject(Object object) but it only searchs a subset of this array as specified by range.

Parameters:

object - all occurrences of this within the subrange are removed from this array

range - the specified range

Returns:

true if one or more objects were actually removed

Throws:

IllegalArgumentException - if object is null or if range is out of bounds

See Also:

NSMutableArray.removeIdenticalObject(Object)

removeObjects

public void removeObjects(Object[] objects)

This method is similar to removeObject, but allows you to efficiently remove all the objects in objects with a single operation.

Parameters:

objects - the set of objects to be removed

See Also:

NSMutableArray.removeObjects(Object[])

removeObjectsInArray

public void removeObjectsInArray(NSArray otherArray)

This method is similar to removeObject, but allows you to efficiently remove the set of objects in otherArray with a single operation.

Parameters:

otherArray - the set of objects in this are removed

See Also:

NSMutableArray.removeObject(Object)

removeObjectsInRange

public void removeObjectsInRange(NSRange range)

Removes each of the objects within the specified range from this array using removeObjectAtIndex.

Parameters:

range - the range specified

Throws:

IllegalArgumentException - if range is out of bounds

See Also:

NSMutableArray.removeObjectAtIndex(int)

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)

Removes from this list all of the elements whose index is between fromIndex, inclusive, and toIndex, exclusive. Shifts any succeeding elements to the left (reduces their index). This call shortens the ArrayList by (toIndex - fromIndex) elements. (If toIndex==fromIndex, this operation has no effect.)

This method is called by the clear operation on this list and its subLists. Overriding this method to take advantage of the internals of the list implementation can substantially improve the performance of the clear operation on this list and its subLists.

This implementation gets a list iterator positioned before fromIndex, and repeatedly calls ListIterator.next followed by ListIterator.remove until the entire range has been removed. Note: if ListIterator.remove requires linear time, this implementation requires quadratic time.

Parameters:

fromIndex - index of first element to be removed.

toIndex - index after last element to be removed.

Since:

5.4

clone

public Object clone()

Creates a clone of this array. NSMutableArray's implementation simply creates a new NSMutableArray with the same objects as this array.

Overrides:

clone in class NSArray

Returns:

a clone of this array

See Also:

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

immutableClone

public NSArray immutableClone()

Creates a new NSArray with the same elements as this array.

Overrides:

immutableClone in class NSArray

Returns:

an immutable clone of this array

See Also:

NSMutableArray.mutableClone(), NSMutableArray.clone()

mutableClone

public NSMutableArray mutableClone()

Creates a new NSMutableArray with the same elements as this array.

Overrides:

mutableClone in class NSArray

Returns:

a clone of this array

See Also:

NSMutableArray.immutableClone(), NSMutableArray.clone()

remove

public Object remove(int index)

Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

Specified by:

remove in interface List

Overrides:

remove in class NSArray

Parameters:

index - the index of the element to removed.

Returns:

the element previously at the specified position.

Throws:

UnsupportedOperationException - if the remove method is not supported by this list.

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

Since:

5.4

See Also:

List.remove(int)

remove

public boolean remove(Object object)

Removes the first occurrence in this list of the specified element. If this list does not contain the element, it is unchanged. More formally, removes the element with the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))) (if such an element exists).

Specified by:

remove in interface Collection

Specified by:

remove in interface List

Overrides:

remove in class NSArray

Parameters:

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

Returns:

true if this list contained the specified element.

Throws:

ClassCastException - if the type of the specified element is incompatible with this list (optional).

NullPointerException - if the specified element is null and this list does not support null elements (optional).

UnsupportedOperationException - if the remove method is not supported by this list.

Since:

5.4

See Also:

List.remove(Object)

clear

public void clear()

Description copied from class: NSArray

Operation not supported

Specified by:

clear in interface Collection

Specified by:

clear in interface List

Overrides:

clear in class NSArray

Since:

5.4

See Also:

List.clear(), NSMutableArray.removeAllObjects()

retainAll

public boolean retainAll(Collection collection)

Description copied from class: NSArray

Operation not supported

Specified by:

retainAll in interface Collection

Specified by:

retainAll in interface List

Overrides:

retainAll in class NSArray

Since:

5.4

See Also:

List.retainAll(java.util.Collection)

removeAll

public boolean removeAll(Collection collection)

Description copied from class: NSArray

Operation not supported

Specified by:

removeAll in interface Collection

Specified by:

removeAll in interface List

Overrides:

removeAll in class NSArray

Since:

5.4

See Also:

List.removeAll(java.util.Collection)

add

public void add(int index,
                Object element)

Description copied from class: NSArray

add is not a supported operation in NSArray

Specified by:

add in interface List

Overrides:

add in class NSArray

Since:

5.4

See Also:

List.add(int, Object)

add

public boolean add(Object element)

Description copied from class: NSArray

add is not a supported operation in NSArray

Specified by:

add in interface Collection

Specified by:

add in interface List

Overrides:

add in class NSArray

Parameters:

element - - object to add

Since:

5.4

See Also:

List.add(Object)

addAll

public boolean addAll(Collection collection)

Description copied from class: NSArray

addAll is not a supported operation in NSArray

Specified by:

addAll in interface Collection

Specified by:

addAll in interface List

Overrides:

addAll in class NSArray

Parameters:

collection - - collection to add

Since:

5.4

See Also:

List.addAll(Collection)

addAll

public boolean addAll(int index,
                      Collection collection)

Description copied from class: NSArray

addAll is not a supported operation in NSArray

Specified by:

addAll in interface List

Overrides:

addAll in class NSArray

Parameters:

index - - index of element to add

collection - - collection to add

Since:

5.4

See Also:

List.addAll(int, Collection)

set

public Object set(int index,
                  Object element)

Specified by:

set in interface List

Overrides:

set in class NSArray

Throws:

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

Since:

5.4

See Also:

List.set(int, E)

subList

public List subList(int fromIndex,
                    int toIndex)

Create a linked sublist.

Note: This list does not implement the NSMutableArray protocol

Specified by:

subList in interface List

Overrides:

subList in class NSArray

Throws:

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

Since:

5.4

See Also:

List.subList(int, int)

listIterator

public ListIterator listIterator(int index)

Specified by:

listIterator in interface List

Overrides:

listIterator in class NSArray

Parameters:

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

Since:

5.4.1

See Also:

listIterator(int)

listIterator

public ListIterator listIterator()

Specified by:

listIterator in interface List

Overrides:

listIterator in class NSArray

Since:

5.4.1

See Also:

listIterator()