structure
Interface List

All Superinterfaces:

Structure

All Known Implementing Classes:

AbstractList

public interface List

extends Structure

Interface describing lists. Lists are collections of data with a head and tail. Values may be added or removed from either end, as well as by value from the middle. The structure package provides several implementations of the List interface, each of which has its particular strengths and weaknesses.

Example usage:

To place a copy of every unique parameter passed to a program into a List, we could use the following:

 public static void main(String[] arguments)
 {
     List argList = new SinglyLinkedList();
     for (int i = 0; i < arguments.length; i++){
	   if (!argList.contains(arguments[i])){
	       argList.add(arguments[i]);
         }
    }
    System.out.println(argList);
 }
 

See Also:

SinglyLinkedList, DoublyLinkedList, CircularList

Method Summary

void	add(int i, Object o) Insert value at location.
void	add(Object value) Add an object to tail of list.
void	addFirst(Object value) Add a value to the head of the list.
void	addLast(Object value) Add a value to tail of list.
void	clear() Remove all elements of list.
boolean	contains(Object value) Check to see if a value is in list.
Object	get() Retrieves value from tail of list.
Object	get(int i) Get value at location i.
Object	getFirst() Fetch first element of list.
Object	getLast() Fetch last element of list.
int	indexOf(Object value) Determine first location of a value in list.
boolean	isEmpty() Determine if list is empty.
Iterator	iterator() Construct an iterator to traverse elements of list from head to tail, in order.
int	lastIndexOf(Object value) Determine last location of a value in list.
Object	remove() Removes value from tail of list.
Object	remove(int i) Remove and return value at location i.
Object	remove(Object value) Remove a value from list.
Object	removeFirst() Remove a value from first element of list.
Object	removeLast() Remove last value from list.
Object	set(int i, Object o) Set value stored at location i to object o, returning old value.
int	size() Determine size of list.

Methods inherited from interface structure.Structure

elements, values

Method Detail

size

public int size()

Determine size of list.

Specified by:

size in interface Structure

Postcondition:

returns number of elements in list

Returns:

The number of elements in list.

isEmpty

public boolean isEmpty()

Determine if list is empty.

Specified by:

isEmpty in interface Structure

Postcondition:

returns true iff list has no elements

Returns:

True if list has no elements.

clear

public void clear()

Remove all elements of list.

Specified by:

clear in interface Structure

Postcondition:

empties list

addFirst

public void addFirst(Object value)

Add a value to the head of the list.

Parameters:

value - The value to be added to the head of the list.

Postcondition:

value is added to beginning of list

addLast

public void addLast(Object value)

Add a value to tail of list.

Parameters:

value - The value to be added to tail of list.

Postcondition:

value is added to end of list

getFirst

public Object getFirst()

Fetch first element of list.

Precondition:

list is not empty

Postcondition:

returns first value in list

Returns:

A reference to first element of list.

getLast

public Object getLast()

Fetch last element of list.

Precondition:

list is not empty

Postcondition:

returns last value in list

Returns:

A reference to last element of list.

removeFirst

public Object removeFirst()

Remove a value from first element of list.

Precondition:

list is not empty

Postcondition:

removes first value from list

Returns:

The value actually removed.

removeLast

public Object removeLast()

Remove last value from list.

Precondition:

list is not empty

Postcondition:

removes last value from list

Returns:

The value actually removed.

remove

public Object remove(Object value)

Remove a value from list. At most one of value will be removed.

Specified by:

remove in interface Structure

Parameters:

value - The value to be removed.

Postcondition:

removes and returns element equal to value otherwise returns null

Returns:

The actual value removed.

add

public void add(Object value)

Add an object to tail of list.

Specified by:

add in interface Structure

Parameters:

value - The value to be added to tail of list.

Postcondition:

value is added to tail of list

See Also:

addLast(java.lang.Object)

remove

public Object remove()

Removes value from tail of list.

Precondition:

list has at least one element

Postcondition:

removes last value found in list

Returns:

object removed.

get

public Object get()

Retrieves value from tail of list.

Precondition:

list has at least one element

Postcondition:

returns last value found in list

Returns:

object found at end of list

contains

public boolean contains(Object value)

Check to see if a value is in list.

Specified by:

contains in interface Structure

Parameters:

value - value sought.

Precondition:

value is not null

Postcondition:

returns true iff list contains an object equal to value

Returns:

True if value is within list.

indexOf

public int indexOf(Object value)

Determine first location of a value in list.

Parameters:

value - The value sought.

Precondition:

value is not null

Postcondition:

returns (0-origin) index of value, or -1 if value is not found

Returns:

index (0 is first element) of value, or -1

lastIndexOf

public int lastIndexOf(Object value)

Determine last location of a value in list.

Parameters:

value - value sought.

Precondition:

value is not null

Postcondition:

returns (0-origin) index of value, or -1 if value is not found

Returns:

index (0 is first element) of value, or -1

get

public Object get(int i)

Get value at location i.

Parameters:

i - position of value to be retrieved.

Precondition:

0 <= i < size()

Postcondition:

returns object found at that location

Returns:

value retrieved from location i (returns null if i invalid)

set

public Object set(int i,
                  Object o)

Set value stored at location i to object o, returning old value.

Parameters:

i - location of entry to be changed.

o - new value

Precondition:

0 <= i < size()

Postcondition:

sets ith entry of list to value o; returns old value

Returns:

former value of ith entry of list.

add

public void add(int i,
                Object o)

Insert value at location.

Parameters:

i - index of this new value

o - value to be stored

Precondition:

0 <= i <= size()

Postcondition:

adds ith entry of list to value o

remove

public Object remove(int i)

Remove and return value at location i.

Parameters:

i - position of value to be retrieved.

Precondition:

0 <= i < size()

Postcondition:

removes and returns object found at that location

Returns:

value retrieved from location i (returns null if i invalid)

iterator

public Iterator iterator()

Construct an iterator to traverse elements of list from head to tail, in order.

Specified by:

iterator in interface Structure

Postcondition:

returns an iterator allowing ordered traversal of elements in list

Returns:

Iterator that traverses list.