HSEARCH(3)

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

SINÓPSE
#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, aumentar 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 o caracter.) 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 ENTER o instrui a inserir o novo item, enquanto um valor de FIND significa retornar NULO.

VALORES RETORNADOS
hcreate() retorna NULO se a tabela de 'hash' não puder ser instalada com sucesso.

hsearch() retorna NULO 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'.

DE ACORDO COM

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

PROBLEMAS
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", "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;
      /* 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);
	}
      return 0;
    }

VEJA TAMBÉM
bsearch(3), lsearch(3), tsearch(3), malloc(3).

TRADUZIDO POR LDP-BR em 18/08/2000.

  Tradução:
Valter Ferraz Sanches <vfs@ezlinux.cjb.net>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>