bsearch_s

Articolo
06/09/2015

Esegue una ricerca binaria di una matrice ordinata. Questa è la versione di bsearch con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

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

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 argomento è il puntatore context. Il secondo argomento è un puntatore a key per la ricerca. Il terzo argomento è un puntatore all'elemento del vettore da confrontare con key.
context
Un puntatore a un oggetto che può essere accessibile nella funzione di confronto.

Valore restituito

bsearch_s restituisce un puntatore a un'occorrenza dikey nella matrice puntata 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.

Se alla funzione vengono passati parametri non validi, viene invocato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, errnoviene impostato su EINVAL e la funzione restituisce NULL. Per ulteriori informazioni, vedere errno, _doserrno, _sys_errlist, and _sys_nerr.

Condizioni di errore

key	base	compare	num	width	errno
NULL	any	any	any	any	EINVAL
any	NULL	any	!= 0	any	EINVAL
any	any	any	any	= 0	EINVAL
any	any	NULL	un	any	EINVAL

Note

La funzione bsearch_s 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.

Il puntatore context potrebbe essere utile se la struttura dei dati trovata fa parte di un oggetto e la funzione deve accedere ai relativi membri. La funzione compare può eseguire il cast del puntatore void nel tipo di oggetto appropriato e accedere ai membri dell'oggetto. L'aggiunta del parametro context rende bsearch_s più sicuro affinché il contesto aggiuntivo possa essere utilizzato per evitare il rientro dei bug associati utilizzando variabili statiche per rendere disponibili i dati della funzione compare.

Requisiti

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

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

Esempio

Questo programma ordina una matrice di stringhe con qsort_s, e quindi utilizza bsearch_s per trovare la parola "cat".

// crt_bsearch_s.cpp
// This program uses bsearch_s to search a string array,
// passing a locale as the context.
// compile with: /EHsc
#include <stdlib.h>
#include <stdio.h>
#include <search.h>
#include <process.h>
#include <locale.h>
#include <locale>
#include <windows.h>
using namespace std;

// The sort order is dependent on the code page.  Use 'chcp' at the
// command line to change the codepage.  When executing this application,
// the command prompt codepage must match the codepage used here:

#define CODEPAGE_850

#ifdef CODEPAGE_850
#define ENGLISH_LOCALE "English_US.850"
#endif

#ifdef CODEPAGE_1252
#define ENGLISH_LOCALE "English_US.1252"
#endif

// The context parameter lets you create a more generic compare.
// Without this parameter, you would have stored the locale in a
// static variable, thus making it vulnerable to thread conflicts
// (if this were a multithreaded program).

int compare( void *pvlocale, char **str1, char **str2)
{
    char *s1 = *str1;
    char *s2 = *str2;

    locale& loc = *( reinterpret_cast< locale * > ( pvlocale));

    return use_facet< collate<char> >(loc).compare(
       s1, s1+strlen(s1),
       s2, s2+strlen(s2) );
}

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

   char *key = "cat";
   char **result;
   int i;

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

   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_s( &key,
                                arr,
                                sizeof(arr)/sizeof(arr[0]),
                                sizeof( char * ),
                                (int (*)(void*, const void*, const void*))compare,
                                &locale(ENGLISH_LOCALE) );
   if( result )
      printf( "\n%s found at %Fp\n", *result, result );
   else
      printf( "\nCat not found!\n" );
}