hlt.language.util

Class ArrayList

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList

hlt.language.util.ArrayList

All Implemented Interfaces:

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

Direct Known Subclasses:

Stack, Taxonomy

public class ArrayList
extends java.util.AbstractList
implements java.util.Collection

This class reimplements java.util.ArrayList to avoid paying the penalty of index range checks that are performed needlessly by that class in spite of that being done in any case by the JVM on the underlying array. As its original namesake, this class is not synchronized.

Version:

Last modified on Sun Dec 30 00:53:08 2012 by hak

Author:

Hassan Aït-Kaci

Copyright:

© Hassan Aït-Kaci

Constructor Summary

Constructors

Constructor and Description
ArrayList() Constructs an empty ArrayList so that its internal data array has size 10 and its standard capacity increment is zero.
ArrayList(java.util.Collection c) Constructs an ArrayList containing the objects in the specified collection, in the order they are returned by the collection's iterator.
ArrayList(int initialCapacity) Constructs an empty ArrayList with the specified initial capacity and with its capacity increment equal to zero.
ArrayList(int initialCapacity, int capacityIncrement) Constructs an empty ArrayList with the specified initial capacity and capacity increment.
ArrayList(java.lang.Object[] a) Constructs an ArrayList containing the objects contained in the specified array, in the same order.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(int index, java.lang.Object element) Inserts the specified element at the specified position in this ArrayList.
boolean	add(java.lang.Object element) Appends the specified element to the end of this ArrayList, growing the array if necessary.
boolean	addAll(ArrayList v) Appends all of the elements in the specified ArrayList to the end of this ArrayList.
void	addAll(int index, ArrayList v) Inserts all of the elements in the specified ArrayList into this ArrayList at the specified position.
void	addAll(int index, java.lang.Object[] a) Inserts all the elements in the specified array at the specified index in this ArrayList.
boolean	addAll(java.lang.Object[] a) Appends all of the elements in the specified array to the end of this ArrayList, in the order of the array.
void	addElement(java.lang.Object element) Adds the specified component to the end of this ArrayList, increasing its size by one.
int	capacity() Returns the current capacity of this ArrayList.
void	clear() Removes all of the elements from this ArrayList.
void	clear(int index) Clears all elements of this arraylist at index equal to or greater than the specified index.
java.lang.Object	clone() Returns a clone of this ArrayList.
boolean	contains(java.lang.Object element) Tests if the specified Object is a component in this ArrayList.
boolean	containsAll(ArrayList v) Returns true if this ArrayList contains all of the elements in the specified ArrayList.
boolean	containsAll(java.lang.Object[] a) Returns true if this ArrayList contains all of the elements in the specified array.
void	copyInto(java.lang.Object[] a) Copies the components of this ArrayList into the specified array a.
java.lang.Object	elementAt(int index) Returns the component at the specified index.
void	ensureCapacity(int minCapacity) Increases the capacity of this ArrayList, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.
boolean	equals(java.lang.Object o) Compares the specified object with this ArrayList for equality.
java.lang.Object	firstElement() Returns the first component (the item at index 0) of this ArrayList.
java.lang.Object	get(int index) Returns the element at the specified position in this ArrayList.
boolean	hasGaps() Returns true iff there are null elements between 0 and size()-1.
int	hashCode() Returns the hash code value for this ArrayList.
int	indexOf(java.lang.Object element) Searches for the first occurrence of the given Object; returns -1 if it is not found.
int	indexOf(java.lang.Object element, int index) Searches for the first occurence of the given Object, beginning the search at index; returns -1 if it is not found.
void	insertElementAt(java.lang.Object element, int index) Inserts the specified Object as a component in this ArrayList at the specified index.
boolean	isEmpty() Tests if this ArrayList has no components.
java.util.Iterator	iterator()
java.lang.Object	lastElement() Returns the last component of the ArrayList.
int	lastIndexOf(java.lang.Object element) Returns the index of the last occurrence of the specified Object in this ArrayList; returns -1 if it is not found.
int	lastIndexOf(java.lang.Object element, int index) Searches backwards for the specified Object, starting from the specified index, and returns its index, or -1 if not found.
java.lang.Object	remove(int index) Removes the element at the specified position and shifts any subsequent elements to the left (subtracts one from their indices).
boolean	remove(java.lang.Object element) Removes the first occurrence of the specified element.
boolean	removeAll(ArrayList v) Removes from this ArrayList all of its elements that are contained in the specified ArrayList.
boolean	removeAll(java.lang.Object[] a) Removes from this ArrayList all of its elements that are contained in the specified array.
void	removeAllElements() Removes all components from this ArrayList.
boolean	removeAllFirst(ArrayList v) Removes from this ArrayList the first occurrence of the elements that are contained in the specified ArrayList.
boolean	removeAllFirst(java.lang.Object[] a) Removes from this ArrayList the first occurrence of the elements that are contained in the specified array
boolean	removeElement(java.lang.Object element) Removes the first occurrence of the specified element.
void	removeElementAt(int index) Deletes the component at the specified index.
void	removeGaps() Eliminates null gaps from this ArrayList, compressing it down so that all elements between 0 and size()-1 are non-null.
void	removeRange(int fromIndex, int toIndex) Removes from this ArrayList all of the elements whose index is between fromIndex, inclusive and toIndex, exclusive.
boolean	retainAll(ArrayList v) Retains only the elements in this ArrayList whose elements are contained in the specified ArrayList.
java.lang.Object	set(int index, java.lang.Object element) Replaces the element at the specified position in this ArrayList with the specified element.
void	setElementAt(java.lang.Object element, int index) Sets the component at the specified index of this ArrayList to be the specified Object.
void	setIncrementFactor(float incrementFactor)
void	setLast(java.lang.Object element) Replaces the element at the last position in this ArrayList with the specified element.
void	setSize(int newSize) Sets the size of this ArrayList.
int	size() Returns the number of components in this ArrayList.
java.lang.Object[]	toArray() Returns an array containing all of the elements in this ArrayList in the correct order.
java.lang.String	toString() Returns a string representation of this ArrayList
java.lang.String[]	toStringArray() Returns an array containing all of the string forms of the elements in this ArrayList in the correct order.
void	trimToSize() Trims the capacity of this ArrayList to be the ArrayList's current size.

