Partilhar via

Manipulação de cadeia de caracteres em C++/WinRT

Com C++/WinRT, você pode chamar APIs do Tempo de Execução do Windows usando tipos de cadeia de caracteres amplas da Biblioteca Padrão do C++, como std::wstring (observação: não com tipos de cadeia de caracteres estreitos, como std::string). C++/WinRT tem um tipo de cadeia de caracteres personalizado chamado winrt::hstring (definido na biblioteca base C++/WinRT, que é %WindowsSdkDir%Include\<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h). E esse é o tipo de cadeia de caracteres que os construtores, funções e propriedades do Tempo de Execução do Windows realmente tomam e retornam. Mas, em muitos casos, graças aos construtores e operadores de conversão do hstring, pode escolher se quer ou não estar ciente de hstring no seu código de cliente. Se estiveres a criar APIs, é mais provável que precises de saber sobre hstring.

Há muitos tipos de cadeia de caracteres em C++. Existem variantes em muitas bibliotecas, além de std::basic_string da Biblioteca Padrão C++. C++17 tem utilitários de conversão de cadeia de caracteres e std::basic_string_view, para preencher as lacunas entre todos os tipos de cadeia de caracteres. winrt::hstring oferece convertibilidade com std::wstring_view para fornecer a interoperabilidade para a qual std::basic_string_view foi projetado.

Usar std::wstring (e opcionalmente winrt::hstring) com Uri

Windows::Foundation::Uri é construído a partir de um winrt::hstring.

public:
    Uri(winrt::hstring uri) const;

Mas hstring tem construtores de conversão que permitem que você trabalhe com ele sem precisar estar ciente disso. Aqui está um exemplo de código mostrando como criar um de Uri de a partir de um literal de cadeia de caracteres ampla, de uma visualização de cadeia de caracteres ampla e de umastd::wstring.

#include <winrt/Windows.Foundation.h>
#include <string_view>

using namespace winrt;
using namespace Windows::Foundation;

int main()
{
    using namespace std::literals;

    winrt::init_apartment();

    // You can make a Uri from a wide string literal.
    Uri contosoUri{ L"http://www.contoso.com" };

    // Or from a wide string view.
    Uri contosoSVUri{ L"http://www.contoso.com"sv };

    // Or from a std::wstring.
    std::wstring wideString{ L"http://www.adventure-works.com" };
    Uri awUri{ wideString };
}

O acessador de propriedade Uri::Domain é do tipo hstring.

public:
    winrt::hstring Domain();

Mas, novamente, estar ciente desse detalhe é opcional graças ao operador de conversão hstringpara std::wstring_view.

// Access a property of type hstring, via a conversion operator to a standard type.
std::wstring domainWstring{ contosoUri.Domain() }; // L"contoso.com"
domainWstring = awUri.Domain(); // L"adventure-works.com"

// Or, you can choose to keep the hstring unconverted.
hstring domainHstring{ contosoUri.Domain() }; // L"contoso.com"
domainHstring = awUri.Domain(); // L"adventure-works.com"

Da mesma forma, IStringable::ToString retorna hstring.

public:
    hstring ToString() const;

Uri implementa a interface IStringable.

// Access hstring's IStringable::ToString, via a conversion operator to a standard type.
std::wstring tostringWstring{ contosoUri.ToString() }; // L"http://www.contoso.com/"
tostringWstring = awUri.ToString(); // L"http://www.adventure-works.com/"

// Or you can choose to keep the hstring unconverted.
hstring tostringHstring{ contosoUri.ToString() }; // L"http://www.contoso.com/"
tostringHstring = awUri.ToString(); // L"http://www.adventure-works.com/"

Você pode usar a função hstring::c_str para obter uma cadeia de caracteres larga padrão de um hstring (assim como você pode fazer a partir de um std::wstring).

#include <iostream>
std::wcout << tostringHstring.c_str() << std::endl;

Se tiver um hstring, então pode criar um Uri a partir dele.

Uri awUriFromHstring{ tostringHstring };

Considere um método que tenha um hstring.

public:
    Uri CombineUri(winrt::hstring relativeUri) const;

Todas as opções que você acabou de ver também se aplicam nesses casos.

