winrt：：hstring 结构（C++/WinRT）

项目
08/17/2024

表示文本字符串的 UTF-16 Unicode 字符的顺序集合。有关 winrt：：hstring的详细信息，请参阅 C++/WinRT中的字符串处理。

winrt：：hstring 类型封装 HSTRING 的接口后面，类似于 std：：wstring。 HSTRING 是 Windows 运行时字符串的句柄。有关如何将 HSTRING 设置为 winrt：：hstring的信息，以及如何从 winrt：：hstring检索 HSTRING，请参阅与 ABI 的 HSTRING互操作。

语法

struct hstring

要求

受支持的最低 SDK： Windows SDK 版本 10.0.17134.0 （Windows 10 版本 1803）

Namespace： winrt

标头： %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h （默认包含）

成员类型别名

别名	类型
hstring：：value_type	wchar_t的同义词。
hstring：：size_type	uint32_t的同义词。
hstring：：const_reference	hstring：：value_type const&的同义词。
hstring：：const_pointer	hstring：：value_type const*的同义词。
hstring：：const_iterator	hstring：：const_pointer的同义词。
hstring：：const_reverse_iterator	std：：reverse_iterator<hstring：：const_iterator>的同义词。

构造函数

构造函数	描述
hstring：：hstring 构造函数	使用输入字符串数据的副本初始化 hstring 结构的新实例。

成员函数

功能	描述
hstring：：back 函数	返回对 hstring 对象中最后一个字符的引用。
hstring：：begin 函数	将常数迭代器返回到 hstring 对象中的第一个字符。
hstring：：c_str 函数	返回指向 hstring 对象中字符的基础以 null 结尾的 C 样式字符串的指针;未创建任何副本。
hstring：：cbegin 函数	将常数迭代器返回到 hstring 对象中的第一个字符。
hstring：：cend 函数	将常量迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。
hstring：：clear 函数	使 hstring 对象为空。
hstring：：crbegin 函数	将一个常量反向迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。
hstring：：crend 函数	返回 hstring 对象中的第一个字符的常数反向迭代器。
hstring：:d ata 函数	返回 hstring 对象中字符的以 null 结尾的 C 样式字符串版本。
hstring：：empty 函数	返回一个值，该值指示 hstring 对象是否为空。
hstring：：end 函数	将常量迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。
hstring：：front 函数	返回对 hstring 对象中第一个字符的引用。
hstring：：rbegin 函数	将一个常量反向迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。
hstring：：rend 函数	返回 hstring 对象中的第一个字符的常数反向迭代器。
hstring：：size 函数	返回 hstring 对象中的字符数。

成员运算符

算子	描述
hstring：：operator std：：wstring_view	将 hstring 对象转换为 std：：wstring_view。
hstring：：operator[] （下标运算符））	返回对 hstring 对象中指定位置的字符的引用。
hstring：：operator= （赋值运算符）	将值分配给 hstring 对象。

免费函数

功能	描述
attach_abi 函数	将 hstring 对象附加到 Windows 运行时字符串的句柄。
copy_from_abi 函数	将 hstring 对象从句柄复制到 Windows 运行时字符串。清除 hstring，复制参数并开始管理句柄。
copy_to_abi 函数	从 hstring 对象复制到 Windows 运行时字符串的句柄。
detach_abi 函数	将 hstring 对象从它的句柄中分离出来，或许可以将其返回到调用方。
to_hstring 函数	将输入值转换为包含值的字符串表示形式的 winrt：：hstring。

免费运算符

算子	描述
运算符！= （不等运算符）	返回一个值，该值指示这两个参数是否彼此不相等。
运算符+ （串联运算符）	返回一个新的 hstring 对象，该对象由将两个参数连接在一起。
运算符<（小于运算符）	返回一个值，该值指示第一个参数是否小于第二个参数。
运算符<=	返回一个值，该值指示第一个参数是否小于或等于第二个参数。
operator== （相等运算符）	返回一个值，该值指示这两个参数是否彼此相等。
运算符>（大于运算符）	返回一个值，该值指示第一个参数是否大于第二个参数。
运算符>=	返回一个值，该值指示第一个参数是否大于或等于第二个参数。

迭代器

hstring 是一个范围，该范围由 hstring：：begin 和 hstring：：end 成员函数定义，每个函数返回常量迭代器（hstring：：cbegin 和 hstring：：cend）。因此，可以使用基于区域的 for 语句或使用 std：：for_each 模板函数枚举 hstring 对象中的字符。

