www.delorie.com/gnu/docs/gperf/gperf_12.html

search

	Buy GNU books!

Perfect Hash Function Generator

3.2 Output Format for Generated C Code with gperf

Several options control how the generated C code appears on the standard output. Two C function are generated. They are called hash and in_word_set, although you may modify their names with a command-line option. Both functions require two arguments, a string, char * str, and a length parameter, int len. Their default function prototypes are as follows:

Function: unsigned int hash (const char * str, unsigned int len)

By default, the generated hash function returns an integer value created by adding len to several user-specified str key positions indexed into an associated values table stored in a local static array. The associated values table is constructed internally by gperf and later output as a static local C array called `hash_table'; its meaning and properties are described below (see section 7. Implementation Details of GNU gperf). The relevant key positions are specified via the `-k' option when running gperf, as detailed in the Options section below(see section 4. Invoking gperf).

Function: in_word_set (const char * str, unsigned int len)

If str is in the keyword set, returns a pointer to that keyword. More exactly, if the option `-t' was given, it returns a pointer to the matching keyword's structure. Otherwise it returns NULL.

If the option `-c' is not used, str must be a NUL terminated string of exactly length len. If `-c' is used, str must simply be an array of len characters and does not need to be NUL terminated.

The code generated for these two functions is affected by the following options:

`-t'

`--struct-type'

Make use of the user-defined struct.

`-S total-switch-statements'

`--switch=total-switch-statements'

Generate 1 or more C switch statement rather than use a large, (and potentially sparse) static array. Although the exact time and space savings of this approach vary according to your C compiler's degree of optimization, this method often results in smaller and faster code.

If the `-t' and `-S' options are omitted, the default action is to generate a char * array containing the keys, together with additional null strings used for padding the array. By experimenting with the various input and output options, and timing the resulting C code, you can determine the best option choices for different keyword set characteristics.