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);
引数source
がnullptr
の場合、関数はキャパシティlength + 1
を持つバッファーに確保された長さ0の文字列を返します。
引数source
がnullptr
以外の場合、関数はsource
の最初のlength
文字とnull終端からなるキャパシティlength + 1
の文字列バッファーを返します。source
はlength
文字まで読み込まれます。
引数length
が-1
の場合、関数はlength = wcslen(source)
として動作します(この場合、source
はnullptr
ではないべきです)。
プレーン版はメモリを割り当てられない場合に例外を発生します。
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 等 |
ZeroMemory とLocalFree で解放されます。 |
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
(そのものを返します)HSTRING
(WindowsGetStringRawBuffer
を返します)const std::wstring&
(c_str()
を返します。stl.hが必要です)unique_any_t<T>
(T
を再帰的にラップ解除します)
最後のルールは、例えばunique_hstring
、unique_cotaskmem_string
を渡せて、そのときunique_ptr
を内部オブジェクト(HSTRING
やPCWSTR
)へラップ解除して、内部オブジェクトから生の文字列ポインタの取得を試みることを意味します。
wil::string_get_not_null
このヘルパー関数はスマートポインタ型のラップする文字列を返します。ただし、スマートポインタが空の場合は空文字列L""
を返します。言い換えれば、この関数はnullptr
をL""
へ変換します。
PCWSTR string_get_not_null(anything);
anything
はPWSTR
またはPCWSTR
を返すget()
メソッドを持つ任意のオブジェクトです(訳註:std::wstring
等の特殊化std::basic_string
はget()
メソッドを持たないので適用できません)。
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_type
はstring_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