/* List.java -- An ordered collection which allows indexed access
   Copyright (C) 1998 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

As a special exception, if you link this library with other files to
produce an executable, this library does not by itself cause the
resulting executable to be covered by the GNU General Public License.
This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License. */


// TO DO:
// ~ Doc comment for the interface itself needs to be put into english.
// ~ Some more @see clauses might be nice.

package java.util;

/**
 * [This is what this doc comment will mention:
 * ~ Additional restrictions on some methods. Others included for completeness.
 * ~ ListIterator and what it can do
 * ~ Positional and iterated access
 * ~ search (but linear time)
 * ~ be careful when containing self as an element, because equals and hashCode
 *   loop.]
 */
public interface List extends Collection
{
  /**
   * Insert an element into the list at a given position.
   *
   * @param index the location to insert the item.
   * @param o the object to insert.
   * @exception UnsupportedOperationException if this list does not support the
   *   add operation.
   * @exception IndexOutOfBoundsException if index < 0 || index > size()
   * @exception ClassCastException if o cannot be added to this list due to its
   *   type.
   * @exception IllegalArgumentException if o cannot be added to this list for
   *   some other reason.
   */
  void add(int index, Object o);

  /**
   * Add an element to the end of the list.
   *
   * @param o the object to add.
   * @returns true, as Collection defines this method as returning true if the
   *   list was modified as a result of this action, and it always is for a
   *   list.
   * @exception UnsupportedOperationException if this list does not support the
   *   add operation.
   * @exception ClassCastException if o cannot be added to this list due to its
   *   type.
   * @exception IllegalArgumentException if o cannot be added to this list for
   *   some other reason.
   */
  boolean add(Object o);

  /**
   * Insert the contents of a collection into the list at a given position.
   *
   * @param index the location to insert the collection.
   * @param c the collection to insert.
   * @returns true if the list was modified by this action, that is, if c is
   *   non-empty.
   * @exception UnsupportedOperationException if this list does not support the
   *   addAll operation.
   * @exception IndexOutOfBoundsException if index < 0 || index > size()
   * @exception ClassCastException if some element of c cannot be added to this
   *   list due to its type.
   * @exception IllegalArgumentException if some element of c cannot be added
   *   to this list for some other reason.
   */
  boolean addAll(int index, Collection c);

  /**
   * Add the contents of a collection to the end of the list.
   *
   * @param c the collection to add.
   * @returns true if the list was modified by this action, that is, if c is
   *   non-empty.
   * @exception UnsupportedOperationException if this list does not support the
   *   addAll operation.
   * @exception ClassCastException if some element of c cannot be added to this
   *   list due to its type.
   * @exception IllegalArgumentException if some element of c cannot be added
   *   to this list for some other reason.
   */
  boolean addAll(Collection c);

  /**
   * Clear the list, such that a subsequent call to isEmpty() would return
   * true.
   *
   * @exception UnsupportedOperationException if this list does not support the
   *   clear operation.
   */
  void clear();

  /**
   * Test whether this list contains a given object as one of its elements.
   *
   * @param o the element to look for.
   * @returns true if this list contains an element e such that <code>o ==
   *   null ? e == null : o.equals(e)</code>.
   */
  boolean contains(Object o);

  /**
   * Test whether this list contains every element in a given collection.
   *
   * @param c the collection to test for.
   * @returns true if for every element o in c, contains(o) would return true.
   */
  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 are equal. Two lists l1 and l2 are defined to be equal if and only
   * if <code>l1.size() == l2.size()</code>, and for every integer n between 0
   * and <code>l1.size() - 1</code> inclusive, <code>l1.get(n) == null ?
   * l2.get(n) == null : l1.get(n).equals(l2.get(n))</code>.
   *
   * @param o the object to test for equality with this list.
   * @returns true if o is equal to this list.
   */
  boolean equals(Object o);