std::wstring contact{ L"contact" };
contosoUri = contosoUri.CombineUri(contact);
    
std::wcout << contosoUri.ToString().c_str() << std::endl;

hstring tem um membro operador de conversão std::wstring_view e a conversão é obtida sem nenhum custo.

void legacy_print(std::wstring_view view);

void Print(winrt::hstring const& hstring)
{
    legacy_print(hstring);
}

funções winrt::hstring e operadores

Uma série de construtores, operadores, funções e iteradores são implementados para winrt::hstring.

Um hstring é um intervalo, para que você possa usá-lo com baseados em intervalo ou com . Ele também fornece operadores de comparação para comparação natural e eficiente com seus homólogos na Biblioteca Padrão C++. E inclui tudo o que precisas para usar hstring como uma chave para contêineres associativos.

Reconhecemos que muitas bibliotecas C++ usam std::stringe trabalham exclusivamente com texto UTF-8. Como uma conveniência, nós fornecemos ajudantes, como winrt::to_string e winrt::to_hstring, para realizar conversões bidirecionais.

WINRT_ASSERT é uma definição macro e se expande para _ASSERTE.

winrt::hstring w{ L"Hello, World!" };

std::string c = winrt::to_string(w);
WINRT_ASSERT(c == "Hello, World!");

w = winrt::to_hstring(c);
WINRT_ASSERT(w == L"Hello, World!");

Para obter mais exemplos e informações sobre funções e operadores de hstring, consulte o tópico de referência da API winrt::hstring.

A justificação para winrt::hstring e winrt::param::hstring

O Tempo de Execução do Windows é implementado em termos de wchar_t caracteres, mas a Interface Binária de Aplicativo (ABI) do Tempo de Execução do Windows não é um subconjunto do que std::wstring ou std::wstring_view fornecem. A sua utilização conduziria a uma ineficácia significativa. Em vez disso, o C++/WinRT fornece winrt::hstring , que representa uma cadeia de caracteres imutável consistente com oHSTRING subjacente e implementada por trás de uma interface semelhante à de std::wstring.

Você pode notar que os parâmetros de entrada C++/WinRT que devem logicamente aceitar winrt::hstring realmente esperam winrt::param::hstring. O namespace param contém um conjunto de tipos usados exclusivamente para otimizar os parâmetros de entrada para vincular naturalmente aos tipos de biblioteca padrão C++ e evitar cópias e outras ineficiências. Você não deve usar esses tipos diretamente. Se tu quiseres usar uma otimização para as tuas próprias funções, usa std::wstring_view. Consulte também Passagem de parâmetros através da fronteira ABI.

O resultado é que podes ignorar em grande parte as especificidades da gestão de strings do Windows Runtime e simplesmente trabalhar de forma eficiente com o que já sabes. E isso é importante, dada a frequência com que as cadeias de caracteres são usadas no Tempo de Execução do Windows.

Formatando cadeias de caracteres

Uma opção para formatação de cadeia de caracteres é std::wostringstream. Aqui está um exemplo que formata e exibe uma mensagem de rastreamento de depuração simples.

#include <sstream>
#include <winrt/Windows.UI.Input.h>
#include <winrt/Windows.UI.Xaml.Input.h>
...
void MainPage::OnPointerPressed(winrt::Windows::UI::Xaml::Input::PointerRoutedEventArgs const& e)
{
    winrt::Windows::Foundation::Point const point{ e.GetCurrentPoint(nullptr).Position() };
    std::wostringstream wostringstream;
    wostringstream << L"Pointer pressed at (" << point.X << L"," << point.Y << L")" << std::endl;
    ::OutputDebugString(wostringstream.str().c_str());
}

A maneira correta de definir uma propriedade

Você define uma propriedade passando um valor para uma função setter. Eis um exemplo.

// The right way to set the Text property.
myTextBlock.Text(L"Hello!");

O código abaixo está incorreto. Ele compila, mas tudo o que faz é modificar o temporário winrt::hstring retornado pela função de acessador Text() e, em seguida, jogar o resultado fora.

// *Not* the right way to set the Text property.
myTextBlock.Text() = L"Hello!";

APIs importantes

  • Last updated on