Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

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_DUPLICATESAllow 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 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), AG_List(3), AG_Tree(3)

HISTORY

The AG_Tbl interface first appeared in Agar 1.4