jdsl
Interface PositionalContainer

All Known Subinterfaces:

BinaryTree, BookSequence, CircularSequence, Graph, 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).

See Also:

Position, Container, Sequence, Tree, BinaryTree, Graph

Method Summary

java.util.Iterator	positions() Return an Iterator 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.Container

elements, isEmpty, newContainer, size

Method Detail

positions

public java.util.Iterator positions()

Return an Iterator of the positions in the container. There is no guarantee of the order of the positions in the Iterator. However, certain implementations of PositionalContainer may guarantee a certain order of the positions in the Iterator.

Returns:

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