Methods inherited from class java.util.AbstractList

addAll, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, removeAll, retainAll, toArray

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

addAll, containsAll, removeAll, retainAll, toArray

Methods inherited from interface java.util.List

addAll, containsAll, removeAll, retainAll, toArray

Constructor Detail

ArrayList

public ArrayList(int initialCapacity,
         int capacityIncrement)

Constructs an empty ArrayList with the specified initial capacity and capacity increment.

Parameters:

initialCapacity - the initial capacity of the ArrayList.

capacityIncrement - amount by which the capacity is increased on overflow.

Throws:

java.lang.NegativeArraySizeException - if the specified initial capacity is negative.

ArrayList

public ArrayList(int initialCapacity)

Constructs an empty ArrayList with the specified initial capacity and with its capacity increment equal to zero.

Parameters:

initialCapacity - the initial capacity of the ArrayList.

Throws:

java.lang.NegativeArraySizeException - if the specified initial capacity is negative.

ArrayList

public ArrayList()

Constructs an empty ArrayList so that its internal data array has size 10 and its standard capacity increment is zero.

ArrayList

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

Constructs an ArrayList containing the objects contained in the specified array, in the same order.

Parameters:

a - an array of Objects.

ArrayList

public ArrayList(java.util.Collection c)

Constructs an ArrayList containing the objects in the specified collection, in the order they are returned by the collection's iterator.

Parameters:

c - the collection whose elements are to be placed into this ArrayList.

Method Detail

copyInto

public final void copyInto(java.lang.Object[] a)

Copies the components of this ArrayList into the specified array a. The item at index k in this ArrayList is copied into component k of a. The array must be big enough to hold all the elements of this ArrayList, else an IndexOutOfBoundsException is thrown.

Parameters:

a - the array into which the components get copied.

Throws:

java.lang.IndexOutOfBoundsException - if the array is too small.

trimToSize

public final void trimToSize()

Trims the capacity of this ArrayList to be the ArrayList's current size. If the capacity of this ArrayList is larger than its current size, then the capacity is changed to equal the size by replacing its internal data array, kept in the field _elementData, with a smaller one. An application can use this operation to minimize the storage of an ArrayList.

ensureCapacity

public final void ensureCapacity(int minCapacity)

Increases the capacity of this ArrayList, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.

If the current capacity of this ArrayList is less than minCapacity, then its capacity is increased by replacing its internal data array, kept in the field _elementData, with a larger one. The size of the new data array will be the old size plus capacityIncrement, unless the value of capacityIncrement is less than or equal to zero, in which case the new capacity will be the old capacity multiplied by incrementFactor; but if this new size is still smaller than minCapacity, then the new capacity will be minCapacity.

