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 函式	將 const 反覆運算器傳回 hstring 物件中的第一個字元。
hstring：：c_str 函式	傳回 hstring 物件中字元之基礎 null 終止 C 樣式字串的指標;未製作任何複本。
hstring：：cbegin 函式	將 const 反覆運算器傳回 hstring 物件中的第一個字元。
hstring：：cend 函式	將 const 反覆運算器傳回至 hstring 物件結尾之後的常數反覆運算器。
hstring：：clear 函式	讓 hstring 物件空白。
hstring：：crbegin 函式	將 const 反向反覆運算器傳回至 hstring 物件結尾之後的反轉反覆運算器。
hstring：：crend 函式	將 const 反向反覆運算器傳回 hstring 物件中的第一個字元。
hstring：:d ata 函式	傳回 hstring 物件中字元的 Null 終止 C 樣式字串版本。
hstring：：empty 函式	傳回值，指出 hstring 物件是否空白。
hstring：：end 函式	將 const 反覆運算器傳回至 hstring 物件結尾之後的常數反覆運算器。
hstring：：front 函式	傳回 hstring 物件中第一個字元的參考。
hstring：：rbegin 函式	將 const 反向反覆運算器傳回至 hstring 物件結尾之後的反轉反覆運算器。
hstring：：rend 函式	將 const 反向反覆運算器傳回 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 成員函式所定義，每個函式都會傳回 const 反覆運算器（如 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 函式

將 const 反覆運算器傳回 hstring 物件中的第一個字元。請參閱反覆運算器。

語法

wchar_t const* begin() const noexcept;

傳回值

hstring 物件中第一個字元的 const 反覆運算器。

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

將 const 反覆運算器傳回 hstring 物件中的第一個字元。請參閱反覆運算器。

語法

wchar_t const* cbegin() const noexcept;

傳回值

hstring 物件中第一個字元的 const 反覆運算器。

hstring：：cend 函式

將 const 反覆運算器傳回至 hstring 物件結尾之後的常數反覆運算器。請參閱反覆運算器。

語法

wchar_t const* cend() const noexcept;

傳回值

const 反覆運算器，指向 hstring 物件結尾之後的反覆運算器。

hstring：：clear 函式

讓 hstring 物件空白。

語法

void clear() noexcept;

hstring：：crbegin 函式

將 const 反向反覆運算器傳回至 hstring 物件結尾之後的反轉反覆運算器。

語法

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

傳回值

const 將反覆運算器反轉為 hstring 物件結尾之後的反覆運算器。

hstring：：crend 函式

將 const 反向反覆運算器傳回 hstring 物件中的第一個字元。

語法

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

傳回值

const 反向反覆運算器，指向 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 函式

將 const 反覆運算器傳回至 hstring 物件結尾之後的常數反覆運算器。請參閱反覆運算器。

語法

wchar_t const* end() const noexcept;

傳回值

const 反覆運算器，指向 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;

傳回值

hstring 物件轉換成 std：：wstring_view。

例

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

將 const 反向反覆運算器傳回至 hstring 物件結尾之後的反轉反覆運算器。

語法

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

傳回值

const 將反覆運算器反轉為 hstring 物件結尾之後的反覆運算器。

hstring：：rend 函式

將 const 反向反覆運算器傳回 hstring 物件中的第一個字元。

語法

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

傳回值

const 反向反覆運算器，指向 hstring 物件中的第一個字元。

hstring：：size 函式

傳回 hstring 物件中的字元數。

語法

uint32_t size() const noexcept;

傳回值

uint32_t，包含 hstring 物件中的字元數。

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 要與其他參數串連的 A 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;

參數

hLeft hRight 要與其他參數比較的 hstring 值。

wLeft wRight 要與其他參數比較的 std::wstring 值。

cLeft cRight 要與其他參數比較之常數陣列的指標 wchar_t。

傳回值

如果第一個參數小於第二個參數，則 true，否則 false。

operator<= （less-than-or-equal-to 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== （等號運算符）

傳回值，指出兩個參數是否彼此相等。

語法

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。

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。

另請參閱

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

winrt：：hstring 結構（C++/WinRT）

構造函數