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

Methods inherited from interface jdsl.core.api.InspectableSequence

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

Methods inherited from interface jdsl.core.api.InspectablePositionalContainer

positions

Methods inherited from interface jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Methods inherited from interface jdsl.core.api.PositionalContainer

swapElements

Methods inherited from interface jdsl.core.api.Container

newContainer, replaceElement

Method Detail

insertFirst

public Position insertFirst(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

public Position insertLast(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

public Position insertBefore(Position p,
                             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

public Position insertAfter(Position p,
                            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

public Position insertAtRank(int rank,
                             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

public 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

public 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

public 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

public 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

public 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

public 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