Struct Term 

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

A compact, copyable handle referencing a term stored in a Arena.

Internally a Term stores a single [Handle] enum variant. On 64‑bit targets the discriminant and associated payload occupy 16 bytes in total. Users should never construct Term values directly; instead use the associated constructors or the convenience macros in the [term] module. Instances of Term are cheap to copy (Copy and Clone).

Implementations

impl Term

pub fn display<'a>(&'a self, arena: &'a Arena) -> TermDisplay<'a>

Return a TermDisplay suitable for formatting with fmt::Display.

Use this method when you want to render a term:

println!("{}", term.display(&arena));

impl Term

pub const UNIT: Self

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: Self

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 int(i: impl Into<i64>) -> Self

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(f: impl Into<f64>) -> Self

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

pub fn date(ms: impl Into<i64>) -> Self

Construct a new date term representing a Unix epoch in milliseconds. Dates share the same underlying storage as integers but use a distinct tag so they do not compare equal with integer terms.

pub fn atom(arena: &mut Arena, name: impl AsRef<str>) -> Self

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(arena: &mut Arena, name: impl AsRef<str>) -> Self

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(arena: &mut Arena, s: impl AsRef<str>) -> Self

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(arena: &mut Arena, bytes: impl AsRef<[u8]>) -> Self

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( arena: &mut Arena, functor: impl AsRef<str>, args: impl IntoIterator<Item = impl IntoTerm>, ) -> Self

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( arena: &mut Arena, terms: impl IntoIterator<Item = impl IntoTerm>, ) -> Result<Self, 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( arena: &mut Arena, terms: impl IntoIterator<Item = impl IntoTerm>, ) -> Self

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

pub fn listc( arena: &mut Arena, terms: impl IntoIterator<Item = impl IntoTerm>, tail: impl IntoTerm, ) -> Self

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( arena: &mut Arena, terms: impl IntoIterator<Item = impl IntoTerm>, ) -> Self

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

pub fn unpack_int(&self, arena: &Arena) -> Result<i64, TermError>

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

pub fn unpack_real(&self, arena: &Arena) -> Result<f64, TermError>

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

pub fn unpack_date(&self, arena: &Arena) -> Result<i64, TermError>

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

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

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

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

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

pub fn unpack_atom<'a>( &'a self, arena: &'a Arena, 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, arena: &'a Arena, 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, arena: &'a Arena, 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, arena: &'a Arena, 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, arena: &'a Arena, ) -> 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, arena: &'a Arena, ) -> 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, arena: &Arena, ) -> Result<[Term; ARITY], TermError>

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

pub fn is_inline(&self) -> bool

Returns true if the value fits directly in Term without arena storage, i.e. int, real, date, or a small atom, var, str, or bin.

pub fn is_func(&self) -> bool

Returns true if the term is a compound term.

pub fn is_list(&self) -> bool

Returns true if the term is a list.

pub fn is_tuple(&self) -> bool

Returns true if the term is a tuple.

pub fn is_int(&self) -> bool

Returns true if the term is an integer.

pub fn is_real(&self) -> bool

Returns true if the term is a real (floating-point) number.

pub fn is_date(&self) -> bool

Returns true if the term is a date.

pub fn is_atom(&self) -> bool

Returns true if the term is an atom.

pub fn is_var(&self) -> bool

Returns true if the term is a variable.

pub fn is_number(&self) -> bool

Returns true if the term is a number (int, real, or date).

pub fn is_str(&self) -> bool

Returns true if the term is a string.

pub fn is_bin(&self) -> bool

Returns true if the term is a binary blob.

pub fn arity(&self) -> usize

Returns the arity of the term. Currently the arity of lists and variables is 0.

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

Returns the name of a compound term, atom, or variable. Use [atom_name], [func_name], or [var_name] to ensure the term is of a specific kind.

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

Returns the name of an atom,

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

Returns the name of a variable.

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

Returns the name of a compund term.

pub fn kind_name(&self) -> &'static str

Returns a string describing the kind of this term.

impl Term

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

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

Trait Implementations

impl AsRef<Term> for Term

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Term

fn clone(&self) -> Term

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Term

Implements the standard Debug formatter for Term.

This prints a developer-friendly representation of the term, showing its kind (e.g. int, atom, list, tuple) and its internal value in a form useful for debugging.

The output is not guaranteed to be stable across versions and should not be parsed; it is intended purely for diagnostics and logging.

Example

let t = Term::int(42);
println!("{:?}", t); // e.g. prints `Int(42)`

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

Formats the value using the given formatter.

impl From<f32> for Term

fn from(v: f32) -> Self

Converts to this type from the input type.

impl From<f64> for Term

fn from(v: f64) -> Self

Converts to this type from the input type.

impl From<i16> for Term

fn from(v: i16) -> Self

Converts to this type from the input type.

impl From<i32> for Term

fn from(v: i32) -> Self

Converts to this type from the input type.

impl From<i64> for Term

fn from(v: i64) -> Self

Converts to this type from the input type.

impl From<i8> for Term

fn from(v: i8) -> Self

Converts to this type from the input type.

impl From<u16> for Term

fn from(v: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Term

fn from(v: u32) -> Self

Converts to this type from the input type.

impl From<u8> for Term

fn from(v: u8) -> Self

Converts to this type from the input type.

impl IntoTerm for &Term

fn into_term(self, _arena: &mut Arena) -> Term

impl IntoTerm for Term

fn into_term(self, _arena: &mut Arena) -> Term

impl PartialEq for Term

fn eq(&self, other: &Term) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Term

fn partial_cmp(&self, other: &Term) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Term

impl StructuralPartialEq for Term