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

FreeBSD Manual Pages

  
 
  

home | help 
AG_TBL(3)		     Library Functions Manual		       AG_TBL(3)

NAME
     AG_Tbl -- agar variable hash table structure

SYNOPSIS
     #include <agar/core/tbl.h>

DESCRIPTION
     The  AG_Tbl  structure  describes a hash table consisting of AG_Variable(3)
     elements.	It is defined as follows:

     typedef struct ag_tbl_bucket {
	     AG_Variable  *ents;
	     Uint	  nEnts;
     } AG_TblBucket;

     typedef struct ag_tbl {
	     AG_TblBucket *buckets;
	     Uint	  nBuckets;
     } AG_Tbl;

GENERAL INTERFACE
     AG_Tbl * AG_TblNew(Uint nBuckets, Uint flags)

     void AG_TblInit(AG_Tbl *tbl, Uint nBuckets, Uint flags)

     void AG_TblDestroy(AG_Tbl *tbl)

     AG_Variable * AG_TblLookup(AG_Tbl *tbl, const char *key)

     int AG_TblLookupPointer(AG_Tbl *tbl, const char *key, void **p)

     int AG_TblExists(AG_Tbl *tbl, const char *key)

     int AG_TblInsert(AG_Tbl *tbl, const char *key, const AG_Variable *V)

     int AG_TblInsertPointer(AG_Tbl *tbl, const char *key, void *p)

     int AG_TblDelete(AG_Tbl *tbl, const char *key)

     AG_TBL_FOREACH(AG_Variable *V, int i, int j, AG_Tbl *tbl)

     The AG_TblNew() function allocates and initializes  a  new,  empty  AG_Tbl.
     AG_TblInit()  initializes an existing table structure.  The following flags
     options are accepted:

     AG_TBL_DUPLICATES	 Allow duplicate keys in the database.	Insert calls for
			 duplicate keys will if this option is not set.

     AG_TblDestroy() frees the resources allocated by a table (the table  struc-
     ture itself is not freed).

     AG_TblLookup()  searches  the  table for an entry of the given name and re-
     turns a pointer to it.  On failure, it returns NULL.

     AG_TblExists() returns 1 if there is a table entry matching the giving key.

     AG_TblInsert() inserts an entry in the table, using the specified key.  The
     contents of the variable are duplicated.  On failure, the function  returns
     -1 and sets an error message.

     AG_TblDelete()  removes  the specified table entry by name.  If there is no
     match, it returns -1 and sets an error message.

     The AG_TBL_FOREACH() macro iterates V over every entry of table tbl,  using
     variables i and j as iterators.  Example usage:

     AG_Tbl *tbl;
     AG_Variable *V;
     int i, j;
     AG_TBL_FOREACH(V, i,j, tbl) {
	     printf("Item: %s\n", V->name);
     }

PRECOMPUTED HASHES
     The  following access functions accept a hash argument.  They are useful in
     cases where it is inefficient to reevaluate the  hash  function  repeatedly
     (e.g., a lookup followed by an insert).

     Uint AG_TblHash(AG_Tbl *tbl, const char *key)

     AG_Variable * AG_TblLookupHash(AG_Tbl *tbl, Uint hash, const char *key)

     int AG_TblExistsHash(AG_Tbl *tbl, Uint hash, const char *key)

     int  AG_TblInsertHash(AG_Tbl  *tbl,  Uint	hash,  const  char  *key,  const
     AG_Variable *V)

     int AG_TblDeleteHash(AG_Tbl *tbl, Uint hash, const char *key)

     AG_TblHash() computes and returns the hash for the specified key.

     AG_TblLookupHash(),     AG_TblExistsHash(),     AG_TblInsertHash()      and
     AG_TblDeleteHash()   are	variants   of	AG_TblLookup(),  AG_TblExists(),
     AG_TblInsert(), and AG_TblDelete() with an additional hash argument.

SEE ALSO
     AG_Intro(3), AG_Variable(3)

HISTORY
     The AG_Tbl interface first appeared in Agar 1.4.0.

Agar 1.7			December 21, 2022		       AG_TBL(3)

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

home | help