com.webobjects.foundation
Class NSMutableArray

java.lang.Object
  |
  +--com.webobjects.foundation.NSArray
        |
        +--com.webobjects.foundation.NSMutableArray

All Implemented Interfaces:

Cloneable, NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Serializable

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, addObject(java.lang.Object), addObjects(java.lang.Object[]), insertObjectAtIndex(java.lang.Object, int), removeAllObjects(), removeObjectAtIndex(int), replaceObjectAtIndex(Object, int), setArray(com.webobjects.foundation.NSArray), sortUsingComparator(com.webobjects.foundation.NSComparator), Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSArray

NSArray.Operator

Inner classes inherited from class com.webobjects.foundation.NSCoding

NSCoding.Support

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Fields inherited from class com.webobjects.foundation.NSArray

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

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

NSMutableArray()
Creates an empty mutable array.

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(NSArray otherArray)
One should use the mutableClone method instead.

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(Vector vector, NSRange range, boolean ignoreNull)
Creates a mutable array containing the objects from vector in the range specified by range.

Method Summary

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.
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.
NSMutableArray	mutableClone() Creates a new NSMutableArray with the same elements as this array.
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.
void	replaceObjectAtIndex(int index, Object object) Deprecated. This method was provided for backward compatibility only.
Object	replaceObjectAtIndex(Object object, int index) Replaces the object at index with object.
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.
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.

Methods inherited from class com.webobjects.foundation.NSArray

arrayByAddingObject, arrayByAddingObjectsFromArray, classForCoder, componentsJoinedByString, componentsSeparatedByString, containsObject, count, decodeObject, encodeWithCoder, equals, firstObjectCommonWithArray, getObjects, getObjects, hashCode, indexOfIdenticalObject, indexOfIdenticalObject, indexOfObject, indexOfObject, isEqualToArray, lastObject, makeObjectsPerformSelector, objectAtIndex, objectEnumerator, objects, objects, objectsNoCopy, operatorForKey, operatorNames, removeOperatorForKey, reverseObjectEnumerator, setOperatorForKey, sortedArrayUsingComparator, sortedArrayUsingSelector, subarrayWithRange, takeValueForKey, takeValueForKeyPath, 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:

mutableClone()

NSMutableArray

public NSMutableArray(Vector vector,
                      NSRange range,
                      boolean ignoreNull)

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

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

Parameters:

vector - mutable array contains objects from this

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

Method Detail

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

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

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:

immutableClone(), 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:

mutableClone(), clone()

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

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:

immutableClone(), clone()

removeAllObjects

public void removeAllObjects()

Deletes all of the elements from this array.

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:

removeObject(java.lang.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:

removeIdenticalObject(java.lang.Object)

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:

removeObjectAtIndex(int), NSArray.indexOfObject(java.lang.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:

removeObject(java.lang.Object)

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, or null

Throws:

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

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:

removeObject(java.lang.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:

removeObject(java.lang.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:

removeObjectAtIndex(int)

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

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:

replaceObjectAtIndex(Object, int)

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

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

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