Struct Arena 

pub struct Arena { /* private fields */ }

The arena interns atoms, variables, strings, binaries, and compound terms.
An Arena owns all memory for interned data. Terms store only indices into this arena and remain valid as long as the epoch they belong to is alive.

Epochs

The arena is divided into epochs. Conceptually, epochs form a stack.
Allocation begins in epoch 0, which starts at offset 0 in all underlying storages. At any time, the user can call begin_epoch().
This operation:

• Freezes the current epoch (recording its byte and term offsets).
• Starts a new active epoch for subsequent allocations.

At any point, there are K alive epochs, where:

• K - 1 are frozen (no new data is added),
• The last one is active (all new allocations go there),
• and K <= MAX_LIVE_EPOCHS (typically very small number, currently 8).

Terms remain valid only while the epoch they were created in is alive.

Truncation

The arena can be truncated back to a given epoch m, where 0 <= m < MAX_LIVE_EPOCHS:

• Epoch m and all epochs more recent than m are erased in O(1).
• Terms from those epochs become invalid.
• truncate(0) erases all data (synonym: clear()).
• truncate(current_epoch()) erases only the latest epoch
  (synonym: truncate_current()).

Conceptually, epochs form a stack: you can push with begin_epoch() and pop with truncate_current(). This makes it efficient to manage temporary, scoped allocations. For example:

let mut arena = Arena::with_capacity(4096, 1024);
let epoch = arena.begin_epoch().unwrap();
// … build temporary terms here …
arena.truncate(epoch).unwrap(); // frees them all at once

This is especially useful during iteration: each loop can create short-lived terms, then discard them cleanly all at once at the end.

Implementations

impl Arena

pub const UNIT: Term = Term::UNIT

Constant representing the zero‑arity tuple (unit). Internally this is the atom "unit" encoded as a small atom. It may be copied freely and does not depend on any arena.

pub const NIL: Term = Term::NIL

Constant representing the empty list (nil). Internally this is the atom "nil" encoded as a small atom. It may be copied freely and does not depend on any arena.

pub fn with_capacity(bytes_capacity: usize, terms_capacity: usize) -> Self

Create a new, empty arena with given capacities.

pub fn new() -> Self

Create a new, empty arena with default capacities.

pub fn stats(&self) -> ArenaStats

Returns stats.

pub fn current_epoch(&self) -> EpochID

Returns current epoch.

pub fn begin_epoch(&mut self) -> Result<EpochID, TermError>

Freezes current epoch and begins a new one.

pub fn clear(&mut self) -> Result<(), TermError>

Erases arena in O(1). Does not shrink the allocated capacity.

pub fn truncate_current(&mut self) -> Result<(), TermError>

Epoch m and all epochs more recent than m are erased in O(1) Does not shrink the allocated capacity.

pub fn truncate(&mut self, epoch_id: EpochID) -> Result<(), TermError>

Epoch m and all epochs more recent than m are erased in O(1) Does not shrink the allocated capacity.

pub fn view<'a>(&'a self, term: &'a Term) -> Result<View<'a>, TermError>

Produce a View of the given term that borrows from this Arena. This method decodes any inlined bytes and dereferences indexes into the arena to yield structured references. See View for details.

pub fn term<'a, T: IntoTerm>(&'a mut self, value: T) -> Term

Convert a value into Term.

pub fn int(&mut self, i: impl Into<i64>) -> Term

Construct a new integer term. The full 64 bit two’s complement representation of i is stored in the payload. No truncation occurs.

pub fn real(&mut self, r: impl Into<f64>) -> Term

Construct a new floating point term. The full 64 bit IEEE‑754 bit pattern is stored in the payload without truncation.

pub fn date(&mut self, ms: impl Into<i64>) -> Term

Construct a new date term representing a Unix epoch in milliseconds.

pub fn atom(&mut self, name: impl AsRef<str>) -> Term

Construct or intern an atom into the arena and produce a term referencing it. Small atom names (≤14 bytes of UTF‑8) are inlined directly into the handle; longer names are interned into the arena and referenced by index and length.

pub fn var(&mut self, name: impl AsRef<str>) -> Term

Construct or intern a variable into the arena and produce a term referencing it. Small variable names (≤14 bytes) are inlined directly into the handle; longer names are interned in the arena and referenced by index.

pub fn str(&mut self, s: impl AsRef<str>) -> Term

Construct or intern a UTF‑8 string into the arena and produce a term referencing it. Strings longer than 14 bytes are interned in the arena; shorter strings are inlined. Invalid UTF‑8 will result in an error.

pub fn bin(&mut self, bytes: impl AsRef<[u8]>) -> Term

