jdsl.core.ref
Class CircularNodeSequence

java.lang.Object
  |
  +--jdsl.core.ref.CircularNodeSequence

public class CircularNodeSequence
extends java.lang.Object
implements CircularSequence

A CircularSequence implemented with nodes. This container cannot check container(), because container() is a linear time operation.

Author:
Ryan Shaun Baker (rsb), Mike Boilen (mgb)
See Also:
CNSCircularNode

Constructor Summary
CircularNodeSequence()
          Constructs a new, empty sequence.
 
Method Summary
 Position after(Position predecessor)
          Gets the Position after a given Position in this CircularSequence.
 Position before(Position successor)
          Gets the Position before a given Position in this CircularSequence
 java.util.Enumeration elements()
          Returns an Enumeration of all the elements stored in this container.
 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.
 boolean isEmpty()
          Tests if this container is empty.
 Container newContainer()
          Constructs a new CircularNodeSequence.
 java.util.Enumeration positions()
          Returns all the positions in this container.
 java.lang.Object remove(Position p)
          Removes the specified position.
 java.lang.Object replace(Position p, java.lang.Object newElement)
          Replace the element at the specified position with a new element.
 int size()
          Gets the number of elements in this container.
 void splice(Position afterWhich, CircularSequence toMerge, Position newSuccessor)
          Merges in another CircularNodeSequence 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()
          Returns an arbitrary starting Position in this CircularSequence.
 void swap(Position a, Position b)
          Swaps the elements at two specified positions.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CircularNodeSequence

public CircularNodeSequence()
Constructs a new, empty sequence.
Method Detail

before

public Position before(Position successor)
                throws InvalidPositionException,
                       InvalidContainerException
Gets the Position before a given Position in this CircularSequence
Specified by:
before in interface CircularSequence
Parameters:
successor - Any Position in this Sequence.
Returns:
The Position before successor.
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 predecessor)
               throws InvalidPositionException,
                      InvalidContainerException
Gets the Position after a given Position in this CircularSequence.
Specified by:
after in interface CircularSequence
Parameters:
predecessor - Any Position in this Sequence.
Returns:
The Position before predecessor.
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,
                                 InvalidContainerException
Returns an arbitrary starting Position in this CircularSequence. Note:There is no guarantee what position this method returns, nor is there any guarantee that it remains static.
Specified by:
startingPosition in interface CircularSequence
Returns:
an arbitrary Position in this container.
Throws:
EmptyContainerException - if this 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,
                             InvalidContainerException
Inserts an element before a given position.
Specified by:
insertBefore in interface CircularSequence
Parameters:
p - The Position to insert before.
element - The element to insert.
Returns:
the Position holding the new element.
Throws:
InvalidPositionException - if Position is invalid, from a different container, or null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

insertAfter

public Position insertAfter(Position p,
                            java.lang.Object element)
                     throws InvalidPositionException,
                            InvalidContainerException
Inserts an element after a given position.
Specified by:
insertAfter in interface CircularSequence
Parameters:
p - The Position to insert after.
element - The element to insert.
Returns:
the Position holding the new element.
Throws:
InvalidPositionException - if Position is invalid, from a different container, or null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

insertInitial

public Position insertInitial(java.lang.Object element)
                       throws InvalidContainerException
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.
Specified by:
insertInitial in interface CircularSequence
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,
                               InvalidContainerException
Removes the specified position.
Specified by:
remove in interface CircularSequence
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. This method takes constant time.
Specified by:
split in interface CircularSequence
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

splice

public void splice(Position afterWhich,
                   CircularSequence toMerge,
                   Position newSuccessor)
            throws InvalidContainerException,
                   InvalidPositionException,
                   InvalidArgumentException
Merges in another CircularNodeSequence after a given position. That is, this CircularNodeSequence 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. This method takes constant time.
Specified by:
splice in interface CircularSequence
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:
size

positions

public java.util.Enumeration positions()
                                throws InvalidContainerException
Returns all the positions in this container.
Returns:
An Enumeration of all positions in this container.
Throws:
InvalidContainerException - if this container has been invalidated.
See Also:
splice

replace

public java.lang.Object replace(Position p,
                                java.lang.Object newElement)
                         throws InvalidPositionException,
                                InvalidContainerException
Replace the element at the specified position with a new element.
Parameters:
p - position at which the replacement is to occur
newElement - new element to be stored at position p
Returns:
old element formerly stored at position p
Throws:
InvalidPositionException - is thrown if the specified position does not belong to the container or if the position is null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

swap

public void swap(Position a,
                 Position b)
          throws InvalidPositionException,
                 InvalidContainerException
Swaps the elements at two specified positions.
Parameters:
p - first position participating in the swap.
q - second position participating in the swap.
Throws:
InvalidPositionException - if thrown if on or both of the specified Positions does not belong to this implementation of Container, or if either Position is null.
InvalidContainerException - if this container has been invalidated.
See Also:
splice

size

public int size()
         throws InvalidContainerException
Gets the number of elements in this container. Each element is counted a number of times according to its multiplicity. This is a linear time operation.
Throws:
InvalidContainerException - if this container has been invalidated.
See Also:
splice

isEmpty

public boolean isEmpty()
                throws InvalidContainerException
Tests if this container is empty.
Returns:
true if this container is empty, false otherwise.
Throws:
InvalidContainerException - if this container has been invalidated.
See Also:
splice

newContainer

public Container newContainer()
Constructs a new CircularNodeSequence.
Returns:
a new, empty container identical to this one.
Throws:
InvalidContainerException - if this container has been invalidated.
See Also:
splice

elements

public java.util.Enumeration elements()
Returns an Enumeration of all the elements stored in this container. Duplicated elements appear as many times as they are in the container. Elements are returned in the order they are inserted.
Returns:
An Enumeration of all elements in the container.
Throws:
InvalidContainerException - if this container has been invalidated.
See Also:
splice