FindNLSStringEx 関数 (winnls.h)

[アーティクル]
08/27/2023

名前で指定されたロケールの Unicode 文字列 (ワイド文字) またはその同等の Unicode 文字列を別の Unicode 文字列で検索します。

注意バイナリ表現が非常に異なる文字列は同一と比較できるため、この関数によって特定のセキュリティ上の問題が発生する可能性があります。詳細については、「セキュリティに関する考慮事項: 国際機能」の比較関数の説明を参照してください。

構文

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

パラメーター

[in, optional] lpLocaleName

ロケール名、または次のいずれかの定義済み値へのポインター。

[in] dwFindNLSStringFlags

検索操作の詳細を指定するフラグ。これらのフラグは相互に排他的であり、FIND_FROMSTARTが既定値です。アプリケーションでは、次の表で定義されているフィルターフラグを使用して、検索フラグの 1 つだけを指定できます。アプリケーションでフラグが指定されていない場合、関数は指定されたロケールの既定の比較を使用します。「アプリケーションでの並べ替えの処理」で説明したように、バイナリ比較モードはありません。

値	説明
FIND_FROMSTART	文字列の最初の文字から始まる文字列を検索します。
FIND_FROMEND	文字列の最後の文字から始めて、文字列を逆方向に検索します。
FIND_STARTSWITH	lpStringValue で指定された値が lpStringSource で示されるソース文字列の最初の値であるかどうかを調べるテスト。
FIND_ENDSWITH	lpStringValue で指定された値が lpStringSource によって示されるソース文字列の最後の値であるかどうかを調べるテスト。

アプリケーションでは、以下に定義されているフィルター処理フラグを find フラグと組み合わせて使用できます。

値	説明
LINGUISTIC_IGNORECASE	言語的に適切な検索では大文字と小文字を区別しない。詳細については、「解説」を参照してください。
LINGUISTIC_IGNOREDIACRITIC	言語的に適切な分音記号は無視します。詳細については、「解説」を参照してください。メモこのフラグは、分解された文字、つまり、基本文字と 1 つ以上の非スペーシング文字がそれぞれ異なるコードポイント値を持つ文字と共に使用される場合、予測可能な結果を常に生成するとは限りません。
NORM_IGNORECASE	検索で大文字と小文字を区別しない。詳細については、「解説」を参照してください。
NORM_IGNOREKANATYPE	ひらがなとカタカナの文字を区別しないでください。対応するひらがな文字とカタカナ文字は等しいと比較されます。
NORM_IGNORENONSPACE	非スペーシング文字を無視します。詳細については、「解説」を参照してください。
NORM_IGNORESYMBOLS	記号と句読点を無視します。
NORM_IGNOREWIDTH	半角文字と全角文字の違いを無視します (例: C a t == cat)。全角の形式は、中国語と日本語のスクリプトで使用される書式設定の区別です。
NORM_LINGUISTIC_CASING	ファイルシステム規則 (既定) ではなく、大文字と小文字の区別に言語規則を使用します。詳細については、「解説」を参照してください。

[in] lpStringSource

lpStringValue で指定された文字列を関数が検索するソース文字列へのポインター。

[in] cchSource

lpStringSource で示される文字列の終端の null 文字を除く文字単位のサイズ。アプリケーションでは、このパラメーターに 0 または -1 以外の負の数を指定できません。ソース文字列が null で終了し、関数がサイズを自動的に計算する必要がある場合、アプリケーションは -1 を指定します。

[in] lpStringValue

関数がソース文字列で検索する検索文字列へのポインター。

[in] cchValue

lpStringValue で示される文字列の終端の null 文字を除く文字単位のサイズ。アプリケーションでは、このパラメーターに 0 または -1 以外の負の数を指定できません。検索文字列が null で終了し、関数がサイズを自動的に計算する必要がある場合、アプリケーションは -1 を指定します。

[out, optional] pcchFound

関数が検索する文字列の長さを含むバッファーへのポインター。文字列は、検索文字列より長く、または短くすることができます。関数が検索文字列を見つけられない場合、このパラメーターは変更されません。

関数は、このパラメーターで NULL を 取得できます。この場合、関数は、見つかった文字列の長さがソース文字列の長さと異なるかどうかを示しません。

