jdsl.core.api
Interface PositionalContainer

All Known Subinterfaces:
BinaryTree, BookSequence, CircularSequence, Graph, InspectableBinaryTree, InspectableGraph, InspectableTree, PositionalSequence, RestructurableBinaryTree, Sequence, Tree

public abstract interface PositionalContainer
extends Container

A positional container stores elements at its positions and defines adjacency relationships between the positions (for example, before/after in a sequence, parent/child in a tree). This is the base interface for all the positional containers (e.g., Sequence, Tree, Graph).

Author:
Michael T. Goodrich, Mark Handy, Roberto Tamassia, Mike Boilen (mgb)
See Also:
Position, Container, Sequence, Tree, BinaryTree, Graph

Method Summary
 java.util.Enumeration positions()
          Return an Enumeration of the positions in the container.
 java.lang.Object replace(Position p, java.lang.Object newElement)
          Replace the element at the specified position with a new element.
 void swap(Position p, Position q)
          Swaps the elements at two specified positions.
 
Methods inherited from interface jdsl.core.api.Container
elements, newContainer
 
Methods inherited from interface jdsl.simple.api.SimpleContainer
isEmpty, size
 

Method Detail

positions

public java.util.Enumeration positions()
Return an Enumeration of the positions in the container. There is no guarantee of the order of the positions in the Enumeration. However, certain implementations of PositionalContainer may guarantee a certain order of the positions in the Enumeration.
Returns:
Enumeration of all positions in the container

replace

public java.lang.Object replace(Position p,
                                java.lang.Object newElement)
                         throws InvalidPositionException
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.

swap

public void swap(Position p,
                 Position q)
          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 the same implementation of Container, or if either Position is null.