Strings and UTF-8

StringType and StringViewType

Every string in the API is UTF-8. RealtimeCore::Common::StringType is an alias for std::u8string, StringViewType for std::u8string_view and CharType for char8_t, plain std::string never appears in a signature.

The aliases are defined in RealtimeCore/Common/StringType.h in the RealtimeCore::Common namespace and are used consistently across the whole API surface. Every string parameter, return value and data-type field, room names, player names, property keys, error messages, is a StringType or a StringViewType.

Building on char8_t makes the encoding part of the type system: a StringType is UTF-8 by construction, on every platform and on the wire. This removes the classic ambiguity of std::string, whose encoding depends on platform and locale, and turns accidental mixing of encodings into a compile error instead of corrupted text.

Writing String Literals

Use the PHOTON_STR("...") macro for string literals. It expands to a u8"..." literal, so it produces char8_t text that converts directly to StringType and StringViewType. Writing u8"..." yourself is equivalent, but discuraged as your code won't break if you use the PHOTON_STR("...") macro if there are internal changes on our string data types.

Literals are used wherever the API takes a string.

C++

using namespace RealtimeCore::Matchmaking;

ClientConstructOptions options;
options.AppId = PHOTON_STR("your-app-id");

RealtimeClient client(options);
client.SetPlayerName(PHOTON_STR("Alice"));

Converting To and From Other String Types

RealtimeCore::Common::ToStringType(...) builds a StringType from the common sources: any integral value, a bool (formatted as True or False) and a raw CharType* pointer. It is handy when composing property values or log messages from numeric game state.

C++20 makes char8_t a distinct character type, so a UTF-8 std::string and a StringType do not convert into each other implicitly even when their bytes are identical. Interfacing with code that stores UTF-8 in std::string therefore needs an explicit conversion at the boundary. The conversion is a plain byte copy and is lossless in both directions, because both sides hold the same UTF-8 data. It is important to make sure that any std::string you convert is encoded as UTF-8 (or ASCII which is a subset of UTF-8).

Both directions are a byte-wise copy.

C++

// std::string (holding UTF-8) to StringType:
std::string utf8Name = "Alice";
RealtimeCore::Common::StringType photonName(utf8Name.begin(), utf8Name.end());

// StringType back to std::string, e.g. for display or serialization:
std::string display(reinterpret_cast<const char*>(photonName.data()), photonName.size());