

We are going to store some tuples into our table, that will map each {\itshape name} to a {\itshape number}. The cost to access a given number from the name should be very small, even with many entries in our table. This is the initial data\+: 
\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keyword}{struct }\_Phone\_Entry \{}
\DoxyCodeLine{     \textcolor{keyword}{const} \textcolor{keywordtype}{char} *name; \textcolor{comment}{// Full name.}}
\DoxyCodeLine{     \textcolor{keyword}{const} \textcolor{keywordtype}{char} *number; \textcolor{comment}{// Phone number.}}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{typedef} \textcolor{keyword}{struct }\_Phone\_Entry Phone\_Entry;}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{static} Phone\_Entry \_start\_entries[] = \{}
\DoxyCodeLine{       \{ \textcolor{stringliteral}{"Wolfgang Amadeus Mozart"}, \textcolor{stringliteral}{"+01 23 456-\/78910"} \},}
\DoxyCodeLine{       \{ \textcolor{stringliteral}{"Ludwig van Beethoven"}, \textcolor{stringliteral}{"+12 34 567-\/89101"} \},}
\DoxyCodeLine{       \{ \textcolor{stringliteral}{"Richard Georg Strauss"}, \textcolor{stringliteral}{"+23 45 678-\/91012"} \},}
\DoxyCodeLine{       \{ \textcolor{stringliteral}{"Heitor Villa-\/Lobos"}, \textcolor{stringliteral}{"+34 56 789-\/10123"} \},}
\DoxyCodeLine{       \{ NULL, NULL \}}
\DoxyCodeLine{\}; \textcolor{comment}{// \_start\_entries}}

\end{DoxyCodeInclude}


Before starting to play with the hash, let\textquotesingle{}s write a callback that will be used to free the elements from it. Since we are just storing strduped strings, we just need to free them\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keyword}{static} \textcolor{keywordtype}{void}}
\DoxyCodeLine{\_phone\_entry\_free\_cb(\textcolor{keywordtype}{void} *data)}
\DoxyCodeLine{\{}
\DoxyCodeLine{   free(data);}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}


We also need a callback to iterate over the elements of the list later, so we are defining it now\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{\textcolor{keyword}{static} \mbox{\hyperlink{group__Eina__Types__Group_ga3fe0caf72e93b1bab1ca8ee3ccf3f226}{Eina\_Bool}}}
\DoxyCodeLine{\_phone\_book\_foreach\_cb(\textcolor{keyword}{const} \mbox{\hyperlink{group__Eina__Hash__Group_ga9a89d7d3ee260d3a60572ebf651b07e0}{Eina\_Hash}} *phone\_book \mbox{\hyperlink{group__Eina__Types__Group_ga82d751be730f849719ca292f9558be87}{EINA\_UNUSED}}, \textcolor{keyword}{const} \textcolor{keywordtype}{void} *key,}
\DoxyCodeLine{                       \textcolor{keywordtype}{void} *data, \textcolor{keywordtype}{void} *fdata \mbox{\hyperlink{group__Eina__Types__Group_ga82d751be730f849719ca292f9558be87}{EINA\_UNUSED}})}
\DoxyCodeLine{\{}
\DoxyCodeLine{   \textcolor{keyword}{const} \textcolor{keywordtype}{char} *name = key;}
\DoxyCodeLine{   \textcolor{keyword}{const} \textcolor{keywordtype}{char} *number = data;}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"\%s: \%s\(\backslash\)n"}, name, number);}
\DoxyCodeLine{}
\DoxyCodeLine{   \textcolor{comment}{// Return EINA\_FALSE to stop this callback from being called}}
\DoxyCodeLine{   \textcolor{keywordflow}{return} \mbox{\hyperlink{group__Eina__Types__Group_ga05c12dacc8b4058994df842b41be85fc}{EINA\_TRUE}};}
\DoxyCodeLine{\}}

\end{DoxyCodeInclude}


Now let\textquotesingle{}s create our \mbox{\hyperlink{group__Eina__Hash__Group_ga9a89d7d3ee260d3a60572ebf651b07e0}{Eina\+\_\+\+Hash}} using \mbox{\hyperlink{group__Eina__Hash__Group_gad7203e20b1496445cb819c7862171c87}{eina\+\_\+hash\+\_\+string\+\_\+superfast\+\_\+new}} \+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Main__Group_gafee4bfc0e509b6ffed6598edf6f4b3de}{eina\_init}}();}
\DoxyCodeLine{}
\DoxyCodeLine{   phone\_book = \mbox{\hyperlink{group__Eina__Hash__Group_gad7203e20b1496445cb819c7862171c87}{eina\_hash\_string\_superfast\_new}}(\_phone\_entry\_free\_cb);}

