All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface jdsl.core.api.CircularSequence

public 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.

See Also:
splice

Method Index

o after(Position)
Gets the Position after a given Position in this CircularSequence
o before(Position)
Gets the Position before a given Position in this CircularSequence
o insertAfter(Position, Object)
Inserts an element after a given position.
o insertBefore(Position, Object)
Inserts an element before a given position.
o insertInitial(Object)
Inserts an element into an empty CircularSequence.
o remove(Position)
Removes the specified position.
o splice(Position, CircularSequence, Position)
Merges in another CircularSequence after a given position.
o split(Position, Position)
Snips out a chain of nodes from this CircularSequence, repairs this CircularSequence, and makes a new CircularSequence with the snipped-out nodes.
o 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

o before 
 public abstract 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.
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o after 
 public abstract 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.
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o startingPosition 
 public abstract 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
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o insertBefore 
 public abstract Position insertBefore(Position p,
                                       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
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o insertAfter 
 public abstract Position insertAfter(Position p,
                                      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
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o insertInitial 
 public abstract Position insertInitial(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.
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o remove 
 public abstract 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.
Throws: InvalidPositionException
if p is null or not in this CircularSequence
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice
o split 
 public abstract 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.
Throws: InvalidPositionException
if inNewA or inNewB is null, from a different container, or of an incompatible type.
Throws: InvalidContainerException
if this container has been invalidated.
See Also:
splice, size
o splice 
 public abstract 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.
Throws: InvalidArgumentException
if toMerge is the same container as splice is called on.
Throws: InvalidPositionException
if afterWhich or newSuccessor is either null, or of the wrong type.
See Also:
size 
All Packages  Class Hierarchy  This Package  Previous  Next  Index