potisanのプログラミングメモ

趣味のプログラマーがプログラミング関係で気になったことや調べたことをいつでも忘れられるようにメモするブログです。はてなブログ無料版なので記事の上の方はたぶん広告です。記事中にも広告挿入されるみたいです。

WIL GitHub Wiki 文字列ヘルパーの和訳・改変

MicrosoftがGitHubでMITライセンス公開しているWILのGitHub Wikiから文字列ヘルパーの記事を和訳・改変したものです。素人による翻訳なので、誤訳や著作権上の問題などありましたらご連絡いただけますと幸いです。

一部のリンク切れは意図的なものです。原文をご参照ください。

文字列ヘルパー

dabhattimsft、2020/2/27、リビジョン8個

WILの文字列ヘルパーは基本的な文字列操作として機能します。これはunique_cotaskmem_stringのようなWILリソースラッパー(RAII)に記載されたRAIIリソース型を増強します。

wil::make_something_string

この文字列生成関数は生のUnicode文字列ポインタ(まれにANSI文字列ポインタ)とオプションで長さを受け取ります。これは適切に特殊化されたunique_any_wrapperを返します。

文字列生成関数は次のパターンに従います。

unique_something_string make_something_string         (PCWSTR source, size_t length = -1);
unique_something_string make_something_string_nothrow (PCWSTR source, size_t length = -1);
unique_something_string make_something_string_failfast(PCWSTR source, size_t length = -1);

引数sourcenullptrの場合、関数はキャパシティlength + 1を持つバッファーに確保された長さ0の文字列を返します。

引数sourcenullptr以外の場合、関数はsourceの最初のlength文字とnull終端からなるキャパシティlength + 1の文字列バッファーを返します。sourcelength文字まで読み込まれます。

引数length-1の場合、関数はlength = wcslen(source)として動作します(この場合、sourcenullptrではないべきです)。

  • プレーン版はメモリを割り当てられない場合に例外を発生します。

  • nothrow番はメモリを割り当てられない場合に空のunique_something_stringを返します。

  • failfast版はメモリを割り当てられない場合にフェイルファストします。

有効な関数:

文字列型 生成関数 備考
unique_hlocal_string make_hlocal_string LocalFreeで解放されます。
unique_hlocal_ansistring make_hlocal_ansistring LocalFreeで解放されます。ANSI版です。
unique_hlocal_string_secure make_hlocal_string_secure ZeroMemoryLocalFreeで解放されます。
unique_process_heap_string make_process_heap_string HeapFreeで解放されます。
unique_cotaskmem_string make_cotaskmem_string CoTaskMemFreeで解放されます。
unique_bstr make_bstr SysFreeStringで解放されます。
unique_hglobal_string なし GlobalFreeで解放されます。
unique_hglobal_ansistring なし GlobalFreeで解放されます。 ANSI版です。
unique_hstring 下記参照 WindowsDeleteStringで解放されます。
template: string_type make_unique_string<string_type>等 string_typeに適切な方法で解放されます。

例:

auto string = wil::make_cotaskmem_string(L"sample string");

auto string = wil::make_cotaskmem_string(L"sample string", 3); // 戻り値は"sam"

auto string = wil::make_cotaskmem_string(nullptr, 5); // 5文字+null終端が確保される。

auto string = wil::make_cotaskmem_string_nothrow(L"sample string");
RETURN_IF_NULL_ALLOC(string);

auto string = wil::make_unique_string<wil::unique_cotaskmem_string>(L"sample string");

HSTRING_BUFFERs

WILはHSTRING_BUFFERからHSTRINGを二段階作成する補助メソッドを提供します。

// 定義:
HRESULT make_hstring_from_buffer_nothrow(unique_hstring_buffer&& source, _Out_ HSTRING* promoted);
unique_hstring make_hstring_from_buffer_failfast(unique_hstring_buffer&& source);
unique_hstring make_hstring_from_buffer(unique_hstring_buffer&& source);

