*
* List places additional requirements on iterator,
* add, remove, equals, and
* hashCode, in addition to requiring more methods. List
* indexing is 0-based (like arrays), although some implementations may
* require time proportional to the index to obtain an arbitrary element.
* The List interface is incompatible with Set; you cannot implement both
* simultaneously.
*
*
* Lists also provide a ListIterator which allows bidirectional
* traversal and other features atop regular iterators. Lists can be
* searched for arbitrary elements, and allow easy insertion and removal
* of multiple elements in one method call.
*
*
* Note: While lists may contain themselves as elements, this leads to
* undefined (usually infinite recursive) behavior for some methods like
* hashCode or equals.
*
* @author Original author unknown
* @author Eric Blake o == null ? e == null : o.equals(e).
*
* @param o the element to look for
* @return true if this list contains the element
*/
boolean contains(Object o);
/**
* Test whether this list contains every element in a given collection.
*
* @param c the collection to test for
* @return true if for every element o in c, contains(o) would return true
* @throws NullPointerException if the collection is null
* @see #contains(Object)
*/
boolean containsAll(Collection c);
/**
* Test whether this list is equal to another object. A List is defined to be
* equal to an object if and only if that object is also a List, and the two
* lists have the same sequence. Two lists l1 and l2 are equal if and only
* if l1.size() == l2.size(), and for every integer n between 0
* and l1.size() - 1 inclusive, l1.get(n) == null ?
* l2.get(n) == null : l1.get(n).equals(l2.get(n)).
*
* @param o the object to test for equality with this list
* @return true if o is equal to this list
* @see Object#equals(Object)
* @see #hashCode()
*/
boolean equals(Object o);
/**
* Get the element at a given index in this list.
*
* @param index the index of the element to be returned
* @return the element at index index in this list
* @throws IndexOutOfBoundsException if index < 0 || index >= size()
*/
Object get(int index);
/**
* Obtain a hash code for this list. In order to obey the general contract of
* the hashCode method of class Object, this value is calculated as follows:
*
* hashCode = 1;
* Iterator i = list.iterator();
* while (i.hasNext())
* {
* Object obj = i.next();
* hashCode = 31 * hashCode + (obj == null ? 0 : obj.hashCode());
* }
*
* This ensures that the general contract of Object.hashCode() is adhered to.
*
* @return the hash code of this list
* @see Object#hashCode()
* @see #equals(Object)
*/
int hashCode();
/**
* Obtain the first index at which a given object is to be found in this
* list.
*
* @param o the object to search for
* @return the least integer n such that o == null ? get(n) == null :
* o.equals(get(n)), or -1 if there is no such index
*/
int indexOf(Object o);
/**
* Test whether this list is empty, that is, if size() == 0.
*
* @return true if this list contains no elements
*/
boolean isEmpty();
/**
* Obtain an Iterator over this list, whose sequence is the list order.
*
* @return an Iterator over the elements of this list, in order
*/
Iterator iterator();
/**
* Obtain the last index at which a given object is to be found in this
* list.
*
* @return the greatest integer n such that o == null ? get(n) == null
* : o.equals(get(n)), or -1 if there is no such index
*/
int lastIndexOf(Object o);
/**
* Obtain a ListIterator over this list, starting at the beginning.
*
* @return a ListIterator over the elements of this list, in order, starting
* at the beginning
*/
ListIterator listIterator();
/**
* Obtain a ListIterator over this list, starting at a given position.
* A first call to next() would return the same as get(index), and a
* first call to previous() would return the same as get(index - 1).
*
* @param index the position, between 0 and size() inclusive, to begin the
* iteration from
* @return a ListIterator over the elements of this list, in order, starting
* at index
* @throws IndexOutOfBoundsException if index < 0 || index > size()
*/
ListIterator listIterator(int index);
/**
* Remove the element at a given position in this list (optional operation).
* Shifts all remaining elements to the left to fill the gap.
*
* @param index the position within the list of the object to remove
* @return the object that was removed
* @throws UnsupportedOperationException if this list does not support the
* remove operation
* @throws IndexOutOfBoundsException if index < 0 || index >= size()
*/
Object remove(int index);
/**
* Remove the first occurrence of an object from this list (optional
* operation). That is, remove the first element e such that
* o == null ? e == null : o.equals(e).
*
* @param o the object to remove
* @return true if the list changed as a result of this call, that is, if
* the list contained at least one occurrence of o
* @throws UnsupportedOperationException if this list does not support the
* remove operation
*/
boolean remove(Object o);
/**
* Remove all elements of a given collection from this list (optional
* operation). That is, remove every element e such that c.contains(e).
*
* @param c the collection to filter out
* @return true if this list was modified as a result of this call
* @throws UnsupportedOperationException if this list does not support the
* removeAll operation
* @throws NullPointerException if the collection is null
* @see #remove(Object)
* @see #contains(Object)
*/
boolean removeAll(Collection c);
/**
* Remove all elements of this list that are not contained in a given
* collection (optional operation). That is, remove every element e such
* that !c.contains(e).
*
* @param c the collection to retain
* @return true if this list was modified as a result of this call
* @throws UnsupportedOperationException if this list does not support the
* retainAll operation
* @throws NullPointerException if the collection is null
* @see #remove(Object)
* @see #contains(Object)
*/
boolean retainAll(Collection c);
/**
* Replace an element of this list with another object (optional operation).
*
* @param index the position within this list of the element to be replaced
* @param o the object to replace it with
* @return the object that was replaced
* @throws UnsupportedOperationException if this list does not support the
* set operation
* @throws IndexOutOfBoundsException if index < 0 || index >= size()
* @throws ClassCastException if o cannot be added to this list due to its
* type
* @throws IllegalArgumentException if o cannot be added to this list for
* some other reason
*/
Object set(int index, Object o);
/**
* Get the number of elements in this list. If the list contains more
* than Integer.MAX_VALUE elements, return Integer.MAX_VALUE.
*
* @return the number of elements in the list
*/
int size();
/**
* Obtain a List view of a subsection of this list, from fromIndex
* (inclusive) to toIndex (exclusive). If the two indices are equal, the
* sublist is empty. The returned list should be modifiable if and only
* if this list is modifiable. Changes to the returned list should be
* reflected in this list. If this list is structurally modified in
* any way other than through the returned list, the result of any subsequent
* operations on the returned list is undefined.
*
* @param fromIndex the index that the returned list should start from
* (inclusive)
* @param toIndex the index that the returned list should go to (exclusive)
* @return a List backed by a subsection of this list
* @throws IndexOutOfBoundsException if fromIndex < 0
* || toIndex > size() || fromIndex > toIndex
* @throws IllegalArgumentException if fromIndex > toIndex (according to
* AbstractList). Don't you love Sun's inconsistent specifications?
*/
List subList(int fromIndex, int toIndex);
/**
* Copy the current contents of this list into an array.
*
* @return an array of type Object[] and length equal to the length of this
* list, containing the elements currently in this list, in order
*/
Object[] toArray();
/**
* Copy the current contents of this list into an array. If the array passed
* as an argument has length less than that of this list, an array of the
* same run-time type as a, and length equal to the length of this list, is
* allocated using Reflection. Otherwise, a itself is used. The elements of
* this list are copied into it, and if there is space in the array, the
* following element is set to null. The resultant array is returned.
* Note: The fact that the following element is set to null is only useful
* if it is known that this list does not contain any null elements.
*
* @param a the array to copy this list into
* @return an array containing the elements currently in this list, in
* order
* @throws ArrayStoreException if the type of any element of the
* collection is not a subtype of the element type of a
* @throws NullPointerException if the specified array is null
*/
Object[] toArray(Object[] a);
}