jdsl.core.api
Interface CircularSequence

All Known Implementing Classes:
VCSVectorCircularSequence, CircularNodeSequence

public abstract interface CircularSequence
extends PositionalContainer

Interface for a circular sequence, a sequence without head or tail and without the possibility of boundary violations in prev(.) and next(.). Note: After splicing a CircularSequence into another sequence, the container that was spliced becomes invalid, and will throw an InvalidContainerException if any method is called on it.

Author:
Mark Handy, Mike Boilen (mgb)
See Also:
splice

Method Summary
 Position after(Position p)
          Gets the Position after a given Position in this CircularSequence
 Position before(Position p)
          Gets the Position before a given Position in this CircularSequence
 Position insertAfter(Position p, java.lang.Object element)
          Inserts an element after a given position.
 Position insertBefore(Position p, java.lang.Object element)
          Inserts an element before a given position.
 Position insertInitial(java.lang.Object element)
          Inserts an element into an empty CircularSequence.
 java.lang.Object remove(Position p)
          Removes the specified position.
 void splice(Position afterWhich, CircularSequence toMerge, Position newSuccessor)
          Merges in another CircularSequence after a given position.
 CircularSequence split(Position inNewA, Position inNewB)
          Snips out a chain of nodes from this CircularSequence, repairs this CircularSequence, and makes a new CircularSequence with the snipped-out nodes.
 Position startingPosition()
          Since there's no first() or last() in a circular sequence, a method is needed that will give a position -- any position -- in the circular sequence, to get things started.
 
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

before

public Position before(Position p)
                throws InvalidPositionException
Gets the Position before a given Position in this CircularSequence
Parameters:
p - Position of element in this sequence
Returns:
Position of previous element
Throws:
InvalidPositionException - if Position is invalid, from a different container, or null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

after

public Position after(Position p)
               throws InvalidPositionException
Gets the Position after a given Position in this CircularSequence
Parameters:
p - Position of element in this sequence
Returns:
Position of next element
Throws:
InvalidPositionException - if Position is invalid, from a different container, or null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

startingPosition

public Position startingPosition()
                          throws EmptyContainerException
Since there's no first() or last() in a circular sequence, a method is needed that will give a position -- any position -- in the circular sequence, to get things started. No guarantees about what position is returned.
Returns:
An arbitrary position in the circular sequence
Throws:
EmptyContainerException - if the container is empty
InvalidContainerException - if this container has been invalidated.
See Also:
splice

insertBefore

public Position insertBefore(Position p,
                             java.lang.Object element)
                      throws InvalidPositionException
Inserts an element before a given position.
Parameters:
p - Position of element in this sequence
element - Any java.lang.Object
Returns:
Position of Object element, now stored ahead of Position p (the parameter)
Throws:
InvalidPositionException - if p is null or not in this CircularSequence
InvalidContainerException - if this container has been invalidated.
See Also:
splice

insertAfter

public Position insertAfter(Position p,
                            java.lang.Object element)
                     throws InvalidPositionException
Inserts an element after a given position.
Parameters:
p - Position of element in this sequence
element - Any java.lang.Object
Returns:
Position of Object element, now stored ahead of Position p (the parameter)
Throws:
InvalidPositionException - if p is null or not in this CircularSequence
InvalidContainerException - if this container has been invalidated.
See Also:
splice

insertInitial

public Position insertInitial(java.lang.Object element)
                       throws NotEmptyContainerException
Inserts an element into an empty CircularSequence. The counterpart to startingPosition: intended for use only in an empty circular sequence, where there is no position before or after which you can insert.
Parameters:
element - Any Object
Returns:
Position of the object inserted
Throws:
NotEmptyContainerException - if this sequence is not empty.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

remove

public java.lang.Object remove(Position p)
                        throws EmptyContainerException,
                               InvalidPositionException
Removes the specified position.
Parameters:
p - The Position of the element after the element to be removed.
Returns:
The removed element.
Throws:
EmptyContainerException - If there are no elements in this container.
InvalidPositionException - if p is null or not in this CircularSequence
InvalidContainerException - if this container has been invalidated.
See Also:
splice

split

public CircularSequence split(Position inNewA,
                              Position inNewB)
                       throws EmptyContainerException,
                              InvalidPositionException,
                              InvalidContainerException
Snips out a chain of nodes from this CircularSequence, repairs this CircularSequence, and makes a new CircularSequence with the snipped-out nodes. If inNewA==inNewB, only that one Position is removed from this CircularSequence. @param inNewA Start of sequence of Positions to be removed from this CircularSequence. In structures that can implement this method in constant time, size() will be implemented in linear time.
Parameters:
inNewA - Beginning of sequence of Positions to be removed from.
inNewB - End of sequence of Positions to be removed from this CircularSequence.
Returns:
A new CircularSequence holding inNewA, inNewB, and all the Positions between them
Throws:
EmptyContainerException - if this container is empty.
InvalidPositionException - if inNewA or inNewB is null, from a different container, or of an incompatible type.
InvalidContainerException - if this container has been invalidated.
See Also:
splice, SimpleContainer.size()

splice

public void splice(Position afterWhich,
                   CircularSequence toMerge,
                   Position newSuccessor)
            throws InvalidContainerException,
                   InvalidPositionException,
                   InvalidArgumentException
Merges in another CircularSequence after a given position. That is, this CircularSequence is snipped after a given Position, and the merged-in CircularSequence is snipped before a given Position. toMerge will be invalidated after this method returns. In structures that can implement this method in constant time, size() will be implemented in linear time.
Parameters:
afterWhich - Position after which to break this CircularSequence
toMerge - CircularSequence to be spliced into this one
newSuccessor - Position from toMerge that will follow Position afterWhich from this CircularSequence.
Throws:
InvalidContainerException - If this container is invalid or if toMerge is invalid or of an incompatible type.
InvalidArgumentException - if toMerge is the same container as splice is called on.
InvalidPositionException - if afterWhich or newSuccessor is either null, or of the wrong type.
See Also:
SimpleContainer.size()