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