Apache
/
commons-collections
mirror of https://github.com/apache/commons-collections.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improved javadoc of Trie interface. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1371959 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2012-08-11 14:07:23 +00:00
parent 3254e85306
commit a5c9272431
1 changed files with 74 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
src/main/java/org/apache/commons/collections/Trie.java
View File

@ -44,8 +44,9 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* return 'L', because the XOR distance between D &amp; L is smaller * return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H. * than the XOR distance between D &amp; H.
* *
* @return The {@link Entry} whose key is closest in a bitwise XOR metric * @param key the key to use in the search
* to the provided key. * @return the {@link Entry} whose key is closest in a bitwise XOR metric
* to the provided key
*/ */
public Map.Entry<K, V> select(K key); public Map.Entry<K, V> select(K key);
@ -65,7 +66,8 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* return 'L', because the XOR distance between D &amp; L is smaller * return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H. * than the XOR distance between D &amp; H.
* *
* @return The key that is closest in a bitwise XOR metric to the provided key. * @param key the key to use in the search
* @return the key that is closest in a bitwise XOR metric to the provided key
*/ */
public K selectKey(K key); public K selectKey(K key);
@ -85,8 +87,9 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* return 'L', because the XOR distance between D &amp; L is smaller * return 'L', because the XOR distance between D &amp; L is smaller
* than the XOR distance between D &amp; H. * than the XOR distance between D &amp; H.
* *
* @return The value whose key is closest in a bitwise XOR metric * @param key the key to use in the search
* to the provided key. * @return the value whose key is closest in a bitwise XOR metric
* to the provided key
*/ */
public V selectValue(K key); public V selectValue(K key);
@ -96,90 +99,119 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* entry is found, the {@link Trie} will call select on that entry and continue * entry is found, the {@link Trie} will call select on that entry and continue
* calling select for each entry (traversing in order of XOR closeness, * calling select for each entry (traversing in order of XOR closeness,
* NOT lexicographically) until the cursor returns {@link Decision#EXIT}. * NOT lexicographically) until the cursor returns {@link Decision#EXIT}.
* * <p>
* <p>The cursor can return {@link Decision#CONTINUE} to continue traversing. * The cursor can return {@link Decision#CONTINUE} to continue traversing.
* * <p>
* <p>{@link Decision#REMOVE_AND_EXIT} is used to remove the current element * {@link Decision#REMOVE_AND_EXIT} is used to remove the current element
* and stop traversing. * and stop traversing.
* <p>
* Note: The {@link Decision#REMOVE} operation is not supported.
* *
* <p>Note: The {@link Decision#REMOVE} operation is not supported. * @param key the key to use in the search
* * @param cursor the cursor used throughout the search
* @return The entry the cursor returned {@link Decision#EXIT} on, or null * @return the entry the cursor returned {@link Decision#EXIT} on, or null
* if it continued till the end. * if it continued till the end
*/ */
public Map.Entry<K,V> select(K key, Cursor<? super K, ? super V> cursor); public Map.Entry<K,V> select(K key, Cursor<? super K, ? super V> cursor);
/** /**
* Traverses the {@link Trie} in lexicographical order. * Traverses the {@link Trie} in lexicographical order.
* {@link Cursor#select(java.util.Map.Entry)} will be called on each entry. * {@link Cursor#select(java.util.Map.Entry)} will be called on each entry.
* * <p>
* <p>The traversal will stop when the cursor returns {@link Decision#EXIT}, * The traversal will stop when the cursor returns {@link Decision#EXIT},
* {@link Decision#CONTINUE} is used to continue traversing and * {@link Decision#CONTINUE} is used to continue traversing and
* {@link Decision#REMOVE} is used to remove the element that was selected * {@link Decision#REMOVE} is used to remove the element that was selected
* and continue traversing. * and continue traversing.
* * <p>
* <p>{@link Decision#REMOVE_AND_EXIT} is used to remove the current element * {@link Decision#REMOVE_AND_EXIT} is used to remove the current element
* and stop traversing. * and stop traversing.
* *
* @return The entry the cursor returned {@link Decision#EXIT} on, or null * @param cursor the cursor used while traversing the {@link Trie}
* if it continued till the end. * @return the entry the cursor returned {@link Decision#EXIT} on, or null
* if it continued till the end
*/ */
public Map.Entry<K,V> traverse(Cursor<? super K, ? super V> cursor); public Map.Entry<K,V> traverse(Cursor<? super K, ? super V> cursor);
/** /**
* Returns a view of this {@link SortedTrie} of all elements that are prefixed * Returns a view of this {@link Trie} of all elements that are prefixed
* by the given key. * by the given key.
* * <p>
* <p>In a {@link SortedTrie} with fixed size keys, this is essentially a * In a {@link Trie} with fixed size keys, this is essentially a
* {@link #get(Object)} operation. * {@link #get(Object)} operation.
* * <p>
* <p>For example, if the {@link SortedTrie} contains 'Anna', 'Anael', * For example, if the {@link Trie} contains 'Anna', 'Anael',
* 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then * 'Analu', 'Andreas', 'Andrea', 'Andres', and 'Anatole', then
* a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'. * a lookup of 'And' would return 'Andreas', 'Andrea', and 'Andres'.
*
* @param key the key used in the search
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/ */
public SortedMap<K, V> getPrefixedBy(K key); public SortedMap<K, V> getPrefixedBy(K key);
/** /**
* Returns a view of this {@link SortedTrie} of all elements that are prefixed * Returns a view of this {@link Trie} of all elements that are prefixed
* by the length of the key. * by the length of the key.
* * <p>
* <p>{@link SortedTrie}s with fixed size keys will not support this operation * {@link Trie}s with fixed size keys will not support this operation
* (because all keys are the same length). * (because all keys are the same length).
* * <p>
* <p>For example, if the {@link SortedTrie} contains 'Anna', 'Anael', 'Analu', * For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for 'Andrey' * 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for 'Andrey'
* and a length of 4 would return 'Andreas', 'Andrea', and 'Andres'. * and a length of 4 would return 'Andreas', 'Andrea', and 'Andres'.
*
* @param key the key used in the search
* @param length the length of the prefix
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/ */
public SortedMap<K, V> getPrefixedBy(K key, int length); public SortedMap<K, V> getPrefixedBy(K key, int length);
/** /**
* Returns a view of this {@link SortedTrie} of all elements that are prefixed * Returns a view of this {@link Trie} of all elements that are prefixed
* by the key, starting at the given offset and for the given length. * by the key, starting at the given offset and for the given length.
* * <p>
* <p>{@link SortedTrie}s with fixed size keys will not support this operation * {@link Trie}s with fixed size keys will not support this operation
* (because all keys are the same length). * (because all keys are the same length).
* * <p>
* <p>For example, if the {@link SortedTrie} contains 'Anna', 'Anael', 'Analu', * For example, if the {@link Trie} contains 'Anna', 'Anael', 'Analu',
* 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for * 'Andreas', 'Andrea', 'Andres', and 'Anatole', then a lookup for
* 'Hello Andrey Smith', an offset of 6 and a length of 4 would return * 'Hello Andrey Smith', an offset of 6 and a length of 4 would return
* 'Andreas', 'Andrea', and 'Andres'. * 'Andreas', 'Andrea', and 'Andres'.
*
* @param key the key used in the search
* @param offset the prefix start
* @param length the length of the prefix
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/ */
public SortedMap<K, V> getPrefixedBy(K key, int offset, int length); public SortedMap<K, V> getPrefixedBy(K key, int offset, int length);
/** /**
* Returns a view of this {@link SortedTrie} of all elements that are prefixed * Returns a view of this {@link Trie} of all elements that are prefixed
* by the number of bits in the given Key. * by the number of bits in the given Key.
* * <p>
* <p>In {@link SortedTrie}s with fixed size keys like IP addresses this method * In {@link Trie}s with fixed size keys like IP addresses this method
* can be used to lookup partial keys. That is you can lookup all addresses * can be used to lookup partial keys. That is you can lookup all addresses
* that begin with '192.168' by providing the key '192.168.X.X' and a * that begin with '192.168' by providing the key '192.168.X.X' and a
* length of 16. * length of 16.
*
* @param key the key to use in the search
* @param lengthInBits the number of significant key bits
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/ */
public SortedMap<K, V> getPrefixedByBits(K key, int lengthInBits); public SortedMap<K, V> getPrefixedByBits(K key, int lengthInBits);
/** /**
* Returns a view of this {@link SortedTrie} of all elements that are prefixed * Returns a view of this {@link Trie} of all elements that are prefixed
* by the number of bits in the given Key. * by the number of bits in the given Key.
*
* @param key the key to use in the search
* @param offsetInBits the prefix offset
* @param lengthInBits the number of significant prefix bits
* @return a {@link SortedMap} view of this {@link Trie} with all elements whose
* key is prefixed by the search key
*/ */
public SortedMap<K, V> getPrefixedByBits(K key, int offsetInBits, int lengthInBits); public SortedMap<K, V> getPrefixedByBits(K key, int offsetInBits, int lengthInBits);
@ -230,8 +262,11 @@ public interface Trie<K, V> extends SortedMap<K, V> {
* {@link Decision#REMOVE} to remove the {@link Entry} and * {@link Decision#REMOVE} to remove the {@link Entry} and
* continue iterating or {@link Decision#REMOVE_AND_EXIT} to * continue iterating or {@link Decision#REMOVE_AND_EXIT} to
* remove the {@link Entry} and stop iterating. * remove the {@link Entry} and stop iterating.
* * <p>
* Note: Not all operations support {@link Decision#REMOVE}. * Note: Not all operations support {@link Decision#REMOVE}.
*
* @param entry the current entry
* @return the {@link Decision} based on the current entry
*/ */
public Decision select(Map.Entry<? extends K, ? extends V> entry); public Decision select(Map.Entry<? extends K, ? extends V> entry);
} }