FoldStringW

関数

文字列に指定の正規化マッピングを適用する。

DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

INT FoldStringW(
    FOLD_STRING_MAP_FLAGS dwMapFlags,
    LPCWSTR lpSrcStr,
    INT cchSrc,
    LPWSTR lpDestStr,   // optional
    INT cchDest
);

パラメーター

名前

型

方向

説明

dwMapFlags

FOLD_STRING_MAP_FLAGS

文字列のマッピング時に使用する変換の種類を指定するフラグです。このパラメーターには、次の値の組み合わせを指定できます。

フラグ	意味
MAP_COMPOSITE	アクセント付き文字を分解された文字、つまり基底文字と 1 つ以上の非スペース文字がそれぞれ個別のコードポイント値を持つ文字にマッピングします。たとえば Ä は A + ¨、すなわち LATIN CAPITAL LETTER A (U+0041) + COMBINING DIAERESIS (U+0308) で表されます。このフラグは Windows Vista における正規化形式 D に相当します。なお、このフラグは MB_PRECOMPOSED と併用できません。
MAP_EXPAND_LIGATURES	すべての合字文字を展開し、対応する 2 文字で表現します。たとえば合字「æ」(U+00e6) は 2 つの文字「a」(U+0061) + 「e」(U+0065) に展開されます。この値は MAP_PRECOMPOSED または MAP_COMPOSITE と組み合わせることはできません。
MAP_FOLDCZONE	互換ゾーンの文字を標準的な Unicode の等価文字に畳み込みます。MAP_COMPOSITE フラグも設定されている場合、このフラグは Windows Vista における正規化形式 KD に相当します。合成フラグが設定されていない場合(既定)、このフラグは Windows Vista における正規化形式 KC に相当します。
MAP_FOLDDIGITS	すべての数字を Unicode 文字の 0 から 9 にマッピングします。
MAP_PRECOMPOSED	アクセント付き文字を合成済み文字にマッピングします。合成済み文字では、アクセントと基底文字が 1 つの文字値に結合されています。このフラグは Windows Vista における正規化形式 C に相当します。この値は MAP_COMPOSITE と組み合わせることはできません。

lpSrcStr

LPCWSTR

この関数がマッピングするソース文字列へのポインターです。

cchSrc

INT

lpSrcStr で示されるソース文字列のサイズ(文字数)で、終端の null 文字は含みません。アプリケーションがこのパラメーターに任意の負の値を設定すると、ソース文字列が null 終端であることを指定できます。この場合、関数は文字列の長さを自動的に計算し、lpDestStr で示されるマッピング後の文字列を null 終端します。

lpDestStr

LPWSTR

outoptional

この関数がマッピング後の文字列を取得するバッファーへのポインターです。

cchDest

INT

lpDestStr で示される変換先文字列のサイズ(文字数)です。cchSrc に終端の null 文字分のスペースが含まれている場合、cchDest にも終端の null 文字分のスペースを含める必要があります。

アプリケーションは cchDest に 0 を設定できます。この場合、関数は lpDestStr パラメーターを使用せず、マッピング後の文字列に必要なバッファーサイズを返します。MAP_FOLDDIGITS フラグが指定されている場合、実際に必要な文字数が最大サイズより小さくても、戻り値は必要となる最大サイズになります。最大サイズが渡されない場合、関数は ERROR_INSUFFICIENT_BUFFER で失敗します。

戻り値の型: INT

公式ドキュメント

指定した変換を実行して、ある Unicode 文字列を別の文字列にマッピングします。(FoldStringW)

戻り値

成功した場合、終端の null 文字を含む変換後の文字列の文字数を返します。関数が成功し、かつ cchDest の値が 0 の場合、戻り値は終端の null 文字を含む変換後の文字列を格納するために必要なバッファーのサイズです。

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

ERROR_INSUFFICIENT_BUFFER。指定されたバッファーサイズが十分に大きくなかったか、誤って NULL に設定されていました。
ERROR_INVALID_DATA。データが無効でした。
ERROR_INVALID_FLAGS。フラグに指定された値が無効でした。
ERROR_INVALID_PARAMETER。いずれかのパラメーター値が無効でした。
ERROR_MOD_NOT_FOUND。モジュールが見つかりませんでした。
ERROR_OUTOFMEMORY。この操作を完了するための十分なストレージがありませんでした。
ERROR_PROC_NOT_FOUND。必要なプロシージャが見つかりませんでした。

解説(Remarks)

lpSrcStr パラメーターと lpDestStr パラメーターの値は同一であってはなりません。同一の場合、関数は ERROR_INVALID_PARAMETER で失敗します。

Unicode の互換ゾーンは、0xF900 から 0xFFEF の範囲にある文字で構成されます。これらは他の文字エンコーディング標準の文字に割り当てられていますが、実際には既に Unicode に存在する文字の異体字です。互換ゾーンは、これらの標準とのラウンドトリップマッピングをサポートするために使用されます。アプリケーションは MAP_FOLDCZONE フラグを使用することで、互換ゾーン内の文字の重複をサポートしなくて済むようにできます。

Windows Vista 以降: この関数は Unicode 正規化をサポートします。すべての Unicode 互換文字がマッピングされます。

