HSEARCH(3)

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)