text: // Tbl.h: an abstract API for tables with string keys.
  //
  // Written by Tony Finch <dot@dotat.at>
  // You may do anything with this. It has no warranty.
  // <http://creativecommons.org/publicdomain/zero/1.0/>
  
  #ifndef Tbl_h
  #define Tbl_h
  
  // A table is represented by a pointer to this incomplete struct type.
  // You initialize an empty table by setting the pointer to NULL.
  //
  typedef struct Tbl Tbl;
  
  // Get the value associated with a key.
  // Returns NULL if the key is not in the Table.
  //
  void *Tgetl(Tbl *tbl, const char *key, size_t klen);
  void *Tget(Tbl *tbl, const char *key);
  
  // Returns false if the key is not found, otherwise returns true and
  // sets *rkey and *rval to the table's key and value pointers.
  //
  bool Tgetkv(Tbl *tbl, const char *key, size_t klen, const char **rkey, void **rval);
  
  // Associate a key with a value in a table. Returns a new pointer to
  // the modified table. If there is an error it sets errno and returns
  // NULL. To delete a key, set its value to NULL. When the last key is
  // deleted, Tset() returns NULL without setting errno. The key and
  // value are borrowed not copied.
  //
  // Errors:
  // EINVAL - value pointer is not word-aligned
  // ENOMEM - allocation failed
  //
  Tbl *Tsetl(Tbl *tbl, const char *key, size_t klen, void *value);
  Tbl *Tset(Tbl *tbl, const char *key, void *value);
  Tbl *Tdell(Tbl *tbl, const char *key, size_t klen);
  Tbl *Tdel(Tbl *tbl, const char *key);
  
  // Deletes an entry from the table as above, and sets *rkey and *rval
  // to the removed key and value pointers.
  //
  Tbl *Tdelkv(Tbl *tbl, const char *key, size_t klen, const char **rkey, void **rval);
  
  // Find the next item in the table. The p... arguments are in/out
  // parameters. To find the first key, pass *pkey=NULL and *pklen=0.
  // For subsequent keys, *pkey must be present in the table and is
  // updated to the lexicographically following key. Returns false or
  // NULL when there are no more keys.
  //
  bool Tnextl(Tbl *tbl, const char **pkey, size_t *pklen, void **pvalue);
  bool Tnext(Tbl *tbl, const char **pkey, void **pvalue);
  const char *Tnxt(Tbl *tbl, const char *key);
  
  // Debugging
  //
  void Tdump(Tbl *tbl);
  void Tsize(Tbl *tbl, const char **rtype,
      size_t *rsize, size_t *rdepth, size_t *rbranches, size_t *rleaves);
  
  #endif // Tbl_h
  