NOME

       hcreate, hdestroy, hsearch - gerencimento de tabela de 'hash'

SINOPSE

       #include <search.h>

       ENTRY *hsearch(ENTRY item, ACTION action);

       int hcreate(unsigned nel);

       void hdestroy(void);

DESCRIÇÃO

       Essas  três  funções  permitem  que  o usuário crie uma tabela de hash, a qual associa uma
       chave com quaisquer dados.

       Primeiro, a tabela precisa ser criada com a função hcreate().  nel é uma uma esimativa  do
       número  de  entradas  na  tabela.   hcreate()  pode ajustar esse valor para maior a fim de
       melhorar o desempenho da tabela de hash resultante. A imnplementação GNU de hsearch() irá,
       também, aumnetar a tabela se a mesma ficar praticamente cheia.  malloc(3) é utilizado para
       alocar espaço para a tabela.

       A função correspondente hdestroy() libera a memória ocupada pela tabela de hash  para  que
       uma nova tabela possa ser construída.

       item  é  do  tipo  ENTRY,  a  qual  é  um  'typedef' definido em <search.h> e inclui estes
       elementos:

            typedef struct entry
              {
                char *key;
                char *data;
              } ENTRY;

       key aponta para a string ASCII terminada em zero, a qual é uma chave de busca. data aponta
       para  os  dados associados àquela chave.  (um apontador para um tipo diferente de caracter
       deve ser substituído  por  um  ponteiro-para-caracter  ("pointer-to-character").)  hserach
       procura  na  tabela  de  hash  um  item  com a mesma chave que item e se for bem sucedido,
       retornará um apontador para ele. action determina o que  hsearch()  fará  após  uma  busca
       infrutífera.  Um valor de FIND o instrui a inserir o novo item, enquanto um valor de  FIND
       significa retornar NULL.

VALOR DE RETURN

       hcreate() retorna NULL se a tabela de hash não puder ser instalada com sucesso.

       hsearch() retorna NULL se action é ENTER e não  há  memória  suficiente  para  expandir  a
       tabela hash, ou action é FIND e item não puser ser encontrado na tabela de hash.

EM CONFORMIDADE COM

       SVID, exceto em SysV, a tabela de hash não pode crescer.

BUGS

       A implementação só consegue gerenciar uma tabela hash por vez.  Entradas de tabela de hash
       individuais podem ser acrescidas, mas não apagadas.

EXEMPLO

       O seguinte programa insere 24 itens em uma tabela de hash e então imnprime alguns deles.

            #include <stdio.h>
            #include <search.h>

            char *data[]={ "alpha", "bravo", "charlie", "delta",
                 "echo", "foxtrot", "golf", "hotel", "india", "julliete",
                 "kilo", "lima", "mike", "november", "oscar", "papa",
                 "quebec", "romeo", "sierra", "tango", "uniform",
                 "victor, "whiskey", "x-ray", "yankee", "zulu"
             };

            int main()
            {
              ENTRY e, *ep;
              int i;

              /* inicia com uma tabela pequena e permite-lhe crescer */
              hcreate(3);
              for (i = 0; i < 24; i++)
                {
                  e.key = data[i];
                  /* data é apenas um inteiro, ao invés de um ponteiro para algo */
                  e.data = (char *)i;
                  ep = hsearch(e, ENTER);
                  /* não deve haver falhas */
                  if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
                }
              for (i = 22; i < 26; i++)
                /* imprime duas entradas vindas da tabela e mostra
                   as duas que não estão na tabela */
                {
                  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);
                }
              return0;
            }

VEJA TAMBÉM

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

TRADUZIDO PELO LDP-BR EM 18.8.2000

       Valter 'Geddy' Ferraz Sanches <geddy@lawyer.com> (tradução)
       Revisor <revisor@revisolandia.com> (revisão)

                                                                                       HSEARCH(3)