net.sf.eBus.util

Class TernarySearchTree<V>

java.lang.Object

net.sf.eBus.util.TernarySearchTree<V>

Type Parameters:

V - Value type.

All Implemented Interfaces:

Serializable, Map<CharSequence,V>

public final class TernarySearchTree<V>
extends Object
implements Map<CharSequence,V>, Serializable

Ternary search tree (TST)-based implementation of the Map interface. This implementation provides all optional interface methods, allows null values but restricts keys to non-null java.lang.CharSequence objects.

It must be pointed out that this implementation of entrySet(), keySet() and values() does not return sets backed by the map. Changes to the map are not reflected in the returned set nor are changes to the returned set reflected in the map.

Note: this implementation is not synchronized. If multiple threads currently access this map and at least one thread modifies the map by adding or removing an entry, then this map must be externally synchronized. External synchronization is accomplished in two ways:

1. Placing the map inside a synchronized block:

          
            synchronized (tstMap)
            {
                tstMap.put("abcd", obj);
            }
          
        

2. Constructing a TernarySearchTree within a java.util.Collections.synchronizedMap():

          
            Map m =
                Collections.synchronizedMap(
                    new TernarySearchTree(...));
          
        

For more information on ternary search trees, see Bentley, J., and Sedgewick, R. Fast algorithms for sorting and searching strings. In Eighth Annual ACM-SIAM Symposium on Discrete Algorithms (1997), SIAM Press.

Author:

Charles Rapp

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
TernarySearchTree() Constructs an empty ternary search tree map.
TernarySearchTree(Map<? extends CharSequence,? extends V> m) Construct a new TernarySearchTree with the same mappings as the specified Map.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears out all stored values, leaving an empty map.
boolean	containsKey(Object key) Returns true if the key is in the ternary search tree and false otherwise.
boolean	containsValue(Object value) Returns true if value is stored in the ternary search tree and false otherwise.
Set<Map.Entry<CharSequence,V>>	entrySet() Returns the set of all key-value mappings.
Set<Map.Entry<CharSequence,V>>	entrySet(Pattern query) Returns the set of all key-value mappings whose keys match the given query.
Set<Map.Entry<CharSequence,V>>	entrySet(Pattern query, int maxMatches) Returns the set of at most maxMatches key-value mappings whose keys match the given query.
V	get(Object key) Returns the value associated with key.
boolean	isEmpty() Returns true if this map contains no key-value mappings and false otherwise.
Set<CharSequence>	keySet() Returns all keys currently stored in the tree.
Set<CharSequence>	keySet(Pattern query) Returns the words matching the query.
Set<CharSequence>	keySet(Pattern query, int maxMatches) Returns at most maxMatches words matching the query.
Collection<CharSequence>	nearSearch(CharSequence s, int distance) Returns the keys which are within a specified Hamming distance of character sequence s.
long	nodeCount() Returns the number of nodes used in this map.
V	put(CharSequence key, V value) Enters a value into the ternary search tree using the text key.
void	putAll(Map<? extends CharSequence,? extends V> map) Copies all the mappings from the specified map to this tree.
V	remove(Object key) Removes the key-value mapping from the tree and returns the now removed value.
int	size() Returns the number of key-value mappings in this tree.
Collection<V>	values() Returns a collection of all the trees values.
Collection<V>	values(Pattern query) Returns a non-null collection of all trees values with keys matching the given pattern.
Collection<V>	values(Pattern query, int maxMatches) Returns a collection of at most maxMatches values whose keys match the given pattern.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

TernarySearchTree

public TernarySearchTree()

Constructs an empty ternary search tree map.

TernarySearchTree

public TernarySearchTree(Map<? extends CharSequence,? extends V> m)

Construct a new TernarySearchTree with the same mappings as the specified Map.

Parameters:

m - Copies mappings from here.

Method Detail

isEmpty

public boolean isEmpty()

Returns true if this map contains no key-value mappings and false otherwise.

Specified by:

isEmpty in interface Map<CharSequence,V>

Returns:

true if this map contains no key-value mappings and false otherwise.

size

public int size()

Returns the number of key-value mappings in this tree.

Specified by:

size in interface Map<CharSequence,V>

Returns:

the number of key-value mappings in this tree.

nodeCount

public long nodeCount()

Returns the number of nodes used in this map.

Returns:

the number of nodes used in this map.

clear

public void clear()

Clears out all stored values, leaving an empty map.

Specified by:

clear in interface Map<CharSequence,V>

containsKey

public boolean containsKey(Object key)

Returns true if the key is in the ternary search tree and false otherwise.

Specified by:

containsKey in interface Map<CharSequence,V>

Parameters:

key - Search for this key in the tree.

Returns:

true if the key is in the ternary search tree and false otherwise.

containsValue

public boolean containsValue(Object value)

Returns true if value is stored in the ternary search tree and false otherwise.

Specified by:

containsValue in interface Map<CharSequence,V>

Parameters:

value - Searches for this value.

Returns:

true if value is stored in the ternary search tree and false otherwise.

get

public V get(Object key)

Returns the value associated with key. If the ternary search tree does not contain the key, then returns null.

Specified by:

get in interface Map<CharSequence,V>

Parameters:

key - Search for this key.

