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.
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 ↑
HISTORY ↑
The
AG_Tbl interface first appeared in
Agar 1.4.0.