#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 构造函数

使用输入字符串数据的副本初始化 hstring 结构的新实例。

语法

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);

参数

h 初始化 hstring 对象的 hstring 值。

v 初始化 hstring 对象的 std：：wstring_view 值。

c 指向常量 wchar_t 数组的指针，该数组初始化 hstring 对象。

s 指定 hstring 对象的固定大小的数字。

例

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 函数

返回对 hstring 对象中最后一个字符的引用。

语法

wchar_t const& back() const noexcept;

返回值

对 hstring 对象中最后一个字符的引用。

hstring：：begin 函数

将常数迭代器返回到 hstring 对象中的第一个字符。请参阅迭代器。

语法

wchar_t const* begin() const noexcept;

返回值

hstring 对象中第一个字符的常客迭代器。

hstring：：c_str 函数

返回指向 hstring 对象中字符的基础以 null 结尾的 C 样式字符串的指针;未创建任何副本。

语法

wchar_t const* c_str() const noexcept;

返回值

指向 hstring 对象中字符的基础以 null 结尾的 C 样式字符串的指针;未创建任何副本。

例

#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 函数

将常数迭代器返回到 hstring 对象中的第一个字符。请参阅迭代器。

语法

wchar_t const* cbegin() const noexcept;

返回值

hstring 对象中第一个字符的常客迭代器。

hstring：：cend 函数

将常量迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。请参阅迭代器。

语法

wchar_t const* cend() const noexcept;

返回值

hstring 对象末尾之外的一个常量迭代器（超出最后一个字符）。

hstring：：clear 函数

使 hstring 对象为空。

语法

void clear() noexcept;

hstring：：crbegin 函数

将一个常量反向迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。

语法

std::reverse_iterator<wchar_t const*> crbegin() const noexcept;

返回值

一个常量将迭代器反向迭代器反转为 hstring 对象末尾之外的迭代器（一个超出最后一个字符）。

hstring：：crend 函数

返回 hstring 对象中的第一个字符的常数反向迭代器。

语法

std::reverse_iterator<wchar_t const*> crend() const noexcept;

返回值

hstring 对象中的第一个字符的常客反转迭代器。

hstring：:d ata 函数

返回 hstring 对象中字符的以 null 结尾的 C 样式字符串版本。

语法

wchar_t const* data() const noexcept;

返回值

hstring 对象中字符的以 null 结尾的 C 样式字符串版本。

例

#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 函数

返回一个值，该值指示 hstring 对象是否为空。

语法

bool empty() const noexcept;

返回值

如果 hstring 对象为空，则为 true;否则为 false。

hstring：：end 函数

将常量迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。请参阅迭代器。

语法

wchar_t const* end() const noexcept;

返回值

hstring 对象末尾之外的一个常量迭代器（超出最后一个字符）。

hstring：：front 函数

返回对 hstring 对象中第一个字符的引用。

语法

wchar_t const& front() const noexcept;

返回值

对 hstring 对象中第一个字符的引用。

hstring：：operator std：：wstring_view

将 hstring 对象转换为 std：：wstring_view。

语法

operator std::wstring_view() const noexcept;

返回值

转换为 std：：wstring_view的 hstring 对象。

例

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[] （下标运算符）

返回对 hstring 对象中指定位置的字符的引用。

语法

wchar_t const& operator[](uint32_t pos) const noexcept;

参数

pos 从零开始的字符位置或索引。

返回值

对 hstring 对象中指定位置的字符的引用。

hstring：：operator= （赋值运算符）

将值分配给 hstring 对象。

语法

winrt::hstring& operator=(winrt::hstring const& h);
winrt::hstring& operator=(std::wstring_view const& v);

参数

h 要分配给 hstring 对象的 hstring 值。

v 要分配给 hstring 对象的 std：：wstring_view 值。

返回值

对 hstring 对象的引用。

hstring：：rbegin 函数

将一个常量反向迭代器返回到 hstring 对象末尾（最后一个字符超出最后一个字符）的迭代器。

语法

std::reverse_iterator<wchar_t const*> rbegin() const noexcept;

返回值

一个常量将迭代器反向迭代器反转为 hstring 对象末尾之外的迭代器（一个超出最后一个字符）。

hstring：：rend 函数

返回 hstring 对象中的第一个字符的常数反向迭代器。

语法

std::reverse_iterator<wchar_t const*> rend() const noexcept;

返回值

