Ternary Search Tree.

A ternary search tree is a hybrid between a binary tree and a digital search
tree (trie). Keys are limited to strings. A data value of type char is stored
in each leaf node. It can be used as an index (or pointer) to the data.
Branches that only contain one key are compressed to one node by storing a
pointer to the trailer substring of the key. This class is intended to serve
as base class or helper class to implement Dictionary collections or the
like. Ternary trees have some nice properties as the following: the tree can
be traversed in sorted order, partial matches (wildcard) can be implemented,
retrieval of all keys within a given distance from the target, etc. The
storage requirements are higher than a binary tree but a lot less than a
trie. Performance is comparable with a hash table, sometimes it outperforms a
hash function (most of the time can determine a miss faster than a hash).

The main purpose of this java port is to serve as a base for implementing
TeX's hyphenation algorithm (see The TeXBook, appendix H). Each language
requires from 5000 to 15000 hyphenation patterns which will be keys in this
tree. The strings patterns are usually small (from 2 to 5 characters), but
each char in the tree is stored in a node. Thus memory usage is the main
concern. We will sacrifice 'elegance' to keep memory requirements to the
minimum. Using java's char type as pointer (yes, I know pointer it is a
forbidden word in java) we can keep the size of the node to be just 8 bytes
(3 pointers and the data char). This gives room for about 65000 nodes. In my
tests the english patterns took 7694 nodes and the german patterns 10055
nodes, so I think we are safe.

All said, this is a map with strings as keys and char as value. Pretty
limited!. It can be extended to a general map by using the string
representation of an object and using the char value as an index to an array
that contains the object values.

This class has been taken from the Apache FOP project (http://xmlgraphics.apache.org/fop/). They have been slightly modified.

length

BLOCK_SIZE

Method Detail

init

insert

Branches are initially compressed, needing one node per key plus the size
of the string key. They are decompressed as needed when another key with
same prefix is inserted. This saves a lot of space, specially for long
keys.

knows

size

clone

insertBalanced

Recursively insert the median first and then the median of the lower and
upper halves, and so on in order to get a balanced tree. The array of keys
is assumed to be sorted in ascending order.

balance

public void balance()

Balance the tree for best search performance

trimToSize

public void trimToSize()

Each node stores a character (splitchar) which is part of some key(s). In a
compressed branch (one that only contain a single string key) the trailer
of the key which is not already in nodes is stored externally in the kv
array. As items are inserted, key substrings decrease. Some substrings may
completely disappear when the whole branch is totally decompressed. The
tree is traversed to find the key substrings actually used. In addition,
duplicate substrings are removed using a map (implemented with a
TernaryTree!).