struct winrt::hstring (C++/WinRT)

Artigo
08/17/2024

Uma coleção sequencial de caracteres Unicode UTF-16 que representam uma cadeia de caracteres de texto. Para obter mais exemplos e informações sobre winrt::hstring, consulte Tratamento de cadeia de caracteres noC++/WinRT.

O tipo winrt::hstring encapsula HSTRING por trás de uma interface semelhante à de std::wstring. Um HSTRING é um identificador para uma cadeia de caracteres do Windows Runtime. Para obter informações sobre como definir um HSTRING em umwinrt::hstring e como recuperar um HSTRING de um winrt::hstring, consulte Interoperação com o HSTRINGda ABI.

Sintaxe

struct hstring

Requisitos

SDK mínimo com suporte: SDK do Windows versão 10.0.17134.0 (Windows 10, versão 1803)

Namespace : winrt

Cabeçalho : %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (incluído por padrão)

Aliases de tipo de membro

Nome do alias	Tipo
hstring::value_type	Um sinônimo para wchar_t.
hstring::size_type	Um sinônimo para uint32_t.
hstring::const_reference	Um sinônimo para hstring::value_type const&.
hstring::const_pointer	Um sinônimo para hstring::value_type const*.
hstring::const_iterator	Um sinônimo para hstring::const_pointer.
hstring::const_reverse_iterator	Um sinônimo para std::reverse_iterator<hstring::const_iterator>.

Construtores

Construtor	Descrição
construtor hstring::hstring	Inicializa uma nova instância do hstring struct com uma cópia dos dados da cadeia de caracteres de entrada.

Funções de membro

Função	Descrição
de função hstring::back	Retorna uma referência ao último caractere no objeto de hstring.
função hstring::begin	Retorna um iterador const para o primeiro caractere no objeto de hstring.
função hstring::c_str	Retorna um ponteiro para a cadeia de caracteres de estilo C terminada em nulo subjacente dos caracteres no objeto de hstring ; nenhuma cópia é feita.
função hstring::cbegin	Retorna um iterador const para o primeiro caractere no objeto de hstring.
função hstring::cend	Retorna um iterador const para um além do final de (um além do último caractere) do objeto de hstring.
de função hstring::clear	Torna o objeto vazio.
função hstring::crbegin	Retorna um iterador invertido const para um além do final (um além do último caractere) do objeto de hstring.
função hstring::crend	Retorna um iterador reverso const para o primeiro caractere no objeto de hstring.
função hstring::d ata	Retorna uma versão de cadeia de caracteres no estilo C terminada em nulo dos caracteres no objeto de hstring.
de função hstring::empty	Retorna um valor que indica se o objeto de está vazio.
função hstring::end	Retorna um iterador const para um além do final de (um além do último caractere) do objeto de hstring.
de função hstring::front	Retorna uma referência ao primeiro caractere no objeto de hstring.
função hstring::rbegin	Retorna um iterador invertido const para um além do final (um além do último caractere) do objeto de hstring.
função hstring::rend	Retorna um iterador reverso const para o primeiro caractere no objeto de hstring.
função hstring::size	Retorna o número de caracteres no objeto de hstring.

Operadores de membro

Operador	Descrição
hstring::operator std::wstring_view	Converte o objeto de hstring em um std::wstring_view.
hstring::operator[] (operador subscrito))	Retorna uma referência ao caractere na posição especificada no objeto hstring.
hstring::operator= (operador de atribuição)	Atribui um valor ao objeto de hstring.

Funções gratuitas

Função	Descrição
attach_abi função	Anexa um objeto hstring a um identificador a uma cadeia de caracteres do Windows Runtime.
copy_from_abi função	Copia para um objeto hstring de um identificador para uma cadeia de caracteres do Windows Runtime. Limpa ode hstring, copia o parâmetro e começa a gerenciar o identificador.
de função copy_to_abi	Copia para um identificador para uma cadeia de caracteres do Windows Runtime de um objeto de hstring.
detach_abi função	Desanexa um objeto de hstring de seu identificador, talvez para devolvê-lo a um chamador.
to_hstring função	Converte um valor de entrada em um winrt::hstring que contém a representação de cadeia de caracteres do valor.

