1
2The \eslmod{keyhash} module provides a semblance of associative arrays
3(for example, Perl hashes), by associating keywords with an integer
4array index, and storing the association in an internal hash table for
5rapid access.
6
7Table~\ref{tbl:keyhash_api} lists the functions in the
8\eslmod{keyhash} API. The module implements one object: the
9\ccode{ESL\_KEYHASH}.
10
11% Table generated by autodoc -t esl_keyhash.c (so don't edit here, edit esl_keyhash.c:)
12\begin{table}[hbp]
13\begin{center}
14{\small
15\begin{tabular}{|ll|}\hline
16\apisubhead{The \ccode{ESL\_KEYHASH} object}\\
17\hyperlink{func:esl_keyhash_Create()}{\ccode{esl\_keyhash\_Create()}} & Allocates a new keyhash.\\
18\hyperlink{func:esl_keyhash_Clone()}{\ccode{esl\_keyhash\_Clone()}} & Duplicates a keyhash.\\
19\hyperlink{func:esl_keyhash_Get()}{\ccode{esl\_keyhash\_Get()}} & Returns a key name, given its index.\\
20\hyperlink{func:esl_keyhash_GetNumber()}{\ccode{esl\_keyhash\_GetNumber()}} & Returns the total number of keys stored.\\
21\hyperlink{func:esl_keyhash_Reuse()}{\ccode{esl\_keyhash\_Reuse()}} & Reuse a keyhash.\\
22\hyperlink{func:esl_keyhash_Destroy()}{\ccode{esl\_keyhash\_Destroy()}} & Frees a keyhash.\\
23\hyperlink{func:esl_keyhash_Dump()}{\ccode{esl\_keyhash\_Dump()}} & Dumps debugging information about a keyhash.\\
24\apisubhead{Storing and retrieving keys }\\
25\hyperlink{func:esl_keyhash_Store()}{\ccode{esl\_key\_Store()}} & Store a key and get a key index for it.\\
26\hyperlink{func:esl_keyhash_Lookup()}{\ccode{esl\_key\_Lookup()}} & Look up a key's array index.\\
27\hline
28\end{tabular}
29}
30\end{center}
31\caption{The \eslmod{keyhash} API.}
32\label{tbl:keyhash_api}
33\end{table}
34
35\subsection{Example of using the keyhash API}
36
37The idea behind using the keyhash module is shown in this fragment of
38pseudocode:
39
40\begin{cchunk}
41       #include "easel.h"
42       #include "esl_keyhash.h"
43
44       ESL_KEYHASH *kh = esl_keyhash_Create();
45       int          idx;
46       char        *key;
47       esl_pos_t    keylen;
48
49       /* To store keys: */
50       (foreach key) {
51          esl_keyhash_Store(hash, key, keylen, &idx);
52          (reallocate foo, bar as needed)
53          foo[idx] = whatever;
54          bar[idx] = whatever;
55       }
56       /* To look up keys: */
57       (foreach key) {
58          if (esl_keyhash_Lookup(hash, key, keylen, &idx) != eslOK) { no_such_key; }
59          (do something with) foo[idx];
60          (do something with) bar[idx];
61       }
62       esl_keyhash_Destroy();
63\end{cchunk}
64
65That is, the application maintains data in normal C-style arrays that
66are indexed by an integer index value, and it uses the keyhash to
67associate a specific key with that integer index. To store info, you
68first store the keyword and obtain a new index value (this simply
69starts at 0 and counts up, as you store successive keys), then you
70store the info your arrays at that index. To look up info, you look up
71the keyword to obtain the index, then you access the info by indexing
72into your arrays.
73
74This is the moral equivalent of Perl's associative arrays, as in
75\ccode{\$foo\{\$key\} = whatever; \$bar\{\$key\} = whatever}.
76
77For example, Figure~\ref{fig:keyhash_example} is a contrived example
78of storing the keywords obtained from a list in one file, then looking
79up keywords listed in a second file. It doesn't demonstrate the idea
80of using the index to store and retrieve additional info associated
81with the keyword, but it demonstrates the essentials of the
82\eslmod{keyhash} API.
83
84\begin{figure}
85\input{cexcerpts/keyhash_example}
86\caption{Example of using the \eslmod{keyhash} API.}
87\label{fig:keyhash_example}
88\end{figure}
89
90