WriteChar v0.1.0

Package: Format

Signature

func WriteChar(
    builder: *StringBuilder,
    value: char32
);
func WriteChar(
    builder: *StringBuilder,
    value: char16
);

Parameters

char is an alias for char32, so an ordinary char reaches that overload.

There is no char8 overload, and none is needed: a char8 is already one byte of UTF-8, so StringBuilder::Append takes it as it stands, with nothing to encode.

Remarks

Encodes the character as UTF-8 and appends the bytes. A char32 holds one code point and becomes one to four bytes; a char16 holds one UTF-16 code unit and becomes one to three. A String holds bytes and its contents are UTF-8, which is why a character has to be encoded on the way in rather than copied.

A value that is not a code point comes out as the replacement character U+FFFD (three bytes, EF BF BD) rather than as an ill-formed sequence. Two things fail that test: a value past U+10FFFF, which is beyond the last code point there is, and a lone half of a surrogate pair, which only means something inside UTF-16 — the character it belongs to is spread across two code units, and this conversion sees one. The compiler rejects a surrogate as a constant, so one can only arrive through a cast at run time.

Example

import Format::WriteChar;
import Text::StringBuilder;

func Main() -> int {
    var builder = StringBuilder::New();
    WriteChar(@builder, c32'R');  // one byte
    WriteChar(@builder, c32'é');  // two
    WriteChar(@builder, c32'€');  // three
    builder.Append(c8'!');        // a char8 needs no encoding

    var text = builder.IntoString(); // "Ré€!"
    text.Length();                   // 7 bytes, 4 characters

    text.Free();
    return 0;
}

See also

• Format — the package overview
• ToString — the character in a String of its own, and what a char8 does instead
• Text::StringBuilder::Append — append bytes that are already UTF-8
• Text::String::Length — bytes, not characters