次の方法で共有


LCMapStringEx 関数 (winnls.h)

名前で指定されたロケールの場合は、指定した変換を使用して入力文字列を別の文字列にマップするか、入力文字列の並べ替えキーを生成します。

メモ Windows Vista 以降でのみ実行するように設計されている場合、アプリケーションは LCMapString を優先してこの関数を呼び出す必要があります。

 

構文

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

パラメーター

[in, optional] lpLocaleName

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

[in] dwMapFlags

文字列マッピング中に使用する変換の種類または生成する並べ替えキーの型を指定するフラグ。 このパラメーターには、次の値を指定できます。

フラグ 説明
LCMAP_BYTEREV バイト反転を使用します。 たとえば、アプリケーションが 0x3450 0x4822 で渡された場合、結果は0x5034 0x2248。
LCMAP_FULLWIDTH 該当する場合は、Unicode (ワイド) 文字を使用します。 このフラグとLCMAP_HALFWIDTHは相互に排他的です。 このフラグを使用すると、入力文字が既に全角であっても、マッピングで正規化フォーム C が使用される場合があります。 たとえば、文字列 "は゛" (既に全角です) は "ば" に正規化されます。 Unicode の正規形をご覧ください。
LCMAP_HALFWIDTH 必要に応じて、狭い文字を使用します。 このフラグとLCMAP_FULLWIDTHは相互に排他的です。
LCMAP_HIRAGANA すべてのカタカナ文字をひらがなにマップします。 このフラグとLCMAP_KATAKANAは相互に排他的です。
LCMAP_KATAKANA すべてのひらがな文字をカタカナにマップします。 このフラグとLCMAP_HIRAGANAは相互に排他的です。
LCMAP_LINGUISTIC_CASING ファイル システム規則 (既定値) ではなく、大文字と小文字の区別に言語ルールを使用します。 このフラグは、LCMAP_LOWERCASEまたはLCMAP_UPPERCASEでのみ有効です。
LCMAP_LOWERCASE 大文字と小文字を処理できるロケールとスクリプトの場合は、すべての文字を小文字にマップします。
LCMAP_HASH 文字列の生の並べ替え重みのハッシュを返します。

通常、等価に表示される文字列は、同じハッシュを返します (たとえば、"hello" と "HELLO" with LCMAP_IGNORECASE)。 ただし、東アジア言語などの一部の複雑なケースでは、等しいと比較しても同じハッシュを返さない、同じ重みを持つ同じ文字列を含めることができます。

LCMAP_HASHでは、出力バッファーのサイズが sizeof(int) である必要があります
LCMAP_SIMPLIFIED_CHINESE 繁体字中国語を簡体字中国語にマップします。 このフラグとLCMAP_TRADITIONAL_CHINESEは相互に排他的です。
LCMAP_SORTHANDLE
並べ替えハンドルを使用すると、パフォーマンスが最小限に向上し、推奨されません。
ロケールの解決済み並べ替えパラメーター (ロケール名など) を表すトークンを返します。そのため、今後の呼び出しで並べ替え名を渡 NULL し、以前にクエリされた並べ替えハンドルを 、CompareStringEx または LCMapStringEx の後続の呼び出しで最後のパラメーター (sortHandle) として渡すことができます。

LCMAP_SORTHANDLEでは、出力バッファーのサイズが sizeof(lparam) である必要があります
LCMAP_SORTKEY 正規化された並べ替えキーを生成します。 LCMAP_SORTKEY フラグが指定されていない場合、関数は文字列マッピングを実行します。 並べ替えキーの生成と文字列マッピングの詳細については、「解説」セクションを参照してください。
LCMAP_TITLECASE Windows 7: すべての文字をタイトル ケースにマップします。このケースでは、各メジャー ワードの最初の文字が大文字になります。
LCMAP_TRADITIONAL_CHINESE 簡体字中国語を繁体字中国語にマップします。 このフラグとLCMAP_SIMPLIFIED_CHINESEは相互に排他的です。
LCMAP_UPPERCASE 大文字と小文字を処理できるロケールとスクリプトの場合は、すべての文字を大文字にマップします。