Parameters:

minCapacity - the desired minimum capacity.

setSize

public final void setSize(int newSize)

Sets the size of this ArrayList. If the new size is greater than the current size, new nulls are added to the end of the ArrayList. If the new size is less than the current size, all components at index newSize and greater are set to null.

Parameters:

newSize - the new size of this ArrayList.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if new size is negative.

capacity

public final int capacity()

Returns the current capacity of this ArrayList.

Returns:

the current capacity the length of its internal data array.

size

public final int size()

Returns the number of components in this ArrayList. Note that if null exists (by adding nulls or setting higher positions to null), this will return the index just above that of the highest non-null element.

Specified by:

size in interface java.util.Collection

Specified by:

size in interface java.util.List

Specified by:

size in class java.util.AbstractCollection

Returns:

the number of components in this ArrayList.

hasGaps

public final boolean hasGaps()

Returns true iff there are null elements between 0 and size()-1.

removeGaps

public final void removeGaps()

Eliminates null gaps from this ArrayList, compressing it down so that all elements between 0 and size()-1 are non-null.

isEmpty

public final boolean isEmpty()

Tests if this ArrayList has no components.

Specified by:

isEmpty in interface java.util.Collection

Specified by:

isEmpty in interface java.util.List

Overrides:

isEmpty in class java.util.AbstractCollection

Returns:

true if this ArrayList's size is zero; false otherwise.

contains

public final boolean contains(java.lang.Object element)

Tests if the specified Object is a component in this ArrayList.

Specified by:

contains in interface java.util.Collection

Specified by:

contains in interface java.util.List

Overrides:

contains in class java.util.AbstractCollection

Parameters:

element - a Object.

Returns:

true if the specified Object is in this ArrayList; false otherwise.

indexOf

public final int indexOf(java.lang.Object element)

Searches for the first occurrence of the given Object; returns -1 if it is not found.

Specified by:

indexOf in interface java.util.List

Overrides:

indexOf in class java.util.AbstractList

Parameters:

element - a Object.

Returns:

the index of the first occurrence of the argument or -1.

indexOf

public final int indexOf(java.lang.Object element,
          int index)

Searches for the first occurence of the given Object, beginning the search at index; returns -1 if it is not found.

Parameters:

element - a Object.

index - the non-negative index to start searching from.

Throws:

java.lang.IndexOutOfBoundsException - if index is negative.

lastIndexOf

public final int lastIndexOf(java.lang.Object element)

Returns the index of the last occurrence of the specified Object in this ArrayList; returns -1 if it is not found.

Specified by:

lastIndexOf in interface java.util.List

Overrides:

lastIndexOf in class java.util.AbstractList

Parameters:

element - the desired component.

Returns:

the index of the last occurrence of the specified Object, or -1.

lastIndexOf

public final int lastIndexOf(java.lang.Object element,
              int index)

Searches backwards for the specified Object, starting from the specified index, and returns its index, or -1 if not found.

Parameters:

element - a Object.

index - the non-negative index to start searching from.

Throws:

java.lang.IndexOutOfBoundsException - if index is invalid.

elementAt

public final java.lang.Object elementAt(int index)

Returns the component at the specified index. This method is identical in functionality to the get method.

Parameters:

index - an index into this ArrayList.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid.

firstElement

public final java.lang.Object firstElement()

Returns the first component (the item at index 0) of this ArrayList.

Returns:

the first component of this ArrayList.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if this ArrayList is empty.

lastElement

public final java.lang.Object lastElement()

Returns the last component of the ArrayList.

Returns:

the last component of the ArrayList, i.e., the component at size() - 1.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if this ArrayList is empty.

setElementAt

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

Sets the component at the specified index of this ArrayList to be the specified Object. The previous component at that position is lost.

The index must be a value greater than or equal to 0 and less than the current size of the ArrayList.

This method is identical in functionality to the set method except that the latter returns the old object that was stored at the specified position and it has its argument in a different order.

Parameters:

element - what the component is to be set to.

index - the specified index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

removeElementAt

public final void removeElementAt(int index)

Deletes the component at the specified index. Each component in this ArrayList with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously. The size of this ArrayList is decreased by 1.

The index must be a value greater than or equal to 0 and less than the current size of the ArrayList.

This method is identical in functionality to the remove(int) method except that the remove(int) method returns the old value that was stored at the specified position.

Parameters:

index - the index of the Object to remove.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

insertElementAt

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

Inserts the specified Object as a component in this ArrayList at the specified index. Each component in this ArrayList with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

