_lsearch

[アーティクル]
08/09/2011

線形検索を行って値を探します。見つからなかった場合は、リストの末尾に値を追加します。この関数のセキュリティが強化されたバージョンを使用できるようになりました。「_lsearch_s」を参照してください。

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

パラメーター

key
検索するオブジェクト。
base
検索する配列のベースへのポインター。
num
要素の数。
width
各配列要素の大きさ。
compare
比較ルーチンへのポインター。最初のパラメーターは、検索用のキーへのポインターです。 2 番目のパラメーターは、キーと比較される配列要素へのポインターです。

戻り値

キーが見つかった場合、_lsearch は、key に一致する base の指す配列要素へのポインターを返します。キーが見つからなかった場合、_lsearch は、配列の末尾に新しく追加された項目へのポインターを返します。

解説

_lsearch 関数は、width のバイト数ごとに、num 要素の配列で key 値の線形検索を実行します。 bsearch 関数とは異なり、_lsearch 関数では、配列を並べ替える必要がありません。 key が見つからなかった場合、_lsearch 関数は、その key を配列の末尾に追加し、num をインクリメントします。

compare 引数は、2 つの配列要素を比較し、両者の関係を指定する値を返すユーザー指定ルーチンへのポインターです。 _lsearch 関数は、検索中に 1 回以上 compare ルーチンを呼び出し、そのたびに 2 つの配列要素へのポインターを渡します。 compare は、要素を比較し、0 以外の値 (2 つの要素が異なることを示す場合) または 0 (2 つの要素が同じであることを示す場合) を返す必要があります。

この関数は、パラメーターを検証します。 compare、key、または num が NULL の場合、base が NULL で *num が 0 以外の値の場合、あるいは width が 0 より小さい場合は、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、errno が EINVAL に設定され、関数から NULL が返されます。

必要条件

ルーチン	必須ヘッダー
_lsearch	<search.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// 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 ) );
}