#include <search.h> int hcreate(size_t nel); ENTRY *hsearch(ENTRY item, ACTION action); void hdestroy(void); #define _GNU_SOURCE
#include <search.h> int hcreate_r(size_t nel, struct hsearch_data *tab); int hsearch_r(ENTRY item, ACTION action, ENTRY **ret, struct hsearch_data *tab); void hdestroy_r(struct hsearch_data *tab);
La table doit d'abord être créée avec la fonction hcreate(). nel est une estimation du nombre maximum d'éléments dans la table. La fonction hcreate() peut décider d'augmenter cette valeur, afin d'améliorer les performances de la table de hachage.
La fonction hdestroy() libère la mémoire occupée par la table, afin de pouvoir en construire une nouvelle.
L'argument item est du type ENTRY, qui est définie dans <search.h> ainsi :
typedef struct entry { char *key; void *data; } ENTRY;
Le champ key pointe sur une chaîne de caractères ASCII terminée par un octet nul. Cette chaîne est la clé de recherche. Le champ data pointe sur les données associées à cette clé. La fonction hsearch() recherche dans la table un élément associé à la même clé que item (comparées avec strcmp(3)), et si elle réussit, elle renvoie un pointeur sur cet élément. Le paramètre action détermine ce que fera hsearch() si la recherche est infructueuse. Si action vaut ENTER, hsearch() insérera une copie de item. Si action vaut FIND, elle renverra NULL.
Les fonctions hcreate_r(), hsearch_r() et hdestroy_r() sont des versions réentrantes qui permettent d'utiliser plusieurs tables. Le dernier argument utilisé identifie la table. La structure sur laquelle il pointe doit être mise à zéro avant le premier appel à hcreate_r().
hsearch() renvoie NULL si l'action est ENTER et si la table est pleine ou si l'action est FIND et si l'item n'est pas trouvé dans la table.
hsearch_r() renvoie zéro si action est ENTER et si la table de hachage est pleine et une valeur non nulle dans le cas contraire.
L'implémentation glibc renvoie les deux erreurs suivantes :
Les entrées ne peuvent être qu'ajoutées dans la table, on ne peut pas les supprimer individuellement.
Le programme suivant insère 24 éléments dans une table de hachage, puis affiche quelques uns d'entre-eux.
#include <stdio.h> #include <stdlib.h> #include <search.h> char *data[]= { "alpha", "bravo", "charlie", "delta", "echo", "foxtrot", "golf", "hotel", "india", "juliet", "kilo", "lima", "mike", "november", "oscar", "papa", "quebec", "romeo", "sierra", "tango", "uniform", "victor", "whisky", "x-ray", "yankee" "zoulou" }; int main(void) { ENTRY e, *ep; int i; /* On commence avec une petite table, qu'on agrandit ensuite */ hcreate(30); for (i = 0; i < 24; i++) { e.key = data[i]; /* Les données sont de simples entiers, pas des pointeurs */ e.data = (void *) i; ep = hsearch(e, ENTER); /* Il ne devrait pas y avoir d'échec */ if (ep == NULL) { fprintf(stderr, "Échec\n"); exit(EXIT_FAILURE); } } for (i = 22; i < 26; i++) { /* Afficher 2 entrées, et vérifier que 2 autres sont absentes */ e.key = data[i]; ep = hsearch(e, FIND); printf("%9.9s -> %9.9s:%d\n", e.key, ep ? ep->key : "NULL", ep ? (int)(ep->data) : 0); } exit(EXIT_SUCCESS); }
Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 4 novembre 1996 et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 hsearch ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.
Dernière mise à jour : 17 juillet 2008