nz.ac.waikato.jdsl.core.api
Interface Sequence

All Superinterfaces:

Container, InspectableContainer, InspectablePositionalContainer, InspectableSequence, PositionalContainer

All Known Implementing Classes:

ArraySequence, NodeSequence

public interface Sequence
extends InspectableSequence, PositionalContainer

A positional container whose elements are linearly organized. It is a generalization of stacks, queues, linked lists, and arrays.

For a Sequence, methods InspectableContainer.elements() and InspectablePositionalContainer.positions() are guaranteed to return iterators in first-to-last order.

Version:

JDSL 2.1.1

Author:

Mark Handy (mdh), Luca Vismara (lv), Andrew Schwerin (schwerin)

See Also:

InspectableSequence, PositionalContainer

Method Summary

Position	insertAfter(Position p, java.lang.Object element) Inserts an object after a position in the sequence.
Position	insertAtRank(int rank, java.lang.Object element) Inserts based on an integer rank similar to array indices.
Position	insertBefore(Position p, java.lang.Object element) Inserts an object before a position in the sequence.
Position	insertFirst(java.lang.Object element) Inserts an object as first element of the sequence
Position	insertLast(java.lang.Object element) Inserts an object as last element of the sequence.
java.lang.Object	remove(Position pos) Removes and invalidates the specified position
java.lang.Object	removeAfter(Position pos) Remove and invalidates the position after the position specified
java.lang.Object	removeAtRank(int rank) Removes and invalidates the position at the specified rank
java.lang.Object	removeBefore(Position pos) Removes and invalidates the position before the position specified.
java.lang.Object	removeFirst() Removes and invalidates the first position of this.
java.lang.Object	removeLast() Removes and invalidates the last position of this.

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableSequence

after, atRank, before, first, isFirst, isLast, last, rankOf

Methods inherited from interface nz.ac.waikato.jdsl.core.api.PositionalContainer

swapElements

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectablePositionalContainer

positions

Methods inherited from interface nz.ac.waikato.jdsl.core.api.Container

newContainer, replaceElement

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Method Detail

insertFirst

Position insertFirst(java.lang.Object element)

Inserts an object as first element of the sequence

Parameters:

element - Any java.lang.Object

Returns:

The Position containing that element, which is now the first position in the sequence.

insertLast

Position insertLast(java.lang.Object element)

Inserts an object as last element of the sequence.

Parameters:

element - Any java.lang.Object

Returns:

The Position containing that element, which is now the last in the sequence.

insertBefore

Position insertBefore(Position p,
                      java.lang.Object element)
                      throws InvalidAccessorException

Inserts an object before a position in the sequence.

Parameters:

p - Position in this sequence before which to insert an element.

element - Any java.lang.Object

Returns:

Position containing element and before Position p.

Throws:

InvalidAccessorException - Thrown if p is not a valid position in this sequence

insertAfter

Position insertAfter(Position p,
                     java.lang.Object element)
                     throws InvalidAccessorException

Inserts an object after a position in the sequence.

Parameters:

p - Position in this sequence after which to insert an element.

element - Any java.lang.Object

Returns:

Position containing element and after Position p.

Throws:

InvalidAccessorException - Thrown if p is not a valid position in this sequence

insertAtRank

Position insertAtRank(int rank,
                      java.lang.Object element)
                      throws BoundaryViolationException

Inserts based on an integer rank similar to array indices. The first element in the sequence has rank 0, and the last has rank size() - 1. It is valid to insert at any rank greater than or equal to zero and less than or equal to size().

Parameters:

rank - Rank that element should have after insertion.

element - Any java.lang.Object

Returns:

Position of element in the sequence.

Throws:

BoundaryViolationException - if rank exceeds size() or if 0 exceeds rank

removeFirst

java.lang.Object removeFirst()
                             throws EmptyContainerException

Removes and invalidates the first position of this.

Returns:

the element formerly stored at the first position of this

Throws:

EmptyContainerException - if this sequence is empty

removeLast

java.lang.Object removeLast()
                            throws EmptyContainerException

Removes and invalidates the last position of this.

Returns:

the element formerly stored at the last position of this

Throws:

EmptyContainerException - if this sequence is empty

remove

java.lang.Object remove(Position pos)
                        throws InvalidAccessorException

Removes and invalidates the specified position

Parameters:

pos - the position to be removed

Returns:

the element formerly stored at pos

Throws:

InvalidAccessorException - if the specified position is invalid or not belong to this container.

removeAfter

java.lang.Object removeAfter(Position pos)
                             throws BoundaryViolationException,
                                    InvalidAccessorException

Remove and invalidates the position after the position specified

Parameters:

pos - a position

Returns:

the element formerly stored at the position after pos

Throws:

BoundaryViolationException - if pos is the last position of this sequence

InvalidAccessorException - if the specified position is invalid or not belong to this container.

removeBefore

java.lang.Object removeBefore(Position pos)
                              throws BoundaryViolationException,
                                     InvalidAccessorException

Removes and invalidates the position before the position specified.

Parameters:

pos - a position

Returns:

the element formerly stored at the position before pos

Throws:

BoundaryViolationException - if pos is the first position of this sequence.

InvalidAccessorException - if the specified position is invalid or not belong to this container.

removeAtRank

java.lang.Object removeAtRank(int rank)
                              throws BoundaryViolationException

Removes and invalidates the position at the specified rank

Parameters:

rank - the rank of the position to be removed

Returns:

the element formerly stored at the position at rank

Throws:

BoundaryViolationException - if rank is less than 0 or greater than the size of this sequence