LCMapStringEx 関数 (winnls.h)
名前で指定されたロケールの場合は、指定した変換を使用して入力文字列を別の文字列にマップするか、入力文字列の並べ替えキーを生成します。
構文
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フラグと共に使用することもできます。 ただし、上記の他のフラグと組み合わせることはできません。
以下に示すフラグは、LCMAP_SORTKEY フラグでのみ使用されます。
[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 である必要があります。
注意
CompareStringEx と LCMapStringEx では、並べ替えハンドルを指定できます (ロケール名が null の場合)。 この使用は、ほとんどのアプリでは推奨されません。
戻り値
関数が文字列マッピングに使用されたときに成功した場合、変換された文字列の文字数が返されます (詳細については 、cchSrc と cchDest を参照してください)。
並べ替えキーの生成に使用されたときに関数が成功した場合は、並べ替えキーのバイト数が返されます。
成功しなかった場合、この関数は 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 |