次のフラグは、単独で、互いに使用することも、LCMAP_SORTKEYフラグやLCMAP_BYTEREVフラグと共に使用することもできます。 ただし、上記の他のフラグと組み合わせることはできません。

フラグ 説明
NORM_IGNORENONSPACE
非スペーシング文字を無視します。 多くのスクリプト (特にラテン文字) の場合、NORM_IGNORENONSPACEはLINGUISTIC_IGNOREDIACRITICと一致します。
メモ NORM_IGNORENONSPACEは、区別記号の有無にかかわらず、二次的な区別を無視します。 韓国語、日本語、中国語、インド言語のスクリプトは、区別記号以外の目的でこの区別を使用します。 LINGUISTIC_IGNOREDIACRITIC、関数は、2 番目の並べ替えの重みを無視するのではなく、実際の分音記号のみを無視します。
 
NORM_IGNORESYMBOLS
記号と句読点を無視します。
 

以下に示すフラグは、LCMAP_SORTKEY フラグでのみ使用されます。

フラグ 説明
LINGUISTIC_IGNORECASE
言語的に適切な大文字と小文字は無視します。
LINGUISTIC_IGNOREDIACRITIC
言語的に適切なように、非スペーシング文字を無視します。
メモ このフラグは、分解された文字、つまり、基本文字と 1 つ以上の非スペーシング文字がそれぞれ異なるコード ポイント値を持つ文字と共に使用される場合、予測可能な結果を常に生成するとは限りません。
 
NORM_IGNORECASE
大文字と小文字を区別しない。 多くのスクリプト (特にラテン文字) の場合、NORM_IGNORECASEはLINGUISTIC_IGNORECASEと一致します。
メモ NORM_IGNORECASEは、実際に言語的なケースかどうかに関係なく、3 次的な区別を無視します。 たとえば、アラビア語とインド語のスクリプトでは、このフラグは文字の代替形式を区別しますが、違いは言語的なケースには対応していません。 LINGUISTIC_IGNORECASE、関数は、3 番目の並べ替え重みを無視するのではなく、実際の言語的大文字と小文字のみを無視します。
 
メモ 2 バイト文字セット (DBCS) ロケールの場合、NORM_IGNORECASEは、すべての Unicode 文字だけでなく、ギリシャ文字やキリル文字を含む狭い (1 バイト) 文字にも影響します。
 
NORM_IGNOREKANATYPE
ひらがなとカタカナの文字を区別しないでください。 対応するひらがなとカタカナの文字は等しいと比較されます。
NORM_IGNOREWIDTH
半角文字と全角文字の違いを無視します (例: C a t == cat)。 全角フォームは、中国語と日本語のスクリプトで使用される書式設定の区別です。
NORM_LINGUISTIC_CASING
ファイル システム規則 (既定値) ではなく、大文字と小文字の区別に言語ルールを使用します。
SORT_DIGITSASNUMBERS
Windows 7: 並べ替え時に数字を数値として扱います。たとえば、"10" の前に "2" を並べ替えます。
SORT_STRINGSORT
句読点は記号と同じように扱います。

[in] lpSrcStr

関数によってマップされるソース文字列か、関数によって並べ替えキーの生成に使用されるソース文字列へのポインター。 この文字列のサイズを 0 にすることはできません。

[in] cchSrc

lpSrcStr で示されるソース文字列のサイズ (文字単位)。 ソース文字列のサイズには終端の null 文字を含めることができますが、必要はありません。 終端の null 文字が含まれている場合、終了する null 文字は並べ替え不可能と見なされ、常にそれ自体にマップされるため、関数のマッピング動作は大きな影響を受けません。

アプリケーションでは、このパラメーターを任意の負の値に設定して、ソース文字列が null で終了することを指定できます。 この場合、 LCMapStringEx がその文字列マッピング モードで使用されている場合、関数は文字列の長さ自体を計算し、 lpDestStr で示されるマップされた文字列を null で終了します。