Construct or intern a binary blob into the arena and produce a term referencing it. Blobs longer than 14 bytes are interned in the arena; shorter blobs are inlined.

pub fn func( &mut self, functor: impl AsRef<str>, args: impl IntoIterator<Item = impl IntoTerm>, ) -> Term

Construct a new compound term by interning the functor and arguments in the arena. The returned term references a slice in the arena’s term storage consisting of the functor atom as the first entry followed by the argument handles. A functor of arity zero results in an atom.

pub fn funcv( &mut self, terms: impl IntoIterator<Item = impl IntoTerm>, ) -> Result<Term, TermError>

Construct a new compound term by interning the functor and its arguments into the arena as a sequence of terms (functor first, then arguments). A functor with no arguments yields the atom itself. Errors if no functor is provided or if the first term is not an atom.

pub fn list(&mut self, terms: impl IntoIterator<Item = impl IntoTerm>) -> Term

Constructs a new list. A list is represented internally as an array of terms. If terms is empty, returns nil.

pub fn listc( &mut self, terms: impl IntoIterator<Item = impl IntoTerm>, tail: impl IntoTerm, ) -> Term

Constructs a new improper list. An improper list is represented as a list and additional argument. If terms is empty, returns nil.

pub fn tuple(&mut self, terms: impl IntoIterator<Item = impl IntoTerm>) -> Term

Constructs a new tuple. A tuple is represented internally as an array of terms.

pub fn name<'a>(&'a self, term: &'a Term) -> Result<&'a str, TermError>

Returns the name of a compound term, atom, or variable. Use [unpack_atom], [unpack_func], or [unpack_var] to ensure the term is of a specific kind.

pub fn atom_name<'a>(&'a self, term: &'a Term) -> Result<&'a str, TermError>

Returns the name of an atom,

pub fn var_name<'a>(&'a self, term: &'a Term) -> Result<&'a str, TermError>

Returns the name of a variable.

pub fn func_name<'a>(&'a self, term: &'a Term) -> Result<&'a str, TermError>

Returns the name of a compund term.

pub fn unpack_int(&self, term: &Term) -> Result<i64, TermError>

Returns the value if term is an integer, otherwise an error.

pub fn unpack_real(&self, term: &Term) -> Result<f64, TermError>

Returns the value if term is a real, otherwise an error.

pub fn unpack_date(&self, term: &Term) -> Result<i64, TermError>

Returns the value if term is a date, otherwise an error.

pub fn unpack_str<'a>(&'a self, term: &'a Term) -> Result<&'a str, TermError>

Returns the string slice if term is a string, otherwise an error.

pub fn unpack_bin<'a>(&'a self, term: &'a Term) -> Result<&'a [u8], TermError>

Returns the slice if term is a binary blob, otherwise an error.

pub fn unpack_atom<'a>( &'a self, term: &'a Term, allowed_names: &[&str], ) -> Result<&'a str, TermError>

Returns the name if term is an atom, otherwise an error.

pub fn unpack_var<'a>( &'a self, term: &'a Term, allowed_names: &[&str], ) -> Result<&'a str, TermError>

Returns the name if term is a variable, otherwise an error.

pub fn unpack_func_any<'a>( &'a self, term: &'a Term, allowed_names: &[&str], ) -> Result<(&'a Term, &'a [Term]), TermError>

Returns the name and arguments if term is a compound term of any arity or an atom and its name is in allowed_names (or if allowed_names is empty), otherwise returns an error.

pub fn unpack_func<'a, const ARITY: usize>( &'a self, term: &'a Term, allowed_names: &[&str], ) -> Result<(&'a Term, [Term; ARITY]), TermError>

Returns the name and arguments if term is a compound term of arity ARITY (or an atom if ARITY == 0) and its name is in allowed_names (or if allowed_names is empty), otherwise returns an error.

pub fn unpack_list<'a>( &'a self, term: &'a Term, ) -> Result<(&'a [Term], &'a Term), TermError>

Returns the slice with list elements and the tail if term is a list, otherwise returns an error.

pub fn unpack_tuple_any<'a>( &'a self, term: &'a Term, ) -> Result<&'a [Term], TermError>

Returns the slice with tuple elements if term is a tuple of any arity, otherwise returns an error.

pub fn unpack_tuple<const ARITY: usize>( &self, term: &Term, ) -> Result<[Term; ARITY], TermError>

Returns the tuple elements if term is a tuple of arity ARITY, otherwise returns an error.

Trait Implementations

impl Clone for Arena

fn clone(&self) -> Arena

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Arena

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

Formats the value using the given formatter.

impl Default for Arena

fn default() -> Arena

Returns the “default value” for a type.