_lsearch

Articolo
06/09/2015

Esegue una ricerca lineare di un valore; aggiunge alla fine dell'elenco se non viene trovata corrispondenza. È disponibile una versione più sicura di questa funzione; vedere _lsearch_s.

void *_lsearch(
   const void *key,
   void *base,
   unsigned int *num,
   unsigned int width,
   int (__cdecl *compare)(const void *, const void *) 
);

Parametri

key
Oggetto da ricercare.
base
Puntatore alla base dell'array da cercare.
num
Numero di elementi
width
Grandezza di ogni elemento della matrice.
compare
Puntatore alla routine di confronto. Il primo parametro è un puntatore alla chiave per la ricerca. Il secondo parametro è un puntatore ad un elemento dell'array da confrontare con la chiave.

Valore restituito

Se la chiave viene trovata, _lsearch restituisce un puntatore all'elemento alla base dell'array che corrisponde a key. Se la chiave non viene trovata, _lsearch restituisce un puntatore all'elemento appena aggiunto alla fine dell'array.

Note

La funzione _lsearch esegue una ricerca lineare del valore key in un array di num elementi, ognuno di width byte. A differenza di bsearch, _lsearch non richiede che l'array sia ordinato. Se key non viene trovato, _lsearch lo aggiunge alla fine dell'array e incrementa num.

L'argomento compare è un puntatore a una routine fornita dall'utente che confronta due elementi di un array e restituisce un valore che specifica la loro relazione. _lsearch chiama la routine compare una o più volte durante la ricerca, passando i puntatori a due elementi di array ad ogni chiamata. compare deve confrontare gli elementi e restituire un valore diverso da zero (che indica che gli elementi sono differenti) o 0 (che indica che gli elementi sono identici).

Questa funzione convalida i parametri. Se compare, key o num è NULL, o se base è NULL e *num è diverso da zero, o se width è minore di zero, viene richiamato 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
_lsearch	<search.h>

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

Esempio

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

int compare( const void *arg1, const void *arg2 );

int main(void)
{
   char * wordlist[4] = { "hello", "thanks", "bye" };
                            // leave room to grow...
   int n = 3;
   char **result;
   char *key = "extra";
   int i;

   printf( "wordlist before _lsearch:" );
   for( i=0; i<n; ++i ) printf( " %s", wordlist[i] );
   printf( "\n" );

   result = (char **)_lsearch( &key, wordlist, 
                      &n, sizeof(char *), compare );

   printf( "wordlist after _lsearch:" );
   for( i=0; i<n; ++i ) printf( " %s", wordlist[i] );
   printf( "\n" );
}

int compare(const void *arg1, const void *arg2 )
{
   return( _stricmp( * (char**)arg1, * (char**)arg2 ) );
}