hstring 对象中的第一个字符的常客反转迭代器。

hstring：：size 函数

返回 hstring 对象中的字符数。

语法

uint32_t size() const noexcept;

返回值

包含 hstring 对象中的字符数的 uint32_t。

attach_abi 函数

将 hstring 对象附加到 Windows 运行时字符串的句柄。

语法

void attach_abi(winrt::hstring& object, HSTRING value) noexcept;

参数

object 要操作的 hstring 对象。

value Windows 运行时字符串的句柄。

copy_from_abi 函数

将 hstring 对象从句柄复制到 Windows 运行时字符串。清除 hstring，复制参数并开始管理句柄。

语法

void copy_from_abi(winrt::hstring& object, HSTRING value);

参数

object 要操作的 hstring 对象。

value Windows 运行时字符串的句柄。

copy_to_abi 函数

从 hstring 对象复制到 Windows 运行时字符串的句柄。

语法

void copy_to_abi(winrt::hstring const& object, HSTRING& value);

参数

object 要操作的 hstring 对象。

value 句柄引用，通过该引用复制 hstring的句柄。

detach_abi函数

将 hstring 对象从它的句柄中分离出来，或许可以将其返回到调用方。

语法

HSTRING detach_abi(winrt::hstring& object) noexcept;
HSTRING detach_abi(winrt::hstring&& object) noexcept;

参数

object 要操作的 hstring 对象。

返回值

Windows 运行时字符串的句柄。

operator！= （不等运算符）

返回一个值，该值指示这两个参数是否彼此不相等。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果两个参数彼此不相等，则 true 否则 false。

operator+ （串联运算符）

返回一个新的 hstring 对象，该对象由将两个参数连接在一起。

语法

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);

参数

hLeft hRight 要与其他参数连接 hstring 值。

wLeft wRight 要与其他参数连接 std::wstring 值。

vLeft vRight std：：wstring_view 值以与其他参数连接。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数连接。

scLeft scRight 要与其他参数连接 wchar_t A。

返回值

一个新的 hstring 对象，由将两个参数串联在一起。

运算符<（小于运算符）

返回一个值，该值指示第一个参数是否小于第二个参数。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果第一个参数小于第二个参数，则 true 否则 false。

运算符<= （小于或等于运算符）

返回一个值，该值指示第一个参数是否小于或等于第二个参数。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果第一个参数小于或等于第二个参数，则 true 否则 false。

operator== （相等运算符）

返回一个值，该值指示这两个参数是否彼此相等。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果两个参数彼此相等，则 true 否则 false。

运算符>（大于运算符）

返回一个值，该值指示第一个参数是否大于第二个参数。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果第一个参数大于第二个参数，则 true 否则 false。

运算符>= （大于或等于运算符）

返回一个值，该值指示第一个参数是否大于或等于第二个参数。

语法

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;

参数

hLeft hRight 要与其他参数进行比较的 hstring 值。

wLeft wRight 要与其他参数进行比较的 std::wstring 值。

cLeft cRight 指向常量数组的指针，wchar_t 与其他参数进行比较。

返回值

如果第一个参数大于或等于第二个参数，则 true 否则 false。

另请参阅

winrt 命名空间
C++/WinRT 中的字符串处理

通过

winrt：：hstring 结构（C++/WinRT）

语法

要求

成员类型别名

构造 函数

成员函数

成员运算符

免费函数

免费运算符

迭代器

hstring：：hstring 构造函数

语法

参数

例

hstring：：back 函数

语法

返回值

hstring：：begin 函数

语法

返回值

hstring：：c_str 函数

语法

返回值

例

hstring：：cbegin 函数

语法

返回值

hstring：：cend 函数

语法

返回值

hstring：：clear 函数

语法

hstring：：crbegin 函数

语法

返回值

hstring：：crend 函数

语法

返回值

hstring：:d ata 函数

语法

返回值

例

hstring：：empty 函数

语法

返回值

hstring：：end 函数

语法

返回值

hstring：：front 函数

语法

返回值

hstring：：operator std：：wstring_view

语法

返回值

例

hstring：：operator[] （下标运算符）

语法

参数

返回值

hstring：：operator= （赋值运算符）

语法

参数

返回值

hstring：：rbegin 函数

语法

返回值

hstring：：rend 函数

语法

返回值

hstring：：size 函数

语法

返回值

attach_abi 函数

语法

参数

copy_from_abi 函数

语法

参数

copy_to_abi 函数

构造函数