Expose winrt::impl::hstring_builder as winrt::hstring_builder

[lhecker]

winrt::impl::hstring_builder is a rather useful class. It can be used as the out parameter for various Win32 methods, avoiding the need for extra intermediate copies. The idea of making it public was also suggested in #1018.

Would it be feasible to create a public alias of hstring_builder?

[sylveon]

I ended up not making it public in my std::format support PR, because it requires some work to make safe for use with std::format. Would rather see that work happen before moving it out of the impl namespace to avoid locking the builder into unsafe by default.

[lhecker]

Ah sorry. I didn't know it was unsafe... Can you explain what makes winrt::impl::hstring_builder unsafe to use?

[sylveon]

There's no bounds checking, so something like format_to(back_inserter(builder)) will eventually buffer overflow.

[lhecker]

Ah okay... yeah but that's fine in this case, isn't it? Member functions called data() almost always return raw pointers including for boundary-checked classes like std::vector. Apart from the finalizing to_hstring(), the hstring_builder has no other member functions. Adding boundary checked iterators to the class in the future should thus be possible I believe.

[kennykerr]

It can be used as the out parameter for various Win32 methods

Can you give an example? HSTRING is not generally used with Win32 APIs. You're likely better off with something from the standard library.

[lhecker]

@kennykerr There are a number of Win32 APIs which offer an alternative mode returning the required number of output bytes. For instance CryptBinaryToStringW.
Personally I used it in some fairly disgusting code in combination with ReadProcessMemory here: https://github.com/microsoft/terminal/blob/479ef264b2d9e284db1fc8457f3897d1b19ac32e/src/cascadia/TerminalConnection/ConptyConnection.cpp#L587-L591
Due to the minimalism of the hstring_builder class I believe it's alright to make it public. In my personal opinion there's not much that could break the winrt::hstring_builder API, since that class has not much of an API to begin with. (...which is great!) 😄

[sylveon]

Yeah the get size then fill pattern is pretty common in C APIs. std::string is even getting support for it soon (resize_and_overwrite)

[kennykerr]

Thanks for the example. I typically use std::vector for this today but std::string/std::wstring support would be great. I'd like to keep C++/WinRT focused on API binding support and reduce, rather than increase, the number of random helpers that it has to support. Other libraries can and do fill the gaps.

[DHowett]

Is there a version of those things that automatically manages an HSTRING_REFERENCE to effect a zero-copy hstring?

[kennykerr]

@DHowett that's implemented by C++/WinRT automatically.

[sylveon]

hstring_builder seemingly taps into implementation details of hstring, so my hope by making that public is that we'd have a guarantee that it will work in the future or be updated to follow the implementation, unlike if we where to just copy it within our own project.

[kennykerr]

There is a public API for this. You can simply call WindowsPreallocateStringBuffer/WindowsPromoteStringBuffer/WindowsDeleteStringBuffer.

[lhecker]

Are you aware of an alternative API that works on Win7?

[kennykerr]

No, that's why C++/WinRT inlines all HSTRING support. But again your example doesn't need HSTRING support. You just need to preallocate a buffer which you can easily do today.

[sylveon]

The reason it's an hstring is because it ends up exposed as a public property:

https://github.com/microsoft/terminal/blob/479ef264b2d9e284db1fc8457f3897d1b19ac32e/src/cascadia/TerminalConnection/ConptyConnection.cpp#L352

But then this isn't really a hotpath (it gets called upon construction). Converting to hstring later sounds fine. And if they really want the best possible performance, then it's possible to wrap around WindowsPreallocateStringBuffer.