The index must be a value greater than or equal to 0 and less than or equal to the current size of the ArrayList. (If the index is equal to the current size of the ArrayList, the new element is appended to the ArrayList.)

This method is identical in functionality to the add(int, Object) method except that the latter method reverses the order of the arguments, to match array usage more closely.

Parameters:

element - the element to insert.

index - where to insert the new component.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index was invalid.

addElement

public final void addElement(java.lang.Object element)

Adds the specified component to the end of this ArrayList, increasing its size by one. The capacity of this ArrayList is increased if its size becomes greater than its capacity.

This method is identical in functionality to the add(Object) method except that the latter returns a boolean.

Parameters:

element - the component to be added.

removeAllElements

public final void removeAllElements()

Removes all components from this ArrayList. This method is identical in functionality to the clear method.

clone

public final java.lang.Object clone()

Returns a clone of this ArrayList. The copy will contain a reference to a clone of the internal data array, not a reference to the original internal data array of this ArrayList object.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this ArrayList.

toArray

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

Returns an array containing all of the elements in this ArrayList in the correct order.

Specified by:

toArray in interface java.util.Collection

Specified by:

toArray in interface java.util.List

Overrides:

toArray in class java.util.AbstractCollection

toStringArray

public final java.lang.String[] toStringArray()

Returns an array containing all of the string forms of the elements in this ArrayList in the correct order.

get

public final java.lang.Object get(int index)

Returns the element at the specified position in this ArrayList.

Specified by:

get in interface java.util.List

Specified by:

get in class java.util.AbstractList

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the index is invalid.

set

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

Replaces the element at the specified position in this ArrayList with the specified element. If the position is out of range of the current element array, an ArrayIndexOutOfBoundsException is thrown. To avoid this, one should call ensureCapacity before calling this method. Note that, if the specified index is still in range but higher than the current size, this will update the current size. This means that this may introduce gaps of null elements.

Specified by:

set in interface java.util.List

Overrides:

set in class java.util.AbstractList

Parameters:

index - index of element to replace.

element - element to be stored at the specified position.

Returns:

the element previously at the specified position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range.

setLast

public final void setLast(java.lang.Object element)

Replaces the element at the last position in this ArrayList with the specified element.

Parameters:

element - element to be stored at the last position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range.

add

public final boolean add(java.lang.Object element)

Appends the specified element to the end of this ArrayList, growing the array if necessary. Note that, of the specified object is null, the element count is increased nonetheless.

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.List

Overrides:

add in class java.util.AbstractList

Parameters:

element - object to be appended to this ArrayList.

Returns:

true (following the java.util.ArrayList API).

remove

public final boolean remove(java.lang.Object element)

Removes the first occurrence of the specified element. If this ArrayList does not contain the element, it is left unchanged.

N.B.Because remove(Object) is ambiguous, it is not supported for ArrayLists; its functionality is provided by removeIndex(int) and removeElement(Object).

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.List

Overrides:

remove in class java.util.AbstractCollection

Parameters:

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

Returns:

true if this ArrayList contained the specified element.

removeElement

public final boolean removeElement(java.lang.Object element)

Removes the first occurrence of the specified element. If this ArrayList does not contain the element, it is left unchanged. Note that this method is identical to remove(Object).

Parameters:

element - element to be removed from this ArrayList, if present.

Returns:

true if this ArrayList contained the specified element.

add

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

Inserts the specified element at the specified position in this ArrayList. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Specified by:

add in interface java.util.List

Overrides:

add in class java.util.AbstractList

Parameters:

index - index at which the specified element is to be inserted.

element - object to be inserted.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range.

remove

public final java.lang.Object remove(int index)

Removes the element at the specified position and shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed.

Specified by:

remove in interface java.util.List

Overrides:

remove in class java.util.AbstractList

Parameters:

index - the index of the element to removed.

Returns:

the element that was at this index position.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range.

clear

public final void clear()

Removes all of the elements from this ArrayList.

Specified by:

clear in interface java.util.Collection

Specified by:

clear in interface java.util.List

Overrides:

clear in class java.util.AbstractList

containsAll

public final boolean containsAll(java.lang.Object[] a)

Returns true if this ArrayList contains all of the elements in the specified array.

Parameters:

a - array containing the elements to be tested for membership.

Returns:

true if all of the elements of the specified array belong in this.

containsAll

public final boolean containsAll(ArrayList v)

Returns true if this ArrayList contains all of the elements in the specified ArrayList.

