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
       structure itself	is not freed).

       AG_TblLookup() searches the table for an	entry of the  given  name  and
       returns 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  re-
       peatedly	(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+14.3.quarterly>

home | help