Skip to content

Strings

String is UTF-8 text. Use double quotes for literals, <> to join text, and #{...} to interpolate strings, numbers, booleans, or atoms.

A String contains valid UTF-8. Raw bytes use Binary; converting them to text requires validation. Interpolation accepts strings, numbers, booleans and atoms.

Double quotes make a literal, <> joins, and #{...} interpolates:

mod strings
pub fn greet(name: String) -> String {
"hello, #{name}"
}
pub fn join(left: String, right: String) -> String {
left <> right
}
pub fn label(count: Integer) -> String {
"count: #{count}"
}

Interpolation accepts the primitive types that have an unambiguous textual form: strings, integers, floats, booleans and atoms. A raw Binary has no guaranteed UTF-8 spelling, so validate it before interpolation.

Validate bytes first: string.from_binary returns the same bytes as a String exactly when they are valid UTF-8, and Error(:invalid_utf8) otherwise. The errors chapter builds that flow.

Strings interpret escapes: \n, \t, \", \\, and Unicode escapes that name code points directly. Documentation heredocs (@doc) do not process escapes.

mod strings
alias gale_std.string
@doc "Escapes are interpreted inside strings; Unicode escapes name code points."
pub fn escaped() -> String {
"\"Gale\"\n\t\u{1f300}\\"
}
pub fn status(ready: Boolean, phase: Atom, ratio: Float) -> String {
"ready=#{ready}, phase=#{phase}, ratio=#{ratio}"
}
pub fn as_bytes(text: String) -> Binary {
string.as_binary(text)
}

The full escape set also includes \0, \a, \b, \v, \f, \e, \s, \uNNNN, \xNN and \#{...} for a literal #{.

Multiline text uses expression heredocs: the closing delimiter’s indentation is stripped and line breaks are kept, and interpolation works inside them.

@doc "Expression heredocs are multiline strings with interpolation."
pub fn multiline(name: String) -> String {
"""
Hello, #{name}!
Welcome to Gale.
"""
}

Gale’s byte types stack: String <: Binary <: Bitstring. A String is UTF-8; a Binary is byte-aligned and arbitrary; a Bitstring can end mid-byte. Every String is already a Binary, so string.as_binary is a change of view, not a conversion.

The distinction shows up in measurement. Native string.length counts graphemes; binary.byte_size counts bytes. The cyclone 🌀 is one grapheme and four bytes. The tests check both counts.

Binary patterns destructure packets directly, with integer segments at literal bit widths:

pub fn packet_payload(packet: Binary) -> Option<Binary> {
case packet {
<<size::16, payload::binary-size(size)>> -> Some(payload)
_ -> None
}
}

The rules are deliberately narrow: integer fields use literal widths with unsigned, big-endian, 8-bit defaults; payload segments are sized by an earlier-bound value; only a trailing payload may omit its size. Computed sizes, runtime-chosen widths and other codecs need externs. For supported patterns, the prover models bit lengths, alignment and match branches.

Charlists, sigils and character literals are not part of Gale; native adapters may use them internally.