LCMapString

https://msdn.microsoft.com/ja-jp/library/cc709428.aspx https://msdn.microsoft.com/ja-jp/library/cc709430.aspx https://msdn.microsoft.com/ja-jp/library/ms776310.aspx

ある文字列に対してロケール依存の変換を実行し、別の文字列にマップします。入力文字列の並び替えキーを生成することもできます。

int LCMapString(
  LCID Locale,       // ロケール識別子
  DWORD dwMapFlags,  // マップ変換の種類
  LPCTSTR lpSrcStr,  // マップ元文字列のアドレス
  int cchSrc,        // マップ元文字列の文字数
  LPTSTR lpDestStr,  // マップ先バッファのアドレス
  int cchDest        // マップ先バッファのサイズ
);

パラメータ

Locale
ロケール識別子を指定します。このロケールは、文字列マッピング、または並び替えキー生成のコンテキストを提供します。使用できるロケール識別子は、MAKELCID マクロで作成されたものです。
dwMapFlags
文字列マッピング時の変換方法、または並び替えキーを生成するかどうか指定する一連のフラグをセットします。1 度の変換で複数のフラグをセットできますが、下に示しているように同時に使えないフラグもあります。次のフラグが定義されています。
定数意味
LCMAP_BYTEREVWindows NT のみ : バイト順序を反転します。たとえば 0x3450 と 0x4822 を渡すと、結果は 0x5034 と 0x2248 になります。
LCMAP_FULLWIDTH全角文字にします(適用される場合)。
LCMAP_HALFWIDTH半角文字にします(適用される場合)。
LCMAP_HIRAGANAひらがなにします。
LCMAP_KATAKANAカタカナにします。
LCMAP_LINGUISTIC_CASING大文字と小文字の区別に、ファイルシステムの規則(既定値)ではなく、言語上の規則を使います。LCMAP_LOWERCASE、または LCMAP_UPPERCASE とのみ組み合わせて使えます。
LCMAP_LOWERCASE小文字を使います。
LCMAP_SIMPLIFIED_CHINESE中国語の簡体字を繁体字にマップします。
LCMAP_SORTKEY正規化されたワイド文字並び替えキーを作成します。
LCMAP_TRADITIONAL_CHINESE中国語の繁体字を簡体字にマップします。
LCMAP_UPPERCASE大文字を使います。
NORM_IGNORECASE大文字と小文字を区別しません。
NORM_IGNOREKANATYPEひらがなとカタカナを区別しません。ひらがなとカタカナを同じと見なします。
NORM_IGNORENONSPACE送りなし文字を無視します。このフラグをセットすると、日本語アクセント文字も削除されます。
NORM_IGNORESYMBOLS記号を無視します。
NORM_IGNOREWIDTHシングルバイト文字と、ダブルバイトの同じ文字とを区別しません。
SORT_STRINGSORT区切り記号を記号と同じものとして扱います。

LCMAP_SORTKEY フラグをセットしない場合は、文字列マッピングが行われます。その場合、次の制限が適用されます。

  • LCMAP_LOWERCASE と LCMAP_UPPERCASE とは同時にセットできません。

  • LCMAP_HIRAGANA と LCMAP_KATAKANA とは同時にセットできません。

  • LCMAP_HALFWIDTH と LCMAP_FULLWIDTH とは同時にセットできません。

  • SORT_STRINGSORT、NORM_IGNOREKANATYPE、NORM_IGNOREWIDTH、NORM_IGNORECASE は無効です。

  • LCMAP_TRADITIONAL_CHINESE と LCMAP_SIMPLIFIED_CHINESE とは同時にセットできません。

  • LCMAP_HIRAGANA、LCMAP_KATAKANA、LCMAP_HALFWIDTH のいずれかのフラグと、LCMAP_FULLWIDTHLCMAP_LOWERCASE、LCMAP_UPPERCASE を組み合わせて使うことはできません。
    LCMAP_SORTKEY をセットした場合は、並び替えキーが生成されます。その場合、次の制限が適用されます。

  • LCMAP_BYTEREV を除く他のフラグは同時にセットできません。
lpSrcStr
マップ元文字列、または並び替えキーの生成に使う文字列へのポインタを指定します。
cchSrc
lpSrcStr パラメータが指す文字列のバイト数(ANSI 版)、または文字数(Unicode 版)を指定します。

この数に終端の NULL を含めることができます。また、含めなくてもかまいません。終端の NULL を文字数に含めても、マッピングの動作に大きく影響しません。NULL は並び替えできないと見なされ、常に NULL そのものにマップされるからです。

lpSrcStr パラメータが NULL で終わる文字列を指定する場合は、cchSrc パラメータに -1 を指定します。文字列マッピング時は、文字列の長さが関数によって計算され、*lpDestStr に格納されるマップ先の文字列の最後に NULL が付けられます。

lpDestStr
マップ先文字列、または並び替えキーを受け取るバッファへのポインタを指定します。

