1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
132 .TH tst 3 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
134 tst \- ternary search trie functions
136 .IX Header "SYNOPSIS"
137 \&\fB#include <inn/tst.h>\fR
141 \&\fBstruct tst *tst_init(int \fR\fInode_line_width\fR\fB);\fR
143 \&\fBvoid tst_cleanup(struct tst *\fR\fItst\fR\fB);\fR
145 \&\fBint tst_insert(struct tst *\fR\fItst\fR\fB, const unsigned char *\fR\fIkey\fR\fB, void *\fR\fIdata\fR\fB, int \fR\fIoption\fR\fB, void **\fR\fIexist_ptr\fR\fB);\fR
147 \&\fBvoid *tst_search(struct tst *\fR\fItst\fR\fB, const unsigned char *\fR\fIkey\fR\fB);\fR
149 \&\fBvoid *tst_delete(struct tst *\fR\fItst\fR\fB, const unsigned char *\fR\fIkey\fR\fB);\fR
151 .IX Header "DESCRIPTION"
152 \&\fBtst_init\fR allocates memory for members of \fIstruct tst\fR, and
153 allocates the first \fInode_line_width\fR nodes. A \s-1NULL\s0 pointer is
154 returned by \fBtst_init\fR if any part of the memory allocation fails. On
155 success, a pointer to a \fIstruct tst\fR is returned.
157 The value for \fInode_line_width\fR must be chosen very carefully. One
158 node is required for every character in the tree. If you choose a
159 value that is too small, your application will spend too much time
160 calling \fImalloc\fR\|(3) and your node space will be too spread out. Too large
161 a value is just a waste of space.
163 \&\fBtst_cleanup\fR frees all memory allocated to nodes, internal structures,
164 as well as \fItst\fR itself.
166 \&\fBtst_insert\fR inserts the string \fIkey\fR into the tree. Behavior when a
167 duplicate key is inserted is controlled by \fIoption\fR. If \fIkey\fR is
168 already in the tree then \fB\s-1TST_DUPLICATE_KEY\s0\fR is returned, and the
169 data pointer for the existing key is placed in \fIexist_ptr\fR. If
170 \&\fIoption\fR is set to \fB\s-1TST_REPLACE\s0\fR then the existing data pointer for
171 the existing key is replaced by \fIdata\fR. Note that the old data
172 pointer will still be placed in \fIexist_ptr\fR.
174 If a duplicate key is encountered and \fIoption\fR is not set to
175 \&\fB\s-1TST_REPLACE\s0\fR then \fB\s-1TST_DUPLICATE_KEY\s0\fR is returned. If \fIkey\fR is
176 zero length then \fB\s-1TST_NULL_KEY\s0\fR is returned. A successful insert or
177 replace returns \fB\s-1TST_OK\s0\fR. A return value of \fB\s-1TST_ERROR\s0\fR indicates
178 that a memory allocation error occurred while trying to grow the node
181 Note that the \fIdata\fR argument must never be \fB\s-1NULL\s0\fR. If it is, then
182 calls to \fBtst_search\fR will fail for a key that exists because the
183 data value was set to \fB\s-1NULL\s0\fR, which is what \fBtst_search\fR returns. If
184 you just want a simple existence tree, use the \fBtst\fR pointer as the
187 \&\fBtst_search\fR finds the string \fIkey\fR in the tree if it exists and
188 returns the data pointer associated with that key.
190 If \fIkey\fR is not found then \fB\s-1NULL\s0\fR is returned, otherwise the data pointer
191 associated with \fIkey\fR is returned.
193 \&\fBtst_delete\fR deletes the string \fIkey\fR from the tree if it exists and
194 returns the data pointer assocaited with that key.
196 If \fIkey\fR is not found then \fB\s-1NULL\s0\fR is returned, otherwise the data
197 pointer associated with \fIkey\fR is returned.
200 Converted to \s-1POD\s0 from Peter A. Friend's ternary search trie
201 documentation by Alex Kiernan <alex.kiernan@thus.net> for InterNetNews
204 $Id: tst.3 7880 2008-06-16 20:37:13Z iulius $