/**
 * @file trie.h
 * @author Joe Wingbermuehle
 * @date 2007-07-02
 */

#ifndef TRIE_H
#define TRIE_H

/** Pointer to trie data. */
typedef void *Trie;

/** Function pointer used for enumerating possible trie matches.
 * @param match The matched character.
 * @param data The data at the matched location.
 * @param arg User-supplied argument.
 */
typedef void (*TrieEnumerator)(char match, void *data, void *arg);

/** Create an empty trie.
 * @return An empty trie.
 */
Trie *CreateTrie();

/** Destroy a trie.
 * @param trie The trie to destroy.
 */
void DestroyTrie(Trie *trie);

/** Insert an item to a trie.
 * Note that if there is already data in the trie at the specified
 * location it will be returned and replaced.
 * @param trie The trie.
 * @param str The key.
 * @param data The data to insert.
 * @return The data currently in the trie.
 */
void *InsertTrie(Trie *trie, const char *str, void *data);

/** Remove an item from a trie.
 * @param trie The trie.
 * @param str The key.
 * @return The data removed.
 */
void *RemoveTrie(Trie *trie, const char *str);

/** Find an item in a trie.
 * @param trie The trie.
 * @param str The key.
 * @return The item.
 */
void *FindTrie(const Trie *trie, const char *str);

/** Enumerate possible trie matches.
 * @param trie The trie.
 * @param str The base string.
 * @param func A function to call on each possible match (can be NULL).
 * @param arg An argument to pass func.
 * @return The number of enumerated items.
 */
int EnumerateTrie(const Trie *trie, const char *str,
   TrieEnumerator func, void *arg);

#endif /* TRIE_H */