bsearch

Artigo
06/09/2015

Executa uma pesquisa binária de uma matriz classificada. Uma versão mais segura dessa função está disponível; consulte bsearch_s.

void *bsearch( 
   const void *key,
   const void *base,
   size_t num,
   size_t width,
   int ( __cdecl *compare ) (const void *key, const void *datum) 
);

Parâmetros

key
Objeto para pesquisar por.
base
Ponteiro para a base de dados de pesquisa.
num
Número de elementos.
width
Largura dos elementos.
compare
Função de retorno de chamada que compara dois elementos. O primeiro é um ponteiro para a chave para a pesquisa e o segundo é um ponteiro para o elemento da matriz a ser comparado com a chave.

Valor de retorno

bsearch retorna um ponteiro para uma ocorrência de key na matriz apontada por base. Se key não for localizado, a função retornará NULL. Se a matriz não está em ordem crescente de classificação ou contiver registros duplicados com chaves idênticas, o resultado é imprevisível.

Comentários

A função de bsearch executa uma pesquisa binária de uma matriz classificada de elementos de num , cada um de width em bytes de tamanho. O valor de base é um ponteiro para a base da matriz a ser pesquisada e, key é o valor que está sendo buscadas. O parâmetro de compare é um ponteiro para uma rotina fornecida pelo usuário que compara a chave solicitada a um elemento da matriz e retorna um dos seguintes valores que especificam a relação:

Valor retornado por rotina de compare	Descrição
< 0	A chave é menor que o elemento da matriz.
0	A chave é igual ao elemento da matriz.
> 0	A chave é maior que o elemento da matriz.

Essa função valida seus parâmetros. Se compare, key ou num são NULL, ou se base é NULL e *num for diferente de zero, ou se width for zero, o manipulador inválido do parâmetro é chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, errno será definido como EINVAL e a função retornará NULL.

Requisitos

Rotina	Cabeçalho necessário
bsearch	<stdlib.h e> search.h <>

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

Esse programa classifica uma matriz de cadeia de caracteres com qsort, e depois usar o bsearch para localizar as palavras “cat”.

// crt_bsearch.c
#include <search.h>
#include <string.h>
#include <stdio.h>

int compare( char **arg1, char **arg2 )
{
   /* Compare all of both strings: */
   return _strcmpi( *arg1, *arg2 );
}

int main( void )
{
   char *arr[] = {"dog", "pig", "horse", "cat", "human", "rat", "cow", "goat"};
   char **result;
   char *key = "cat";
   int i;

   /* Sort using Quicksort algorithm: */
   qsort( (void *)arr, sizeof(arr)/sizeof(arr[0]), sizeof( char * ), (int (*)(const 
   void*, const void*))compare );

   for( i = 0; i < sizeof(arr)/sizeof(arr[0]); ++i )    /* Output sorted list */
      printf( "%s ", arr[i] );

   /* Find the word "cat" using a binary search algorithm: */
   result = (char **)bsearch( (char *) &key, (char *)arr, sizeof(arr)/sizeof(arr[0]),
                              sizeof( char * ), (int (*)(const void*, const void*))compare );
   if( result )
      printf( "\n%s found at %Fp\n", *result, result );
   else
      printf( "\nCat not found!\n" );
}