Interface ListInterface

All Known Implementing Classes:
ListArrayBased

public interface ListInterface

An ordered collection (also known as a sequence). The user of this interface has precise control over where in the list each element is inserted. The user can access elements by their integer index (position in the list), and search for elements in the list. Unlike sets, lists typically allow duplicate elements. More formally, lists typically allow pairs of elements e1 and e2 such that e1.equals(e2), and they typically allow multiple null elements if they allow null elements at all. It is not inconceivable that someone might wish to implement a list that prohibits duplicates, by throwing runtime exceptions when the user attempts to insert them, but we expect this usage to be rare.


Method Summary
 void add(int index, java.lang.Object item)
          Inserts the specified element at the specified position in this list.
 java.lang.Object get(int index)
          Returns the element at the specified position in this list.
 boolean isEmpty()
          Returns true if this list contains no elements.
 void remove(int index)
          Removes the element at the specified position in this list.
 void removeAll()
          Removes from this list all the elements that are contained in the specified collection.
 int size()
          Returns the number of elements in this list.
 

Method Detail

isEmpty

public boolean isEmpty()
Returns true if this list contains no elements.

Pre-condition: None
Post-condition: Returns true if the list is empty and false otherwise

Returns:
true if this list contains no elements

size

public int size()
Returns the number of elements in this list.

Pre-condition: None
Post-condition: Returns the number of elements in the list, or Integer.MAX_VALUE if there are more than Integer.MAX_VALUE elements in the list.

Returns:
the number of elements in this list.

add

public void add(int index,
                java.lang.Object item)
         throws ListIndexOutOfBoundsException,
                ListException
Inserts the specified element at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Pre-condition: index is between 1 and this.size()+1.
Post-condition: item becomes the list element at position index; the position of later elements in the list is increased by 1 to make room for it.

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

Throws:
ListIndexOutOfBoundsException - if the index is out of the range 1 up to the size of the list
ListException - if the item cannot be added to the list for any reason

get

public java.lang.Object get(int index)
                     throws ListIndexOutOfBoundsException
Returns the element at the specified position in this list.

Pre-condition: index is between 1 and this.size().
Post-condition: Returns the element at position index.

Parameters:
index - index of element to return.

Returns:
the element at the specified position in this list

Throws:
ListIndexOutOfBoundsException - if the index is out of the range 1 up to the size of the list

remove

public void remove(int index)
            throws ListIndexOutOfBoundsException
Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices).

Pre-condition: index is between 1 and this.size()+1.
Post-condition: Removes the element at position index; the position of later elements in the list is decreased by 1.

Parameters:
index - index of element to remove.

Throws:
ListIndexOutOfBoundsException - if the index is out of the range 1 up to the size of the list

removeAll

public void removeAll()
Removes from this list all the elements that are contained in the specified collection.

Pre-condition: None.
Post-condition: The list is empty (this.isEmpty() returns true).