多くの場合、 pcchFound の値は cchValue で指定された値と同じですが、次の場合は異なる場合があります。

cchValue に指定された値は負の値です。
文字列は同等ですが、長さが異なります。たとえば、"A" と "Combining Ring" (U+0041 U+030A) は、"A リング" (U+00c5) と同じです。

[in, optional] lpVersionInformation

予約; は NULL である必要があります。

[in, optional] lpReserved

予約; は NULL である必要があります。

[in, optional] sortHandle

予約;は 0 である必要があります。

戻り値

成功した場合、 lpStringSource によって示されるソース文字列に 0 から始まるインデックスを返します。このインデックスは、 pcchFound の値と組み合わせて、ソース文字列内で見つかった文字列全体の正確な場所を提供します。戻り値 0 はソース文字列へのエラーのないインデックスであり、一致する文字列はオフセット 0 のソース文字列にあります。

成功しなかった場合、関数は -1 を返します。拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。このエラーコードは、次のいずれかのエラーコードを返すことができます。

ERROR_INVALID_FLAGS。フラグに指定された値が無効です。
ERROR_INVALID_PARAMETER。パラメーター値のいずれかが無効です。
ERROR_SUCCESS。アクションは正常に完了しましたが、結果は生成されません。

解説

この関数は、検索方向、文字の等価性フィルター処理、ロケール固有のフィルター処理など、さまざまな検索オプションを提供します。等価性は、関数の呼び出しで指定されたロケールとフラグによって異なります。フィルター処理フラグは、検索の結果を変更できます。たとえば、検索の実行時に関数が大文字と小文字または分音記号を無視すると、一致する可能性が高くなります。

既定では、 Locale パラメーターがトルコ語 (トルコ) またはアゼルバイジャン (アゼルバイジャン) を指定している場合でも、この関数は小文字の "i" を大文字の "I" にマップします。トルコ語またはアゼルバイジャン語のこの動作をオーバーライドするには、アプリケーションで NORM_LINGUISTIC_CASING を指定する必要があります。このフラグが正しいロケールに指定されている場合、"ı" (小文字のドットなしの I) は小文字の形式の "I" (大文字のドットなしの I) で、"i" (小文字の点線 I) は小文字の "ı" (大文字の点線 I) です。

多くのスクリプト (特にラテン語のスクリプト) の場合、NORM_IGNORENONSPACEはLINGUISTIC_IGNOREDIACRITICと一致し、NORM_IGNORECASEはLINGUISTIC_IGNORECASEと一致しますが、次の例外があります。

NORM_IGNORENONSPACEは、分音記号であるかどうかに関係なく、二次的な区別を無視します。韓国語、日本語、中国語、インド語などのスクリプトでは、この区別を分音記号以外の目的で使用します。 LINGUISTIC_IGNOREDIACRITICは、単に 2 番目の並べ替え重みを無視するのではなく、実際の分音記号のみを無視します。
NORM_IGNORECASEは、実際に言語的なケースであるかどうかに関係なく、3 次的な区別を無視します。たとえば、アラビア語とインド語のスクリプトでは、このフラグは文字の代替形式を区別します。ただし、違いは言語的なケースには対応していません。 LINGUISTIC_IGNORECASEは、3 番目の並べ替え重みを無視するのではなく、実際の言語的大文字と小文字のみを無視します。

失敗した場合に 0 を返す他の NLS API 関数とは対照的に、この関数は失敗した場合は -1 を返します。成功すると、0 から始まるインデックスが返されます。このインデックスを使用すると、関数が 1 つずつオフエラーや 1 文字のバッファーオーバーランを回避できます。

この関数は、成功した場合でも SetLastError を呼び出す数少ない NLS 関数の 1 つです。この呼び出しは、検索文字列との一致に失敗したときにスレッドの最後のエラーをクリアします。 これにより、GetLastError によって返される値がクリアされます。

Windows 8 以降: アプリが Windows.Globalization 名前空間からこの関数に言語タグを渡す場合は、最初に ResolveLocaleName を呼び出してタグを変換する必要があります。

要件


サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	winnls.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

次の方法で共有

FindNLSStringEx 関数 (winnls.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース