Структура winrt::hstring (C++/WinRT)
Последовательная коллекция символов Юникода UTF-16, представляющих текстовую строку. Дополнительные примеры и сведения о winrt::hstring см. в разделе Обработка строк в C++/WinRT.
Тип winrt::hstring инкапсулирует HSTRING за интерфейсом, аналогичным интерфейсу std::wstring. HSTRING — это дескриптор строки среда выполнения Windows. Сведения о том, как установить HSTRING в winrt::hstring и как повторно получить HSTRING из winrt::hstring, см. в разделе Взаимодействие с HSTRING ABI.
Синтаксис
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 | Возвращает указатель на базовую строку В стиле C, завершающуюся null, для символов в объекте hstring ; копия не сделана. |
| Функция hstring::cbegin | Возвращает константный итератор для первого символа в объекте hstring . |
| Функция hstring::cend | Возвращает константный итератор за пределами конца (за последним символом в) объекта hstring . |
| Функция hstring::clear | Делает объект hstring пустым. |
| Функция hstring::crbegin | Возвращает константный обратный итератор за пределами конца (за последним символом) объекта hstring . |
| Функция hstring::crend | Возвращает константный обратный итератор для первого символа в объекте hstring . |
| функция hstring::d ata | Возвращает строковую версию символов в объекте hstring в стиле C, завершающуюся null. |
| Функция 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. Очищает hstring, копирует параметр и начинает управление дескриптором. |
| Функция copy_to_abi | Копирует в дескриптор в строку среда выполнения Windows из объекта hstring. |
| Функция detach_abi | Отсоединяет объект hstring от его дескриптора, возможно, чтобы вернуть его вызывающему объекту. |
| Функция to_hstring | Преобразует входное значение в winrt::hstring , содержащее строковое представление значения. |
Операторы free
| Оператор | Описание |
|---|---|
| operator!= (оператор неравенства) | Возвращает значение, указывающее, не равны ли эти два параметра друг другу. |
| operator+ (оператор объединения) | Возвращает новый объект hstring , полученный в результате объединения двух параметров вместе. |
| оператор< (оператор меньше) | Возвращает значение, указывающее, меньше ли первый параметр второго. |
| 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(wchar_t const* c);
hstring(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 .
Синтаксис
wchar_t const& back() const noexcept;
Возвращаемое значение
Ссылка на последний символ в объекте hstring .
Функция hstring::begin
Возвращает константный итератор для первого символа в объекте hstring . См. раздел Итераторы.
Синтаксис
wchar_t const* begin() const noexcept;
Возвращаемое значение
Константный итератор для первого символа в объекте hstring .
Функция hstring::c_str
Возвращает указатель на базовую строку В стиле C, завершающуюся null, для символов в объекте hstring ; копия не сделана.
Синтаксис
wchar_t const* c_str() 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.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 в стиле C, завершающуюся null.
Синтаксис
wchar_t const* data() const noexcept;
Возвращаемое значение
Строковая версия символов в объекте hstring в стиле C, заканчивающаяся null.
Пример
#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;
Возвращаемое значение
Объект 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 .
Синтаксис
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<wchar_t const*> rbegin() const noexcept;
Возвращаемое значение
Константный обратный итератор на один за пределами конца (один за последним символом в) объекта hstring .
Функция hstring::rend
Возвращает обратный итератор const к первому символу в объекте hstring .
Синтаксис
std::reverse_iterator<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. Очищает hstring, копирует параметр и начинает управлять дескриптором.
Синтаксис
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, 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 Значение std::wstring_view для объединения с другим параметром.
cLeftcRight Указатель на массив констант wchar_t для объединения с другим параметром.
scLeftscRightWchar_t для объединения с другим параметром.
Возвращаемое значение
Новый объект hstring, полученный в результате объединения двух параметров.
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значение .
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значение .
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значение .
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по