jdsl.core.api
Interface Sequence

All Known Implementing Classes:
NodeSequence, VectorSequence

public abstract interface Sequence
extends PositionalSequence

Interface for a Sequence. A sequence is a positional container whose positions are linearly arranged and that supports both position-based and rank-based operations. It is a generalization of basic data structures such as stacks, queues, deques, arrays, vectors, and linked lists.

This interface defines Sequence by extending PositionalSequence with the rank-based methods rankOf, atRank and insertAtRank. However, it does not extend simple.api.RankedSequence as BookSequence does.

The enumerations returned by methods Container.elements() and PositionalContainer.positions() are guaranteed to give the elements/position in the same order as they are arranged in the sequence.

Author:
Michael T. Goodrich, Mark Handy, Roberto Tamassia
See Also:
PositionalSequence, PositionalContainer, BookSequence, simple.api.RankedSequence

Method Summary
 Position atRank(int rank)
          Return the position with the specified rank.
 Position insertAtRank(int rank, java.lang.Object newElement)
          Insert a new position into the sequence at the specified rank, and store the given element into the position.
 int rankOf(Position p)
          Return the rank of the specified position.
 java.lang.Object removeAtRank(int rank)
          Remove the position at the designated rank
 
Methods inherited from interface jdsl.core.api.PositionalSequence
after, before, first, insertAfter, insertBefore, insertFirst, insertLast, last, remove, removeAfter, removeBefore, removeFirst, removeLast
 
Methods inherited from interface jdsl.core.api.PositionalContainer
positions, replace, swap
 
Methods inherited from interface jdsl.core.api.Container
elements, newContainer
 
Methods inherited from interface jdsl.simple.api.SimpleContainer
isEmpty, size
 

Method Detail

atRank

public Position atRank(int rank)
                throws BoundaryViolationException
Return the position with the specified rank.

Note that the first position of a sequence has rank 0.

A BoundaryViolationException is thrown if rank < 0 or if rank > n - 1, where n is the size (number of positions) of the sequence.

Parameters:
rank - integer specifying the rank.
Returns:
position at the specified rank.

rankOf

public int rankOf(Position p)
           throws InvalidPositionException
Return the rank of the specified position. Note that the first position has rank 0, and the last position has rank n - 1, where n is the size (number of positions) of the sequence.
Parameters:
p - position
Returns:
rank of the specified position in the sequence.

insertAtRank

public Position insertAtRank(int rank,
                             java.lang.Object newElement)
                      throws BoundaryViolationException
Insert a new position into the sequence at the specified rank, and store the given element into the position. Return the newly created position.
Parameters:
rank - rank that the new position should have. For example, if rank = 0, the insertion is done at the beginning, and if rank = n, where n is the old size (number of positions) of the sequence, the insertion is done at the end.
newElement - new element to be inserted.
Returns:
newly created position.

removeAtRank

public java.lang.Object removeAtRank(int rank)
                              throws BoundaryViolationException
Remove the position at the designated rank
Parameters:
rank - Index of the position to be removed
Returns:
Element formerly stored at the position removed