Структура winrt::hstring (C++/WinRT)

Последовательная коллекция символов Юникода UTF-16, представляющая текстовую строку. Дополнительные примеры и сведения о winrt::hstring см. в разделе "Обработка строк" в C++/WinRT. Тип winrt::hstring инкапсулирует HSTRING за интерфейсом, аналогичным интерфейсу std::wstring. HSTRING — это дескриптор строки среда выполнения Windows.

Синтаксис

struct hstring

Требования

Минимальный поддерживаемый пакет SDK: пакет SDK Windows версии 10.0.17134.0 (Windows 10 версии 1803)

Пространство имен: winrt

Заголовок: %WindowsSdkDir%IncludeWindowsTargetPlatformVersion<>\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 Возвращает указатель на базовую строку, завершающуюся значением NULL, в стиле C символов в объекте hstring ; копирование не производится.
Функция hstring::cbegin Возвращает константный итератор первому символу в объекте hstring .
Функция hstring::cend Возвращает константный итератор к одному за пределами (один за последним символом) объекта hstring .
Функция hstring::clear Делает объект hstring пустым.
Функция hstring::crbegin Возвращает константный обратный итератор к одному за пределами (один за последним символом) объекта hstring .
Функция hstring::crend Возвращает константный обратный итератор к первому символу в объекте hstring .
функция hstring::d ata Возвращает строку в стиле C, завершающуюся null, версию символов в объекте hstring .
Функция 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[] (оператор subscript)) Возвращает ссылку на символ в указанной позиции в объекте hstring .
hstring::operator= (оператор присваивания) Присваивает значение объекту hstring .

Бесплатные функции

Функция Описание
Функция attach_abi Присоединяет объект hstring к дескриптором к строке среда выполнения Windows.
Функция copy_from_abi Копирует в объект hstring из дескриптора в строку среда выполнения Windows. Очищает строку, копирует параметр и начинает управлять дескриптором.
Функция copy_to_abi Копирует в дескриптор в строку среда выполнения Windows из объекта hstring.
Функция detach_abi Отсоединяет объект hstring от его дескриптора, возможно, чтобы вернуть его вызывающему объекту.
Функция to_hstring Преобразует входное значение в winrt::hstring , содержащее строковое представление значения.

Бесплатные операторы

Оператор Описание
operator!= (оператор неравенства) Возвращает значение, указывающее, не совпадают ли два параметра друг с другом.
operator+ (оператор объединения) Возвращает новый объект hstring , полученный из объединения двух параметров.
operator< (оператор less-than) Возвращает значение, указывающее, меньше ли первый параметр, чем второй.
operator<= (оператор меньше или равно) Возвращает значение, указывающее, меньше или равен ли первый параметр второму параметру.
operator== (оператор равенства) Возвращает значение, указывающее, равны ли два параметра друг другу.
оператор> (оператор больше) Возвращает значение, указывающее, больше ли первый параметр, чем второй параметр.
operator>= (оператор больше или равно) Возвращает значение, указывающее, больше или равен ли первый параметр второму параметру.

Iterators

Hstring — это диапазон, и этот диапазон определяется функциями-членами hstring::begin и hstring::end, каждый из которых возвращает константный итератор (как и hstring::cbegin и hstring::cend). Из-за этого можно перечислить символы в объекте hstring с помощью инструкции на основе for диапазона или с помощью функции шаблона std::for_each .

#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(std::wchar_t const* c);
hstring(std::wchar_t const* c, uint32_t s);

Параметры

h Значение hstring , которое инициализирует объект hstring .

v Значение std::wstring_view , которое инициализирует объект hstring .

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 .

Синтаксис

std::wchar_t const& back() const noexcept;

Возвращаемое значение

Ссылка на последний символ в объекте hstring .

Функция hstring::begin

Возвращает константный итератор первому символу в объекте hstring . См. итераторы.

Синтаксис

std::wchar_t const* begin() const noexcept;

Возвращаемое значение

Константный итератор к первому символу в объекте hstring .

Функция hstring::c_str

Возвращает указатель на базовую строку, завершающуюся значением NULL, в стиле C символов в объекте hstring ; копирование не производится.

Синтаксис

std::wchar_t const* c_str() const noexcept;

Возвращаемое значение

Указатель на базовую строку, завершающуюся значением NULL, в стиле C символов в объекте hstring ; копирование не производится.

Пример

#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 . См. итераторы.

Синтаксис

