bsearch_s

Article
06/09/2015

Effectue une recherche binaire d'un tableau trié. Il s'agit de versions de bsearch avec des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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
);

Paramètres

key
Objet à rechercher.
base
Pointeur vers la base de données de recherche.
num
Nombre d'éléments
width
Largeur des éléments.
compare
Fonction de rappel qui compare deux éléments. Le premier argument est le pointeur context. Le deuxième argument est un pointeur vers key pour la recherche. Le troisième argument est un pointeur sur l'élément de tableau à comparer à key.
context
Un pointeur vers un objet, qui peut être accessible dans la fonction de comparaison.

Valeur de retour

bsearch_s retourne un pointeur vers une occurrenced'key dans la table référencé par base. Si key n'y figure pas, la fonction retourne la valeur NULL. Si la table n'est pas dans l'ordre de tri croissant ou si elle contient les enregistrements en double avec des clés identiques, le résultat est imprévisible.

Si des paramètres non valides sont transmis à la fonction, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, errno est défini comme EINVAL et la fonction retourne NULL. Pour plus d'informations, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

Conditions d'erreur

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

Notes

La fonction bsearch_s effectue une recherche binaire d'un tableau trié d'éléments num, chacun de width octets en taille. La valeur base est un pointeur vers la base de la table à rechercher, puis key est la valeur désirée. Le paramètre compare est un pointeur vers une routine fournie à l'utilisateur qui compare la clé requise à un élément du tableau et retourne l'une des valeurs suivantes en spécifiant leur relation :

Valeur retournée par la routine compare	Description
< 0	La clé est inférieur à l'élément du tableau.
0	La clé est égale à l'élément du tableau.
> 0	La clé est supérieure à l'élément du tableau.

Le pointeur de context peut être utile si la structure de données recherchée fait partie d'un objet et que la fonction comparative doit accéder à des membres de l'objet. La fonction compare peut convertir le pointeur void dans le type d'objet approprié et accéder aux membres de cet objet. L'ajout du pointeur context permet de rendrebsearch_s plus sécurisé car le contexte supplémentaire peut être utilisé pour éviter les bogues de reentrées associés à l'utilisation des variables statiques pour rendre les données disponibles à la fonction compare.

Configuration requise

Routine	En-tête requis
bsearch_s	<stdlib.h> et <malloc.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité dans l'introduction.

Exemple

Ce programme trie un tableau de chaînes avec qsort_s, puis utilise des bsearch_s pour rechercher le mot « 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" );
}