Parameters:

v - ArrayList of elements to be tested for membership.

Returns:

true if all the elements of the specified collection belong to this.

addAll

public final boolean addAll(java.lang.Object[] a)

Appends all of the elements in the specified array to the end of this ArrayList, in the order of the array.

Parameters:

a - array containing the elements to be inserted.

Returns:

true (following the java.util.ArrayList API).

Throws:

java.lang.ClassCastException - if the collection contains a non-number.

addAll

public final boolean addAll(ArrayList v)

Appends all of the elements in the specified ArrayList to the end of this ArrayList.

Parameters:

v - the ArrayList of elements to be added.

Returns:

true (following the java.util.ArrayList API).

removeAll

public final boolean removeAll(java.lang.Object[] a)

Removes from this ArrayList all of its elements that are contained in the specified array. Note that all occurrences of such elemeents are removed - not just the first.

Parameters:

a - array of elements to be removed.

Returns:

true if this ArrayList changed as a result of the call.

removeAll

public final boolean removeAll(ArrayList v)

Removes from this ArrayList all of its elements that are contained in the specified ArrayList. Note that all occurrences of such elemeents are removed - not just the first.

Parameters:

v - the ArrayList of elements to be removed.

Returns:

true if this ArrayList changed as a result of the call.

removeAllFirst

public final boolean removeAllFirst(java.lang.Object[] a)

Removes from this ArrayList the first occurrence of the elements that are contained in the specified array

Parameters:

a - array of elements to be removed.

Returns:

true if this ArrayList changed as a result of the call.

removeAllFirst

public final boolean removeAllFirst(ArrayList v)

Removes from this ArrayList the first occurrence of the elements that are contained in the specified ArrayList.

Parameters:

v - the ArrayList of elements to be removed.

Returns:

true if this ArrayList changed as a result of the call.

retainAll

public final boolean retainAll(ArrayList v)

Retains only the elements in this ArrayList whose elements are contained in the specified ArrayList. In other words, removes from this ArrayList all of its elements that are not contained in the specified ArrayList.

Parameters:

v - the ArrayList of elements to be retained.

Returns:

true if this ArrayList changed as a result of the call.

addAll

public final void addAll(int index,
          java.lang.Object[] a)

Inserts all the elements in the specified array at the specified index in this ArrayList. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds the length of the array to their indices).

Parameters:

index - index at which the specified element is to be inserted.

a - arrays of element to be inserted.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range.

addAll

public final void addAll(int index,
          ArrayList v)

Inserts all of the elements in the specified ArrayList into this ArrayList at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this ArrayList in their order in the specified ArrayList.

Parameters:

index - index where to insert the first element

v - ArrayList to be inserted into this ArrayList.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is invalid.

equals

public final boolean equals(java.lang.Object o)

Compares the specified object with this ArrayList for equality. Returns true if and only if the specified object is also an ArrayList, both have the same size, and all corresponding pairs of elements are equal. In other words, two ArrayLists are defined to be equal if all their elements are equal in the same order.

Specified by:

equals in interface java.util.Collection

Specified by:

equals in interface java.util.List

Overrides:

equals in class java.util.AbstractList

Parameters:

o - the object to be compared for equality with this ArrayList.

Returns:

true if the specified object is equal to this ArrayList

hashCode

public int hashCode()

Returns the hash code value for this ArrayList.

Specified by:

hashCode in interface java.util.Collection

Specified by:

hashCode in interface java.util.List

Overrides:

hashCode in class java.util.AbstractList

toString

public java.lang.String toString()

Returns a string representation of this ArrayList

Overrides:

toString in class java.util.AbstractCollection

Returns:

a string representation of this collection.

removeRange

public void removeRange(int fromIndex,
               int toIndex)

Removes from this ArrayList 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.)

N.B. Note that this method is public, whereas - strangely enough, it is protected in the java.util.ArrayList API!

Overrides:

removeRange in class java.util.AbstractList

Parameters:

fromIndex - index of first element to be removed.

toIndex - index after last element to be removed.

setIncrementFactor

public final void setIncrementFactor(float incrementFactor)

Parameters:

incrementFactor - a float that is between 1.1 and 5.0

Throws:

java.lang.IllegalArgumentException - if not between 1.1 and 5.0

clear

public final void clear(int index)

Clears all elements of this arraylist at index equal to or greater than the specified index. If this index value is out range, this clears all the arraylist.

Parameters:

index - the index above which clearing takes effect

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

Overrides:

iterator in class java.util.AbstractList