bsearch

Articolo
06/09/2015

Esegue una ricerca binaria di una matrice ordinata. È disponibile una versione più sicura di questa funzione; vedere 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) 
);

Parametri

key
Oggetto da ricercare.
base
Puntatore alla base dei dati della ricerca.
num
Numero di elementi
width
Larghezza degli elementi.
compare
Funzione di callback che confronta due elementi. Il primo è un puntatore alla chiave per la ricerca e il secondo è un puntatore all'elemento dell'array da confrontare con la chiave.

Valore restituito

bsearch restituisce un puntatore a un'occorrenza di key nell'array puntato da base. Se key non è reperibile, la funzione restituisce NULL. Se la matrice non è in ordine crescente o contiene record duplicati con chiavi identiche, il risultato sarà imprevedibile.

Note

La funzione bsearch esegue una ricerca binaria di un array ordinato di num elementi, ciascuno di width byte di dimensione. Il valore base è un puntatore alla base della matrice da cercare e key è il valore da cercare. Il parametro compare è un puntatore a una routine fornita all'utente che confronta la chiave richiesta con un elemento dell'array e restituisce uno dei seguenti valori che specificano la loro relazione:

Valore restituito dalla routine compare	Descrizione
< 0	La chiave è inferiore all'elemento dell'array.
0	La chiave è uguale all'elemento dell'array.
> 0	La chiave è maggiore dell'elemento dell'array.

Questa funzione convalida i parametri. Se compare, key o num sono NULL, o se base è NULL e *num è diverso da zero, o se width è zero, viene invocato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, errno viene impostato su EINVAL e la funzione restituisce NULL.

Requisiti

Routine	Intestazione obbligatoria
bsearch	<stdlib.h> e <search.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'Introduzione.

Esempio

Questo programma ordina una matrice di stringhe con qsort, e quindi utilizza bsearch per trovare la parola "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" );
}