CompareStringEx 関数 (stringapiset.h)

  • [アーティクル]

name で指定された ロケール について、2 つの Unicode (ワイド文字) 文字列を比較します。

注意CompareStringEx を誤って使用すると、アプリケーションのセキュリティが損なわれる可能性があります。 正しく比較されない文字列は、無効な入力を生成する可能性があります。 文字列をテストして、使用する前に有効であることを確認し、エラー ハンドラーを提供します。 詳細については、「 セキュリティに関する考慮事項: 国際機能」を参照してください。
 
メモ アプリケーションは、Windows Vista 以降でのみ実行するように設計されている場合は 、CompareString を優先してこの関数を呼び出す必要があります。
 

構文

int CompareStringEx(
  [in, optional] LPCWSTR                          lpLocaleName,
  [in]           DWORD                            dwCmpFlags,
  [in]           _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in]           int                              cchCount1,
  [in]           _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in]           int                              cchCount2,
  [in, optional] LPNLSVERSIONINFO                 lpVersionInformation,
  [in, optional] LPVOID                           lpReserved,
  [in, optional] LPARAM                           lParam
);

パラメーター

[in, optional] lpLocaleName

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

[in] dwCmpFlags

関数が 2 つの文字列を比較する方法を示すフラグ。 既定では、これらのフラグは設定されません。 このパラメーターは、次のいずれかの値の組み合わせを指定することも、0 に設定して既定の動作を取得することもできます。

フラグ 説明
LINGUISTIC_IGNORECASE
 言語的に適切な大文字と小文字を無視します。
LINGUISTIC_IGNOREDIACRITIC
 言語的に適切なように、非スペーシング文字を無視します。
メモ このフラグは、分解された文字、つまり、基本文字と 1 つ以上の非スペーシング文字がそれぞれ異なるコード ポイント値を持つ文字と共に使用される場合、予測可能な結果を常に生成するとは限りません。
 
NORM_IGNORECASE
 大文字と小文字を区別しない。 多くのスクリプト (特にラテン文字) の場合、NORM_IGNORECASEはLINGUISTIC_IGNORECASEと一致します。
メモ NORM_IGNORECASEは、実際に言語的なケースであるかどうかに関係なく、3 次的な区別を無視します。 たとえば、アラビア語とインド語のスクリプトでは、これは文字の代替形式を区別しますが、違いは言語的な大文字と小文字には対応していません。 LINGUISTIC_IGNORECASE、関数は、3 番目の並べ替え重みを無視するのではなく、実際の言語的な大文字と小文字のみを無視します。
 
メモ このフラグを設定すると、関数は CJK 互換文字のワイド形式とナロー形式の区別を無視します。
 
NORM_IGNOREKANATYPE
 ひらがなとカタカナの文字を区別しないでください。 対応するひらがな文字とカタカナ文字は等しいと比較されます。
NORM_IGNORENONSPACE
 非スペーシング文字を無視します。 多くのスクリプト (特にラテン文字) の場合、NORM_IGNORENONSPACEはLINGUISTIC_IGNOREDIACRITICと一致します。
メモ NORM_IGNORENONSPACEは、分音記号であるかどうかに関係なく、二次的な区別を無視します。 韓国語、日本語、中国語、インド言語のスクリプトでは、この区別を分音記号以外の目的で使用します。 LINGUISTIC_IGNOREDIACRITIC、関数は 2 番目の並べ替え重みを無視するのではなく、実際の分音記号のみを無視します。
 
メモNORM_IGNORENONSPACEは、アクセント記号付き文字がメイン文字からの 2 番目のパスで並べ替えられるロケールにのみ有効です。 通常、文字列内のすべての文字はアクセント記号に関係なく最初に比較され、文字列が等しい場合は、アクセントを比較するために文字列の 2 番目のパスが実行されます。 このフラグにより、2 番目のパスは実行されません。 最初のパスでアクセント記号付き文字を並べ替えるロケールの場合、このフラグは無効です。
 
NORM_IGNORESYMBOLS
 記号と句読点を無視します。
NORM_IGNOREWIDTH
 半角文字と全角文字の違いを無視します (例: C a t == cat)。 全角の形式は、中国語と日本語のスクリプトで使用される書式設定の区別です。
NORM_LINGUISTIC_CASING
 ファイル システム規則ではなく、大文字と小文字の区別に既定の言語規則を使用します。 CompareStringEx のほとんどのシナリオでは、このフラグが使用されることに注意してください。 アプリケーションが CompareStringOrdinal を呼び出すときに、このフラグを使用する必要はありません。