\end{DoxyCodeInclude}


Now we add the keys and data to the hash using \mbox{\hyperlink{group__Eina__Hash__Group_gafe3bb7c1f5616b4e158f60322e133260}{eina\+\_\+hash\+\_\+add}} . This means that the key is copied inside the table, together with the pointer to the data (phone numbers).


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \textcolor{keywordflow}{for} (i = 0; \_start\_entries[i].name != NULL; i++)}
\DoxyCodeLine{     \{}
\DoxyCodeLine{        \mbox{\hyperlink{group__Eina__Hash__Group_gafe3bb7c1f5616b4e158f60322e133260}{eina\_hash\_add}}(phone\_book, \_start\_entries[i].name,}
\DoxyCodeLine{                      strdup(\_start\_entries[i].number));}
\DoxyCodeLine{     \}}

\end{DoxyCodeInclude}


Some basic manipulations with the hash, like finding a value given a key, deleting an entry, modifying an entry are exemplified in the following lines. Notice that the \mbox{\hyperlink{group__Eina__Hash__Group_gaabf2f2af1d93f969591f2c5b7378c543}{eina\+\_\+hash\+\_\+modify}} function returns the old value stored in that entry, and it needs to be freed, while the \mbox{\hyperlink{group__Eina__Hash__Group_gad8a9ac3c61ead249a6927a12e9de871a}{eina\+\_\+hash\+\_\+del}} function already calls our free callback\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \textcolor{comment}{// Look for a specific entry and get its phone number}}
\DoxyCodeLine{   phone = \mbox{\hyperlink{group__Eina__Hash__Group_ga45703d00fbabffc86e6836ffe98a4c92}{eina\_hash\_find}}(phone\_book, entry\_name);}
\DoxyCodeLine{   \textcolor{keywordflow}{if} (phone)}
\DoxyCodeLine{     \{}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"Printing entry.\(\backslash\)n"});}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"Name: \%s\(\backslash\)n"}, entry\_name);}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"Number: \%s\(\backslash\)n\(\backslash\)n"}, phone);}
\DoxyCodeLine{     \}}
\DoxyCodeLine{}
\DoxyCodeLine{   \textcolor{comment}{// Delete this entry}}
\DoxyCodeLine{   r = \mbox{\hyperlink{group__Eina__Hash__Group_gad8a9ac3c61ead249a6927a12e9de871a}{eina\_hash\_del}}(phone\_book, entry\_name, NULL);}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"Hash entry successfully deleted? \%d\(\backslash\)n\(\backslash\)n"}, r);}
\DoxyCodeLine{}
\DoxyCodeLine{   \textcolor{comment}{// Modify the pointer data of an entry and free the old one}}
\DoxyCodeLine{   phone = \mbox{\hyperlink{group__Eina__Hash__Group_gaabf2f2af1d93f969591f2c5b7378c543}{eina\_hash\_modify}}(phone\_book, \textcolor{stringliteral}{"Richard Georg Strauss"},}
\DoxyCodeLine{                            strdup(\textcolor{stringliteral}{"+23 45 111-\/11111"}));}
\DoxyCodeLine{   free(phone);}

\end{DoxyCodeInclude}


The \mbox{\hyperlink{group__Eina__Hash__Group_ga53fd5f171289d63c5d8532bb28434cb3}{eina\+\_\+hash\+\_\+set}} function can be used to set a key-\/value entry to the table if it doesn\textquotesingle{}t exist, or to modify an existent entry. It returns the old entry if it was already set, and N\+U\+LL otherwise. But since it will return N\+U\+LL on error too, we need to check if an error has occurred\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \textcolor{comment}{// Modify or add an entry to the hash with eina\_hash\_set}}
\DoxyCodeLine{   \textcolor{comment}{// Let's first add a new entry}}
\DoxyCodeLine{   phone = \mbox{\hyperlink{group__Eina__Hash__Group_ga53fd5f171289d63c5d8532bb28434cb3}{eina\_hash\_set}}(phone\_book, \textcolor{stringliteral}{"Raul Seixas"},}
\DoxyCodeLine{                         strdup(\textcolor{stringliteral}{"+55 01 234-\/56789"}));}
\DoxyCodeLine{   \textcolor{keywordflow}{if} (!phone)}
\DoxyCodeLine{     \{}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"No previous phone found for Raul Seixas. "});}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"Creating new entry.\(\backslash\)n"});}
\DoxyCodeLine{     \}}
\DoxyCodeLine{   \textcolor{keywordflow}{else}}
\DoxyCodeLine{     \{}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"Old phone for Raul Seixas was \%s\(\backslash\)n"}, phone);}
\DoxyCodeLine{        free(phone);}
\DoxyCodeLine{     \}}
\DoxyCodeLine{}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"\(\backslash\)n"});}

