WebObjects 5.2

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.