Provided by: manpages-pt-dev_20040726-4_all bug

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)