improved javadoc

This commit is contained in:
Greg Wilkins 2014-11-05 17:53:46 +11:00
parent c9c6ec8d63
commit d1ead3dcd6
3 changed files with 89 additions and 17 deletions

View File

@ -25,7 +25,8 @@ import java.util.Set;
/* ------------------------------------------------------------ */ /* ------------------------------------------------------------ */
/** A Ternary Trie String lookup data structure. /**
* <p>A Ternary Trie String lookup data structure.</p>
* This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache). * This Trie is of a fixed size and cannot grow (which can be a good thing with regards to DOS when used as a cache).
* <p> * <p>
* The Trie is stored in 3 arrays:<dl> * The Trie is stored in 3 arrays:<dl>
@ -36,10 +37,21 @@ import java.util.Set;
* indicates that the _tree row is a complete key rather than an intermediate character of a longer key.</dd> * indicates that the _tree row is a complete key rather than an intermediate character of a longer key.</dd>
* <dt>V[] _value</dt><dd>An array of values corresponding to the _key array</dd> * <dt>V[] _value</dt><dd>An array of values corresponding to the _key array</dd>
* </dl> * </dl>
* </p>
* <p>The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed, * <p>The lookup of a value will iterate through the _tree array matching characters. If the equal tree branch is followed,
* then the _key array is looked up to see if this is a complete match. If a match is found then the _value array is looked up * then the _key array is looked up to see if this is a complete match. If a match is found then the _value array is looked up
* to return the matching value. * to return the matching value.
* </p> * </p>
* <p>
* This Trie may be instantiated either as case sensitive or insensitive.
* </p>
* <p>This Trie is not Threadsafe and contains no mutual exclusion
* or deliberate memory barriers. It is intended for an ArrayTrie to be
* built by a single thread and then used concurrently by multiple threads
* and not mutated during that access. If concurrent mutations of the
* Trie is required external locks need to be applied.
* </p>
*
* @param <V> * @param <V>
*/ */
public class ArrayTernaryTrie<V> extends AbstractTrie<V> public class ArrayTernaryTrie<V> extends AbstractTrie<V>
@ -78,27 +90,53 @@ public class ArrayTernaryTrie<V> extends AbstractTrie<V>
*/ */
private char _rows; private char _rows;
/* ------------------------------------------------------------ */
/** Create a case insensitive Trie of default capacity.
*/
public ArrayTernaryTrie() public ArrayTernaryTrie()
{ {
this(128); this(128);
} }
/* ------------------------------------------------------------ */
/** Create a Trie of default capacity
* @param insensitive true if the Trie is insensitive to the case of the key.
*/
public ArrayTernaryTrie(boolean insensitive) public ArrayTernaryTrie(boolean insensitive)
{ {
this(insensitive,128); this(insensitive,128);
} }
public ArrayTernaryTrie(int capacityInNodes) /* ------------------------------------------------------------ */
/** Create a case insensitive Trie
* @param capacity The capacity of the Trie, which is in the worst case
* is the total number of characters of all keys stored in the Trie.
* The capacity needed is dependent of the shared prefixes of the keys.
* For example, a capacity of 6 nodes is required to store keys "foo"
* and "bar", but a capacity of only 4 is required to
* store "bar" and "bat".
*/
public ArrayTernaryTrie(int capacity)
{ {
this(true,capacityInNodes); this(true,capacity);
} }
public ArrayTernaryTrie(boolean insensitive, int capacityInNodes) /* ------------------------------------------------------------ */
/** Create a Trie
* @param insensitive true if the Trie is insensitive to the case of the key.
* @param capacity The capacity of the Trie, which is in the worst case
* is the total number of characters of all keys stored in the Trie.
* The capacity needed is dependent of the shared prefixes of the keys.
* For example, a capacity of 6 nodes is required to store keys "foo"
* and "bar", but a capacity of only 4 is required to
* store "bar" and "bat".
*/
public ArrayTernaryTrie(boolean insensitive, int capacity)
{ {
super(insensitive); super(insensitive);
_value=(V[])new Object[capacityInNodes]; _value=(V[])new Object[capacity];
_tree=new char[capacityInNodes*ROW_SIZE]; _tree=new char[capacity*ROW_SIZE];
_key=new String[capacityInNodes]; _key=new String[capacity];
} }
/* ------------------------------------------------------------ */ /* ------------------------------------------------------------ */

