xtc.util
Class Pair<T>

java.lang.Object
  xtc.util.Pair<T>

All Implemented Interfaces:

java.lang.Iterable<T>

public class Pair<T>
extends java.lang.Object
implements java.lang.Iterable<T>

Implementation of a pair. Pairs are used to construct singly-linked lists, not unlike cons cells in Scheme. Generally, pairs should be treated as immutable data structures. In particular, a pair must not be modified if it is memoized by a Rats!-generated parser.

Version:

$Revision: 1.41 $

Author:

Robert Grimm

Field Summary

static Pair

EMPTY The pair representing the empty list.

Constructor Summary

Pair(T head)
Create a new pair.

Pair(T head, Pair<T> tail)
Create a new pair.

Method Summary

Pair<T>	add(T element) Add the specified element to the list starting at this pair.
void	addTo(java.util.List<? super T> l) Add the values of the list starting at this pair in order to the specified Java collections framework list.
Pair<T>	append(Pair<T> tail) Set the tail of a copy of this list's last pair to the specified value.
Pair<T>	combine(Pair<T> list) Combine the elements on the list starting at this pair with the elements on the list starting at the specified pair.
boolean	consists() Determine whether the list starting at this pair consists of no elements.
boolean	consists(java.lang.Object... os) Determine whether the list starting at this pair consists of the specified objects.
boolean	consists(java.lang.Object o) Determine whether the list starting at this pair consists of the specified object.
boolean	consists(java.lang.Object o1, java.lang.Object o2) Determine whether the list starting at this pair consists of the specified two objects.
boolean	consists(java.lang.Object o1, java.lang.Object o2, java.lang.Object o3) Determine whether the list starting at this pair consists of the specified three objects.
boolean	consists(java.lang.Object o1, java.lang.Object o2, java.lang.Object o3, java.lang.Object o4) Determine whether the list starting at this pair consists of the specified four objects.
boolean	consists(java.lang.Object o1, java.lang.Object o2, java.lang.Object o3, java.lang.Object o4, java.lang.Object o5) Determine whether the list starting at this pair consists of the specified five objects.
boolean	contains(java.lang.Object o) Determine whether the list starting at this pair contains the specified element.
static <T> Pair<T>	empty() Get the canoncial empty pair.
boolean	equals(java.lang.Object o) Determine whether the list starting at this pair equals the specified object.
T	get(int index) Get the element at the specified index of the list starting at this pair.
int	hashCode() Get a hashcode for the list starting at this pair.
T	head() Get the head.
Pair<T>	intersect(Pair<T> list) Intersect the elements on the list starting at this pair with the elements on the list starting at the specified pair.
boolean	isEmpty() Determine whether the list starting at this pair is empty.
java.util.Iterator<T>	iterator() Get an iterator over the values of the list starting at this pair.
java.util.List<T>	list() Convert the list starting at this pair into a Java collections framework list.
Pair<T>	reverse() Reverse the list starting at this pair in place.
T	set(int index, T element) Replace the element at the specified index of the list starting at this pair.
T	setHead(T head) Set the head.
void	setLastTail(Pair<T> tail) Set the tail of this list's last pair to the specified value.
Pair<T>	setTail(Pair<T> tail) Set the tail.
int	size() Get the size of the list starting at this pair.
Pair<T>	subtract(Pair<T> list) Subtract the elements on the list starting at the specified list from the elements on the list starting at this pair.
Pair<T>	tail() Get the tail.
java.lang.String	toString() Get a string representation for the list starting at this pair.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY

public static final Pair EMPTY

The pair representing the empty list.

Constructor Detail

Pair

public Pair(T head)

Create a new pair. The newly created pair represents a singleton list.

Parameters:

head - The head.

Pair

public Pair(T head,
            Pair<T> tail)

Create a new pair.

Parameters:

head - The head.

tail - The tail.

Throws:

java.lang.NullPointerException - Signals that tail is null.

Method Detail

hashCode

public int hashCode()

Get a hashcode for the list starting at this pair.

Overrides:

hashCode in class java.lang.Object

Returns:

A hashcode.

equals

public boolean equals(java.lang.Object o)

Determine whether the list starting at this pair equals the specified object.

Overrides:

equals in class java.lang.Object

Parameters:

o - The object.

Returns:

true if the list starting at this pair equals the object.

isEmpty

public boolean isEmpty()

Determine whether the list starting at this pair is empty.

Returns:

true if the list is empty.

head

public T head()

Get the head.

Returns:

The head.

Throws:

java.lang.IllegalStateException - Signals that this pair represents the empty list.

setHead

public T setHead(T head)

Set the head.

Parameters:

head - The new head.

Returns:

The old head.

Throws:

java.lang.IllegalStateException - Signals that this pair represents the empty list.

tail

public Pair<T> tail()

Get the tail.

Returns:

The tail.

Throws:

java.lang.IllegalStateException - Signals that this pair represents the empty list.

setTail

public Pair<T> setTail(Pair<T> tail)

Set the tail.

Parameters:

tail - The new tail.

Returns:

The old tail.

Throws:

java.lang.NullPointerException - Signals that tail is null.

java.lang.IllegalStateException - Signals that this pair represents the empty list.

get

public T get(int index)

Get the element at the specified index of the list starting at this pair. Note that this method's performance is linear to the index.

Parameters:

index - The element's index.

Returns:

The element.

Throws:

java.lang.IndexOutOfBoundsException - Signals an invalid index.

set

public T set(int index,
             T element)

Replace the element at the specified index of the list starting at this pair. Note that this method's performance is linear to the index.

Parameters:

index - The element's index.

element - The new element.

Returns:

The old element.

Throws:

java.lang.IndexOutOfBoundsException - Signals an invalid index.