Operadores gratuitos

Operador	Descrição
operador != (operador de desigualdade)	Retorna um valor que indica se os dois parâmetros são diferentes um do outro.
operador + (operador de concatenação)	Retorna um novo objeto hstring resultante da concatenação dos dois parâmetros juntos.
operador < (operador menor que)	Retorna um valor que indica se o primeiro parâmetro é menor que o segundo parâmetro.
operador <= (operador menor ou igual a)	Retorna um valor que indica se o primeiro parâmetro é menor ou igual ao segundo parâmetro.
operator== (operador de igualdade)	Retorna um valor que indica se os dois parâmetros são iguais um ao outro.
operador > (operador maior que)	Retorna um valor que indica se o primeiro parâmetro é maior que o segundo parâmetro.
operador >= (operador maior ou igual a)	Retorna um valor que indica se o primeiro parâmetro é maior ou igual ao segundo parâmetro.

Iteradores

Um de hstring é um intervalo e esse intervalo é definido pelas funções de membro hstring::begin e hstring::end, cada uma das quais retorna um iterador const (assim como hstring::cbegin e hstring::cend). Por isso, você pode enumerar os caracteres em um objeto de hstring com uma instrução baseada em intervalo ou com a função de modelo 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; });
}

Construtor hstring::hstring

Inicializa uma nova instância do hstring struct com uma cópia dos dados da cadeia de caracteres de entrada.

Sintaxe

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

Parâmetros

Um valor de hstring que inicializa o objeto de hstring.

um valor std::wstring_view que inicializa o objeto de hstring.

um ponteiro para uma matriz de wchar_t constante que inicializa o objeto de hstring.

Um número que especifica um tamanho fixo para o objeto de hstring.

Exemplo

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

Função hstring::back

Retorna uma referência ao último caractere no objeto de hstring.

Sintaxe

wchar_t const& back() const noexcept;

Valor de retorno

Uma referência ao último caractere no objeto de hstring.

Função hstring::begin

Retorna um iterador const para o primeiro caractere no objeto de hstring. Consulte iteradores.

Sintaxe

wchar_t const* begin() const noexcept;

Valor de retorno

Um iterador const para o primeiro caractere no objeto de hstring.

Função hstring::c_str

Retorna um ponteiro para a cadeia de caracteres de estilo C terminada em nulo subjacente dos caracteres no objeto de hstring ; nenhuma cópia é feita.

Sintaxe

wchar_t const* c_str() const noexcept;

Valor de retorno

Um ponteiro para a cadeia de caracteres de estilo C terminada em nulo subjacente dos caracteres no objeto de hstring; nenhuma cópia é feita.

Exemplo

#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;
}

Função hstring::cbegin

Retorna um iterador const para o primeiro caractere no objeto de hstring. Consulte iteradores.

Sintaxe

wchar_t const* cbegin() const noexcept;

Valor de retorno

Um iterador const para o primeiro caractere no objeto de hstring.

Função hstring::cend

Retorna um iterador const para um além do final de (um além do último caractere) do objeto de hstring. Consulte iteradores.

Sintaxe

wchar_t const* cend() const noexcept;

Valor de retorno

Um iterador const para um além do final de (um além do último caractere em) o objeto de de hstring.

Função hstring::clear

Torna o objeto vazio.

Sintaxe

void clear() noexcept;

Função hstring::crbegin

Retorna um iterador invertido const para um além do final (um além do último caractere) do objeto de hstring.

Sintaxe

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

Valor de retorno

Um iterador invertido const para um além do final (um além do último caractere) do objeto hstring.

Função hstring::crend

Retorna um iterador reverso const para o primeiro caractere no objeto de hstring.

Sintaxe

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

Valor de retorno

Um iterador inverso const para o primeiro caractere no objeto de hstring.

Função hstring::d ata

Retorna uma versão de cadeia de caracteres no estilo C terminada em nulo dos caracteres no objeto de hstring.

Sintaxe

wchar_t const* data() const noexcept;

Valor de retorno

Uma versão de cadeia de caracteres de estilo C terminada em nulo dos caracteres no objeto de hstring.

Exemplo

#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;
}

Função hstring::empty

Retorna um valor que indica se o objeto de está vazio.

Sintaxe

bool empty() const noexcept;

Valor de retorno

se o objeto de estiver vazio, caso contrário, .

Função hstring::end

Retorna um iterador const para um além do final de (um além do último caractere) do objeto de hstring. Consulte iteradores.

Sintaxe

wchar_t const* end() const noexcept;

Valor de retorno

Um iterador const para um além do final de (um além do último caractere em) o objeto de de hstring.

Função hstring::front

Retorna uma referência ao primeiro caractere no objeto de hstring.

Sintaxe

wchar_t const& front() const noexcept;

Valor de retorno

Uma referência ao primeiro caractere no objeto de hstring.

hstring::operator std::wstring_view

Converte o objeto de hstring em um std::wstring_view.

Sintaxe

operator std::wstring_view() const noexcept;

Valor de retorno

O objeto de hstring convertido em um std::wstring_view.

Exemplo

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[] (operador subscrito)

Retorna uma referência ao caractere na posição especificada no objeto hstring.

Sintaxe

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

Parâmetros

pos uma posição de caractere baseada em zero ou índice.

Valor de retorno

Uma referência ao caractere na posição especificada dentro do objeto de hstring.

hstring::operator= (operador de atribuição)

Atribui um valor ao objeto de hstring.

Sintaxe

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

Parâmetros

Um valor de de hstring a ser atribuído ao objeto de hstring.

um valor std::wstring_view a ser atribuído ao objeto de hstring.

Valor de retorno

Uma referência ao objeto de hstring.

Função hstring::rbegin

Retorna um iterador invertido const para um além do final (um além do último caractere) do objeto de hstring.

Sintaxe

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

Valor de retorno

Um iterador invertido const para um além do final (um além do último caractere) do objeto hstring.

Função hstring::rend

Retorna um iterador reverso const para o primeiro caractere no objeto de hstring.

Sintaxe

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

Valor de retorno

Um iterador inverso const para o primeiro caractere no objeto de hstring.

Função hstring::size

Retorna o número de caracteres no objeto de hstring.

Sintaxe

uint32_t size() const noexcept;

Valor de retorno

Um uint32_t que contém o número de caracteres no objeto de hstring.

função attach_abi

Anexa um objeto hstring a um identificador a uma cadeia de caracteres do Windows Runtime.

Sintaxe

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

Parâmetros

um objeto de de hstring para operar.

value um identificador para uma cadeia de caracteres do Windows Runtime.

função copy_from_abi

Copia para um objeto hstring de um identificador para uma cadeia de caracteres do Windows Runtime. Limpa ode hstring, copia o parâmetro e começa a gerenciar o identificador.

Sintaxe

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

Parâmetros

um objeto de de hstring para operar.

value um identificador para uma cadeia de caracteres do Windows Runtime.

função copy_to_abi

Copia para um identificador para uma cadeia de caracteres do Windows Runtime de um objeto de hstring.

Sintaxe

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

Parâmetros

um objeto de de hstring para operar.

uma referência de identificador, por meio da qual copiar o identificador dode hstring.

função detach_abi

Desanexa um objeto de hstring de seu identificador, talvez para devolvê-lo a um chamador.

Sintaxe

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

Parâmetros

um objeto de de hstring para operar.

Valor de retorno

O identificador para a cadeia de caracteres do Windows Runtime.

