12.15 data.trie - Trie

Module: data.trie

This module provides Trie, a dictionary-like data
structure that maps keys to values, where a key is an arbitrary sequence.
Internally it stores the data as a tree where each node corresponds
to each element in the key sequence.
Key lookup is O(n) where n is the length of the key, and not affected
much by the number of total entries.
Also it is easy to find a set of values whose keys have a common prefix.

Tries are frequently used with string keys, but you are not
limited to do so; any sequence (see Sequence framework) can be
a key. If the types of keys differ, they are treated as different
keys:

(trie-put! t '(#\p #\h #\o) 8) ;; different key from "pho"

Trie inherits <collection> and implements collection framework
including the builder. So you can apply generic collection
operations on a trie (see Collection framework).
When iterated, each element of a trie appears as a pair of a key
and a value.

Class: <trie>

A class for Trie. No slots are intended for public.
Use the following procedures to operate on tries.

It is important that tab-put! must return an updated
table—by that, you can replace the table structure on the fly.
For example, you may design a table which uses assoc list when
the number of children are small, and then switches to a vector
(indexed by character code) once the number of children grows over
a certain threshold.

Function: trieparams kv …

Construct a trie with the initial contents
kv …, where each kv is a pair of a key and a value.
Params are a list of arguments
which will be given to make-trie to create the trie.
The following example creates a trie with two entries
and the default table procedures.

(trie '() '("foo" . a) '("bar" . b))

Function: trie-with-keysparams key …

A convenient version of trie when you only concern
the keys. Each value is the same as its key.
The following example creates a trie with two entries
and the default table procedures.

(trie-with-keys '() "foo" "bar")

Function: trie?obj

Returns #t if obj is a trie, or #f otherwise.

Function: trie-num-entriestrie

Returns the number of entries in trie.

Function: trie-exists?trie key

Returns #t if trie contains an entry with key,
or returns #f otherwise.

Removes an entry associated with key from trie.
If there’s no such entry, this procedure does nothing.

Function: trie->listtrie

Makes each entry in trie to a pair (key . value)
and returns a list of pairs of all entries. The order of entries
are undefined.

Function: trie-keystrie

Function: trie-valuestrie

Returns a list of all keys and values in trie, respectively.
The order of keys/values are undefined.

Function: trie->hash-tabletrie ht-type

Creates a hash table with type ht-type (see Hashtables,
about hash table types), and populates it with every key and value
pair in trie.

Function: trie-longest-matchtrie seq :optional fallback

Returns a pair of the key and its value, where the key is the
longest prefix of seq. If no such key is found, fallback
is returned if it is provided, or an error is thrown.

Do not confuse this with trie-common-prefix-* procedures below;
In this procedure, the key is the prefix of the given argument.
In trie-common-prefix-* procedures, the given argument is
the prefix of the keys.

Gathers all entries whose keys begin with prefix;
trie-common-prefix returns those entries in a list of
pairs (key . value); trie-common-prefix-keys returns
a list of keys; and trie-common-prefix-values returns a list
of values. The order of entries in a returned list is undefined.
If trie contains no entry whose key has prefix, an
empty list is returned.

Note that prefix matching doesn’t consider the type of sequence;
if trie has entries for "foo" and (#\f #\o #\o),
(trie-common-prefix trie "foo") will return both entries.

Function: trie-common-prefix-foldtrie prefix proc seed

For each entry whose key begins with prefix,
calls proc with three arguments, the entry’s key,
its value, and the current seed value. Seed is
used for the first seed value, and the value proc
returns is used for the seed value of the next call of proc.
The last returned value from proc is returned from
trie-common-prefix-fold.
The order of entries on which proc is called is undefined.
If trie contains no entry whose key has prefix,
proc is never called and seed is returned.

Function: trie-common-prefix-maptrie prefix proc

Function: trie-common-prefix-for-eachtrie prefix proc

These are to trie-common-prefix-fold as map and for-each
are to fold; trie-common-prefix-map calls
proc with key and value for matching entries and
gathers its result to a list; trie-common-prefix-for-each
also applies proc, but discards its results.

Function: trie-foldtrie proc seed

Function: trie-maptrie proc

Function: trie-for-eachtrie proc

These procedures are like their common-prefix versions, but
traverse entire trie instead.