edu.nrao.sss.util
Class LookupTable<K extends Comparable<K>,V>

java.lang.Object
  edu.nrao.sss.util.LookupTable<K,V>

All Implemented Interfaces:

Cloneable

public class LookupTable<K extends Comparable<K>,V>
extends Object
implements Cloneable

A lookup table.

A lookup table is very similar to a map. The main difference is that to get a value from a map, you need to specify exactly a key that the map holds. To get a value from a lookup table, though, all you need to have is a key that is at least as great as the key for the first entry in the table. The value returned for any key, K, is the value found in the entry whose key is less than or equal to K. The entries in a lookup table are sorted in ascending order of the entries' keys. The definition of "ascending" depends on the comparator used to construct the table.

A classic use of a lookup table is a table of marginal income tax rates. Your marginal tax rate is given by the entry whose income is less than or equal to your own.

The keys of this table may be any object that implements the Comparable interface. Examples of common key types are numbers, strings, and dates. Via the use of generics, this table is type safe.

CVS Info:

$Revision: 161 $

$Date: 2006-12-15 11:48:34 -0700 (Fri, 15 Dec 2006) $

$Author: btruitt $

Since:

2006-07-31

Author:

David M. Harland

Constructor Summary

LookupTable()
Creates a new, empty table, sorted according to the keys' natural order.

LookupTable(Comparator<? super K> c)
Constructs a new, empty table, sorted according to the given comparator.

Method Summary

void	clear() Removes all entries from this table.
LookupTable<K,V>	clone() Returns a shallow copy of this lookup table.
boolean	containsKey(K key) Returns true if this table contains an entry whose key is key.
boolean	containsValue(V value) Returns true if this table contains one or more entries whose value is value.
boolean	equals(Object o) Returns true if o is equal to this table.
V	get(K key) Returns the value associated with the first key that is less than or equal to key.
SortedSet<K>	getKeySet() Returns this table's set of keys.
SortedSet<K>	getKeySetFor(V value) Returns the set of keys under which value is stored.
int	hashCode() Returns a hash code value for this table.
V	put(K key, V value) Puts the given key / value pair into this table.
void	putAll(Map<K,V> map) Copies all the mappings from map into this table.
V	remove(K key) Removes the entry whose key is key from this table, if present.
int	removeValue(V value) Removes all entries in this table whose value is value.
int	size() Returns the number of entries in this table.
SortedMap<K,V>	toMap() Returns this table in the form of a sorted map.
String	toString() Returns a text representation of this table.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

LookupTable

public LookupTable()

Creates a new, empty table, sorted according to the keys' natural order.

LookupTable

public LookupTable(Comparator<? super K> c)

Constructs a new, empty table, sorted according to the given comparator.

Parameters:

c - the comparator that will be used to sort this map. A null value indicates that the keys' natural ordering should be used.

Method Detail

clear

public void clear()

Removes all entries from this table.

put

public V put(K key,
             V value)

Puts the given key / value pair into this table.

Parameters:

key - key with which the specified value is to be associated.

value - value to be associated with the specified key.

Returns:

the value that had been previously mapped to key.

putAll

public void putAll(Map<K,V> map)

Copies all the mappings from map into this table.

Parameters:

map - a source of key / value pairs.

remove

public V remove(K key)

Removes the entry whose key is key from this table, if present.

Parameters:

key - the key whose entry should be removed from this table.

Returns:

the value that had been associated with key, or null if this table had no entry for key.

removeValue

public int removeValue(V value)

Removes all entries in this table whose value is value.

Parameters:

value - the value to be removed entirely from this table.

Returns:

the number of entries that were removed from this table.

containsKey

public boolean containsKey(K key)

Returns true if this table contains an entry whose key is key.

Parameters:

key - a key that may be present in this table.

Returns:

true if this table contains an entry whose key is key.

containsValue

public boolean containsValue(V value)

Returns true if this table contains one or more entries whose value is value.

Parameters:

value - a value that may be present in this table.

Returns:

true if this table contains one or more entries whose value is value.

get

public V get(K key)

Returns the value associated with the first key that is less than or equal to key. The keys of this table are ordered according to the compartor specified during the construction of this table. If no comparator was so specified, then the keys are in their natural order.

A return value of null means either that key is less than the first key in this table, or that the greatest key that is not greater than key maps to a value of null.

Parameters:

key - the key for which a value is sought.

Returns:

the value associated with the first key that is less than or equal to key.

getKeySet

public SortedSet<K> getKeySet()

Returns this table's set of keys.

Returns:

this table's set of keys.

getKeySetFor

public SortedSet<K> getKeySetFor(V value)

Returns the set of keys under which value is stored.

Parameters:

value - a value that might be stored in this table.

Returns:

the set of keys under which value is stored.

size

public int size()

Returns the number of entries in this table.

Returns:

the number of entries in this table.

toMap

public SortedMap<K,V> toMap()

Returns this table in the form of a sorted map. The keys and values of the map are references to the keys and values of this table.

Returns:

a sorted map expression of this lookup table.

toString

public String toString()

Returns a text representation of this table. The form of the returned text is

 
   (key1.toString, value1.toString)
   ...
   (keyN.toString, valueN.toString)

Overrides:

toString in class Object

Returns:

a text representation of this table.

clone

public LookupTable<K,V> clone()

Returns a shallow copy of this lookup table. The returned table is distinct from this one, but shares the actual instances of the keys and values with this table.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this table. See AbstractMap.equals(Object) for a description on how the comparison is performed.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this table. See AbstractMap.hashCode() for a description on how the comparison is performed.

Overrides:

hashCode in class Object