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 the name for `in_word_set'
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:

     static int hash (char *str, int len);
     int in_word_set (char *str, 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 Implementation. The relevant key positions are specified via the `-k'
option when running `gperf', as detailed in the *Options* section
below. See Options.

   Two options, `-g' (assume you are compiling with GNU C and its
`inline' feature) and `-a' (assume ANSI C-style function prototypes),
alter the content of both the generated `hash' and `in_word_set'
routines.  However, function `in_word_set' may be modified more
extensively, in response to your option settings.  The options that
affect the `in_word_set' structure are:

    `-p'
          Have function `in_word_set' return a pointer rather than a
          boolean.

    `-t'
          Make use of the user-defined `struct'.

    `-S 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', `-S', and `-p' 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.