winrt::hstring struct (C++/WinRT)
A sequential collection of UTF-16 Unicode characters representing a text string. For more examples and info about winrt::hstring, see String handling in C++/WinRT.
The winrt::hstring type encapsulates HSTRING behind an interface similar to that of std::wstring. A HSTRING is a handle to a Windows Runtime string. For info about how to set an HSTRING into a winrt::hstring, and how to retrieve an HSTRING from a winrt::hstring, see Interoperating with the ABI's HSTRING.
Syntax
struct hstring
Requirements
Minimum supported SDK: Windows SDK version 10.0.17134.0 (Windows 10, version 1803)
Namespace: winrt
Header: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (included by default)
Member type aliases
| Alias name | Type |
|---|---|
| hstring::value_type | A synonym for wchar_t. |
| hstring::size_type | A synonym for uint32_t. |
| hstring::const_reference | A synonym for hstring::value_type const&. |
| hstring::const_pointer | A synonym for hstring::value_type const*. |
| hstring::const_iterator | A synonym for hstring::const_pointer. |
| hstring::const_reverse_iterator | A synonym for std::reverse_iterator<hstring::const_iterator>. |
Constructors
| Constructor | Description |
|---|---|
| hstring::hstring constructor | Initializes a new instance of the hstring struct with a copy of the input string data. |
Member functions
| Function | Description |
|---|---|
| hstring::back function | Returns a reference to the last character in the hstring object. |
| hstring::begin function | Returns a const iterator to the first character in the hstring object. |
| hstring::c_str function | Returns a pointer to the underlying null-terminated C-style string of the characters in the hstring object; no copy is made. |
| hstring::cbegin function | Returns a const iterator to the first character in the hstring object. |
| hstring::cend function | Returns a const iterator to one beyond the end of (one beyond the last character in) the hstring object. |
| hstring::clear function | Makes the hstring object empty. |
| hstring::crbegin function | Returns a const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object. |
| hstring::crend function | Returns a const reverse iterator to the first character in the hstring object. |
| hstring::data function | Returns a null-terminated C-style string version of the characters in the hstring object. |
| hstring::empty function | Returns a value indicating whether the hstring object is empty. |
| hstring::end function | Returns a const iterator to one beyond the end of (one beyond the last character in) the hstring object. |
| hstring::front function | Returns a reference to the first character in the hstring object. |
| hstring::rbegin function | Returns a const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object. |
| hstring::rend function | Returns a const reverse iterator to the first character in the hstring object. |
| hstring::size function | Returns the number of characters in the hstring object. |
Member operators
| Operator | Description |
|---|---|
| hstring::operator std::wstring_view | Converts the hstring object to a std::wstring_view. |
| hstring::operator[] (subscript operator)) | Returns a reference to the character at the specified position within the hstring object. |
| hstring::operator= (assignment operator) | Assigns a value to the hstring object. |
Free functions
| Function | Description |
|---|---|
| attach_abi function | Attaches a hstring object to a handle to a Windows Runtime string. |
| copy_from_abi function | Copies to a hstring object from a handle to a Windows Runtime string. Clears the hstring, copies the parameter, and begins managing the handle. |
| copy_to_abi function | Copies to a handle to a Windows Runtime string from a hstring object. |
| detach_abi function | Detaches a hstring object from its handle, perhaps to return it to a caller. |
| to_hstring function | Converts an input value to a winrt::hstring containing the value's string representation. |
Free operators
| Operator | Description |
|---|---|
| operator!= (inequality operator) | Returns a value indicating whether the two parameters are unequal to one another. |
| operator+ (concatenation operator) | Returns a new hstring object resulting from concatenating the two parameters together. |
| operator< (less-than operator) | Returns a value indicating whether the first parameter is less than the second parameter. |
| operator<= (less-than-or-equal-to operator) | Returns a value indicating whether the first parameter is less than or equal to the second parameter. |
| operator== (equality operator) | Returns a value indicating whether the two parameters are equal to one another. |
| operator> (greater-than operator) | Returns a value indicating whether the first parameter is greater than the second parameter. |
| operator>= (greater-than-or-equal-to operator) | Returns a value indicating whether the first parameter is greater than or equal to the second parameter. |
Iterators
An hstring is a range, and that range is defined by the hstring::begin and hstring::end member functions, each of which returns a const iterator (as do hstring::cbegin and hstring::cend). Because of this, you can enumerate the characters in an hstring object with either a range-based for statement, or with the std::for_each template function.
#include <iostream>
using namespace winrt;
...
void Iterators(hstring const& theHstring)
{
for (auto const& element : theHstring)
{
std::wcout << element;
}
std::for_each(theHstring.cbegin(), theHstring.cend(), [](T const& element) { std::wcout << element; });
}
hstring::hstring constructor
Initializes a new instance of the hstring struct with a copy of the input string data.
Syntax
hstring() noexcept;
hstring(winrt::hstring const& h);
explicit hstring(std::wstring_view const& v);
hstring(wchar_t const* c);
hstring(wchar_t const* c, uint32_t s);
Parameters
h
An hstring value that initializes the hstring object.
v
A std::wstring_view value that initializes the hstring object.
c
A pointer to an array of constant wchar_t that initializes the hstring object.
s
A number that specifies a fixed size for the hstring object.
Example
using namespace winrt;
...
void Constructors(
hstring const& theHstring,
std::wstring_view const& theWstringView,
wchar_t const* wideLiteral,
std::wstring const& wideString)
{
// hstring() noexcept
hstring fromDefault{};
// hstring(hstring const& h)
hstring fromHstring{ theHstring };
// explicit hstring(std::wstring_view const& value)
hstring fromWstringView{ theWstringView };
// hstring(wchar_t const* value)
hstring fromWideLiteral{ wideLiteral };
hstring fromWideString{ wideString.c_str() };
// hstring(wchar_t const* value, uint32_t size)
hstring fromWideLiteralWithSize{ wideLiteral, 256 };
hstring fromWideStringWithSize{ wideString.c_str(), 256 };
}
hstring::back function
Returns a reference to the last character in the hstring object.
Syntax
wchar_t const& back() const noexcept;
Return value
A reference to the last character in the hstring object.
hstring::begin function
Returns a const iterator to the first character in the hstring object. See Iterators.
Syntax
wchar_t const* begin() const noexcept;
Return value
A const iterator to the first character in the hstring object.
hstring::c_str function
Returns a pointer to the underlying null-terminated C-style string of the characters in the hstring object; no copy is made.
Syntax
wchar_t const* c_str() const noexcept;
Return value
A pointer to the underlying null-terminated C-style string of the characters in the hstring object; no copy is made.
Example
#include <iostream>
using namespace winrt;
...
void PrintHstring(hstring const& theHstring)
{
// You can get a standard wide string from an hstring.
std::wcout << theHstring.c_str() << std::endl;
}
hstring::cbegin function
Returns a const iterator to the first character in the hstring object. See Iterators.
Syntax
wchar_t const* cbegin() const noexcept;
Return value
A const iterator to the first character in the hstring object.
hstring::cend function
Returns a const iterator to one beyond the end of (one beyond the last character in) the hstring object. See Iterators.
Syntax
wchar_t const* cend() const noexcept;
Return value
A const iterator to one beyond the end of (one beyond the last character in) the hstring object.
hstring::clear function
Makes the hstring object empty.
Syntax
void clear() noexcept;
hstring::crbegin function
Returns a const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object.
Syntax
std::reverse_iterator<wchar_t const*> crbegin() const noexcept;
Return value
A const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object.
hstring::crend function
Returns a const reverse iterator to the first character in the hstring object.
Syntax
std::reverse_iterator<wchar_t const*> crend() const noexcept;
Return value
A const reverse iterator to the first character in the hstring object.
hstring::data function
Returns a null-terminated C-style string version of the characters in the hstring object.
Syntax
wchar_t const* data() const noexcept;
Return value
A null-terminated C-style string version of the characters in the hstring object.
Example
#include <iostream>
using namespace winrt;
...
void PrintHstring(hstring const& theHstring)
{
// You can get a standard wide string from an hstring.
std::wcout << theHstring.data() << std::endl;
}
hstring::empty function
Returns a value indicating whether the hstring object is empty.
Syntax
bool empty() const noexcept;
Return value
true if the hstring object is empty, otherwise false.
hstring::end function
Returns a const iterator to one beyond the end of (one beyond the last character in) the hstring object. See Iterators.
Syntax
wchar_t const* end() const noexcept;
Return value
A const iterator to one beyond the end of (one beyond the last character in) the hstring object.
hstring::front function
Returns a reference to the first character in the hstring object.
Syntax
wchar_t const& front() const noexcept;
Return value
A reference to the first character in the hstring object.
hstring::operator std::wstring_view
Converts the hstring object to a std::wstring_view.
Syntax
operator std::wstring_view() const noexcept;
Return value
The hstring object converted to a std::wstring_view.
Example
using namespace winrt;
...
Uri contosoUri{ L"https://www.contoso.com" };
Uri awUri{ L"https://www.adventure-works.com" };
// Uri::Domain() is of type hstring. But we can use hstring's conversion operator to std::wstring_view.
std::wstring domainWstring{ contosoUri.Domain() }; // L"contoso.com"
domainWstring = awUri.Domain(); // L"https://www.adventure-works.com"
hstring::operator[] (subscript operator)
Returns a reference to the character at the specified position within the hstring object.
Syntax
wchar_t const& operator[](uint32_t pos) const noexcept;
Parameters
pos
A zero-based character position, or index.
Return value
A reference to the character at the specified position within the hstring object.
hstring::operator= (assignment operator)
Assigns a value to the hstring object.
Syntax
winrt::hstring& operator=(winrt::hstring const& h);
winrt::hstring& operator=(std::wstring_view const& v);
Parameters
h
An hstring value to assign to the hstring object.
v
A std::wstring_view value to assign to the hstring object.
Return value
A reference to the hstring object.
hstring::rbegin function
Returns a const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object.
Syntax
std::reverse_iterator<wchar_t const*> rbegin() const noexcept;
Return value
A const reverse iterator to one beyond the end of (one beyond the last character in) the hstring object.
hstring::rend function
Returns a const reverse iterator to the first character in the hstring object.
Syntax
std::reverse_iterator<wchar_t const*> rend() const noexcept;
Return value
A const reverse iterator to the first character in the hstring object.
hstring::size function
Returns the number of characters in the hstring object.
Syntax
uint32_t size() const noexcept;
Return value
A uint32_t containing the number of characters in the hstring object.
attach_abi function
Attaches a hstring object to a handle to a Windows Runtime string.
Syntax
void attach_abi(winrt::hstring& object, HSTRING value) noexcept;
Parameters
object
A hstring object to operate on.
value
A handle to a Windows Runtime string.
copy_from_abi function
Copies to a hstring object from a handle to a Windows Runtime string. Clears the hstring, copies the parameter, and begins managing the handle.
Syntax
void copy_from_abi(winrt::hstring& object, HSTRING value);
Parameters
object
A hstring object to operate on.
value
A handle to a Windows Runtime string.
copy_to_abi function
Copies to a handle to a Windows Runtime string from a hstring object.
Syntax
void copy_to_abi(winrt::hstring const& object, HSTRING& value);
Parameters
object
A hstring object to operate on.
value
A handle reference, via which to copy the hstring's handle.
detach_abi function
Detaches a hstring object from its handle, perhaps to return it to a caller.
Syntax
HSTRING detach_abi(winrt::hstring& object) noexcept;
HSTRING detach_abi(winrt::hstring&& object) noexcept;
Parameters
object
A hstring object to operate on.
Return value
The handle to the Windows Runtime string.
operator!= (inequality operator)
Returns a value indicating whether the two parameters are unequal to one another.
Syntax
inline bool operator!=(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator!=(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator!=(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator!=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator!=(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the two parameters are unequal to one another, otherwise false.
operator+ (concatenation operator)
Returns a new hstring object resulting from concatenating the two parameters together.
Syntax
inline hstring operator+(winrt::hstring const& hLeft, winrt::hstring const& hRight);
inline hstring operator+(winrt::hstring const& hLeft, std::wstring const& wRight);
inline hstring operator+(winrt::hstring const& hLeft, std::wstring_view const& vRight);
inline hstring operator+(winrt::hstring const& hLeft, wchar_t const* cRight);
inline hstring operator+(winrt::hstring const& hLeft, wchar_t scRight);
inline hstring operator+(std::wstring const& wLeft, winrt::hstring const& hRight);
inline hstring operator+(std::wstring_view const& vLeft, winrt::hstring const& hRight);
inline hstring operator+(wchar_t const* cLeft, winrt::hstring const& hRight);
inline hstring operator+(wchar_t scLeft, winrt::hstring const& hRight);
Parameters
hLeft hRight
An hstring value to concatenate with the other parameter.
wLeft wRight
A std::wstring value to concatenate with the other parameter.
vLeft vRight
A std::wstring_view value to concatenate with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to concatenate with the other parameter.
scLeft scRight
A wchar_t to concatenate with the other parameter.
Return value
A new hstring object resulting from concatenating the two parameters together.
operator< (less-than operator)
Returns a value indicating whether the first parameter is less than the second parameter.
Syntax
inline bool operator<(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator<(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator<(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the first parameter is less than the second parameter, otherwise false.
operator<= (less-than-or-equal-to operator)
Returns a value indicating whether the first parameter is less than or equal to the second parameter.
Syntax
inline bool operator<=(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<=(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator<=(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator<=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<=(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the first parameter is less than or equal to the second parameter, otherwise false.
operator== (equality operator)
Returns a value indicating whether the two parameters are equal to one another.
Syntax
inline bool operator==(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator==(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator==(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator==(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator==(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the two parameters are equal to one another, otherwise false.
operator> (greater-than operator)
Returns a value indicating whether the first parameter is greater than the second parameter.
Syntax
inline bool operator>(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator>(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator>(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the first parameter is greater than the second parameter, otherwise false.
operator>= (greater-than-or-equal-to operator)
Returns a value indicating whether the first parameter is greater than or equal to the second parameter.
Syntax
inline bool operator>=(winrt::hstring const& hLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>=(winrt::hstring const& hLeft, std::wstring const& wRight) noexcept;
inline bool operator>=(winrt::hstring const& hLeft, wchar_t const* cRight) noexcept;
inline bool operator>=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>=(wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;
Parameters
hLeft hRight
An hstring value to compare with the other parameter.
wLeft wRight
A std::wstring value to compare with the other parameter.
cLeft cRight
A pointer to an array of constant wchar_t to compare with the other parameter.
Return value
true if the first parameter is greater than or equal to the second parameter, otherwise false.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for