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)