lib/symbol.x

Immediate encoded names.

Primary API

Symbol

Symbol.last

char Symbol.last(Symbol symbol)

Returns the final decoded byte of symbol, or NUL for zero.

Source: lib/symbol.x:247

Symbol.len

int Symbol.len(Symbol symbol)

Returns the number of decoded bytes in symbol.

Source: lib/symbol.x:121

Symbol.new

Symbol Symbol.new(const char *str)

Encodes the nonnull NUL-terminated spelling str as a compact Symbol. Encoding and truncation follow Symbol.new_len.

Source: lib/symbol.x:104

Symbol.try_new

int Symbol.try_new(String spelling, Symbol *out)

Encodes spelling only when the Symbol preserves every byte. Returns 1 and writes out on success; returns 0 and leaves out untouched when case folding, _/- folding, or truncation would change the spelling. The null String is the empty Symbol.

Raises: <alloc-fail> while checking the decoded spelling.

Source: lib/symbol.x:112

Symbol.write_str

Buffer Symbol.write_str(Symbol symbol, Buffer out)

Appends the decoded spelling of symbol to out. The bytes go straight into out, allocating no String. A zero Symbol appends nothing.

Raises: <size-limit> or <alloc-fail> when out cannot grow.

Source: lib/symbol.x:206

Advanced and interop API

Symbol

Symbol.compare

int Symbol.compare(Symbol a, Symbol b)

Compares decoded Symbol spellings bytewise. Zero sorts before nonzero values. Equal decoded lengths and bytes are ordered by the encoded value, so distinct encodings still have a total order. The result is -1, 0, or 1.

Source: lib/symbol.x:174

Symbol.decode

void Symbol.decode(Symbol symbol, char *dest)

Decodes symbol into caller-owned byte storage. dest must hold at least SYMBOL_MAX_5BIT + 1 bytes. A nonzero Symbol is NUL-terminated there. A null destination or zero Symbol leaves storage unchanged.

Source: lib/symbol.x:133

Symbol.first

char Symbol.first(Symbol symbol)

Returns the first decoded byte of symbol, or NUL for zero.

Source: lib/symbol.x:236

Symbol.new_len

Symbol Symbol.new_len(const char *str, int len)

Encodes at most len bytes of str as a compact Symbol. A null str or nonpositive len returns zero. All len readable bytes select the encoding before the result is truncated to ten restricted or seven general bytes. The restricted encoding folds ASCII case and treats underscore as hyphen; the general encoding retains each low seven bits, including embedded NUL. String and Buffer conversions stop at the first decoded NUL.

Source: lib/symbol.x:78

Symbol.parse

Symbol Symbol.parse(char *text)

Parses the first compact Symbol spelling from text. The parser accepts an angled literal or a bare Atom prefix and ignores trailing text. Quoted angled literals use String escape rules. The parsed bytes then take Symbol.new_len folding and truncation. Null, empty, or malformed input returns zero. Zero is also the empty Symbol.

Raises: <alloc-fail> while unescaping a quoted literal.

Source: lib/symbol.x:261

Symbol.repr

String Symbol.repr(Symbol symbol)

Returns the canonical readable representation of symbol. Zero becomes <>; other values use the form emitted by Symbol.write_repr. The result follows the canonical pool-chain lifetime described by Symbol.str.

Raises: <alloc-fail> while constructing the result.

Source: lib/symbol.x:194

Symbol.str

String Symbol.str(Symbol symbol)

Returns the decoded spelling as a canonical String. Conversion stops at the first decoded NUL. The result follows the canonical pool chain: it may already belong to an ancestor and lives until its actual owning pool is released. A zero Symbol returns NULL, the empty String.

Raises: <alloc-fail> while canonicalizing the spelling.

Source: lib/symbol.x:162

Symbol.write_repr

Buffer Symbol.write_repr(Symbol symbol, Buffer out)

Appends the readable representation of symbol to out. Zero writes <>; restricted values use a bare angled spelling and general values use a quoted angled spelling, escaping backslash and double quote.

Raises: <size-limit> or <alloc-fail> when out cannot grow.

Source: lib/symbol.x:218

Design notes

Symbol stores closed-vocabulary names directly in an integer. Restricted spellings use ten 5-bit characters; other spellings use seven 7-bit bytes. The restricted form folds ASCII case and aliases underscore with hyphen; the general form retains only the low seven bits. Construction truncates beyond the selected capacity. Use Atom when every input byte must round-trip.

Tests and examples

make verify (unittest/test-symbol.x) and make examples (symbol-literal-demo).