.TH HSEARCH 3
.SH NOME
hcreate, hdestroy, hsearch \- gerencimento de tabela de 'hash'

.SH SINOPSE
.nf
.B #include  <search.h>
.sp
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ");"
.sp
.BI "int hcreate(unsigned "nel ");"
.sp
.B "void hdestroy(void);"
.RE
.fi
.SH 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.
.PP
Primeiro, a tabela precisa ser criada com a função \fBhcreate()\fP.
\fInel\fP é uma uma esimativa do número de entradas na tabela.
\fBhcreate()\fP pode ajustar esse valor para maior a fim de melhorar o
desempenho da tabela de hash resultante. A imnplementação GNU de
\fBhsearch()\fP irá, também, aumnetar a tabela se a mesma ficar
praticamente cheia.
\fBmalloc\fP(3) é utilizado para alocar espaço para a tabela.
.PP
A função correspondente \fBhdestroy()\fP libera a memória ocupada pela
tabela de hash para que uma nova tabela possa ser construída.
.PP
\fIitem\fP é do tipo \fBENTRY\fP, a qual é um 'typedef' definido em
\fI<search.h>\fP e inclui estes elementos:
.sp
.nf
	typedef struct entry
	  {
	    char *\fIkey\fP;
	    char *\fIdata\fP;
	  } ENTRY;
.fi
.sp
\fIkey\fP aponta para a string ASCII terminada em zero, a qual é uma
chave de busca. \fIdata\fP 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").) \fBhserach\fP
procura na tabela de hash um item com a mesma chave que \fIitem\fP e se
for bem sucedido, retornará um apontador para ele. \fIaction\fP determina
o que \fBhsearch()\fP fará após uma busca infrutífera. Um valor de \fBFIND\fP o instrui a inserir o novo
item, enquanto um valor de  \fBFIND\fP significa retornar \fBNULL\fP.
.SH "VALOR DE RETURN"
\fBhcreate()\fP retorna \fBNULL\fP se a tabela de hash não puder ser instalada com sucesso.
.PP
\fBhsearch()\fP retorna \fBNULL\fP se \fIaction\fP é \fBENTER\fP e não há memória suficiente para
expandir a tabela hash, ou \fIaction\fP é \fBFIND\fP e \fBitem\fP não puser ser encontrado na tabela de
hash.
.SH "EM CONFORMIDADE COM"
.TP
SVID, exceto em SysV, a tabela de hash não pode crescer.
.SH 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.
.SH EXEMPLO
.PP
O seguinte programa insere 24 itens em uma tabela de hash e então imnprime alguns deles.
.nf

	#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;
	}

.fi
.SH "VEJA TAMBÉM"
.BR bsearch "(3), " lsearch "(3), " tsearch "(3), " malloc "(3)"

.SH "TRADUZIDO PELO LDP-BR EM 18.8.2000"
\&\fR\&\f(CWValter 'Geddy' Ferraz Sanches <geddy@lawyer.com> (tradução)\fR
.fi
\&\fR\&\f(CWRevisor <revisor@revisolandia.com> (revisão)\fR