LCMapStringW

識別子で指定されたロケールに対し、入力文字列を指定した変換で別の文字列へマップするか、入力文字列のソート キーを生成する。(Unicode)

LCMapStringW Locale, dwMapFlags, lpSrcStr, cchSrc, lpDestStr, cchDest

Locale : [int] ロケールを指定するロケール識別子。MAKELCID マクロでロケール識別子を作成するか、次の定義済み値のいずれかを指定する。
dwMapFlags : [int] 文字列マッピングで使う変換の種類、または生成するソート キーの種類を指定するフラグ。詳細は LCMapStringEx の dwMapFlags パラメータを参照のこと。
lpSrcStr : [wstr] 関数がマップまたはソート キー生成に使う変換元文字列へのポインタ。この文字列のサイズは 0 にできない。
cchSrc : [int] lpSrcStr が示す変換元文字列のサイズ（文字数単位）。変換元文字列のサイズには終端 null 文字を含めてもよいが、含めなくてもよい。終端 null 文字はソート不可能な文字として扱われ常に自分自身にマップされるため、含めても関数のマッピング動作に大きな影響はない。アプリケーションはこのパラメータに任意の負の値を指定して、変換元文字列が null 終端であることを示せる。この場合、LCMapString が文字列マッピング モードで使われているなら、関数は文字列長を自身で計算し、lpDestStr が示す変換後文字列を null 終端する。このパラメータを 0 にはできない。
lpDestStr : [wstr] この関数が変換後文字列またはソート キーを取得するバッファへのポインタ。アプリケーションがソート キー生成 (LCMAP_SORTKEY) に使う場合: - ソート キーはバッファに格納され、不透明なバイト配列として扱われる。格納値には任意の位置に 0 バイトが埋め込まれることがある。- 変換先文字列には奇数バイトが含まれることがある。LCMAP_BYTEREV フラグは偶数バイトのみを反転し、ソート キーの最後のバイト（奇数位置）は反転されない。呼び出し側が文字列の一部を明示的に要求した場合、cchDest で指定しない限り変換先文字列には終端 null 文字が含まれない。関数が失敗すると、変換先バッファには部分結果または何の結果も含まれないことがある。この場合、すべての結果を無効と見なすべきである。> [!NOTE] > LCMAP_UPPERCASE や LCMAP_LOWERCASE を設定するとき、変換先文字列は変換元文字列と同じバッファを使える。しかし、状況によってケース変換後の文字列の長さが変わる可能性があるため、これは強く非推奨である。
cchDest : [int] lpDestStr が示す変換先文字列のサイズ（文字数単位）。文字列マッピングに使う場合、このパラメータには文字数を指定する。cchSrc に終端 null 文字のための領域を含める場合、cchDest にも終端 null 文字のための領域を含めなければならない。ソート キー生成に使う場合はバイト数を指定する。このバイト数にはソート キーの 0x00 終端の領域を含めなければならない。cchDest を 0 にできる。この場合、関数は lpDestStr パラメータを使わず、変換後文字列またはソート キーに必要なバッファサイズを返す。

(プラグイン / モジュール : kernel32.dll)

解説

識別子で指定されたロケールに対し、入力文字列を指定した変換で別の文字列へマップするか、入力文字列のソート
キーを生成する。(Unicode)

[戻り値]
文字列マッピング用途で成功した場合、変換後文字列の文字数を返す（詳細は *cchSrc* および *cchDest*
を参照のこと）。ソート キー生成用途で成功した場合、ソート キーのバイト数を返す。成功しなかった場合は 0
を返す。拡張エラー情報を取得するには、アプリケーションから GetLastError を呼ぶ。次のいずれかのエラーコードが返ることがある:
（以下省略）

[備考]
LCMapStringEx の Remarks を参照のこと。LCMapString の ANSI
版は、指定したロケールに関連付けられた既定の Windows (ANSI) コードページを基に Unicode
との間で文字列をマップする。この関数の ANSI 版が Unicode 専用ロケールで使われた場合、OS はシステム既定の Windows
ANSI コードページを表す CP_ACP を使うので、関数は成功することがある。しかし、システム
コードページで未定義の文字は文字列内に疑問符 (?) として現れる。
> [!NOTE] > winnls.h ヘッダーは LCMapString を、UNICODE プリプロセッサ定数の定義に基づいて
ANSI 版か Unicode
版を自動選択するエイリアスとして定義している。エンコーディング中立のエイリアスとそうでないコードを混在させると、コンパイルまたは実行時エラーになるミスマッチが発生することがある。詳細は
[Conventions for Function
Prototypes](/windows/win32/intl/conventions-for-function-prototypes)
を参照のこと。

情報