Gestão de strings em C++/WinRT

Com C++/WinRT, é possível chamar APIs do Windows Runtime usando tipos de cadeias de carateres largas da Biblioteca Padrão de C++, como std::wstring (nota: não com tipos de cadeias de carateres estreitas, como std::string). C++/WinRT tem um tipo de string personalizado chamado winrt::hstring (definido na biblioteca base C++/WinRT, que é %WindowsSdkDir%Include\<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h). E esse é o tipo de string que os construtores, funções e propriedades do Windows Runtime realmente assumem e retornam. Mas, em muitos casos — graças aos construtores e operadores de conversão de hstring — pode escolher ter ou não consciência de hstring no código do cliente. Se estás a criar APIs, é mais provável que precises de conhecer hstring.

Existem muitos tipos de cadeias em C++. Existem variantes em muitas bibliotecas para além do std::basic_string da Biblioteca Padrão de C++. O C++17 tem utilitários de conversão de strings e std::basic_string_view, para colmatar as lacunas entre todos os tipos de strings. Winrt::Hstring fornece conversibilidade com STD::wstring_view para proporcionar a interoperabilidade para a qual o STD::basic_string_view foi concebido.

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 o hstring tem construtores de conversão que permitem trabalhar com ele sem precisar de estar consciente disso. Aqui está um exemplo de código que mostra como criar um Uri a partir de uma string larga literal, a partir de uma vista de string ampla e a partir de uma std::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 acessor da propriedade Uri::Domain é do tipo hstring.

public:
    winrt::hstring Domain();

Mas, novamente, estar ciente desse detalhe é opcional graças ao operador de conversão do 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"

De forma semelhante, IStringable::ToString devolve hstring.

public:
    hstring ToString() const;

O 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/"

Pode usar a função hstring::c_str para obter uma cadeia de caracteres larga padrão a partir de um hstring (tal como pode fazer com uma std::wstring).

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

Se tiveres um hstring , podes criar um Uri a partir dele.

Uri awUriFromHstring{ tostringHstring };

Considere um método que recebe um hstring.

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

Todas as opções que acabaste 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 operador de conversão membro Std::wstring_view , e a conversão é realizada sem custos.

void legacy_print(std::wstring_view view);

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

Funções e operadores winrt::hstring

Uma série de construtores, operadores, funções e iteradores está implementada para winrt::hstring.

Uma hstring é uma sequência, pelo que a podes utilizar com forbaseado em sequência, ou com std::for_each. Também fornece operadores de comparação para comparar de forma natural e eficiente com os seus equivalentes na Biblioteca Padrão C++. E inclui tudo o que precisas para usar hstring como chave para containers associativos.

Reconhecemos que muitas bibliotecas C++ usam std::string e funcionam exclusivamente com texto UTF-8. Por conveniência, fornecemos ajudantes, como winrt::to_string e winrt::to_hstring, para converter de um lado para o outro.

WINRT_ASSERT é uma definição macro, e expande-se 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 mais exemplos e informações sobre funções e operadores hstring , consulte o tópico de referência da API winrt::hstring .

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

O Windows Runtime é implementado com base em caracteres wchar_t, mas a Interface Binária da Aplicação (ABI) do Windows Runtime não é um subconjunto do que quer std::wstring quer std::wstring_view disponibilizam. Usá-los levaria a uma ineficiência significativa. Em vez disso, o C++/WinRT fornece winrt::hstring, que representa uma cadeia de caracteres imutável consistente com o HSTRING subjacente e cuja implementação assenta numa interface semelhante à de std::wstring.

Poderá notar que os parâmetros de entrada do C++/WinRT que, em termos lógicos, deveriam aceitar winrt::hstring na realidade esperam winrt::param::hstring. O espaço de nomes param contém um conjunto de tipos usados exclusivamente para otimizar parâmetros de entrada, para que se associem de forma natural a tipos da Biblioteca Padrão de C++ e evitem cópias e outras ineficiências. Não deves usar estes tipos diretamente. Se quiseres usar uma otimização para as tuas próprias funções, então usa std::wstring_view. Veja também Passar parâmetros através da fronteira da ABI.

A conclusão é que pode, em grande parte, ignorar os detalhes da gestão de strings do Windows Runtime e trabalhar com eficiência com o que se sabe. E isso é importante, dado o uso intenso de strings no Windows Runtime.

Cadeias de formatação

Uma opção para formatação de strings é std::wostringstream. Eis um exemplo que formata e apresenta uma mensagem de rastreio de depuração simples.

#include <sstream>
#include <winrt/Microsoft.UI.Input.h>
#include <winrt/Microsoft.UI.Xaml.Input.h>
...
void MainPage::OnPointerPressed(winrt::Microsoft::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 forma correta de definir uma propriedade

Defines 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. Compila, mas tudo o que faz é modificar o winrt::hstring temporário devolvido pela função de acesso Text( ), e depois descartar o resultado.

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

APIs importantes

  • Last updated on