doc/pod/tst.pod

   1 =head1 NAME
   2
   3 tst - ternary search trie functions
   4
   5 =head1 SYNOPSIS
   6
   7 B<#include E<lt>inn/tst.hE<gt>>
   8
   9 B<struct tst;>
  10
  11 B<struct tst *tst_init(int >I<node_line_width>B<);>
  12
  13 B<void tst_cleanup(struct tst *>I<tst>B<);>
  14
  15 B<int tst_insert(struct tst *>I<tst>B<, const unsigned char *>I<key>B<, void *>I<data>B<, int >I<option>B<, void **>I<exist_ptr>B<);>
  16
  17 B<void *tst_search(struct tst *>I<tst>B<, const unsigned char *>I<key>B<);>
  18
  19 B<void *tst_delete(struct tst *>I<tst>B<, const unsigned char *>I<key>B<);>
  20
  21 =head1 DESCRIPTION
  22
  23 B<tst_init> allocates memory for members of I<struct tst>, and
  24 allocates the first I<node_line_width> nodes. A NULL pointer is
  25 returned by B<tst_init> if any part of the memory allocation fails. On
  26 success, a pointer to a I<struct tst> is returned.
  27
  28 The value for I<node_line_width> must be chosen very carefully. One
  29 node is required for every character in the tree. If you choose a
  30 value that is too small, your application will spend too much time
  31 calling malloc(3) and your node space will be too spread out. Too large
  32 a value is just a waste of space.
  33
  34 B<tst_cleanup> frees all memory allocated to nodes, internal structures,
  35 as well as I<tst> itself.
  36
  37 B<tst_insert> inserts the string I<key> into the tree. Behavior when a
  38 duplicate key is inserted is controlled by I<option>. If I<key> is
  39 already in the tree then B<TST_DUPLICATE_KEY> is returned, and the
  40 data pointer for the existing key is placed in I<exist_ptr>.  If
  41 I<option> is set to B<TST_REPLACE> then the existing data pointer for
  42 the existing key is replaced by I<data>.  Note that the old data
  43 pointer will still be placed in I<exist_ptr>.
  44
  45 If a duplicate key is encountered and I<option> is not set to
  46 B<TST_REPLACE> then B<TST_DUPLICATE_KEY> is returned. If I<key> is
  47 zero length then B<TST_NULL_KEY> is returned. A successful insert or
  48 replace returns B<TST_OK>. A return value of B<TST_ERROR> indicates
  49 that a memory allocation error occurred while trying to grow the node
  50 free.
  51
  52 Note that the I<data> argument must never be B<NULL>. If it is, then
  53 calls to B<tst_search> will fail for a key that exists because the
  54 data value was set to B<NULL>, which is what B<tst_search> returns. If
  55 you just want a simple existence tree, use the B<tst> pointer as the
  56 data pointer.
  57
  58 B<tst_search> finds the string I<key> in the tree if it exists and
  59 returns the data pointer associated with that key.
  60
  61 If I<key> is not found then B<NULL> is returned, otherwise the data pointer
  62 associated with I<key> is returned.
  63
  64 B<tst_delete> deletes the string I<key> from the tree if it exists and
  65 returns the data pointer assocaited with that key.
  66
  67 If I<key> is not found then B<NULL> is returned, otherwise the data
  68 pointer associated with I<key> is returned.
  69
  70 =head1 HISTORY
  71
  72 Converted to POD from Peter A. Friend's ternary search trie
  73 documentation by Alex Kiernan <alex.kiernan@thus.net> for InterNetNews
  74 2.4.0.
  75
  76 $Id: tst.pod 6104 2003-01-02 09:16:09Z alexk $