lib/atom.x

Canonical exact names.

Primary API

Atom

Atom.write_str

Buffer Atom.write_str(Atom atom, Buffer out)

Appends the exact spelling of atom to out. Neither representation allocates a String. An <lsym> Atom already owns its bytes, and a compact <symbol> decodes straight into out. An invalid Atom appends nothing.

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

Source: lib/atom.x:52

Var

Var.is_atom

int Var.is_atom(Var value)

Reports whether value is an exact-spelling Atom.

Source: lib/atom.x:92

Advanced and interop API

Atom

Atom.bare_spelling

int Atom.bare_spelling(String spelling)

Reports whether a spelling can round-trip as a bare Lisp Atom.

Source: lib/atom.x:36

Atom.first

char Atom.first(Atom atom)

Returns the first byte of atom’s exact spelling, or NUL when invalid.

Raises: the same causes as Atom.str.

Source: lib/atom.x:110

Atom.initialize

void Atom.initialize(void)

Initializes the process-wide Atom runtime owner. Repeated calls after successful registration have no effect.

Raises: <bad-state> after descriptor registration is frozen, <alloc-fail> while lower-casing the descriptor name, or <init-fail> when registration returns zero.

Source: lib/atom.x:165

Atom.intern

Atom Atom.intern(String spelling)

Returns the canonical Atom with the supplied exact spelling. Repeated interning of equal bytes returns a bit-identical Atom. A spelling that round-trips through either compact encoding becomes an immediate Symbol; every other spelling borrows its canonical String under the module lifetime rule above. Use Atom.promote before a long Atom escapes its innermost owning pool.

Raises: <bad-arg> when spelling is null or empty, <alloc-fail> when its canonical String cannot be allocated, or <bad-enc> if the long-Atom pointer cannot be boxed.

Source: lib/atom.x:218

Atom.promote

Self Atom.promote(Self atom)

Promotes a long Atom spelling into its parent String pool. Returns atom unchanged. Compact Atoms and long spellings not owned by the innermost pool are unchanged. A promoted spelling keeps the same pointer.

Raises: <alloc-fail> when promotion metadata cannot be allocated.

Source: lib/atom.x:26

Atom.str

String Atom.str(Atom atom)

Returns the exact spelling of atom as a String. A compact Atom is decoded and canonicalized through the active pool chain. A long Atom returns its borrowed canonical spelling under the module lifetime rule above. An invalid Atom returns NULL.

Raises: <alloc-fail> while canonicalizing a compact spelling.

Source: lib/atom.x:101

Atom.write_repr

Buffer Atom.write_repr(Atom value, Buffer out)

Writes the escaped readable spelling of atom to out. The escaping makes the result readable as the same exact Atom. An invalid Atom appends nothing.

Raises: <alloc-fail> while decoding a compact Atom, or <size-limit> or <alloc-fail> when out cannot grow.

Source: lib/atom.x:65

Design notes

An Atom preserves its spelling exactly. Compact spellings use immediate Symbols when Symbol encoding round-trips every byte; all other spellings use the private <lsym> representation with a direct pointer to the canonical String. String canonicalization makes equal long Atoms bit-identical. Compact Atoms have value lifetime. A long Atom borrows its canonical spelling, which may belong to any pool in the active chain and lives until its owning pool is released.

Tests and examples

make verify (unittest/test-atom.x).