nz.ac.waikato.jdsl.core.api
Interface InspectableOrderedDictionary

All Superinterfaces:

InspectableContainer, InspectableDictionary, InspectableKeyBasedContainer

All Known Subinterfaces:

OrderedDictionary

All Known Implementing Classes:

RedBlackTree

public interface InspectableOrderedDictionary
extends InspectableDictionary

A read-only lookup structure in which an ordering of the keys is maintained; please refer to the documentation of OrderedDictionary for more details.

Version:

JDSL 2.1.1

Author:

Mark Handy, Luca Vismara, Andrew Schwerin

See Also:

OrderedDictionary, InspectableDictionary

Nested Class Summary

Nested classes/interfaces inherited from interface nz.ac.waikato.jdsl.core.api.InspectableDictionary

InspectableDictionary.InvalidLocator

Field Summary

static Locator

BOUNDARY_VIOLATION Object returned from all four methodsof InspectableOrderedDictionary to indicate that the user tried to access before the first element of the dictionary or after the last.

Fields inherited from interface nz.ac.waikato.jdsl.core.api.InspectableDictionary

NO_SUCH_KEY

Method Summary

Locator	after(Locator locator) Returns the Locator that is sequentially after another Locator in this Container.
Locator	before(Locator locator) Returns the Locator that is sequentially before another Locator in this Container.
Locator	closestAfter(java.lang.Object key) Returns the locator with smallest key greater than or equal to the search key.
Locator	closestBefore(java.lang.Object key) Returns the locator with largest key less than or equal to the search key.
Locator	first() Returns the Locator that is sequentially before any other Locator in this Container.
Locator	last() Returns the Locator that is sequentially after any other Locator in this Container.

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableDictionary

find, findAll

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableKeyBasedContainer

keys, locators

Methods inherited from interface nz.ac.waikato.jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Field Detail

BOUNDARY_VIOLATION

static final Locator BOUNDARY_VIOLATION

Object returned from all four methodsof InspectableOrderedDictionary to indicate that the user tried to access before the first element of the dictionary or after the last. Note that dictionaries have special values returned from lookup methods, rather than exceptions, when the lookup fails.

Method Detail

before

Locator before(Locator locator)
               throws InvalidAccessorException

Returns the Locator that is sequentially before another Locator in this Container. If there is no such element then the returned Locator will be invalid.

Parameters:

locator - An abstract position in this Container.

Returns:

A Locator which is sequentially before locator. Note: Will return the invalid BOUNDARY_VIOLATION Locator if no such locator exists.

Throws:

InvalidAccessorException - If locator is invalid (For example: It does not actually reference an element within this Container).

after

Locator after(Locator locator)
              throws InvalidAccessorException

Returns the Locator that is sequentially after another Locator in this Container. If there is no such element then the returned Locator will be invalid.

Parameters:

locator - An abstract position in this Container.

Returns:

A Locator which is sequentially after locator. Note: Will return the invalid BOUNDARY_VIOLATION Locator if no such locator exists.

Throws:

InvalidAccessorException - If locator is invalid (For example: It does not actually reference an element within this Container).

closestBefore

Locator closestBefore(java.lang.Object key)
                      throws InvalidKeyException

Returns the locator with largest key less than or equal to the search key. There may exist more than one locator satisfying this property; which one is returned is implementation dependent.

Parameters:

key - A valid key.

Returns:

The locator with largest key less than or equal to key. Note: If no such locator exists, the returned locator will be BOUNDARY_VIOLATION.

Throws:

InvalidKeyException - If key is not of a type accepted by this Container (For example: the key is not comparable).

closestAfter

Locator closestAfter(java.lang.Object key)
                     throws InvalidKeyException

Returns the locator with smallest key greater than or equal to the search key. There may exist more than one locator satisfying this property; which one is returned is implementation dependent.

Parameters:

key - A valid key.

Returns:

The locator with smallest key greater than or equal to key. Note: If no such Locator exists, the returned locator will be BOUNDARY_VIOLATION.

Throws:

InvalidKeyException - If key is not of a type accepted by this Container (For example: the key is not comparable).

first

Locator first()

Returns the Locator that is sequentially before any other Locator in this Container. If there is no such element then the returned Locator will be invalid.

Returns:

A Locator which is sequentially before any other locator. Note: Will return the invalid BOUNDARY_VIOLATION Locator if no such locator exists.

last

Locator last()

Returns the Locator that is sequentially after any other Locator in this Container. If there is no such element then the returned Locator will be invalid.

Returns:

A Locator which is sequentially after any other locator. Note: Will return the invalid BOUNDARY_VIOLATION Locator if no such locator exists.