org.jtiger.framework
Interface Sequence<E>

All Superinterfaces:

Cloneable, Iterable<E>, ReadOnlyArray<E>, Serializable

public interface Sequence<E>
extends Iterable<E>, ReadOnlyArray<E>, Serializable

A sequentially ordered set of elements that cannot be mutated (changed).

Version:

2.1
Build Number 0376
Build Time 2006-07-28 01:50.16.218

Author:

Tony Morris

Method Summary

Sequence<E>	append(Sequence<E> sequence) Appends the given sequence to this sequence and returns a new sequence.
Sequence<E>	clone() Returns a clone of this Sequence.
Sequence<E>	delete(int fromPosition, int toPosition) Deletes elements between the given positions and returns the resulting sequence.
boolean	equals(Object o) Determines equality for this Sequence.
E	get(int index) Returns the element at the given index in the sequence.
SequenceIterator<E>	getIterator() Returns an iterator for this Sequence.
SequenceIterator<E>	getIterator(int position) Returns an iterator for this Sequence from the given position.
Sequence<E>	getSubSequence(int fromPosition, int toPosition) Returns a sequence that contains a subset of the elements of this sequence within the given positional range.
int	hashCode() Returns a hash code for this Sequence.
int	indexOf(E e) Returns the first index of the given element in the sequence, or less than zero if it is not present.
int	indexOf(int position, E e) Returns the first index of the given element in the sequence from the given position, or less than zero if it is not present.
Sequence<E>	insert(int position, Sequence<E> sequence) Inserts the given sequence at the given position and returns the resulting sequence.
boolean	isEmpty() Returns true is the sequence is empty, false otherwise.
int	lastIndexOf(E e) Returns the last index of the given element in the sequence, or less than zero if it is not present.
int	lastIndexOf(int position, E e) Returns the last index of the given element in the sequence from the given position, or less than zero if it is not present.
int	length() Returns the number of elements held in this sequence.
String	toString() Returns a String representation of this Sequence.

Method Detail

get

E get(int index)
      throws IndexOutOfBoundsException

Returns the element at the given index in the sequence.

Specified by:

get in interface ReadOnlyArray<E>

Parameters:

index - The index of the element to return.

Returns:

The element at the specified index.

Throws:

IndexOutOfBoundsException - If the given index is out of range (index < 0 || index >= length()).

length

int length()

Returns the number of elements held in this sequence.

Specified by:

length in interface ReadOnlyArray<E>

Returns:

The number of elements held in this sequence.

append

Sequence<E> append(Sequence<E> sequence)
                   throws NullPointerException

Appends the given sequence to this sequence and returns a new sequence.

Parameters:

sequence - The sequence to append to this sequence.

Returns:

A new sequence that has the passed sequence appended.

Throws:

NullPointerException - If sequence is null.

getSubSequence

Sequence<E> getSubSequence(int fromPosition,
                           int toPosition)
                           throws PositionOutOfBoundsException

Returns a sequence that contains a subset of the elements of this sequence within the given positional range. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

fromPosition - The position from which to take the subsequence.

toPosition - The position to which to take the subsequence.

Returns:

A sequence that contains a subset of the elements of this sequence within the given range.

Throws:

PositionOutOfBoundsException - If (fromPosition < 0 || toPosition > length() || fromPosition > toPosition) evaluates to true.

insert

Sequence<E> insert(int position,
                   Sequence<E> sequence)
                   throws PositionOutOfBoundsException,
                          NullPointerException

Inserts the given sequence at the given position and returns the resulting sequence. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

position - The position at which to insert the given sequence.

sequence - The sequence to insert at the given position.

Returns:

A sequence that contains the given sequence inserted at the given position.

Throws:

PositionOutOfBoundsException - If position is less than zero or greater than the length of this Sequence. If (fromIndex < 0 || fromIndex > length()) holds true.

NullPointerException - If sequence is null.

delete

Sequence<E> delete(int fromPosition,
                   int toPosition)
                   throws PositionOutOfBoundsException

Deletes elements between the given positions and returns the resulting sequence. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

fromPosition - The position from which to start deleting elements.

toPosition - The position to which to start deleting elements.

Returns:

A sequence that contains the elements of this sequence without the deleted elements.

Throws:

PositionOutOfBoundsException - If (fromPosition < 0 || toPosition > length() || fromPosition > toPosition) evaluates to true.

indexOf

int indexOf(E e)

Returns the first index of the given element in the sequence, or less than zero if it is not present.

Parameters:

e - The element to find the first index of.

Returns:

The first index of the given element in the sequence, or less than zero if it is not present.

indexOf

int indexOf(int position,
            E e)
            throws PositionOutOfBoundsException

Returns the first index of the given element in the sequence from the given position, or less than zero if it is not present. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

position - The position from which to find the element.

e - The element to find the first index of from the given position.

Returns:

The first index of the given element in the sequence from the given position, or less than zero if it is not present.

Throws:

PositionOutOfBoundsException - If position is less than zero or greater than the length of this Sequence. If (fromIndex < 0 || fromIndex > length()) holds true.

lastIndexOf

int lastIndexOf(E e)

Returns the last index of the given element in the sequence, or less than zero if it is not present.

Parameters:

e - The element to find the last index of.

Returns:

The last index of the given element in the sequence, or less than zero if it is not present.

lastIndexOf

int lastIndexOf(int position,
                E e)
                throws PositionOutOfBoundsException

Returns the last index of the given element in the sequence from the given position, or less than zero if it is not present. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

position - The position from which to find the element.

e - The element to find the last index of from the given position.

Returns:

The last index of the given element from the given position in the sequence, or less than zero if it is not present.

Throws:

PositionOutOfBoundsException - If position is less than zero or greater than the length of this Sequence. If (fromIndex < 0 || fromIndex > length()) holds true.

getIterator

SequenceIterator<E> getIterator()

Returns an iterator for this Sequence.

Returns:

An iterator for this Sequence.

getIterator

SequenceIterator<E> getIterator(int position)
                                throws PositionOutOfBoundsException

Returns an iterator for this Sequence from the given position. The position is indexed from zero and represents a position between elements within the sequence. For example, the start position is zero, where the position between the first and second element is one.

Parameters:

position - The position from which the iterator should iterate.

Returns:

An iterator for this Sequence from the given position.

Throws:

PositionOutOfBoundsException - If position is less than zero or greater than the length of this Sequence. If (fromIndex < 0 || fromIndex > length()) holds true.

isEmpty

boolean isEmpty()

Returns true is the sequence is empty, false otherwise.

Returns:

true is the sequence is empty, false otherwise.

toString

String toString()

Returns a String representation of this Sequence.

Overrides:

toString in class Object

Returns:

A String representation of this Sequence.

equals

boolean equals(Object o)

Determines equality for this Sequence. Returns true if each element in this Sequence is equal to each element in the Sequence that is passed as an argument, returns false otherwise. Equal elements in a different order of two Sequence instances deems the two Sequence instances unequal and therefore, false is returned. Implementations of this method must adhere to the contract set out by Object.equals(Object).

Overrides:

equals in class Object

Parameters:

o - The object to test equality for.

Returns:

true if each element in this Sequence is equal to each element in the Sequence that is passed as an argument, returns false otherwise.

hashCode

int hashCode()

Returns a hash code for this Sequence. Implementations of this method must adhere to the contract set out by Object.hashCode().

Overrides:

hashCode in class Object

Returns:

A hash code for this Sequence.

clone

Sequence<E> clone()

Returns a clone of this Sequence.

Specified by:

clone in interface ReadOnlyArray<E>

Returns:

A clone of this Sequence.