Windows Vista 以降: MAP_FOLDCZONE、MAP_PRECOMPOSED、MAP_COMPOSITE の各フラグで示される変換は、マッピングを行うために(NormalizeString 関数を通じて)Unicode 正規化形式 KC、C、D を使用します。

Windows 8 以降: この関数の ANSI バージョンは Winnls.h で宣言され、Unicode バージョンは Stringapiset.h で宣言されています。Windows 8 より前は、両方のバージョンが Winnls.h で宣言されていました。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

INT FoldStringW(
    FOLD_STRING_MAP_FLAGS dwMapFlags,
    LPCWSTR lpSrcStr,
    INT cchSrc,
    LPWSTR lpDestStr,   // optional
    INT cchDest
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern int FoldStringW(
    uint dwMapFlags,   // FOLD_STRING_MAP_FLAGS
    [MarshalAs(UnmanagedType.LPWStr)] string lpSrcStr,   // LPCWSTR
    int cchSrc,   // INT
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder lpDestStr,   // LPWSTR optional, out
    int cchDest   // INT
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FoldStringW(
    dwMapFlags As UInteger,   ' FOLD_STRING_MAP_FLAGS
    <MarshalAs(UnmanagedType.LPWStr)> lpSrcStr As String,   ' LPCWSTR
    cchSrc As Integer,   ' INT
    <MarshalAs(UnmanagedType.LPWStr)> lpDestStr As System.Text.StringBuilder,   ' LPWSTR optional, out
    cchDest As Integer   ' INT
) As Integer
End Function

' dwMapFlags : FOLD_STRING_MAP_FLAGS
' lpSrcStr : LPCWSTR
' cchSrc : INT
' lpDestStr : LPWSTR optional, out
' cchDest : INT
Declare PtrSafe Function FoldStringW Lib "kernel32" ( _
    ByVal dwMapFlags As Long, _
    ByVal lpSrcStr As LongPtr, _
    ByVal cchSrc As Long, _
    ByVal lpDestStr As LongPtr, _
    ByVal cchDest As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FoldStringW = ctypes.windll.kernel32.FoldStringW
FoldStringW.restype = ctypes.c_int
FoldStringW.argtypes = [
    wintypes.DWORD,  # dwMapFlags : FOLD_STRING_MAP_FLAGS
    wintypes.LPCWSTR,  # lpSrcStr : LPCWSTR
    ctypes.c_int,  # cchSrc : INT
    wintypes.LPWSTR,  # lpDestStr : LPWSTR optional, out
    ctypes.c_int,  # cchDest : INT
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
FoldStringW = Fiddle::Function.new(
  lib['FoldStringW'],
  [
    -Fiddle::TYPE_INT,  # dwMapFlags : FOLD_STRING_MAP_FLAGS
    Fiddle::TYPE_VOIDP,  # lpSrcStr : LPCWSTR
    Fiddle::TYPE_INT,  # cchSrc : INT
    Fiddle::TYPE_VOIDP,  # lpDestStr : LPWSTR optional, out
    Fiddle::TYPE_INT,  # cchDest : INT
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn FoldStringW(
        dwMapFlags: u32,  // FOLD_STRING_MAP_FLAGS
        lpSrcStr: *const u16,  // LPCWSTR
        cchSrc: i32,  // INT
        lpDestStr: *mut u16,  // LPWSTR optional, out
        cchDest: i32  // INT
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern int FoldStringW(uint dwMapFlags, [MarshalAs(UnmanagedType.LPWStr)] string lpSrcStr, int cchSrc, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder lpDestStr, int cchDest);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_FoldStringW' -Namespace Win32 -PassThru
# $api::FoldStringW(dwMapFlags, lpSrcStr, cchSrc, lpDestStr, cchDest)

#uselib "KERNEL32.dll"
#func global FoldStringW "FoldStringW" wptr, wptr, wptr, wptr, wptr
; FoldStringW dwMapFlags, lpSrcStr, cchSrc, varptr(lpDestStr), cchDest   ; 戻り値は stat
; dwMapFlags : FOLD_STRING_MAP_FLAGS -> "wptr"
; lpSrcStr : LPCWSTR -> "wptr"
; cchSrc : INT -> "wptr"
; lpDestStr : LPWSTR optional, out -> "wptr"
; cchDest : INT -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global FoldStringW "FoldStringW" int, wstr, int, var, int
; res = FoldStringW(dwMapFlags, lpSrcStr, cchSrc, lpDestStr, cchDest)
; dwMapFlags : FOLD_STRING_MAP_FLAGS -> "int"
; lpSrcStr : LPCWSTR -> "wstr"
; cchSrc : INT -> "int"
; lpDestStr : LPWSTR optional, out -> "var"
; cchDest : INT -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global FoldStringW "FoldStringW" int, wstr, int, sptr, int
; res = FoldStringW(dwMapFlags, lpSrcStr, cchSrc, varptr(lpDestStr), cchDest)
; dwMapFlags : FOLD_STRING_MAP_FLAGS -> "int"
; lpSrcStr : LPCWSTR -> "wstr"
; cchSrc : INT -> "int"
; lpDestStr : LPWSTR optional, out -> "sptr"
; cchDest : INT -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。