View File

@ -24,9 +24,25 @@ import java.util.HashSet;
import java.util.Set; import java.util.Set;
/* ------------------------------------------------------------ */ /* ------------------------------------------------------------ */
/** A Trie String lookup data structure using a fixed size array. /**
* <p>A Trie String lookup data structure using a fixed size array.</p>
* <p>This implementation is always case insensitive and is optimal for * <p>This implementation is always case insensitive and is optimal for
* a small number of fixed strings with few special characters. * a small number of fixed strings with few special characters. The
* Trie is stored in an array of lookup tables, each indexed by the
* next character of the key. Frequently used characters are directly
* indexed in each lookup table, whilst infrequently used characters
* must use a big character table.
* </p>
* <p>This Trie is very space efficient if the key characters are
* from ' ', '+', '-', ':', ';', '.', 'A' to 'Z' or 'a' to 'z'.
* Other ISO-8859-1 characters can be used by the key, but less space
* efficiently.
* </p>
* <p>This Trie is not Threadsafe and contains no mutual exclusion
* or deliberate memory barriers. It is intended for an ArrayTrie to be
* built by a single thread and then used concurrently by multiple threads
* and not mutated during that access. If concurrent mutations of the
* Trie is required external locks need to be applied.
* </p> * </p>
* @param <V> * @param <V>
*/ */
@ -47,8 +63,8 @@ public class ArrayTrie<V> extends AbstractTrie<V>
private static final int[] __lookup = private static final int[] __lookup =
{ // 0 1 2 3 4 5 6 7 8 9 A B C D E F { // 0 1 2 3 4 5 6 7 8 9 A B C D E F
/*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, /*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
/*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 30, /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
/*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1, /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, 30, -1,
/*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1, /*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1,
/*4*/-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, /*4*/-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
/*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1, /*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1,
@ -99,13 +115,22 @@ public class ArrayTrie<V> extends AbstractTrie<V>
this(128); this(128);
} }
/* ------------------------------------------------------------ */
/**
* @param capacity The capacity of the trie, which at the worst case
* is the total number of characters of all keys stored in the Trie.
* The capacity needed is dependent of the shared prefixes of the keys.
* For example, a capacity of 6 nodes is required to store keys "foo"
* and "bar", but a capacity of only 4 is required to
* store "bar" and "bat".
*/
@SuppressWarnings("unchecked") @SuppressWarnings("unchecked")
public ArrayTrie(int capacityInNodes) public ArrayTrie(int capacity)
{ {
super(true); super(true);
_value=(V[])new Object[capacityInNodes]; _value=(V[])new Object[capacity];
_rowIndex=new char[capacityInNodes*32]; _rowIndex=new char[capacity*32];
_key=new String[capacityInNodes]; _key=new String[capacity];
} }

View File

@ -31,6 +31,15 @@ import java.util.Set;
* <p>This implementation is always case insensitive and is optimal for * <p>This implementation is always case insensitive and is optimal for
* a variable number of fixed strings with few special characters. * a variable number of fixed strings with few special characters.
* </p> * </p>
* <p>This Trie is stored in a Tree and is unlimited in capacity</p>
*
* <p>This Trie is not Threadsafe and contains no mutual exclusion
* or deliberate memory barriers. It is intended for an ArrayTrie to be
* built by a single thread and then used concurrently by multiple threads
* and not mutated during that access. If concurrent mutations of the
* Trie is required external locks need to be applied.
* </p>
*
* @param <V> * @param <V>
*/ */
public class TreeTrie<V> extends AbstractTrie<V> public class TreeTrie<V> extends AbstractTrie<V>
@ -38,8 +47,8 @@ public class TreeTrie<V> extends AbstractTrie<V>
private static final int[] __lookup = private static final int[] __lookup =
{ // 0 1 2 3 4 5 6 7 8 9 A B C D E F { // 0 1 2 3 4 5 6 7 8 9 A B C D E F
/*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, /*0*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
/*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 30, /*1*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
/*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, -1, -1, /*2*/31, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 26, -1, 27, 30, -1,
/*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1, /*3*/-1, -1, -1, -1, -1, -1, -1, -1, -1, -1, 28, 29, -1, -1, -1, -1,
/*4*/-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, /*4*/-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
/*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1, /*5*/15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, -1, -1, -1, -1, -1,