\end{DoxyCodeInclude}


There are different ways of iterate over the entries of a hash. Here we show two of them\+: using \mbox{\hyperlink{group__Eina__Hash__Group_ga2c23f8425d3afcc61827ab67b46d7190}{eina\+\_\+hash\+\_\+foreach}} and \mbox{\hyperlink{group__Eina__Iterator__Group_ga15b975bb881d955249ce13d4ebc96948}{Eina\+\_\+\+Iterator}}.


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"List of phones:\(\backslash\)n"});}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Hash__Group_ga2c23f8425d3afcc61827ab67b46d7190}{eina\_hash\_foreach}}(phone\_book, \_phone\_book\_foreach\_cb, NULL);}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"\(\backslash\)n"});}
\DoxyCodeLine{}
\DoxyCodeLine{   \textcolor{comment}{// Now iterate using an iterator}}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"List of phones:\(\backslash\)n"});}
\DoxyCodeLine{   it = \mbox{\hyperlink{group__Eina__Hash__Group_gaf0e7e38ec02c4bcfca3c3c4dd13c6af9}{eina\_hash\_iterator\_tuple\_new}}(phone\_book);}
\DoxyCodeLine{   \textcolor{keywordflow}{while} (\mbox{\hyperlink{group__Eina__Iterator__Group_ga83346e93c32dbebc8fd66e4f278140c5}{eina\_iterator\_next}}(it, \&data))}
\DoxyCodeLine{     \{}
\DoxyCodeLine{        \mbox{\hyperlink{struct__Eina__Hash__Tuple}{Eina\_Hash\_Tuple}} *t = data;}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} *name = t-\/>key;}
\DoxyCodeLine{        \textcolor{keyword}{const} \textcolor{keywordtype}{char} *number = t-\/>data;}
\DoxyCodeLine{        printf(\textcolor{stringliteral}{"\%s: \%s\(\backslash\)n"}, name, number);}
\DoxyCodeLine{     \}}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Iterator__Group_gaf9261991a4b05dc63e3401278a3281f8}{eina\_iterator\_free}}(it); \textcolor{comment}{// Always free the iterator after its use}}

\end{DoxyCodeInclude}


It\textquotesingle{}s also possible to change the key for a specific entry, without having to remove the entry from the table and adding it again\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Hash__Group_gaa390160f31c235d91947281244e77628}{eina\_hash\_move}}(phone\_book, \textcolor{stringliteral}{"Raul Seixas"}, \textcolor{stringliteral}{"Alceu Valenca"});}

\end{DoxyCodeInclude}


We can remove all the elements from the table without free the table itself\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \textcolor{comment}{// Empty the phone book, but don't destroy it}}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Hash__Group_gabe2ba51e5dbf6fd5f60628b8e8f00eaa}{eina\_hash\_free\_buckets}}(phone\_book);}
\DoxyCodeLine{   printf(\textcolor{stringliteral}{"There are \%d items in the hash.\(\backslash\)n\(\backslash\)n"},}
\DoxyCodeLine{          \mbox{\hyperlink{group__Eina__Hash__Group_ga9289542f6724083eab306e5bb3ab10b0}{eina\_hash\_population}}(phone\_book));}

\end{DoxyCodeInclude}


Or free the the entire table with its content\+:


\begin{DoxyCodeInclude}{0}
\DoxyCodeLine{   \mbox{\hyperlink{group__Eina__Hash__Group_gadb6acb720ce267cc1cd4f51893539f59}{eina\_hash\_free}}(phone\_book);}

\end{DoxyCodeInclude}


The full code for this example can be seen here\+: \mbox{\hyperlink{eina_hash_01_c}{Hash table in action}} 