geneseo.cs.sc
Class List

java.lang.Object
  geneseo.cs.sc.List

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

OrderedList, Stack

public class List

extends java.lang.Object

implements java.io.Serializable

Represents lists of arbitrary objects. This class reflects a recursive definition of "list", specifically a definition that says that a list is either

• Empty, or
• An object (the list's head) followed by another list (the list's tail)

These lists handle the common messages needed for any list class. Some messages are destructive (i.e., cause a list to change itself), and therefore do not require assignment within the client code when modifying lists.

This class was created to support the text Algorithms & Data Structures: The Science of Computing by Doug Baldwin and Greg Scragg. All references herein to "the text" refer to that book. This class is the one described in Chapter 11, with a few extensions and with some methods completed that were "left to an exercise" in the text.

See Also:

Serialized Form

Constructor Summary

List()
Initialize a list to be empty.

List(java.lang.Object newItem)
Initialize a List to contain one element.

Method Summary

void	addItem(java.lang.Object newItem) Adds an object to a list.
void	concat(List extraList) Concatenates two lists.
List	copy() Create a duplicate of a list.
void	delete(java.lang.Object value) Remove an object from a list.
boolean	find(java.lang.Object target) Search a list for an object.
java.lang.Object	getAndRemove() Removes a list's first item and returns it.
java.lang.Object	getFirst() Extracts the head of a list.
List	getRest() Extracts the tail of a list.
boolean	isEmpty() Determines whether a list is empty or not.
List	makeNewList() Create a new list that is an instance of the same class as this list.
void	printList() Print the elements in a list from first to last.
void	printListForward() Print the elements in a list from last to first.
void	removeItem() Removes a list's head.
void	restore(java.lang.String fileName) Restore a list from a file.
void	save(java.lang.String fileName) Write a List to a file, replacing any previous data in that file.
protected void	setFirstItem(java.lang.Object value) Replaces the head of a list with a new object.
protected void	setRest(List newTail) Replaces the tail of a list with a new list.
java.lang.String	toString() Generate a string representation of a list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

List

public List()

Initialize a list to be empty. For example

List things = new List();

List

public List(java.lang.Object newItem)

Initialize a List to contain one element. For example

List words = new List( "lion" );

Parameters:

newItem - The single item the List will initially contain.

Method Detail

makeNewList

public List makeNewList()

Create a new list that is an instance of the same class as this list. This message is used, for example, when adding an item to a list requires creating a new tail for that list. The new tail should be an instance of the same class as the list itself, even if that list is an instance of a subclass of List. Every subclass of List must therefore provide a method for handling this message that returns a new instance of that subclass. Clients are unlikely to ever invoke this method directly, but it is essential to the correct functioning of other methods defined for lists.

Returns:

A new, empty, list, of the same class as the one that received the makeNewList message

getFirst

public java.lang.Object getFirst()

Extracts the head of a list. The list itself is left unchanged. For example

Object obj = myList.getFirst();

Returns:

The head of the list.

getRest

public List getRest()

Extracts the tail of a list. The list itself is left unchanged. For example

List theRest = myList.getRest();

Returns:

The tail of the list.

isEmpty

public boolean isEmpty()

Determines whether a list is empty or not. For example

if ( myList.isEmpty() ) ...

Returns:

True if the list is empty; false otherwise.

removeItem

public void removeItem()

Removes a list's head. This alters the list, but does not return the item removed. For example

myList.removeItem();

getAndRemove

public java.lang.Object getAndRemove()

Removes a list's first item and returns it. For example

Object oldHead = myList.getAndRemove();

Note that this is both a value and side effect producing operation.

Returns:

The item removed from the list (which was the list's head).

addItem

public void addItem(java.lang.Object newItem)

Adds an object to a list. The object becomes the new head of the list, while all objects previously in the list effectively move one place down it. For example

words.addItem( "wombat" );

Parameters:

newItem - The object to be added to the list.

setFirstItem

protected void setFirstItem(java.lang.Object value)

Replaces the head of a list with a new object. For example

words.setFirstItem( "aardvark" );

Parameters:

value - The object that will become the new head of the list.

setRest

protected void setRest(List newTail)

Replaces the tail of a list with a new list. For example

myList.setRest( new List() );

Note that the replacement must be an entire list, not just a new element.

Parameters:

newTail - The new tail for the list.

concat

public void concat(List extraList)

Concatenates two lists. All the items in the parameter list are added to the end of the list that receives the concat message. For example

myList.concat( new List("more") );

Parameters:

extraList - The list to be added to the end of the current list.

printList

public void printList()

Print the elements in a list from first to last. Prints elements from the front (head) of the list to the back, which, in effect, prints the last element entered first. For example

myList.printList();

Since this is intended for student use, it provides a marker at the end of the list to aid with testing and debugging.

printListForward

public void printListForward()

Print the elements in a list from last to first. Prints elements from the back of the list to front (head), which, in effect, prints the first element entered first. For example

myList.printListForward();

Since this is intended for student use, it provides a marker at the end of the list to aid with testing and debugging.

find

public boolean find(java.lang.Object target)

Search a list for an object. Uses equals to compare objects. For example

if ( words.find("capybara") ) ...

Parameters:

target - The object to look for in the list.

Returns:

True if one of the elements of the list is equal to the target, false otherwise.

delete

public void delete(java.lang.Object value)

Remove an object from a list. This removes the first occurrence of the requested object, altering the list in doing so. Uses equals to compare the object to elements of the list. For example

words.delete("monkey");

Parameters:

value - The object to remove from the list.

copy

public List copy()

Create a duplicate of a list. For example

List savedList = myList.copy();

Returns:

The duplicate of the list.

save

public void save(java.lang.String fileName)

Write a List to a file, replacing any previous data in that file. For example

myList.save( "ListFile" );

Parameters:

fileName - The name of the file to write the list to.

restore

public void restore(java.lang.String fileName)

Restore a list from a file. For example

myList.restore( "ListFile" );

After a list handles this message, the list's contents are replaced by the contents of the file, if possible. If for some reason the file couldn't be read, the contents of the list are unchanged.

Parameters:

fileName - The name of the file to restore the list from.

toString

public java.lang.String toString()

Generate a string representation of a list. For example

String text = myList.toString();

Returns:

The string representation of the list.