SORT_DIGITSASNUMBERS
 Windows 7: 並べ替え中に数字を数値として扱います。たとえば、"10" の前に "2" を並べ替えます。
SORT_STRINGSORT
 句読点は記号と同じように扱います。

[in] lpString1

比較する最初の文字列へのポインター。

[in] cchCount1

終端の null 文字を除く、 lpString1 で示される文字列の長さ。 文字列が null で終わる場合、アプリケーションは負の値を指定できます。 この場合、関数は長さを自動的に決定します。

[in] lpString2

比較する 2 番目の文字列へのポインター。

[in] cchCount2

終端の null 文字を除く、 lpString2 で示される文字列の長さ。 文字列が null で終わる場合、アプリケーションは負の値を指定できます。 この場合、関数は長さを自動的に決定します。

[in, optional] lpVersionInformation

関連する NLS 機能に関するバージョン情報を含む NLSVERSIONINFOEX 構造体へのポインター。通常は GetNLSVersionEx から取得されます。

Windows Vista、Windows 7: 予約; は NULL に設定する必要があります。

[in, optional] lpReserved

予約; は NULL に設定する必要があります。

[in, optional] lParam

予約;は 0 に設定する必要があります。

戻り値

成功した場合は、次のいずれかの値を返します。 文字列を比較する C ランタイム規則を維持するために、0 以外の戻り値から値 2 を減算できます。 次に、0、==0、0 の <意味は C ランタイムと >一致します。

  • CSTR_LESS_THAN。 lpString1 で示される文字列は、lpString2 で示される文字列よりも字句値が小さくなります。
  • CSTR_EQUAL。 lpString1 で示される文字列は、lpString2 で示される文字列と構文値で等価です。 2 つの文字列は並べ替えの目的で同等ですが、必ずしも同じではありません。
  • CSTR_GREATER_THAN。 lpString1 で示される文字列は、lpString2 で示される文字列よりも字句値が大きくなります。
成功しなかった場合、関数は 0 を返します。 拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。このエラー コードは、次のいずれかのエラー コードを返すことができます。
  • ERROR_INVALID_FLAGS。 フラグに指定された値が無効です。
  • ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効です。

注釈

DwCmpFlags が 0 またはNORM_IGNORECASEに設定されている場合、cchCount1 と cchCount2 は -1 に設定され、ロケールでは言語的な圧縮はサポートされません。従来のスペイン語の並べ替えでは "ch" が 1 文字として扱われる場合と同様に、CompareString と CompareStringEx の両方が最高速度で実行されるように最適化されています。

CompareString と CompareStringEx はどちらも、比較中にアラビア語のカシダを無視します。 したがって、2 つの文字列が、kashida の存在を除いて同一である場合、関数は CSTR_EQUALを返します。

アプリケーションが並べ替え関数でNORM_IGNORENONSPACEフラグとNORM_IGNORECASEフラグを使用すると、フラグが文字列比較に干渉することがあります。 この状況は、空白以外の文字や大文字と小文字をサポートしていないが、同等の重みレベルを使用して他の重要な操作を処理するロケールの場合に発生する可能性があります。 このような場合は、アプリケーションで LINGUISTIC_IGNOREDIACRITIC フラグと LINGUISTIC_IGNORECASE フラグを使用する必要があります。 これらのフラグは、大文字と小文字と分音記号を使用するコード ポイントを並べ替えるための言語的に適切な結果を提供し、他のコード ポイントには影響しません。

Windows Vista 以降: CompareString と CompareStringEx の両方で、カスタム ロケールからデータを取得できます。 データは、コンピューター間、またはアプリケーションの実行間で同じであるとは限りません。 アプリケーションでデータを永続化または送信する必要がある場合は、「 永続的なロケール データの使用」を参照してください。

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

Windows 8 以降: CompareStringEx は Stringapiset.h で宣言されています。 Windows 8する前は、Winnls.h で宣言されていました。

メモ 並べ替えの動作は、Windows リリース間で変更される可能性があります。 たとえば、新しい Unicode コード ポイントが作成される場合があります。 並べ替えバージョンが変更されたかどうかを検出するには、 GetNlsVersionEx を使用します。
 

例

この関数の使用方法を示す例については、「 NLS: 名前ベースの API サンプル」を参照してください。

要件

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

関連項目

[CompareString]

カスタム ロケール

アプリケーションでの並べ替えの処理

各国語サポート

各国語サポート関数

セキュリティに関する考慮事項: 国際的な機能

Unicode 正規化を使用して文字列を表す