Provided by:
manpages-es_1.55-10_all 
NOMBRE
hcreate, hdestroy, hsearch - funciones para manejar una tabla dispersa
(hash)
SINOPSIS
#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);
DESCRIPCI'ON
Las tres funciones hcreate, hsearch, y hdestroy permiten al usuario
crear una tabla dispersa (solo una al mismo tiempo) que asocia una
clave con cualquier dato. Las tres funciones hcreate_r, hsearch_r,
hdestroy_r son versiones reentrantes que permiten el uso de mas de una
tabla.
En primer lugar, se debe crear la tabla con la funcion hcreate(). El
argumento nel es una estimacion del numero de entradas de la tabla. La
funcion hcreate() puede incrementar este valor para mejorar el
rendimiento de la tabla dispersa resultante.
La funcion correspondiente hdestroy() libera la memoria ocupada por la
tabla dispersa de tal forma que se pueda construir una nueva tabla.
El argumento item es del tipo ENTRY, que se define mediante typedef en
<search.h> e incluye estos elementos:
typedef struct entry {
char *key;
void *data;
} ENTRY;
El campo key apunta a una cadena terminada en NUL que es la clave de
busqueda. El campo data apunta a los datos asociados con esa clave.
La funcion hsearch() busca en la tabla dispersa un elemento con la
misma clave que item (donde "la misma" se determina usando strcmp(3)),
y si tiene exito devuelve un puntero al mismo. El argumento action
determina que debe hacer hsearch() tras una busqueda sin exito. El
valor ENTER le indica que debe insertar una copia de item, mientras que
un valor FIND significa que debe devolver NULL.
VALOR DEVUELTO
hcreate() y hcreate_r() devuelven 0 cuando falla la reserva de memoria
para la tabla dispersa, o un valor distinto de cero en otro caso.
hsearch() devuelve NULL si action es ENTER y la tabla dispersa esta
completa, o action es FIND e item no puede ser encontrado en la tabla
dispersa.
hsearch_r() devuelve 0 si action es ENTER y la tabla dispersa esta
completa, y un valor distinto de cero en otro caso.
ERRORES
ENOMEM Memoria insuficiente.
CONFORME A
Las funciones hcreate, hsearch, y hdestroy son de SVID, y estan
descritas en POSIX 1003.1-2001. Las funciones hcreate_r, hsearch_r,
hdestroy_r son extensiones de GNU.
FALLOS
SVID y POSIX 1003.1-2001 especifican que el argumento action es
significativo solo para busquedas sin exito, por lo que ENTER no
deberia hacer nada para una busqueda exitosa. Las implementaciones de
libc y glibc actualizan data para una clave key dada en este caso.
Se pueden anadir a la tabla dispersa entradas individuales pero no se
pueden eliminar.
EJEMPLO
El siguiente programa inserta 24 elementos en una tabla dispersa y a
continuacion imprime algunos de ellos.
#include <stdio.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", "zulu"
};
int main() {
ENTRY e, *ep;
int i;
/* Comencemos con una pequena tabla y dejemosla que crezca */
hcreate(30);
for (i = 0; i < 24; i++) {
e.key = data[i];
/* Los datos son enteros, en lugar de punteros a alguna cosa */
e.data = (char *)i;
ep = hsearch(e, ENTER);
/* No debe haber fallos */
if(ep == NULL) {
fprintf(stderr, "Fallo en la entrada\n");
exit(1);
}
}
for (i = 22; i < 26; i++) {
/* Imprime dos entradas de la tabla y demuestra que otras dos no
estan en la tabla */
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);
}
return 0;
}
V'EASE TAMBI'EN
bsearch(3), lsearch(3), tsearch(3), malloc(3)