  /**
   * Get the element at a given index in this list.
   *
   * @param index the index of the element to be returned.
   * @returns the element at index index in this list.
   * @exception 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:
   * <pre>
   *   hashCode = 1;
   *   Iterator i = list.iterator();
   *   while (i.hasNext()) {
   *     Object obj = i.next();
   *     hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
   *   }
   * </pre>
   * This ensures that the general contract of Object.hashCode() is adhered to.
   *
   * @returns the hash code of this list.
   */
  int hashCode();

  /**
   * Obtain the first index at which a given object is to be found in this
   * list.
   *
   * @returns the least integer n such that <code>o == null ? get(n) == null :
   *   o.equals(get(n))</code>, or -1 if there is no such index.
   */
  int indexOf(Object o);

  /**
   * Test whether this list is empty, that is, if size() == 0.
   *
   * @returns true if this list contains no elements.
   */
  boolean isEmpty();

  /**
   * Obtain an Iterator over this list.
   *
   * @returns 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.
   *
   * @returns the greatest integer n such that <code>o == null ? get(n) == null
   *   : o.equals(get(n))</code>.
   */
  int lastIndexOf(Object o);

  /**
   * Obtain a ListIterator over this list, starting at the beginning.
   *
   * @returns 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.
   *
   * @param index the position, between 0 and size() inclusive, to begin the
   *   iteration from.
   * @returns a ListIterator over the elements of this list, in order, starting
   *   at index.
   * @exception IndexOutOfBoundsException if index < 0 || index > size()
   */
  ListIterator listIterator(int index);

  /**
   * Remove the element at a given position in this list.
   *
   * @param index the position within the list of the object to remove.
   * @returns the object that was removed.
   * @exception UnsupportedOperationException if this list does not support the
   *   remove operation.
   * @exception IndexOutOfBoundsException if index < 0 || index > size()
   */
  Object remove(int index);

  /**
   * Remove the first occurence of an object from this list. That is, remove
   * the first element e such that <code>o == null ? e == null :
   * o.equals(e)</code>.
   *
   * @param o the object to remove.
   * @returns true if the list changed as a result of this call, that is, if
   *   the list contained at least one occurrence of o.
   * @exception UnsupportedOperationException if this list does not support the
   *   remove operation.
   */
  boolean remove(Object o);

  /**
   * Remove all elements of a given collection from this list. That is, remove
   * every element e such that c.contains(e).
   *
   * @returns true if this list was modified as a result of this call.
   * @exception UnsupportedOperationException if this list does not support the
   *   removeAll operation.
   */
  boolean removeAll(Collection c);

  /**
   * Remove all elements of this list that are not contained in a given
   * collection. That is, remove every element e such that !c.contains(e).
   *
   * @returns true if this list was modified as a result of this call.
   * @exception UnsupportedOperationException if this list does not support the
   *   retainAll operation.
   */
  boolean retainAll(Collection c);

  /**
   * Replace an element of this list with another object.
   *
   * @param index the position within this list of the element to be replaced.
   * @param o the object to replace it with.
   * @returns the object that was replaced.
   * @exception UnsupportedOperationException if this list does not support the
   *   set operation.
   * @exception IndexOutOfBoundsException if index < 0 || index >= size()
   * @exception ClassCastException if o cannot be added to this list due to its
   *   type.
   * @exception 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.
   *
   * @returns 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). 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).
   * @returns a List backed by a subsection of this list.
   * @exception IndexOutOfBoundsException if fromIndex < 0 || toIndex > size()
   *   || fromIndex > toIndex.
   */
  List subList(int fromIndex, int toIndex);

  /**
   * Copy the current contents of this list into an array.
   *
   * @returns 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.
   * @returns an array containing the elements currently in this list, in
   *    order.
   * @exception ArrayStoreException if the type of any element of the
   *   collection is not a subtype of the element type of a.
   */
  Object[] toArray(Object[] a);
}