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 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.