SC::StringConverter Struct Reference

Converts String to a different encoding (UTF8, UTF16). More...

#include <StringConverter.h>

Public Types
enum	StringTermination {   NullTerminate ,   DoNotTerminate }
	Specifies if to add a null terminator. More...

Static Public Member Functions
template<typename T >
static bool	appendEncodingTo (StringEncoding encoding, StringSpan text, T &buffer, StringTermination nullTerminate)
	Appends to buffer text with requested encoding, optionally null-terminating it too.
static bool	appendEncodingTo (StringEncoding encoding, StringSpan text, IGrowableBuffer &buffer, StringTermination nullTerminate)

Detailed Description

Converts String to a different encoding (UTF8, UTF16).

SC::StringConverter converts strings between different UTF encodings and can add null-terminator if requested. Output is appended to the supplied buffer, including a terminator when requested. On Linux, cross-encoding conversion rejects malformed UTF8/UTF16 before changing the buffer and accepts embedded NUL. It requires only the exact output capacity, including the existing prefix and requested terminator. In that fallback, a source wholly inside the existing logical buffer remains valid across growth; other overlaps are not covered.

Example:

    // Setup: Construct some simple test StringViews
    const char utf8String1[]  = "\xE6\x97\xA5\xE6\x9C\xAC\xE8\xAA\x9E"; // "日本語" in UTF-8
    const char utf16String1[] = "\xE5\x65\x2C\x67\x9E\x8a";             // "日本語" in UTF-16LE
 
    StringView u8view  = StringView({utf8String1, sizeof(utf8String1) - 1}, false, StringEncoding::Utf8);
    StringView u16view = StringView({utf16String1, sizeof(utf16String1) - 1}, false, StringEncoding::Utf16);
 
    StringEncoding encoding = StringEncoding::Utf16;
 
    // Example 1: Use a String without needing to add a zero terminator (it's handled automatically)
    String string = encoding; // Important: set the encoding, as StringConverter will not change it
    SC_TEST_EXPECT(StringConverter::appendEncodingTo(encoding, u8view, string, StringConverter::DoNotTerminate));
    SC_TEST_EXPECT(string.view() == u16view);
 
    // Example 2: Manually append to a plain byte buffer works as well, in this case we also null terminate it
    SmallBuffer<255> buffer;
    SC_TEST_EXPECT(StringConverter::appendEncodingTo(encoding, u8view, buffer, StringConverter::NullTerminate));
 
    // Manually build a StringView from the buffer, taking care of slicing the null bytes at the end
    Span<const char> span;
    SC_TEST_EXPECT(buffer.toSpanConst().sliceStartLength(0, buffer.size() - StringEncodingGetSize(encoding), span));
    StringView output = {span, true, encoding}; // true == StringView is null terminated (after span)
    SC_TEST_EXPECT(output == u16view);

Member Enumeration Documentation

StringTermination

enum SC::StringConverter::StringTermination

Specifies if to add a null terminator.

Enumerator
NullTerminate	A null terminator will be added at the end of the String.
DoNotTerminate	A null terminator will NOT be added at the end of the String.

Member Function Documentation

appendEncodingTo()

template<typename T >

static bool SC::StringConverter::appendEncodingTo ( StringEncoding encoding, StringSpan text, T & buffer, StringTermination nullTerminate )

inlinestaticnodiscard

Appends to buffer text with requested encoding, optionally null-terminating it too.

Parameters

encoding	The requested destination encoding to convert to
text	The StringSpan to be converted
buffer	Encoded text will be appended to buffer
nullTerminate	Specifies if the StringSpan will need to be null terminated or not

Returns

true if the conversion succeeds

---

The documentation for this struct was generated from the following file:

• StringConverter.h