// 使い方:
HRESULT Type::MakePath(_Out_ HSTRING* path)
{
    wchar_t* bufferStorage = nullptr;
    wil::unique_hstring_buffer theBuffer;
    RETURN_IF_FAILED(::WindowsPreallocateStringBuffer(65, &bufferStorage, &theBuffer));
    RETURN_IF_FAILED(::PathCchCombine(bufferStorage, 65, m_foo, m_bar));
    RETURN_IF_FAILED(wil::make_hstring_from_buffer_nothrow(wistd::move(theBuffer), path)));
    return S_OK;
}

wil::str_raw_ptr

このヘルパー関数はスマートオブジェクトが生のnull終端Unicode文字列ポインタ(PCWSTR)とみなせる場合、それをラップ解除します。

PCWSTR str_raw_ptr(anything);

「anything」引数は次のいずれかです。

  • PCWSTR(そのものを返します)
  • HSTRINGWindowsGetStringRawBufferを返します)
  • const std::wstring&c_str()を返します。stl.hが必要です)
  • unique_any_t<T>T再帰的にラップ解除します)

最後のルールは、例えばunique_hstringunique_cotaskmem_stringを渡せて、そのときunique_ptrを内部オブジェクト(HSTRINGPCWSTR)へラップ解除して、内部オブジェクトから生の文字列ポインタの取得を試みることを意味します。

wil::string_get_not_null

このヘルパー関数はスマートポインタ型のラップする文字列を返します。ただし、スマートポインタが空の場合は空文字列L""を返します。言い換えれば、この関数はnullptrL""へ変換します。

PCWSTR string_get_not_null(anything);

anythingPWSTRまたはPCWSTRを返すget()メソッドを持つ任意のオブジェクトです(訳註:std::wstring等の特殊化std::basic_stringget()メソッドを持たないので適用できません)。

wil::str_concat

これらの関数は任意個の文字列を受け取って結合します。

  • string_type str_concat<string_type>(...):結合した文字列を返します。失敗時は例外を発生します。
  • string_type str_concat_failfast<string_type>(...):結合した文字列を返します。失敗時はフェイルファストします。
  • HRESULT str_concat_nothrow(buffer, ...):文字列をbufferの既存の内容に結合します。成功か失敗を示すHRESULTを返します。

備考:

  • 文字列はそれぞれがstr_raw_ptrで生のポインタに解決できるオブジェクトの混合でも良いです。
  • 少なくとも1個の文字列を渡すべきです。nullptrは容認され、空文字列として扱われます。
  • string_typestring_makerのサポートする任意の型です。

wil::str_printf

これらの関数はprintfスタイルの書式化文字列と引数リストを受け取ります。戻り値はwil::details::string_makerにより割り当てられます。

  • string_type str_printf<string_type>(PCWSTR formatString, ...):書式化文字列を返します。失敗時は例外を発生します。
  • string_type str_printf_failfast<string_type>(PCWSTR formatString, ...):書式化文字列を返します。失敗時はフェイルファストします。
  • HRESULT str_printf_nothrow(buffer, ...):書式化文字列をbufferに割り当てます(bufferの既存の内容は上書きされます)。成功か失敗を示すHRESULTを返します。

例:

auto fullName = wil::str_printf<wil::unique_cotaskmem_string>(L"%ls %ls", firstName.get(), lastName.get());

auto fullName = wil::str_printf_failfast<wil::unique_cotaskmem_string>(L"%ls %ls", firstName.get(), lastName.get());

wil::unique_cotaskmem_string fullName;
RETURN_IF_FAILED(wil::str_printf_nothrow(fullName, L"%ls %ls", firstName.get(), lastName.get()));

こちらも参照

著作権表示

この記事は以下の著作物を使用しています。

Copyright (c) Microsoft Corporation. All rights reserved. https://github.com/microsoft/wil/blob/master/LICENSE