operator!= (operador de desigualdade)

Retorna um valor que indica se os dois parâmetros são diferentes um do outro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se os dois parâmetros forem diferentes um do outro, caso contrário, false.

operator+ (operador de concatenação)

Retorna um novo objeto hstring resultante da concatenação dos dois parâmetros juntos.

Sintaxe

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

Parâmetros

um valor de de hstring para concatenar com o outro parâmetro.

wLeft wRight um valor std::wstring para concatenar com o outro parâmetro.

vLeft vRight um valor de std::wstring_view para concatenar com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para concatenar com o outro parâmetro.

scLeft scRight um wchar_t para concatenar com o outro parâmetro.

Valor de retorno

Um novo objeto hstring resultante da concatenação dos dois parâmetros juntos.

operador< (operador menor que)

Retorna um valor que indica se o primeiro parâmetro é menor que o segundo parâmetro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se o primeiro parâmetro for menor que o segundo parâmetro, caso contrário, false.

operador<= (operador menor que ou igual a)

Retorna um valor que indica se o primeiro parâmetro é menor ou igual ao segundo parâmetro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se o primeiro parâmetro for menor ou igual ao segundo parâmetro, caso contrário, false.

operator== (operador de igualdade)

Retorna um valor que indica se os dois parâmetros são iguais um ao outro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se os dois parâmetros forem iguais um ao outro, caso contrário, false.

operador> (operador maior que)

Retorna um valor que indica se o primeiro parâmetro é maior que o segundo parâmetro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se o primeiro parâmetro for maior que o segundo parâmetro, caso contrário, false.

operador>= (operador maior que ou igual a)

Retorna um valor que indica se o primeiro parâmetro é maior ou igual ao segundo parâmetro.

Sintaxe

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;

Parâmetros

um valor de de hstring a ser comparado com o outro parâmetro.

wLeft wRight um valor de std::wstring a ser comparado com o outro parâmetro.

cLeft cRight um ponteiro para uma matriz de wchar_t constantes para comparar com o outro parâmetro.

Valor de retorno

true se o primeiro parâmetro for maior ou igual ao segundo parâmetro, caso contrário, false.

Consulte também

namespace winrt
manipulação de cadeia de caracteres no C++/WinRT

Compartilhar via

struct winrt::hstring (C++/WinRT)

Sintaxe

Requisitos

Aliases de tipo de membro

Construtores

Funções de membro

Operadores de membro

Funções gratuitas

Operadores gratuitos

Iteradores

Construtor hstring::hstring

Sintaxe

Parâmetros

Exemplo

Função hstring::back

Sintaxe

Valor de retorno

Função hstring::begin

Sintaxe

Valor de retorno

Função hstring::c_str

Sintaxe

Valor de retorno

Exemplo

Função hstring::cbegin

Sintaxe

Valor de retorno

Função hstring::cend

Sintaxe

Valor de retorno

Função hstring::clear

Sintaxe

Função hstring::crbegin

Sintaxe

Valor de retorno

Função hstring::crend

Sintaxe

Valor de retorno

Função hstring::d ata

Sintaxe

Valor de retorno

Exemplo

Função hstring::empty

Sintaxe

Valor de retorno

Função hstring::end

Sintaxe

Valor de retorno

Função hstring::front

Sintaxe

Valor de retorno

hstring::operator std::wstring_view

Sintaxe

Valor de retorno

Exemplo

hstring::operator[] (operador subscrito)

Sintaxe

Parâmetros

Valor de retorno

hstring::operator= (operador de atribuição)

Sintaxe

Parâmetros

Valor de retorno

Função hstring::rbegin

Sintaxe

Valor de retorno

Função hstring::rend

Sintaxe

Valor de retorno

Função hstring::size

Sintaxe

Valor de retorno

função attach_abi

Sintaxe

Parâmetros

função copy_from_abi

Sintaxe

Parâmetros

função copy_to_abi