LCMAP_SORTKEY フラグをセットすると、並び替えキーが格納されます。並び替えキーは、バイト値の配列として次の形式で格納されます。

[すべての Unicode 並び替え重み] 0x01 [すべての発音区別重み] 0x01 [すべてのケース重み] 0x01 [すべての特殊重み] 0x00

cchSrc パラメータに渡す値にかかわらず、並び替えキーの最後には NULL が付けられます。また、dwMapFlags に1つ以上の無視フラグをセットし、並び替え重みの一部が並び替えキーに存在しないときでも、区切り文字の 0x01 と終端の 0x00 は存在します。

cchDest
lpDestStr パラメータが指すバッファのサイズをバイト数(ANSI 版)または文字数(Unicode 版)で指定します。

この関数で文字列マッピングを行うときは、文字数を指定します。cchSrc に終端の NULL を含める場合は、cchDest にも終端の NULL を含めなければなりません。

この関数で並び替えキーを生成するときは、バイト数を指定します。このバイト数には、並び替えキーの終端の 0x00 が含まなければなりません。

cchDest に 0 を渡すと、マップ先文字列または並び替えキーを保持するために必要な文字数またはバイト数(LCMAP_SORTKEY をセットした場合)が返ります。その場合、lpDestStr を指すバッファは使われません。

戻り値

cchDest パラメータの値が 0 以外の場合、関数が成功すると、バッファに書き込まれた文字数、またはバイト数(LCMAP_SORTKEY をセットした場合)が返ります。この数は、終端の NULL を含みます。
cchDest パラメータの値が 0 の場合、関数が成功すると、変換後の文字列または並び替えキーを受け取るために必要な文字数またはバイト数(LCMAP_SORTKEY をセットした場合)が返ります。この数は終端の NULL を含みます。
関数が失敗すると、0 が返ります。拡張エラー情報を取得するには、GetLastError 関数を使います。GetLastError 関数は、次のいずれかのエラーコードを返します。

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

解説

マップ元文字列が NULL で終わっていると、マップ先文字列も NULL で終わります。
この関数の A 版は、指定された LCID の既定 ANSI コードページに基づいて、Unicode との間で文字列をマップします。
カタカナをひらがなにマップする LCMAP_HIRAGANA フラグをセットし、LCMAP_FULLWIDTH フラグをセットしない場合は、全角文字だけがひらがなにマップされます。この場合、半角のカタカナはひらがなにマップされず、出力文字列に半角のまま残ります。半角のカタカナをひらがなにマップしたい場合は、LCMAP_FULLWIDTH をセットしてください。
lpSrcStr パラメータと lpDestStr パラメータは同じにできません。同じにすると、関数が失敗し、GetLastError 関数は ERROR_INVALID_PARAMETER を返します。
この関数のワイド文字 Unicode 版を呼び出しても、文字列マッピング時は、出力文字列が WCHAR または CHAR 形式にしかなりません。LCMAP_SORTKEY フラグをセットし、並び替えキー生成を行うときは、出力がバイト値の配列になります。並び替えキーは、バイト単位で比較することができます。
NORM_IGNORENONSPACE フラグと NORM_IGNORESYMBOLS フラグをセットし、他のすべてのフラグをクリアすると、入力文字列から文字だけを取り除くことができます。NULL で終わっていない入力文字列に対してこの操作を行うと、LCMapString が空の文字列を返し、エラーを返さないことがあります。

LCMapString 関数はアラビア Kashida を無視します。この関数でアラビア Kashida を含む文字列の並び替えキーを作成しても、Kashida の並び替えキーは存在しません。
ハイフンとアポストロフィは、並び替え時に coop と co-op のような単語が同一視されるように、他の区切り記号と少し異なる扱いをします。ハイフンとアポストロフィ以外の区切り記号は、すべて英数字の前に並び替えが行われます。この動作は、SORT_STRINGSORT フラグをセットすることで変更できます。詳細については、CompareString を参照してください。
LC_MAPSORTKEY フラグをセットし、並び替えキーを生成すると、*lpDestStr に格納される並び替えキーのバイト数が奇数になることがあります。バイト数が偶数のバイト列の順序を反転にするのは LCMAP_BYTEREV フラグ(Windows NT のみ)だけです。LC_MAPSORTKEY と LCMAP_BYTEREV の両方のフラグをセットすると、並び替えキーの最後の(偶数位置の)バイトは反転しません。終端の 0x00 が奇数位置のバイトである場合は、並び替えキーの最後の位置にそのまま残ります。終端の 0x00 が偶数位置のバイトである場合は、その直前のバイトと入れ替わります。

対応情報

  Windows NT/2000:Windows NT 3.1 以降
  Windows 95/98:Windows 95 以降
  ヘッダー:winnls.h 内で宣言
  インポートライブラリ:kernel32.lib を使用
Unicode:Windows NT/2000 は Unicode 版と ANSI 版を実装

参照

、、

表示: