Struct AtomTable 

pub struct AtomTable(/* private fields */);

A string uniquing table - only one copy of a string is stored and all attempts to add the same string again return the same atom. This table is intended to be easily shareable, so it utilizes interior mutability. UnsafeCell<> is safe because we never allow reference to it to escape.

Implementations

impl AtomTable

pub fn new() -> AtomTable

Create a new empty atom table.

pub fn atom<V: Into<String> + AsRef<str>>(&self, value: V) -> Atom

Add a string to the table and return its atom index. The same string always returns the same index.

pub fn str(&self, ident: Atom) -> &str

Return the contents of the specified atom.

pub fn try_str(&self, ident: Atom) -> Option<&str>

pub fn atom_u16<V: Into<Vec<u16>> + AsRef<[u16]>>(&self, value: V) -> AtomU16

Add a string to the table and return its atom index. The same string always returns the same index.

pub fn str_u16(&self, ident: AtomU16) -> &[u16]

Return the contents of the specified atom.

pub fn try_str_u16(&self, ident: AtomU16) -> Option<&[u16]>

pub fn atom_bytes<V: Into<Vec<u8>> + AsRef<[u8]>>(&self, value: V) -> AtomBytes

Add a byte string to the table and return its atom index. The same byte sequence always returns the same index. The bytes need not be valid UTF-8 (e.g., WTF-8 sequences encoding lone surrogates are accepted).

pub fn bytes(&self, ident: AtomBytes) -> &[u8]

Return the contents of the specified atom bytes.

pub fn try_bytes(&self, ident: AtomBytes) -> Option<&[u8]>

pub fn bytes_str_lossy(&self, ident: AtomBytes) -> &str

Return the contents of the specified atom bytes as a string, substituting U+FFFD for anything that cannot be represented.

The atom’s bytes are WTF-8, so a surrogate pair is folded back into the supplementary-plane character it encodes — that is exact, and it is the common case, because with the lexer’s default settings an astral character in a string literal is stored in surrogate-pair form. An unpaired surrogate has no UTF-8 form and becomes exactly one U+FFFD, as does any other ill-formed sequence.

When the bytes are already valid UTF-8, which is always the case for identifiers, the result borrows them directly with no allocation and no lookup. Otherwise the converted string is built once and owned by the table, so the returned reference stays valid for as long as the table does, whatever is interned afterwards.

Use AtomTable::bytes when the exact bytes matter, and AtomTable::try_bytes_str when substitution would be data loss — notably for JS string-literal values, where an unpaired surrogate is a legal value rather than malformed data.

Panics

Panics if ident is not a valid atom of this table, like AtomTable::bytes.

pub fn try_bytes_str(&self, ident: AtomBytes) -> Option<&str>

Return the contents of the specified atom bytes as a string whenever they can be represented as one exactly, and None when they cannot.

None means the atom holds an unpaired surrogate — a legal JS string value with no UTF-8 form — or bytes that are not WTF-8 at all. It does not mean merely “the bytes are not literally valid UTF-8”: a surrogate pair is folded back into the character it encodes and returned as Some, since the pair and that character are two encodings of the same string. An emoji in a string literal is stored in surrogate-pair form and therefore comes back as Some, not None.

Valid UTF-8 borrows the atom’s bytes with no allocation; the folding path builds the string once and anchors it in the table, sharing the one entry with AtomTable::bytes_str_lossy.

Unlike AtomTable::bytes_str_lossy this never substitutes, so it is the right accessor for JS string-literal values, where replacing an unpaired surrogate with U+FFFD would silently corrupt the program’s data.

Also returns None if ident is not a valid atom of this table, so that — like AtomTable::try_bytes — it never panics.

pub fn in_debug_context<R, F: FnOnce() -> R>(&self, f: F) -> R

Execute the callback in a context where this table is used for debug printing of atoms.

pub unsafe fn unsafe_set_debug_context(ptr: *const Self) -> *const Self

Set a table or nullptr as the Atom debug context. If non-null, debug printing of atoms will use it. Return the previous debug context.

Safety

The table must not be destroyed or moved while it is set.

Trait Implementations

impl Debug for AtomTable

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AtomTable

fn default() -> AtomTable

Returns the “default value” for a type.

impl Index<Atom> for AtomTable

type Output = str

The returned type after indexing.

fn index(&self, index: Atom) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<AtomBytes> for AtomTable

type Output = [u8]

The returned type after indexing.

fn index(&self, index: AtomBytes) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<AtomU16> for AtomTable

type Output = [u16]

The returned type after indexing.

fn index(&self, index: AtomU16) -> &Self::Output

Performs the indexing (container[index]) operation.