アプリケーションでは、このパラメーターを 0 に設定できません。

[out, optional] lpDestStr

この関数がマップされた文字列または並べ替えキーを取得するバッファーへのポインター。

アプリケーションが 関数を使用して並べ替えキーを生成する場合 (LCMAP_SORTKEY):

  • 並べ替えキーはバッファーに格納され、バイトの不透明な配列として扱われます。 格納された値には、任意の位置に埋め込まれた 0 バイトを含めることができます。
  • 変換先の文字列には奇数バイトを含めることができます。 LCMAP_BYTEREV フラグは、偶数バイトのみを反転します。 並べ替えキーの最後のバイト (奇数位置) は反転しません。

呼び出し元が文字列のサブセットを明示的に要求した場合、呼び出し元が cchDest で指定しない限り、宛先文字列に終端の null 文字は含まれません。

この関数が失敗した場合、宛先バッファーに部分的な結果が含まれているか、まったく結果が含まれない可能性があります。 この場合、すべての結果が無効と見なされます。

注意

LCMAP_UPPERCASEまたはLCMAP_LOWERCASEを設定する場合、変換先の文字列はソース文字列と同じバッファーを使用できます。 ただし、一部の条件により、返される大文字と小文字の文字列の長さが異なる場合があるため、これは強くお勧めしません。

[in] cchDest

lpDestStr で示される変換先文字列のサイズ (文字単位)。 アプリケーションが文字列マッピングに 関数を使用している場合は、このパラメーターの文字数を指定します。 終了する null 文字のスペースが cchSrc に含まれている場合、 cchDest には終端の null 文字のスペースも含める必要があります。

アプリケーションが関数を使用して並べ替えキーを生成している場合は、サイズのバイト数を指定します。 このバイト数には、並べ替えキー 0x00ターミネータの領域を含める必要があります。

アプリケーションは cchDest を 0 に設定できます。 この場合、関数は lpDestStr パラメーターを使用せず、マップされた文字列または並べ替えキーに必要なバッファー サイズを返します。

[in, optional] lpVersionInformation

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

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

[in, optional] lpReserved

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

[in, optional] sortHandle

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

注意

CompareStringExLCMapStringEx では、並べ替えハンドルを指定できます (ロケール名が null の場合)。 この使用は、ほとんどのアプリでは推奨されません。

戻り値

関数が文字列マッピングに使用されたときに成功した場合、変換された文字列の文字数が返されます (詳細については 、cchSrccchDest を参照してください)。

並べ替えキーの生成に使用されたときに関数が成功した場合は、並べ替えキーのバイト数が返されます。

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

  • ERROR_INSUFFICIENT_BUFFER。 指定されたバッファー サイズが十分に大きくなかったか、 正しく NULL に設定されていませんでした。
  • ERROR_INVALID_FLAGS。 フラグに指定された値が無効でした。
  • ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効です。

注釈

アプリケーションでは、 LCMapString または LCMapStringEx を使用して並べ替えキーを生成できます。 これを行うために、アプリケーションは dwMapFlags パラメーターのLCMAP_SORTKEYを指定します。 詳細については、「 アプリケーションでの並べ替えの処理」を参照してください

注意

並べ替えキーは不透明なバイト ストリームです。 呼び出し元は、API によって返される長さのバイト配列として扱う必要があり、存在しているように見える内部構造には依存しません。 0、返される並べ替えキーの 1 つ以上のバイトが 0 になる可能性があります。 0 バイトが存在しないか、存在しない必要があります。

アプリケーションで LCMapString または LCMapStringEx を使用するもう 1 つの方法は、マッピング文字列です。 この場合、アプリケーションは dwMapFlags パラメーターにLCMAP_SORTKEYを指定せず、他のフラグの組み合わせを提供します。 詳細については、「 アプリケーションでの並べ替えの処理」を参照してください

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

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

要件

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

関連項目

[CompareString]

FindNLSStringEx

GetNLSVersionEx

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

LCMapString

各国語サポート

各国語サポート関数