jdsl.core.api
Interface PositionalSequence

All Known Subinterfaces:
BookSequence, Sequence

public abstract interface PositionalSequence
extends PositionalContainer

Interface for a positional sequence. A positional sequence is a positional container whose positions are linearly arranged and that supports position-based operations. It is a generalization of a linked list.

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 positional sequence.

Author:
Michael T. Goodrich, Mark Handy, Roberto Tamassia
See Also:
Sequence, Position, PositionalContainer

Method Summary
 Position after(Position p)
          Return the position immediately after the specified one.
 Position before(Position p)
          Return the position immediately before the specified one.
 Position first()
          Return the first position.
 Position insertAfter(Position p, java.lang.Object element)
          Create a new position immediately after the specified position and store there the given element.
 Position insertBefore(Position p, java.lang.Object element)
          Create a new position immediately before the specified position and store there the given element.
 Position insertFirst(java.lang.Object element)
          Create a new position at the beginning of the positional sequence and store there the given element.
 Position insertLast(java.lang.Object element)
          Create a new position at the end of the positional sequence and store there the given element.
 Position last()
          Return the last position.
 java.lang.Object remove(Position p)
          Remove and invalidate the specified position.
 java.lang.Object removeAfter(Position p)
          Removes the position after a specified position
 java.lang.Object removeBefore(Position p)
          Removes the position before a specified position
 java.lang.Object removeFirst()
          Removes the first position in the sequence
 java.lang.Object removeLast()
          Removes the last position of the sequence
 
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

first

public Position first()
               throws EmptyContainerException
Return the first position.

An EmptyContainerException is thrown if the positional sequence is empty.

Returns:
first position.

last

public Position last()
              throws EmptyContainerException
Return the last position.

An EmptyContainerException is thrown if the positional sequence is empty.

Returns:
last position.

before

public Position before(Position p)
                throws InvalidPositionException,
                       BoundaryViolationException
Return the position immediately before the specified one.

A BoundaryViolationException is thrown if the position specified is the first one.

Parameters:
p - position.
Returns:
position immediately before position p.

after

public Position after(Position p)
               throws InvalidPositionException,
                      BoundaryViolationException
Return the position immediately after the specified one.

A BoundaryViolationException is thrown if the position specified is the last one.

Parameters:
p - position.
Returns:
position immediately after position p.

insertFirst

public Position insertFirst(java.lang.Object element)
Create a new position at the beginning of the positional sequence and store there the given element. Return the newly created position.
Parameters:
element - element to be inserted.
Returns:
newly created position.

insertLast

public Position insertLast(java.lang.Object element)
Create a new position at the end of the positional sequence and store there the given element. Return the newly created position.
Parameters:
element - element to be inserted.
Returns:
newly created position.

insertBefore

public Position insertBefore(Position p,
                             java.lang.Object element)
                      throws InvalidPositionException
Create a new position immediately before the specified position and store there the given element. Return the newly created position.
Parameters:
p - position immediately before which the insertion should be done.
element - element to be inserted.
Returns:
newly created position.

insertAfter

public Position insertAfter(Position p,
                            java.lang.Object element)
                     throws InvalidPositionException
Create a new position immediately after the specified position and store there the given element. Return the newly created position.
Parameters:
p - position immediately after which the insertion should be done.
element - element to be inserted.
Returns:
newly created position.

remove

public java.lang.Object remove(Position p)
                        throws InvalidPositionException
Remove and invalidate the specified position. Return the element stored at it.
Parameters:
p - position to be removed.
Returns:
element formerly stored at the removed position.

removeBefore

public java.lang.Object removeBefore(Position p)
                              throws InvalidPositionException,
                                     BoundaryViolationException
Removes the position before a specified position
Parameters:
p - Position after position to be removed
Returns:
Element formerly stored at the removed position

removeAfter

public java.lang.Object removeAfter(Position p)
                             throws InvalidPositionException,
                                    BoundaryViolationException
Removes the position after a specified position
Parameters:
p - Position before position to be removed
Returns:
Element formerly stored at the removed position

removeFirst

public java.lang.Object removeFirst()
                             throws EmptyContainerException
Removes the first position in the sequence
Returns:
Element formerly stored in the first position of the sequence

removeLast

public java.lang.Object removeLast()
                            throws EmptyContainerException
Removes the last position of the sequence
Returns:
Element formerly stored in the last position of the sequence