Provided by: manpages-es_1.55-3_all bug

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ÓN

       Las  tres  funciones  hcreate,  hsearch, y hdestroy permiten al usuario
       crear una tabla dispersa (sólo 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 más de  una
       tabla.

       En  primer  lugar, se debe crear la tabla con la función hcreate().  El
       argumento nel es una estimación del número de entradas de la tabla.  La
       función   hcreate()  puede  incrementar  este  valor  para  mejorar  el
       rendimiento de la tabla dispersa resultante.

       La función 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
       búsqueda.   El  campo  data apunta a los datos asociados con esa clave.
       La función 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 éxito devuelve un puntero al  mismo.   El  argumento  action
       determina  qué  debe  hacer  hsearch()  tras una búsqueda sin éxito. 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  está
       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  está
       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 están
       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 sólo para búsquedas  sin  éxito,  por  lo  que  ENTER  no
       debería  hacer  nada para una búsqueda exitosa. Las implementaciones de
       libc y glibc actualizan data para una clave key dada en este caso.

       Se pueden añadir a la tabla dispersa entradas individuales pero  no  se
       pueden eliminar.

EJEMPLO

       El  siguiente  programa  inserta 24 elementos en una tabla dispersa y a
       continuación 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 pequeña tabla y dejémosla 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
                  están 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ÉASE TAMBIÉN

       bsearch(3), lsearch(3), tsearch(3), malloc(3)