jdsl.core.api
Interface OrderedDictionary

All Known Implementing Classes:
RBTree

public abstract interface OrderedDictionary
extends Dictionary

A Dictionary in which the keys are totally ordered. That is, given a set of keys, S, where a and b are elements of S, exactly one of the following properties holds:

This expansion of the Dictionary interface allows OrderedDictionaries to be searched through sequentially.

Author:
John Kloss

Field Summary
static Locator BOUNDARY_VIOLATION
          Returned from all four methods of OrderedDictionary to indicate that the user tried to go before the first element of the dictionary or after the last.
 
Fields inherited from class jdsl.core.api.Dictionary
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 a Locator whose key is sequentially greater than or equal to the search key.
 Locator closestBefore(java.lang.Object key)
          Returns a Locator whose key is sequentially less than or equal to the search key.
 
Methods inherited from interface jdsl.core.api.Dictionary
find, findAll
 
Methods inherited from interface jdsl.core.api.KeyBasedContainer
insert, insert, keys, locators, makeLocator, remove, replaceElement, replaceKey
 
Methods inherited from interface jdsl.core.api.Container
elements, newContainer
 
Methods inherited from interface jdsl.simple.api.SimpleContainer
isEmpty, size
 

Field Detail

BOUNDARY_VIOLATION

public static final Locator BOUNDARY_VIOLATION
Returned from all four methods of OrderedDictionary to indicate that the user tried to go 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

public Locator before(Locator locator)
               throws InvalidLocatorException,
                      UncontainedLocatorException
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: this Locator will be the invalid BOUNDARY_VIOLATION if no such locator exists.
Throws:
InvalidLocatorException - If locator is invalid (For example: It does not actually reference an element within this Container).

after

public Locator after(Locator locator)
              throws InvalidLocatorException,
                     UncontainedLocatorException
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: this Locator will be the invalid BOUNDARY_VIOLATION if no such locator exists.
Throws:
InvalidLocatorException - If locator is invalid (For example: It does not actually reference an element within this Container).

closestBefore

public Locator closestBefore(java.lang.Object key)
                      throws InvalidKeyException,
                             UncontainedLocatorException
Returns a Locator whose key is sequentially less than or equal to the search key. The key which is ordered before key may have many Locators mapped to it. Which one is closest to key is implementation dependent. It is also possible that there are no such Locators ordered before key, in which case, the Locator returned will be invalid. Finally, it is possible that key is actually present in the container, in which case a locator whose key is equal to key will be returned.
Parameters:
key - An abstract position in this Container.
Returns:
The first Locator whose key is less than or equal to key in this Container. Note: If no such Locator exists, the returned Locator will be the invalid BOUNDARY_VIOLATION.
Throws:
InvalidKeyException - If key is not of a type accepted by this Container (For example: The key is not comparable).

closestAfter

public Locator closestAfter(java.lang.Object key)
                     throws InvalidKeyException,
                            UncontainedLocatorException
Returns a Locator whose key is sequentially greater than or equal to the search key. The key which is ordered after key may have many Locators mapped to it. Which one is closest to key is implementation dependent. It is also possible that there are no such Locators ordered after key, in which case, the Locator returned will be invalid. Finally, it is possible that key is actually present in the container, in which case a locator whose key is equal to key will be returned.
Parameters:
key - An abstract position in this Container.
Returns:
The first Locator whose key is greater than or equal to key in this Container. Note: If no such Locator exists, the returned Locator will be the invalid BOUNDARY_VIOLATION.
Throws:
InvalidKeyException - If key is not of a type accepted by this Container (For example: The key is not comparable).