FoldStringA

関数

ANSI文字列に対し正規化など指定の変換を適用する。

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

シグネチャ

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

INT FoldStringA(
    FOLD_STRING_MAP_FLAGS dwMapFlags,
    LPCSTR lpSrcStr,
    INT cchSrc,
    LPSTR 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	アクセント付き文字を合成済み文字、すなわちアクセントと基底文字が単一の文字値に結合された文字にマップします。このフラグは Windows Vista における正規化形式 C に相当します。この値は MAP_COMPOSITE と組み合わせることはできません。

lpSrcStr

LPCSTR

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

cchSrc

INT

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

lpDestStr

LPSTR

outoptional

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

cchDest

INT

lpDestStr で示される宛先文字列のサイズ(文字数単位)。終端の null 文字のための領域が cchSrc に含まれている場合、cchDest にも終端の null 文字のための領域を含める必要があります。

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

戻り値の型: INT

公式ドキュメント

指定された変換を実行して、ある Unicode 文字列を別の文字列にマップします。(FoldStringA)

戻り値

成功した場合、終端の 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  (ANSI / -A)
#include <windows.h>

INT FoldStringA(
    FOLD_STRING_MAP_FLAGS dwMapFlags,
    LPCSTR lpSrcStr,
    INT cchSrc,
    LPSTR lpDestStr,   // optional
    INT cchDest
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern int FoldStringA(
    uint dwMapFlags,   // FOLD_STRING_MAP_FLAGS
    [MarshalAs(UnmanagedType.LPStr)] string lpSrcStr,   // LPCSTR
    int cchSrc,   // INT
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpDestStr,   // LPSTR optional, out
    int cchDest   // INT
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FoldStringA(
    dwMapFlags As UInteger,   ' FOLD_STRING_MAP_FLAGS
    <MarshalAs(UnmanagedType.LPStr)> lpSrcStr As String,   ' LPCSTR
    cchSrc As Integer,   ' INT
    <MarshalAs(UnmanagedType.LPStr)> lpDestStr As System.Text.StringBuilder,   ' LPSTR optional, out
    cchDest As Integer   ' INT
) As Integer
End Function

' dwMapFlags : FOLD_STRING_MAP_FLAGS
' lpSrcStr : LPCSTR
' cchSrc : INT
' lpDestStr : LPSTR optional, out
' cchDest : INT
Declare PtrSafe Function FoldStringA Lib "kernel32" ( _
    ByVal dwMapFlags As Long, _
    ByVal lpSrcStr As String, _
    ByVal cchSrc As Long, _
    ByVal lpDestStr As String, _
    ByVal cchDest As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FoldStringA = ctypes.windll.kernel32.FoldStringA
FoldStringA.restype = ctypes.c_int
FoldStringA.argtypes = [
    wintypes.DWORD,  # dwMapFlags : FOLD_STRING_MAP_FLAGS
    wintypes.LPCSTR,  # lpSrcStr : LPCSTR
    ctypes.c_int,  # cchSrc : INT
    wintypes.LPSTR,  # lpDestStr : LPSTR 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')
FoldStringA = Fiddle::Function.new(
  lib['FoldStringA'],
  [
    -Fiddle::TYPE_INT,  # dwMapFlags : FOLD_STRING_MAP_FLAGS
    Fiddle::TYPE_VOIDP,  # lpSrcStr : LPCSTR
    Fiddle::TYPE_INT,  # cchSrc : INT
    Fiddle::TYPE_VOIDP,  # lpDestStr : LPSTR optional, out
    Fiddle::TYPE_INT,  # cchDest : INT
  ],
  Fiddle::TYPE_INT)

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

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

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

出力引数:

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