Package org.apache.pivot.collections

Class ArrayList<T>

  • Type Parameters:
    T - Type of the list elements.
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<T>, Collection<T>, List<T>, Sequence<T>
    Direct Known Subclasses:
    ValueSeries
    public class ArrayList<T>
extends java.lang.Object
implements List<T>, java.io.Serializable
    Implementation of the List interface that is backed by an array.

    NOTE This class is not thread-safe. For concurrent access, use a SynchronizedList.

    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int DEFAULT_CAPACITY  

    • Constructor Summary

      Constructors 
      Constructor Description
      ArrayList()
      Construct a new unsorted ArrayList with the default capacity.
      ArrayList​(int capacity)
      Construct a new unsorted ArrayList with the given initial capacity.
      ArrayList​(int capacity, java.util.Comparator<T> comparator)
      Construct a new ArrayList to be sorted by the given comparator, with the given capacity.
      ArrayList​(java.util.Collection<T> c)
      Copy the given collection into a new ArrayList.
      ArrayList​(java.util.Comparator<T> comparator)
      Construct a new ArrayList to be sorted by the given comparator, with the default capacity.
      ArrayList​(ArrayList<T> arrayList)
      Copy the given ArrayList into a new one.
      ArrayList​(ArrayList<T> arrayList, int index, int count)
      Construct a new ArrayList with a subset of the given ArrayList.
      ArrayList​(Sequence<T> items)
      Construct a new ArrayList with the given sequence of items.
      ArrayList​(Sequence<T> items, int index, int count)
      Construct a new ArrayList with a subset of the given sequence of items.
      ArrayList​(T... items)
      Construct a new ArrayList with the given list of items.
      ArrayList​(T[] items, int index, int count)
      Construct a new ArrayList with a subset of the given list of items.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int add​(T item)
      Adds an item to the list.
      static <T extends java.lang.Comparable<? super T>>
      int      		 binarySearch​(ArrayList<T> arrayList, T item)
      Search for an item in the given list using the elements' "natural" ordering.
      static <T> int binarySearch​(ArrayList<T> arrayList, T item, java.util.Comparator<T> comparator)
      Search for a given element in the list using the "binary search" algorithm, which requires a comparator to establish the sort order of the elements.
      void clear()
      Removes all elements from the collection.
      void ensureCapacity​(int capacity)
      Ensure there is sufficient capacity in the internal storage for the given number of items.
      boolean equals​(java.lang.Object o)  
      T get​(int index)
      Retrieves the item at the given index.
      int getCapacity()  
      java.util.Comparator<T> getComparator()
      Returns the collection's sort order.
      int getLength()
      Returns the length of the list.
      ListenerList<ListListener<T>> getListListeners()
      Returns the list listener list.
      int hashCode()  
      int indexOf​(T item)
      Returns the index of an item in the sequence.
      void insert​(T item, int index)
      Inserts an item into the list.
      boolean isEmpty()
      Tests the emptiness of the collection.
      List.ItemIterator<T> iterator()  
      Sequence<T> remove​(int index, int count)
      Removes one or more items from the sequence.
      int remove​(T item)
      Removes the first occurrence of the given item from the sequence.
      void setComparator​(java.util.Comparator<T> comparator)
      Sets the collection's sort order, re-ordering the collection's contents and ensuring that new entries preserve the sort order.
      static <T extends java.lang.Comparable<? super T>>
      void      		 sort​(ArrayList<T> arrayList)
      Sort the given array list according to the "natural" sort order of the comparable elements.
      static <T> void sort​(ArrayList<T> arrayList, int from, int to, java.util.Comparator<T> comparator)
      Sort a portion of the given list.
      static <T> void sort​(ArrayList<T> arrayList, java.util.Comparator<T> comparator)
      Sort the current contents of the given list using the given comparator.
      java.lang.Object[] toArray()  
      T[] toArray​(java.lang.Class<? extends T[]> type)  
      java.lang.String toString()  
      void trimToSize()
      Trim the internal storage for this list to exactly fit the current number of items in it.
      T update​(int index, T item)
      Updates the item at the given index.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • ArrayList

        public ArrayList()
        Construct a new unsorted ArrayList with the default capacity.

      • ArrayList

        public ArrayList​(java.util.Comparator<T> comparator)
        Construct a new ArrayList to be sorted by the given comparator, with the default capacity.
        Parameters:
        comparator - A comparator to sort the entries in the list.

      • ArrayList

        public ArrayList​(int capacity)
        Construct a new unsorted ArrayList with the given initial capacity.
        Parameters:
        capacity - The initial capacity for this list.
        Throws:
        java.lang.IllegalArgumentException - if the given capacity is negative.

      • ArrayList

        public ArrayList​(int capacity,
                 java.util.Comparator<T> comparator)
        Construct a new ArrayList to be sorted by the given comparator, with the given capacity.
        Parameters:
        capacity - The initial capacity for this list.
        comparator - The comparator to use when sorting the list.

      • ArrayList

        public ArrayList​(T... items)
        Construct a new ArrayList with the given list of items.
        Parameters:
        items - The initial list of values for the list.

      • ArrayList

        public ArrayList​(T[] items,
                 int index,
                 int count)
        Construct a new ArrayList with a subset of the given list of items.
        Parameters:
        items - The full array of items to choose from.
        index - The starting location of the items to choose.
        count - The count of items to pick from the full array, starting at the index.
        Throws:
        java.lang.IndexOutOfBoundsException - if the given index is negative or greater than the count.

      • ArrayList

        public ArrayList​(Sequence<T> items)
        Construct a new ArrayList with the given sequence of items.
        Parameters:
        items - The initial list of values for the list.

      • ArrayList

        public ArrayList​(Sequence<T> items,
                 int index,
                 int count)
        Construct a new ArrayList with a subset of the given sequence of items.
        Parameters:
        items - The full sequence of items to choose from.
        index - The starting location of the items to choose.
        count - The count of items to pick from the full sequence, starting at the index.
        Throws:
        java.lang.IndexOutOfBoundsException - if the given index is negative or greater than the count.

      • ArrayList

        public ArrayList​(ArrayList<T> arrayList)
        Copy the given ArrayList into a new one.
        Parameters:
        arrayList - The existing list to copy into this one.

      • ArrayList

        public ArrayList​(ArrayList<T> arrayList,
                 int index,
                 int count)
        Construct a new ArrayList with a subset of the given ArrayList.
        Parameters:
        arrayList - The full list of items to choose from.
        index - The starting location of the items to choose.
        count - The count of items to pick from the full list, starting at the index.
        Throws:
        java.lang.IndexOutOfBoundsException - if the given index is negative or greater than the count.

      • ArrayList

        public ArrayList​(java.util.Collection<T> c)
        Copy the given collection into a new ArrayList.
        Parameters:
        c - The existing collection to copy into this list.

    • Method Detail

      • add

        public int add​(T item)
        Description copied from interface: List
        Adds an item to the list. If the list is unsorted, the item is appended to the end of the list. Otherwise, it is inserted at the appropriate index.
        Specified by:
        add in interface List<T>
        Specified by:
        add in interface Sequence<T>
        Parameters:
        item - The item to be added to the sequence.
        Returns:
        The index at which the item was added.
        See Also:
        ListListener.itemInserted(List, int)

      • insert

        public void insert​(T item,
                   int index)
        Description copied from interface: List
        Inserts an item into the list.
        Specified by:
        insert in interface List<T>
        Specified by:
        insert in interface Sequence<T>
        Parameters:
        item - The item to be added to the list.
        index - The index at which the item should be inserted. Must be a value between 0 and getLength().
        See Also:
        ListListener.itemInserted(List, int)

      • update

        public T update​(int index,
                T item)
        Description copied from interface: List
        Updates the item at the given index.
        Specified by:
        update in interface List<T>
        Specified by:
        update in interface Sequence<T>
        Parameters:
        index - The index of the item to update.
        item - The item that will replace any existing value at the given index.
        Returns:
        The item that was previously stored at the given index.
        See Also:
        ListListener.itemUpdated(List, int, Object)

      • remove

        public int remove​(T item)
        Description copied from interface: Sequence
        Removes the first occurrence of the given item from the sequence.
        Specified by:
        remove in interface Sequence<T>
        Parameters:
        item - The item to remove.
        Returns:
        The index of the item that was removed, or -1 if the item could not be found.
        See Also:
        Sequence.remove(int, int)

      • remove

        public Sequence<T> remove​(int index,
                          int count)
        Description copied from interface: Sequence
        Removes one or more items from the sequence.
        Specified by:
        remove in interface List<T>
        Specified by:
        remove in interface Sequence<T>
        Parameters:
        index - The starting index to remove.
        count - The number of items to remove, beginning with index.
        Returns:
        A sequence containing the items that were removed.
        See Also:
        ListListener.itemsRemoved(List, int, Sequence)

      • get

        public T get​(int index)
        Description copied from interface: Sequence
        Retrieves the item at the given index.
        Specified by:
        get in interface Sequence<T>
        Parameters:
        index - The index of the item to retrieve.
        Returns:
        The item at this index in the sequence.

      • indexOf

        public int indexOf​(T item)
        Description copied from interface: Sequence
        Returns the index of an item in the sequence.
        Specified by:
        indexOf in interface Sequence<T>
        Parameters:
        item - The item to locate.
        Returns:
        The index of first occurrence of the item if it exists in the sequence; -1, otherwise.

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: Collection
        Tests the emptiness of the collection.
        Specified by:
        isEmpty in interface Collection<T>
        Returns:
        true if the collection contains no elements; false, otherwise.

      • getLength

        public int getLength()
        Description copied from interface: List
        Returns the length of the list.
        Specified by:
        getLength in interface List<T>
        Specified by:
        getLength in interface Sequence<T>
        Returns:
        The number of items in the list, or -1 if the list's length is not known. In this case, the iterator must be used to retrieve the contents of the list.

      • trimToSize

        public void trimToSize()
        Trim the internal storage for this list to exactly fit the current number of items in it.

      • ensureCapacity

        public void ensureCapacity​(int capacity)
        Ensure there is sufficient capacity in the internal storage for the given number of items. This can be used before a large number of inserts to avoid many incremental storage updates during the inserts.

        If there is already sufficient storage for the given capacity nothing happens, regardless of how many items are currently in the list. This means that to ensure capacity for the current length plus "n" new items, this method should be called with the getLength() plus the number of items to insert.

        Parameters:
        capacity - The new capacity to allow for.

      • getCapacity

        public int getCapacity()
        Returns:
        The current capacity of the list, that is, how many items can be stored before allocating more memory.

      • toArray

        public java.lang.Object[] toArray()
        Returns:
        The current contents of the list as an array of objects.

      • toArray

        public T[] toArray​(java.lang.Class<? extends T[]> type)
        Parameters:
        type - The type of the array elements to be returned (which should match the declared type of this ArrayList).
        Returns:
        The current contents of the list as an array of the given type.

      • getComparator

        public java.util.Comparator<T> getComparator()
        Description copied from interface: Collection
        Returns the collection's sort order.
        Specified by:
        getComparator in interface Collection<T>
        Returns:
        The comparator used to order elements in the collection, or null if the sort order is undefined.
        See Also:
        Collection.setComparator(Comparator)

      • setComparator

        public void setComparator​(java.util.Comparator<T> comparator)
        Description copied from interface: Collection
        Sets the collection's sort order, re-ordering the collection's contents and ensuring that new entries preserve the sort order.

        Calling this method more than once with the same comparator will re-sort the collection.

        Specified by:
        setComparator in interface Collection<T>
        Specified by:
        setComparator in interface List<T>
        Parameters:
        comparator - The comparator used to order elements in the collection, or null if the collection is unsorted.
        See Also:
        ListListener.comparatorChanged(List, Comparator)

      • iterator

        public List.ItemIterator<T> iterator()
        Specified by:
        iterator in interface java.lang.Iterable<T>

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • sort

        public static <T> void sort​(ArrayList<T> arrayList,
                            java.util.Comparator<T> comparator)
        Sort the current contents of the given list using the given comparator.
        Type Parameters:
        T - Type of the list elements.
        Parameters:
        arrayList - The list to sort.
        comparator - The comparator to use to establish the sort order.

      • sort

        public static <T> void sort​(ArrayList<T> arrayList,
                            int from,
                            int to,
                            java.util.Comparator<T> comparator)
        Sort a portion of the given list.
        Type Parameters:
        T - Type of the list elements.
        Parameters:
        arrayList - The list to sort.
        from - The beginning index in the list of the items to sort (inclusive).
        to - The ending index of the items to sort (exclusive), that is, the elements from "from" to "to - 1" are sorted on return.
        comparator - The comparator to use to establish the sorted order.

      • sort

        public static <T extends java.lang.Comparable<? super T>> void sort​(ArrayList<T> arrayList)
        Sort the given array list according to the "natural" sort order of the comparable elements.

        The elements must implement the Comparable interface, as the default sort calls the Comparable.compareTo(T) method to order the elements.

        Type Parameters:
        T - The comparable type of the elements in the list.
        Parameters:
        arrayList - The list to sort.

      • binarySearch

        public static <T> int binarySearch​(ArrayList<T> arrayList,
                                   T item,
                                   java.util.Comparator<T> comparator)
        Search for a given element in the list using the "binary search" algorithm, which requires a comparator to establish the sort order of the elements.
        Type Parameters:
        T - Type of the list elements.
        Parameters:
        arrayList - The list to search.
        item - The item to search for in the list.
        comparator - Comparator to use for testing; if null then the "natural" ordering of the objects is used (see the caveats of Arrays.binarySearch(Object[], Object)).
        Returns:
        The index of the item in the list if found, or -1 if the item cannot be found in the list.

      • binarySearch

        public static <T extends java.lang.Comparable<? super T>> int binarySearch​(ArrayList<T> arrayList,
                                                                           T item)
        Search for an item in the given list using the elements' "natural" ordering.
        Type Parameters:
        T - The comparable type of the elements in the list.
        Parameters:
        arrayList - The list to search.
        item - The item to search for.
        Returns:
        The index of the item in the list if found, or -1 if the item is not found.