Returns:

the value associated with key. If the ternary search tree does not contain the key, then returns null.

put

public V put(CharSequence key,
             V value)

Enters a value into the ternary search tree using the text key. If the key is already in the tree, then replaces the existing value with the new value and returns the replaced value. If the key is not in the tree, then null is returned.

Specified by:

put in interface Map<CharSequence,V>

Parameters:

key - The text key.

value - The key's associated value.

Returns:

the previous value stored under key. May return null.

putAll

public void putAll(Map<? extends CharSequence,? extends V> map)

Copies all the mappings from the specified map to this tree. This method does nothing more than iterate over the specified map, calling put(CharSequence, Object) successively.

Specified by:

putAll in interface Map<CharSequence,V>

Parameters:

map - The copied map.

remove

public V remove(Object key)

Removes the key-value mapping from the tree and returns the now removed value.

Specified by:

remove in interface Map<CharSequence,V>

Parameters:

key - Remove the mapping at this key.

Returns:

the removed value or null if key is not in the tree.

keySet

public Set<CharSequence> keySet()

Returns all keys currently stored in the tree. If the tree is empty, then an empty set is returned. This set is not backed by the tree. Changes to the returned set are not reflected in the tree and changes to the tree are not reflected in the set.

Specified by:

keySet in interface Map<CharSequence,V>

Returns:

all keys currently stored in the tree.

keySet

public Set<CharSequence> keySet(Pattern query)

Returns the words matching the query. This set is not backed by the tree. Changes to the returned set are not reflected in the tree and changes to the tree are not reflected in the set.

Parameters:

query - Match against this query.

Returns:

the words matching the query.

keySet

public Set<CharSequence> keySet(Pattern query,
                                int maxMatches)
                         throws IllegalArgumentException,
                                IllegalStateException

Returns at most maxMatches words matching the query. This set is not backed by the tree. Changes to the returned set are not reflected in the tree and changes to the tree are not reflected in the set.

Parameters:

query - Match against this query.

maxMatches - Match at most this many keys.

Returns:

the words matching the query.

Throws:

IllegalArgumentException - if maxMatches is <= zero.

IllegalStateException - if maxMatches is exceeded.

values

public Collection<V> values()

Returns a collection of all the trees values. This collection is not backed by the tree. Changes to the returned collection are not reflected in the tree and changes to the tree are not reflected in the collection.

Specified by:

values in interface Map<CharSequence,V>

Returns:

a collection of all the trees values.

values

public Collection<V> values(Pattern query)

Returns a non-null collection of all trees values with keys matching the given pattern. This collection is not backed by the tree. Changes to the returned collection are not reflected in the tree and changes to the tree are not reflected in the collection.

Parameters:

query - match against this query.

Returns:

a collection of all the trees values matching query.

values

public Collection<V> values(Pattern query,
                            int maxMatches)
                     throws IllegalArgumentException,
                            IllegalStateException

Returns a collection of at most maxMatches values whose keys match the given pattern. This collection is not backed by the tree. Changes to the returned collection are not reflected in the tree and changes to the tree are not reflected in the collection.

Parameters:

query - Match against this query.

maxMatches - Match at most this many keys.

Returns:

a collection of matching keys' values.

Throws:

IllegalArgumentException - if maxMatches is <= zero.

IllegalStateException - if maxMatches is exceeded.

entrySet

public Set<Map.Entry<CharSequence,V>> entrySet()

Returns the set of all key-value mappings. If this tree is empty, then an empty set is returned. The returned set is not backed by the tree. Changes to the returned set or to this tree are not reflected in the other.

Specified by:

entrySet in interface Map<CharSequence,V>

Returns:

the set of all key-value mappings.

entrySet

public Set<Map.Entry<CharSequence,V>> entrySet(Pattern query)

Returns the set of all key-value mappings whose keys match the given query. If this tree is empty, then an empty set is returned. The returned set is not backed by the tree. Changes to the returned set or to this tree are not reflected in the other.

Parameters:

query - Match against this query.

Returns:

the set of all key-value mappings.

entrySet

public Set<Map.Entry<CharSequence,V>> entrySet(Pattern query,
                                               int maxMatches)

Returns the set of at most maxMatches key-value mappings whose keys match the given query. If this tree is empty, then an empty set is returned. The returned set is not backed by the tree. Changes to the returned set or to this tree are not reflected in the other.

Parameters:

query - Match against this query.

maxMatches - Match at most this many keys.

Returns:

the set of at most maxMatches key-value mappings. Throws IllegalArgumentException if maxMatches is <= zero.

nearSearch

public Collection<CharSequence> nearSearch(CharSequence s,
                                           int distance)

Returns the keys which are within a specified Hamming distance of character sequence s. The Hamming distance between two strings of equal length is the number of positions at which corresponding characters are different. One string may be transformed into the other by changing the characters at these positions to the other strings values. The Hamming distance may be thought of as the number of errors in one string.

If this ternary search tree contains a dictionary, then this method may be used to find possible correct spellings for a misspelled word.

Parameters:

s - find the keys within the specified Hamming distance to this character sequence.

distance - the desired Hamming distance.

Returns:

the keys which are within a specified Hamming distance of character sequence s. If no such keys are found, then returns an empty collection.