std::wchar_t const* cbegin() const noexcept;

Возвращаемое значение

Константный итератор к первому символу в объекте hstring .

Функция hstring::cend

Возвращает константный итератор к одному за пределами (один за последним символом) объекта hstring . См. итераторы.

Синтаксис

std::wchar_t const* cend() const noexcept;

Возвращаемое значение

Константный итератор к одному за пределами (один за последним символом) объекта hstring .

Функция hstring::clear

Делает объект hstring пустым.

Синтаксис

void clear() noexcept;

Функция hstring::crbegin

Возвращает константный обратный итератор к одному за пределами (один за последним символом) объекта hstring .

Синтаксис

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

Возвращаемое значение

Константный обратный итератор до конца (один за последним символом) объекта hstring .

Функция hstring::crend

Возвращает константный обратный итератор к первому символу в объекте hstring .

Синтаксис

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

Возвращаемое значение

Константный обратный итератор до первого символа в объекте hstring .

функция hstring::d ata

Возвращает строку в стиле C, завершающуюся null, версию символов в объекте hstring .

Синтаксис

std::wchar_t const* data() const noexcept;

Возвращаемое значение

Версия строки в стиле C, завершающаяся null, символов в объекте hstring .

Пример

#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 . См. итераторы.

Синтаксис

std::wchar_t const* end() const noexcept;

Возвращаемое значение

Константный итератор к одному за пределами (один за последним символом) объекта hstring .

Функция hstring::front

Возвращает ссылку на первый символ в объекте hstring .

Синтаксис

std::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[] (оператор subscript)

Возвращает ссылку на символ в указанной позиции в объекте hstring .

Синтаксис

std::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 Значение std::wstring_view , присваиваемое объекту hstring .

Возвращаемое значение

Ссылка на объект hstring .

Функция hstring::rbegin

Возвращает константный обратный итератор к одному за пределами (один за последним символом) объекта hstring .

Синтаксис

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

Возвращаемое значение

Константный обратный итератор до конца (один за последним символом) объекта hstring .

Функция hstring::rend

Возвращает константный обратный итератор к первому символу в объекте hstring .

Синтаксис

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

Возвращаемое значение

Константный обратный итератор до первого символа в объекте 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. Очищает строку, копирует параметр и начинает управлять дескриптором.

Синтаксис

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

Параметры

object Объект hstring для работы.

valueДескриптор строки среда выполнения Windows.

Функция copy_to_abi

Копирует в дескриптор в строку среда выполнения Windows из объекта hstring.

Синтаксис

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, std::wchar_t const* cRight) noexcept;
inline bool operator!=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator!=(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::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, std::wchar_t const* cRight);
inline hstring operator+(winrt::hstring const& hLeft, std::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+(std::wchar_t const* cLeft, winrt::hstring const& hRight);
inline hstring operator+(std::wchar_t scLeft, winrt::hstring const& hRight);

Параметры

hLefthRight Значение hstring для объединения с другим параметром.

wLeftwRight Значение std::wstring , сцепляющееся с другим параметром.

vLeftvRight Значение std::wstring_view для объединения с другим параметром.

cLeftcRight Указатель на массив констант wchar_t для объединения с другим параметром.

scLeftscRightWchar_t, сцепляющийся с другим параметром.

Возвращаемое значение

Новый объект hstring , полученный из объединения двух параметров.

operator< (оператор less-than)

Возвращает значение, указывающее, меньше ли первый параметр, чем второй.

Синтаксис

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, std::wchar_t const* cRight) noexcept;
inline bool operator<(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::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, std::wchar_t const* cRight) noexcept;
inline bool operator<=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator<=(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::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, std::wchar_t const* cRight) noexcept;
inline bool operator==(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator==(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::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, std::wchar_t const* cRight) noexcept;
inline bool operator>(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::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, std::wchar_t const* cRight) noexcept;
inline bool operator>=(std::wstring const& wLeft, winrt::hstring const& hRight) noexcept;
inline bool operator>=(std::wchar_t const* cLeft, winrt::hstring const& hRight) noexcept;

Параметры

hLefthRight Значение hstring для сравнения с другим параметром.

wLeftwRightstd::wstring Значение для сравнения с другим параметром.

cLeftcRight Указатель на массив констант wchar_t для сравнения с другим параметром.

Возвращаемое значение

true Значение , если первый параметр больше или равен второму параметру, в противном случае false.

См. также раздел