IntArrayList (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.util

## Class IntArrayList

- java.lang.Object
- - hlt.language.util.IntArrayList

- Direct Known Subclasses:
    IntStack

      public class IntArrayList
      extends java.lang.Object

  This class implements a vector of primitive `int` elements to alleviate the need to use an ArrayList of `Integer` wrappers. It implements all public members items of the `java.util.ArrayList` API that make sense when dealing with primitive `int` elements rather than `Object`s.

  Like `java.util.ArrayList`, its underlying representation can grow dynamically. As well, it is not synchronized.

  Version:
    Last modified on Thu Nov 22 04:53:13 2012 by hak
  Author:
    Hassan Aït-Kaci
  Copyright:
    © Hassan Aït-Kaci

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(int element)` Appends the specified element to the end of this IntArrayList.
    `void` | `add(int index, int element)` Inserts the specified element at the specified position in this IntArrayList.
    `boolean` | `addAll(int[] a)` Appends all of the elements in the specified array to the end of this IntArrayList, in the order of the array.
    `boolean` | `addAll(IntArrayList v)` Appends all of the elements in the specified IntArrayList to the end of this IntArrayList.
    `void` | `addAll(int index, int[] a)` Inserts all the elements in the specified array at the specified index in this IntArrayList.
    `void` | `addAll(int index, IntArrayList v)` Inserts all of the elements in the specified IntArrayList into this IntArrayList at the specified position.
    `void` | `addElement(int element)` Adds the specified component to the end of this IntArrayList, increasing its size by one.
    `int` | `capacity()` Returns the current capacity of this IntArrayList.
    `void` | `clear()` Removes all of the elements from this IntArrayList.
    `void` | `clear(int index)` Clears all elements of this IntArraylist at index equal to or greater than the specified index.
    `java.lang.Object` | `clone()` Returns a clone of this IntArrayList.
    `boolean` | `contains(int element)` Tests if the specified int is a component in this IntArrayList.
    `boolean` | `containsAll(int[] a)` Returns true if this IntArrayList contains all of the elements in the specified array.
    `boolean` | `containsAll(IntArrayList v)` Returns true if this IntArrayList contains all of the elements in the specified IntArrayList.
    `void` | `copyInto(int[] a)` Copies the components of this IntArrayList into the specified array.
    `int` | `elementAt(int index)` Returns the component at the specified index.
    `void` | `ensureCapacity(int minCapacity)` Increases the capacity of this IntArrayList, 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 int with this IntArrayList for equality.
    `int` | `firstElement()` Returns the first component (the item at index 0) of this IntArrayList.
    `int` | `get(int index)` Returns the element at the specified position in this IntArrayList.
    `int` | `hashCode()` Returns the hash code value for this IntArrayList.
    `int` | `indexOf(int element)` Searches for the first occurrence of the given int; returns -1 if it is not found.
    `int` | `indexOf(int element, int index)` Searches for the first occurence of the given int, beginning the search at index; returns -1 if it is not found.
    `void` | `insertElementAt(int element, int index)` Inserts the specified integer as a component in this IntArrayList at the specified index.
    `boolean` | `isEmpty()` Tests if this IntArrayList has no components.
    `int` | `lastElement()` Returns the last component of the IntArrayList.
    `int` | `lastIndexOf(int element)` Returns the index of the last occurrence of the specified int in this IntArrayList; returns -1 if it is not found.
    `int` | `lastIndexOf(int element, int index)` Searches backwards for the specified integer, starting from the specified index, and returns its index, or -1 if not found.
    `boolean` | `removeAll(int[] a)` Removes from this IntArrayList all of its elements that are contained in the specified array.
    `boolean` | `removeAll(IntArrayList v)` Removes from this IntArrayList all of its elements that are contained in the specified IntArrayList.
    `void` | `removeAllElements()` Removes all components from this IntArrayList.
    `boolean` | `removeAllFirst(int[] a)` Removes from this IntArrayList the first occurrence of the elements that are contained in the specified array
    `boolean` | `removeAllFirst(IntArrayList v)` Removes from this IntArrayList the first occurrence of the elements that are contained in the specified IntArrayList.
    `boolean` | `removeElement(int element)` Removes the first occurrence of the specified element.
    `void` | `removeElementAt(int index)` Deletes the component at the specified index.
    `int` | `removeIndex(int index)` Removes the element at the specified position and shifts any subsequent elements to the left (subtracts one from their indices).
    `void` | `removeRange(int fromIndex, int toIndex)` Removes from this IntArrayList all of the elements whose index is between fromIndex, inclusive and toIndex, exclusive.
    `boolean` | `retainAll(IntArrayList v)` Retains only the elements in this IntArrayList whose elements are contained in the specified IntArrayList.
    `int` | `set(int index, int element)` Replaces the element at the specified position in this IntArrayList with the specified element.
    `void` | `setElementAt(int element, int index)` Sets the component at the specified index of this IntArrayList to be the specified integer.
    `void` | `setIncrementFactor(float incrementFactor)`
    `void` | `setLast(int element)` Replaces the element at the last position in this IntArrayList with the specified element.
    `void` | `setSize(int newSize)` Sets the size of this IntArrayList.
    `int` | `size()` Returns the number of components in this IntArrayList.
    `int[]` | `toArray()` Returns an array containing all of the elements in this IntArrayList in the correct order.
    `java.lang.String` | `toString()` Returns a string representation of this IntArrayList
    `void` | `trimToSize()` Trims the capacity of this IntArrayList to be the IntArrayList's current size.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### IntArrayList

          public IntArrayList(int initialCapacity,
                      int capacityIncrement)

      Constructs an empty IntArrayList with the specified initial capacity and capacity increment.
      Parameters:
        `initialCapacity` - the initial capacity of the IntArrayList.
        `capacityIncrement` - amount by which the capacity is increased on overflow.
      Throws:
        `java.lang.NegativeArraySizeException` - if the specified initial capacity is negative.

    - #### IntArrayList

          public IntArrayList(int initialCapacity)

      Constructs an empty IntArrayList with the specified initial capacity and with its capacity increment equal to zero.
      Parameters:
        `initialCapacity` - the initial capacity of the IntArrayList.
      Throws:
        `java.lang.NegativeArraySizeException` - if the specified initial capacity is negative.

    - #### IntArrayList

          public IntArrayList()

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

    - #### IntArrayList

          public IntArrayList(int[] a)

      Constructs an IntArrayList containing the values contained in the specified array, in the same order.
      Parameters:
        `a` - an array of ints.

    - #### IntArrayList

          public IntArrayList(java.util.Collection c)

      Constructs a IntArrayList containing the intValue() values of the java.lang.Number objects in the specified collection, in the order they are returned by the collection's iterator. If any object in the collection is not an instance of java.lang.Number, a ClassCastException exception is thrown.
      Parameters:
        `c` - the collection whose elements are to be placed into this IntArrayList.
      Throws:
        `java.lang.ClassCastException` - if the collection contains a non-number.

  - ### Method Detail

    - #### copyInto

          public final void copyInto(int[] a)

      Copies the components of this IntArrayList into the specified array. The item at index k in this IntArrayList is copied into component k of a. The array must be big enough to hold all the elements of this IntArrayList, 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 IntArrayList to be the IntArrayList's current size. If the capacity of this IntArrayList 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 a IntArrayList.

    - #### ensureCapacity

          public final void ensureCapacity(int minCapacity)

      Increases the capacity of this IntArrayList, 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 IntArrayList 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 IntArrayList. If the new size is greater than the current size, new zeroes are added to the end of the IntArrayList.
      Parameters:
        `newSize` - the new size of this IntArrayList.

    - #### capacity

          public final int capacity()

      Returns the current capacity of this IntArrayList.
      Returns:
        the current capacity the length of its internal data array.

    - #### size

          public final int size()

      Returns the number of components in this IntArrayList.
      Returns:
        the number of components in this IntArrayList.

    - #### isEmpty

          public final boolean isEmpty()

      Tests if this IntArrayList has no components.
      Returns:
        true if this IntArrayList's size is zero; false otherwise.

    - #### contains

          public final boolean contains(int element)

      Tests if the specified int is a component in this IntArrayList.
      Parameters:
        `element` - an int.
      Returns:
        true if the specified int is in this IntArrayList; false otherwise.

    - #### indexOf

          public final int indexOf(int element)

      Searches for the first occurrence of the given int; returns -1 if it is not found.
      Parameters:
        `element` - an int.
      Returns:
        the index of the first occurrence of the argument or -1.

    - #### indexOf

          public final int indexOf(int element,
                    int index)

      Searches for the first occurence of the given int, beginning the search at index; returns -1 if it is not found.
      Parameters:
        `element` - an integer.
        `index` - the non-negative index to start searching from.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is negative.

    - #### lastIndexOf

          public final int lastIndexOf(int element)

      Returns the index of the last occurrence of the specified int in this IntArrayList; returns -1 if it is not found.
      Parameters:
        `element` - the desired component.
      Returns:
        the index of the last occurrence of the specified int, or -1.

    - #### lastIndexOf

          public final int lastIndexOf(int element,
                        int index)

      Searches backwards for the specified integer, starting from the specified index, and returns its index, or -1 if not found.
      Parameters:
        `element` - an integer.
        `index` - the non-negative index to start searching from.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if index is invalid.

    - #### elementAt

          public final int 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 IntArrayList.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if the index is invalid.

    - #### firstElement

          public final int firstElement()

      Returns the first component (the item at index 0) of this IntArrayList.
      Returns:
        the first component of this IntArrayList.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if this IntArrayList is empty.

    - #### lastElement

          public final int lastElement()

      Returns the last component of the IntArrayList.
      Returns:
        the last component of the IntArrayList, i.e., the component at size() - 1.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if this IntArrayList is empty.

    - #### setElementAt

          public final void setElementAt(int element,
                          int index)

      Sets the component at the specified index of this IntArrayList to be the specified integer. 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 IntArrayList.

      This method is identical in functionality to the set method except that the latter returns the old value 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 IntArrayList 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 IntArrayList is decreased by 1.

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

      This method is identical in functionality to the removeIndex method except that the removeIndex method returns the old value that was stored at the specified position.

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

      Parameters:
        `index` - the index of the integer to remove.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if the index was invalid.

    - #### insertElementAt

          public final void insertElementAt(int element,
                             int index)

      Inserts the specified integer as a component in this IntArrayList at the specified index. Each component in this IntArrayList 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 IntArrayList. (If the index is equal to the current size of the IntArrayList, the new element is appended to the IntArrayList.)

      This method is identical in functionality to the add(int, int) 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(int element)

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

      This method is identical in functionality to the add(int) 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 IntArrayList. This method is identical in functionality to the clear method.

    - #### clone

          public final java.lang.Object clone()

      Returns a clone of this IntArrayList. 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 IntArrayList object.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        a clone of this IntArrayList.

    - #### toArray

          public final int[] toArray()

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

    - #### get

          public final int get(int index)

      Returns the element at the specified position in this IntArrayList.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if the index is invalid.

    - #### set

          public final int set(int index,
                int element)

      Replaces the element at the specified position in this IntArrayList with the specified element.
      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(int element)

      Replaces the element at the last position in this IntArrayList 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(int element)

      Appends the specified element to the end of this IntArrayList.
      Parameters:
        `element` - element to be appended to this IntArrayList.
      Returns:
        true (following the `java.util.ArrayList` API).

    - #### removeElement

          public final boolean removeElement(int element)

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

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

      Parameters:
        `element` - element to be removed from this IntArrayList, if present.
      Returns:
        true if this IntArrayList contained the specified element.

    - #### add

          public final void add(int index,
                 int element)

      Inserts the specified element at the specified position in this IntArrayList. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Parameters:
        `index` - index at which the specified element is to be inserted.
        `element` - element to be inserted.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index is out of range.

    - #### removeIndex

          public final int removeIndex(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.
      Parameters:
        `index` - the index of the element to removed.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index is out of range.

    - #### clear

          public final void clear()

      Removes all of the elements from this IntArrayList.

    - #### containsAll

          public final boolean containsAll(int[] a)

      Returns true if this IntArrayList 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(IntArrayList v)

      Returns true if this IntArrayList contains all of the elements in the specified IntArrayList.
      Parameters:
        `v` - IntArrayList of elements to be tested for membership.
      Returns:
        true if all of the elements of the specified collection belong in this.

    - #### addAll

          public final boolean addAll(int[] a)

      Appends all of the elements in the specified array to the end of this IntArrayList, 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(IntArrayList v)

      Appends all of the elements in the specified IntArrayList to the end of this IntArrayList.
      Parameters:
        `v` - the IntArrayList of elements to be added.
      Returns:
        true (following the `java.util.ArrayList` API).

    - #### removeAll

          public final boolean removeAll(int[] a)

      Removes from this IntArrayList 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 IntArrayList changed as a result of the call.

    - #### removeAll

          public final boolean removeAll(IntArrayList v)

      Removes from this IntArrayList all of its elements that are contained in the specified IntArrayList. Note that all occurrences of such elemeents are removed - not just the first.
      Parameters:
        `v` - the IntArrayList of elements to be removed.
      Returns:
        true if this IntArrayList changed as a result of the call.

    - #### removeAllFirst

          public final boolean removeAllFirst(int[] a)

      Removes from this IntArrayList 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 IntArrayList changed as a result of the call.

    - #### removeAllFirst

          public final boolean removeAllFirst(IntArrayList v)

      Removes from this IntArrayList the first occurrence of the elements that are contained in the specified IntArrayList.
      Parameters:
        `v` - the IntArrayList of elements to be removed.
      Returns:
        true if this IntArrayList changed as a result of the call.

    - #### retainAll

          public final boolean retainAll(IntArrayList v)

      Retains only the elements in this IntArrayList whose elements are contained in the specified IntArrayList. In other words, removes from this IntArrayList all of its elements that are not contained in the specified IntArrayList.
      Parameters:
        `v` - IntArrayList of elements to be retained.
      Returns:
        true if this IntArrayList changed as a result of the call.

    - #### addAll

          public final void addAll(int index,
                    int[] a)

      Inserts all the elements in the specified array at the specified index in this IntArrayList. 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` - array of elements to be inserted.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index is out of range.

    - #### addAll

          public final void addAll(int index,
                    IntArrayList v)

      Inserts all of the elements in the specified IntArrayList into this IntArrayList 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 IntArrayList in their order in the specified IntArrayList.
      Parameters:
        `index` - index where to insert the first element
        `v` - IntArrayList to be inserted into this IntArrayList.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - if index is invalid.

    - #### equals

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

      Compares the specified int with this IntArrayList for equality. Returns true if and only if the specified object is also an IntArrayList, both have the same size, and all corresponding pairs of elements are equal. In other words, two IntArrayLists are defined to be equal if they contain the same elements in the same order.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `o` - the object to be compared for equality with this IntArrayList.
      Returns:
        true if the specified object is equal to this IntArrayList

    - #### hashCode

          public int hashCode()

      Returns the hash code value for this IntArrayList.
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this IntArrayList
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of this collection.

    - #### removeRange

          public void removeRange(int fromIndex,
                         int toIndex)

      Removes from this IntArrayList 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!

      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 IntArraylist at index equal to or greater than the specified index. If this index value is out range, this clears all the IntArraylist.
      Parameters:
        `index` - the index above which clearing takes effect