Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
libinn_tst(3)		  InterNetNews Documentation		 libinn_tst(3)

NAME
       tst - Ternary search trie functions

SYNOPSIS
	   #include <inn/tst.h>

	   enum	tst_constants {
	       TST_OK,
	       TST_NULL_KEY,
	       TST_NULL_DATA,
	       TST_DUPLICATE_KEY,
	       TST_REPLACE
	   };

	   struct tst;

	   struct tst *tst_init(int node_line_width);

	   void	tst_cleanup(struct tst *tst);

	   int tst_insert(struct tst *tst, const unsigned char *key,
			  void *data, int option, void **exist_ptr);

	   void	*tst_search(struct tst *tst, const unsigned char *key);

	   void	*tst_delete(struct tst *tst, const unsigned char *key);

DESCRIPTION
       tst_init	allocates memory for members of	struct tst, and	allocates the
       first node_line_width nodes.  A NULL pointer is returned	by tst_init if
       any part	of the memory allocation fails.	 On success, a pointer to a
       struct tst is returned.

       The value for node_line_width must be chosen very carefully.  One node
       is required for every character in the tree.  If	you choose a value
       that is too small, your application will	spend too much time calling
       malloc(3) and your node space will be too spread	out.  Too large	a
       value is	just a waste of	space.

       tst_cleanup frees all memory allocated to nodes,	internal structures,
       as well as tst itself.

       tst_insert inserts the string key into the tree.	 Behavior when a
       duplicate key is	inserted is controlled by option.  If key is already
       in the tree, then "TST_DUPLICATE_KEY" is	returned, and the data pointer
       for the existing	key is placed in exist_ptr.  If	option is set to
       "TST_REPLACE", then the existing	data pointer for the existing key is
       replaced	by data.  Note that the	old data pointer will still be placed
       in exist_ptr.

       If a duplicate key is encountered and option is not set to
       "TST_REPLACE", then "TST_DUPLICATE_KEY" is returned.  If	key is zero
       length, then "TST_NULL_KEY" is returned.	 A successful insert or
       replace returns "TST_OK".  A return value of "TST_ERROR"	indicates that
       a memory	allocation error occurred while	trying to grow the node	free.

       Note that the data argument must	never be "NULL".  If it	is, then calls
       to tst_search will fail for a key that exists because the data value
       was set to "NULL", which	is what	tst_search returns.  If	you just want
       a simple	existence tree,	use the	tst pointer as the data	pointer.

       tst_search finds	the string key in the tree if it exists	and returns
       the data	pointer	associated with	that key.

       If key is not found then	"NULL" is returned, otherwise the data pointer
       associated with key is returned.

       tst_delete deletes the string key from the tree if it exists and
       returns the data	pointer	associated with	that key.

       If key is not found, then "NULL"	is returned, otherwise the data
       pointer associated with key is returned.

HISTORY
       Converted to POD	from Peter A. Friend's ternary search trie
       documentation by	Alex Kiernan <alex.kiernan@thus.net> for
       InterNetNews 2.4.0.

SEE ALSO
       libinn(3).

INN 2.8.0			  2022-04-19			 libinn_tst(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=libinn_tst&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help