HTDB : Docs : Developer's Guide : Functions : Accessors
About
Overview
Philosophy
Features
News
Download
Help Us!

Docs
Overview
Designers
Developers
Functions
Accessors
Database
CGIs
Applications
Roadmap
Architecture

Community
Powered By

[home]
Data Accessors

  • except for the binary data type, all key/value pairs are stored as strings. so even though you may think that you are storing numbers sometimes, you are actually storing string representations of numbers. say it out loud: "everything is a string".
  • the *set*() functions store copies - silently over-writing old values if they exist.
  • the *get*() functions return empty strings (not NULL pointers) if a value is not found at key. this means that you never need to check for NULL pointers before further using values returned.
  • the *get*() functions return pointers to malloc()d data. never directly free() these values, as that would cause corruption of the in-memory storage.
  • unless otherwise specified, all functions are re-entrant.

The following is a description of the various methods by which the programmer may move calculated (and other) values in and out of the in-memory storage.


String object accessors

Used to access and manipulate objects which have been stored according to the string convention.
Array object accessors
Used to access and manipulate objects which have been stored according to the array convention.
Pointer object accessors
Used to access and manipulate objects which have been stored according to the pointer convention.
HTDB object accessors
Used to access and manipulate objects which have been stored according to the HTDB object convention.
Helper functions
These lower-level functions are used internally by the String, Array, Pointer and HTDB objects and may be useful by the programmer directly.

String object accessors Used to access and manipulate objects which have been stored according to the string convention.

In the string convention, object keys (names) are of the form:

key
Keep in mind that all other object types actually use the String object storage methods internally. All objects' keys are simple strings; it is only the naming convention for the keys which determine the class of storage and the functions which may be used to manipulate those storage classes.


int htdb_setint(char *key, int val)
used to store an integer value in the object named key. returns the value stored. note that the internal storage primative for HTDB objects is actually strings, so what is stored here is a strings representation of an integer, not an interger value.
I

input  printf("%d\n", htdb_setint("tmpval", "4"));
output  4

II

input  printf("setting 'tmpval' to '3'\n");
  htdb_setint("tmpval", 3);
  printf("equal to 1? ");
  if (htdb_getint("tmpval") == 1)
   printf("FALSE\n");
  printf("equal to 3? ");
  if (htdb_getint("tmpval") == 3)
   printf("TRUE\n");
output  setting 'tmpval' to '3'
  equal to 1? FALSE
  equal to 3? TRUE

int htdb_getint(char *key)
used to retrieve an integer value in the object named key. returns the value stored, or zero.
I

input  htdb_setint("tmpval", "4");
 printf("%d\n", htdb_getint("tmpval"));
output  4

II

input  printf("%d\n", htdb_getint("aValuesWhichDoesNotExist"));
output  0

char * htdb_setval(char *key, char *val)
used to store a copy of a string in the object named key. returns the value stored.
I

input  printf("%s\n", htdb_setval("tmpval", "hello world"));
output  hello world

II

input  htdb_setval("tmpval", "hello world");
output  
notes result is simply shoved into in-memory storage

char * htdb_setvarg(char *key, char *fmt, ...)
a variable-argument version of htdb_setval.
I

input  printf("%s\n", htdb_setvarg("tmpval", "the answer is %d, dude", 3));
output  the answer is 3, dude

char * htdb_getval(char *key)
used to retrieve a string stored in the object named key. returns the value stored, or an empty string. htdb_getval() is probably the most-used function of the CGI programmer.
I

input  htdb_setval("tmpval", "hello world");
 printf("%s\n", htdb_getval("tmpval"));
output  hello world

II

input  printf("%s\n", htdb_getval("anObjectWhichDoesNotExist"));
output  

void * htdb_setbin(char *key, void *val, off_t size)
shoves binary into storage at key. returns a pointer to the stored value. the data is not copied - it is stored as-is. being a void * type, it is the programmer's responsibility to deal with the "real" type of the data stored.

void * htdb_getbin(char *key)
used to retrieve binary data stored at key. being a void * type, it is the programmer's responsibility to deal with the "real" type of the data stored.

int htdb_checkval(char *key)
used to determine whether an object exists (has size). returns the size, or zero if the object does not exist. effectively, this is a strlen() on a looked-up value. naturally only works on strings. to determine the size of binary stored data, use htdb_size().

int htdb_size(char *key)
returns the number of bytes in an object. returns zero if the object does not exist. uses an internal structure value to determine object size, so can be used to determine number of bytes in binary data.
I

input  htdb_setval("tmpval", "hello world");
 printf("%d\n", htdb_size("tmpval"));
output  11

II

input  htdb_setval("tmpval", "3.14");
 printf("%d\n", htdb_size("tmpval"));