size

public int size()

Get the size of the list starting at this pair. Note that this method's performance is linear to the size of the list.

Returns:

The size.

contains

public boolean contains(java.lang.Object o)

Determine whether the list starting at this pair contains the specified element. If the specified element is not null, the implementation invokes equals() on the element.

Parameters:

o - The element.

Returns:

true if the list starting at this pair contains the element.

consists

public boolean consists()

Determine whether the list starting at this pair consists of no elements.

Returns:

true if the list starting at this pair consists of no elements.

consists

public boolean consists(java.lang.Object o)

Determine whether the list starting at this pair consists of the specified object. If the specified object is not null, the implementation invokes equals() on the object.

Parameters:

o - The object.

Returns:

true if the list starting at this pair consists of the object.

consists

public boolean consists(java.lang.Object o1,
                        java.lang.Object o2)

Determine whether the list starting at this pair consists of the specified two objects. If any of the specified objects is not null, the implementation invokes equals() on the object.

Parameters:

o1 - The first object.

o2 - The second object.

Returns:

true if the list starting at this pair consists of the two objects.

consists

public boolean consists(java.lang.Object o1,
                        java.lang.Object o2,
                        java.lang.Object o3)

Determine whether the list starting at this pair consists of the specified three objects. If any of the specified objects is not null, the implementation invokes equals() on the object.

Parameters:

o1 - The first object.

o2 - The second object.

o3 - The third object.

Returns:

true if the list starting at this pair consists of the three objects.

consists

public boolean consists(java.lang.Object o1,
                        java.lang.Object o2,
                        java.lang.Object o3,
                        java.lang.Object o4)

Determine whether the list starting at this pair consists of the specified four objects. If any of the specified objects is not null, the implementation invokes equals() on the object.

Parameters:

o1 - The first object.

o2 - The second object.

o3 - The third object.

o4 - The fourth object.

Returns:

true if the list starting at this pair consists of the four objects.

consists

public boolean consists(java.lang.Object o1,
                        java.lang.Object o2,
                        java.lang.Object o3,
                        java.lang.Object o4,
                        java.lang.Object o5)

Determine whether the list starting at this pair consists of the specified five objects. If any of the specified objects is not null, the implementation invokes equals() on the object.

Parameters:

o1 - The first object.

o2 - The second object.

o3 - The third object.

o4 - The fourth object.

o5 - The fifth object.

Returns:

true if the list starting at this pair consists of the five objects.

consists

public boolean consists(java.lang.Object... os)

Determine whether the list starting at this pair consists of the specified objects. If any of the specified objects is not null, the implementation invokes equals() on the object.

Parameters:

os - The objects.

Returns:

true if the list starting at this pair consists of the specified objects.

iterator

public java.util.Iterator<T> iterator()

Get an iterator over the values of the list starting at this pair.

Specified by:

iterator in interface java.lang.Iterable<T>

Returns:

The iterator.

reverse

public Pair<T> reverse()

Reverse the list starting at this pair in place. This method destructively reverses the list starting at this pair. Note that this method's performance is linear in the size of the list.

Returns:

The new head of the list.

add

public Pair<T> add(T element)

Add the specified element to the list starting at this pair. If this list is the empty list, this method simply allocates a new pair. Otherwise, it modifies this list's last non-empty element. In either case, this method returns the newly created pair to facilitate incremental construction of lists.

Parameters:

element - The element.

Returns:

The newly added pair.

Throws:

java.lang.IllegalStateException - Signals that this pair represent the empty list.

setLastTail

public void setLastTail(Pair<T> tail)

Set the tail of this list's last pair to the specified value. Effectively, this method destructively appends the list starting at the specified pair to the list starting at this pair. Its performance is linear in the size of the list.

Parameters:

tail - The new tail.

Throws:

java.lang.NullPointerException - Signals that tail is null.

java.lang.IllegalStateException - Signals that this pair represents the empty list.

See Also:

append(Pair)

append

public Pair<T> append(Pair<T> tail)

Set the tail of a copy of this list's last pair to the specified value. Effectively, this method non-destructively appends the list starting at the specified pair to the list starting at this pair. Its performance is linear in the size of the list.

Parameters:

tail - The new tail.

Returns:

The new head.

Throws:

java.lang.NullPointerException - Signals that tail is null.

See Also:

setLastTail(Pair)

combine

public Pair<T> combine(Pair<T> list)

Combine the elements on the list starting at this pair with the elements on the list starting at the specified pair. Note that this method's performance is quadratic in the size of the lists.

Parameters:

list - The other list.

Returns:

The set union.

intersect

public Pair<T> intersect(Pair<T> list)

Intersect the elements on the list starting at this pair with the elements on the list starting at the specified pair. Note that this method's performance is quadratic in the size of the lists.

Parameters:

list - The other list.

Returns:

The set intersection.

subtract

public Pair<T> subtract(Pair<T> list)

Subtract the elements on the list starting at the specified list from the elements on the list starting at this pair. Note that this method's performance is quadratic in the size of the lists.

Parameters:

list - The list to subtract.

Returns:

The set subtraction.

addTo

public void addTo(java.util.List<? super T> l)

Add the values of the list starting at this pair in order to the specified Java collections framework list.

Parameters:

l - The list.

list

public java.util.List<T> list()

Convert the list starting at this pair into a Java collections framework list. Note that this method's performance is linear to the size of the list.

Returns:

The list.

toString

public java.lang.String toString()

Get a string representation for the list starting at this pair. Note that this method's performance is linear to the size of the list.

Overrides:

toString in class java.lang.Object

Returns:

A string representation.

empty

public static final <T> Pair<T> empty()

Get the canoncial empty pair.

Returns:

The canonical empty pair.