pub struct Symbol(/* private fields */);Expand description
A four-byte Copy handle to an interned string, re-exported from
intern_lang so consumers can name the type TokenKind::symbol returns
without depending on intern-lang directly.
A small, copyable handle to a string held by an Interner.
A Symbol is a newtype over a 32-bit id, so it is four bytes, Copy, and as
cheap to pass or store as an integer. The point of interning is that a name in
an AST node or a symbol-table key costs a Symbol instead of an owned
String, and comparing two names becomes an integer comparison instead of a
byte-by-byte walk — ==, Ord, and Hash on a Symbol never touch the
underlying bytes.
A Symbol is only meaningful together with the interner that issued it. Two
symbols from the same interner are equal exactly when they name the same
string; symbols from different interners share no relationship and should not
be compared or resolved across interners (resolving a foreign symbol is
handled safely — see Interner::resolve — but the
result is not meaningful).
§Examples
use intern_lang::Interner;
let mut interner = Interner::new();
let a = interner.intern("loop");
let b = interner.intern("loop");
// Same string interns to the same symbol, so equality is an integer compare.
assert_eq!(a, b);
// A symbol is `Copy`: handing it around never moves or clones a string.
let copy = a;
assert_eq!(copy, a);§Serialization
With the serde feature enabled, Symbol serializes transparently as its raw
integer id (the same value as_u32 returns) and
deserializes back, rejecting 0. The id is only meaningful with the interner
that issued it, so persist symbols alongside the interner that produced them.
Implementations§
Source§impl Symbol
impl Symbol
Sourcepub fn from_u32(id: u32) -> Option<Symbol>
pub fn from_u32(id: u32) -> Option<Symbol>
Reconstructs a symbol from a raw 1-based id, or None if id is 0.
This is the inverse of as_u32, for rebuilding a symbol
from an id stored elsewhere (a file, a wire message, an external table).
It only rebuilds the handle; whether the id names anything is decided when
you resolve it against an interner, which
returns None for an out-of-range id. A symbol is only meaningful with the
interner that issued it.
§Examples
use intern_lang::{Interner, Symbol};
let mut interner = Interner::new();
let sym = interner.intern("persisted");
// Round-trip a symbol through its raw id.
let rebuilt = Symbol::from_u32(sym.as_u32()).unwrap();
assert_eq!(rebuilt, sym);
assert_eq!(interner.resolve(rebuilt), Some("persisted"));
// Zero is never a valid symbol id.
assert_eq!(Symbol::from_u32(0), None);Sourcepub fn as_u32(self) -> u32
pub fn as_u32(self) -> u32
Returns the raw 1-based integer id backing this symbol.
The id is stable for the lifetime of the issuing interner and is assigned
in interning order: the first distinct string interned gets 1, the
second 2, and so on. It is exposed for diagnostics, stable ordering, and
building external side tables keyed by symbol; it is not a string and
carries no meaning outside the interner that produced it.
§Examples
use intern_lang::Interner;
let mut interner = Interner::new();
let first = interner.intern("alpha");
let second = interner.intern("beta");
assert_eq!(first.as_u32(), 1);
assert_eq!(second.as_u32(), 2);
// Re-interning an existing string returns the same id, never a new one.
assert_eq!(interner.intern("alpha").as_u32(), 1);