output  4

III

input  printf("%d\n", htdb_size("anObjectWhichDoesNotExist"));
output  0

IV

input  htdb_setint("tmpval", "666");
 printf("%d\n", htdb_size("tmpval"));
output  3
notes note that even though the stored value was an integer, it was actually stored as a string, so the size of the object is the number of bytes used to hold the value.

int htdb_getnum(char *key)
synonym for htdb_getint()

char * htdb_defined(char *key)
synonym for htdb_getval(()

int htdb_equal(char *key, char *value)
used to determine whether the looked-up value of key is equal to value. is case insensitive in the comparison. returns 0 if either the key or the value is empty or if they are not equal, else returns 1. this function is simply shorthand for (strcasecmp(htdb_getval(key), value) == 0) this function is most often used to determine the correct "state" to be in when programming CGIs.
I

input  htdb_setval("tmpval", "hello");
 if (htdb_equal("tmpval", "world"))
  printf("WORLD");
 else if (htdb_equal("tmpval", "hello"))
  printf("HELLO");
output  HELLO

II

input  if (htdb_equal("cgi->request_method", "GET"))
  printf("access method was GET");
 else if (htdb_equal("cgi->request_method", "POST"))
  printf("access method was POST");
 else
  printf("access method was UNKNOWN");
output  
notes the behavior of this code snippet will depend upon the context in which the web page was called.


Array object accessors Used to access and manipulate objects which have been stored according to the array convention.

In the array convention, object keys (names) are of the form:

key[index]
Note that all objects are actually built on top of the native String object type.


char * htdb_setarrayval(char *key, int index, char *fmt, ...)
stores the variable-arguments format string value into the object named key[index]. returns a pointer to the stored string.

char * htdb_getarrayval(char *key, int index)
fetches the string stored at the object named key[index], or an empty string if no such object exists.

int htdb_setarrayint(char *key, int index, int value)
stores the string representation of an integer, value, at the object named key[index]. returns the stored string evaluated as an integer.

int htdb_getarrayint(char *key, int index)
fetches the integer stored at the object named key[index], or 0 if no such object exists.


Pointer object accessors Used to access and manipulate objects which have been stored according to the pointer convention.

In the pointer convention, object keys (names) are of the form:

key->field
Note that all objects are actually built on top of the native String object type.


char * htdb_getptrval(char *key, char *field)
fetches the string at the object named key->field, or an empty string if no such object exists.

int htdb_getptrint(char *key, char *field)
fetches the integer at the object named key->field, or 0 if no such object exists.

char * htdb_setptrval(char *key, char *field, char *value)
stores a copy of the string value at the object named key->field. returns a pointer to the stored string.

int htdb_setptrint(char *key, char *field, int value)
stores the string representation of an integer, value, at the object named key->field. returns the stored string evaluated as an integer.


HTDB object accessors Used to access and manipulate objects which have been stored according to the HTDB object convention.

In the HTDB object convention, object keys (names) are of the form:

key[index]->field
Note that all objects are actually built on top of the native String object type. I guess you perl perverts would call these things arrays of hashes.


char * htdb_getobjval(char *key, int index, char *field)
fetches the string at the object named key[index]->field, or an empty string if no such object exists.

int htdb_getobjint(char *key, int index, char *field)
fetches the integer at the object named key[index]->field, or 0 if no such object exists.

char * htdb_setobjvarg(char *key, int index, char *field, char *fmt, ...)
stores the variable-arguments format string value into the object named key[index]->field. returns a pointer to the stored string.

char * htdb_setobjval(char *key, int index, char *field, char *value)
stores value into the object named key[index]->field. returns a pointer to the stored string.

int htdb_setobjint(char *key, int index, char *field, int value)
stores the string representaion of the integer value into the object named key[index]->field. returns an integer of the value stored.


Helper functions These lower-level functions are used internally by the String, Array, Pointer and HTDB objects and may be useful by the programmer directly.

The general purpose of the functions in this section is to derive object names in a standard format. There are versions which return static memory, and re-entrant versions which return dynamic memory.


char * htdb_getarrayname(char *key, int index)

char * htdb_getobjdyname(char *key, int index, char *field)

char * htdb_getobjname(char *key, int index, char *field)

char * htdb_getptrdyname(char *key, char *field)


still to classify...
char * htdb_cond(char *to, char *from)

void htdb_loop(char *to, char *from)

void htdb_append(char *to, char *from)

void htdb_appendvarg(char *to, char *fmt, ...)

int htdb_callable(Bucket b, char *key, int *arg_length, int output_to)

void thing_append(Bucket b, char *expanded, int length, int growby)

void thing_appendChar(Bucket b, char expanded, int growby)

char * htdb_expand(char *str)

   
6,569 impressions