winrt::hstring 结构 (C++/WinRT)

项目
02/05/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)

命名空间： 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 。

免费运算符

运算符	说明
operator！= (不相等运算符)	返回一个值，该值指示这两个参数是否不相等。
operator+ (串联运算符)	返回一个新的 hstring 对象，该对象由两个参数连接在一起而生成。
运算符< (小于运算符)	返回一个值，该值指示第一个参数是否小于第二个参数。
operator<= (小于或等于运算符)	返回一个值，该值指示第一个参数是否小于或等于第二个参数。
operator== (相等运算符)	返回一个值，该值指示两个参数是否相等。
运算符> (大于运算符)	返回一个值，该值指示第一个参数是否大于第二个参数。
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指向初始化 hstring 对象的常量wchar_t数组的指针。

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;

返回值

true 如果 hstring 对象为空，则为 ;否则为 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 对象中第一个字符的 const 反向迭代器。

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 对象。

valueWindows 运行时字符串的句柄。

copy_from_abi 函数

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

语法

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

参数

object 要操作的 hstring 对象。

valueWindows 运行时字符串的句柄。

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;

参数

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

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

cLeftcRight 指向常量数组 的指针，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);

参数

hLefthRight 要与其他参数串联的 hstring 值。

wLeftwRight 要 std::wstring 与其他参数连接的值。

vLeftvRight 要与其他参数连接wstring_view std：：wstring_view 值。

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

scLeftscRight 要与其他参数连接 wchar_t 。

返回值

将两个参数串联在一起生成的新 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;

参数

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

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

cLeftcRight 指向常量数组 的指针，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;

参数

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

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

cLeftcRight 指向常量数组 的指针，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;

参数

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

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

cLeftcRight 指向常量数组 的指针，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;

参数

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

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

cLeftcRight 指向常量数组 的指针，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;

参数

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

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

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

返回值

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

通过

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