All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface rebelsky.util.List

public interface List

A collection of potential functions that list implementations might support. To accommodate different implementations, many of these functions may throw an Unimplemented exception.

This interface supports lists that include a cursor that may be moved through the list. The cursor gives users a mechanism for accessing members of the list. The cursor is sometimes referred to as the current element.

The cursor may be manipulated by forward, back, reset, find, deleteFirst and deleteLast. Implementors should strive to ensure that the cursor is always within the list. If this is not possible, implementors should throw a ListException when attempts are made to access the cursor and the cursor is unknown. In any case, reset should always return the cursor to the beginning of a nonempty list.

Version:: 1.1 of March 1998
Author:: Samuel A. Rebelsky

Method Index

o addAfterCurrent(Object): Add an element after the cursor.
o addAtEnd(Object): Add an element at the end of the list.
o addAtFront(Object): Add an element at the front of the list.
o addBeforeCurrent(Object): Add an element before the cursor.
o advance(): Advance the cursor.
o backup(): Move the cursor backwards one position.
o clear(): Delete all the elements in the list.
o deleteCurrent(): Delete the element referred to by the cursor.
o deleteFirst(): Delete the first element of the list.
o deleteLast(): Delete the last element of the list.
o empty(): Determine whether the list is empty.
o find(Object): Advance the cursor to the first element equal to obj after (or including) the cursor.
o getCurrent(): Get the element referred to by the cursor.
o getFirst(): Get the first element in the list.
o getLast(): Get the last element in the list.
o length(): Determine the number of elements in the list.
o reset(): Reset the cursor to the beginning of the list.

Methods

o getCurrent

 public abstract Object getCurrent() throws EmptyListException, ListException, Unimplemented

Get the element referred to by the cursor.
Precondition: The list is nonempty.
Postcondition: The first element in the list is returned.
Postcondition: The list is not modified.
Postcondition: The cursor is not affected.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o getFirst

 public abstract Object getFirst() throws EmptyListException, ListException, Unimplemented

Get the first element in the list.
Precondition: The list is nonempty.
Postcondition: The first element in the list is returned.
Postcondition: The list is not modified.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o getLast

 public abstract Object getLast() throws EmptyListException, ListException, Unimplemented

Get the last element in the list.
Precondition: The list is nonempty.
Postcondition: The last element in the list is returned.
Postcondition: The list is not modified.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o empty

 public abstract boolean empty() throws ListException, Unimplemented

Determine whether the list is empty.
Precondition: (none)
Postcondition: The list is uanffected.

Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o length

 public abstract int length() throws ListException, Unimplemented

Determine the number of elements in the list.
Precondition: (none)
Postcondition: The list is uanffected.
Postcondition: The number of elements in the list is returned.

Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o addAtFront

 public abstract void addAtFront(Object elt) throws ListException, Unimplemented

Add an element at the front of the list. If the list is empty, creates a one-element list.
Precondition: (none)
Postcondition: The element is now at the front of the list.
Postcondition: The list increases in length by one.
Postcondition: If the list was not previously empty, the cursor is unchanged (if it previously referred to the front of the list, it now refers to the second element of the list).
Postcondition: If the list was previously empty, the list now has one element which is front, back, and cursor.

Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o addAtEnd

 public abstract void addAtEnd(Object elt) throws ListException, Unimplemented

Add an element at the end of the list. If the list is empty, creates a one-element list.
Precondition: (none)
Postcondition: The element is now at the end of the list.
Postcondition: The list increases in length by one.
Postcondition: If the list was not previously empty, the cursor is unchanged (if it previously referred to the end of the list, it now refers to the penulitimate element of the list).
Postcondition: If the list was previously empty, the list now has one element which is front, back, and cursor.

Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o addBeforeCurrent

 public abstract void addBeforeCurrent(Object elt) throws EmptyListException, ListException, Unimplemented

Add an element before the cursor.
Precondition: The list is nonempty.
Postcondition: The element is inserted before the cursor.
Postcondition: The list increases in length by one.
Postcondition: The cursor has not moved.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o addAfterCurrent

 public abstract void addAfterCurrent(Object elt) throws EmptyListException, ListException, Unimplemented

Add an element after the cursor.
Precondition: The list is nonempty.
Postcondition: The element is inserted after the cursor.
Postcondition: The list increases in length by one.
Postcondition: The cursor has not moved.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o clear

 public abstract void clear() throws ListException, Unimplemented

Delete all the elements in the list.
Precondition: (none)
Postcondition: The list is empty.

Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o deleteCurrent

 public abstract Object deleteCurrent() throws EmptyListException, ListException, Unimplemented

Delete the element referred to by the cursor.
Precondition: The list is nonempty.
Postcondition: The element referred to by the cursor is deleted.
Postcondition: The list decreases in length by one.
Postcondition: If the cursor was at the end of the list, it is now at the front of the list. Otherwise, it has advanced to the next element of the list.

Returns:: the deleted element.
Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o deleteFirst

 public abstract Object deleteFirst() throws EmptyListException, ListException, Unimplemented

Delete the first element of the list.
Precondition: The list is nonempty.
Postcondition: The first element is deleted.
Postcondition: The list decreases in length by one.
Postcondition: If the cursor was at the front of the list, it is now at the new front of the list. Otherwise, it is unchanged.

Returns:: the deleted element.
Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o deleteLast

 public abstract Object deleteLast() throws EmptyListException, ListException, Unimplemented

Delete the last element of the list.
Precondition: The list is nonempty.
Postcondition: The last element is deleted.
Postcondition: The list decreases in length by one.
Postcondition: If the cursor was at the end of the list, it is now at the new last element. Otherwise, it is unchanged.

Returns:: the deleted element.
Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o reset

 public abstract void reset() throws EmptyListException, ListException, Unimplemented

Reset the cursor to the beginning of the list.
Precondition: The list is nonempty.
Postcondition: The cursor is at the beginning of the list.
Postcondition: The list is not modified.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: if the implementation does not include this function.

o advance

 public abstract void advance() throws EmptyListException, ListException, Unimplemented

Advance the cursor.
Precondition: The list is nonempty.
Precondition: The cursor is not at the end of the list.
Postcondition: The cursor is advanced to the next element.
Postcondition: The list is not modified.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs or the cursor is at the end of the list.
Throws: Unimplemented: if the implementation does not include this function.

o backup

 public abstract void backup() throws EmptyListException, ListException, Unimplemented

Move the cursor backwards one position.
Precondition: The list is nonempty.
Precondition: The cursor is not at the beginning of the list.
Postcondition: The cursor is at the previous element.
Postcondition: The list is not modified.

Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs or the cursor is at the beginning of the list.
Throws: Unimplemented: if the current implementation does not include this function.

o find

 public abstract boolean find(Object obj) throws EmptyListException, ListException, Unimplemented

Advance the cursor to the first element equal to obj after (or including) the cursor. If the cursor is not equal to obj and there are no subsequent instances of obj, then return false and leave the cursor where it was.
Precondition: The list is nonempty.
Postcondition: If there is an appropriate element in the list (equal to obj and after or including the cursor) then the cursor is at the first such object.

Returns:: true if an element is found; false otherwise.
Throws: EmptyListException: if the list is empty.
Throws: ListException: if some implementation-related error occurs.
Throws: Unimplemented: until this implementation supports this method.

All Packages  Class Hierarchy  This Package  Previous  Next  Index