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.