Struct rustler::Term

pub struct Term<'a> { /* private fields */ }

Term is used to represent all erlang terms. Terms are always lifetime limited by a Env.

Term is cloneable and copyable, but it can not exist outside of the lifetime of the Env that owns it.

Implementations

impl<'a> Term<'a>

Atom terms

pub fn atom_to_string(&self) -> NifResult<String>

When the term is an atom, this method will return the string representation of it.

If you only need to test for equality, comparing the terms directly is much faster.

Will return None if the term is not an atom.

impl<'a> Term<'a>

Binary terms

pub fn into_binary(self) -> NifResult<Binary<'a>>

impl<'a> Term<'a>

List terms

pub fn list_new_empty(env: Env<'a>) -> Term<'a>

Returns a new empty list.

pub fn into_list_iterator(self) -> NifResult<ListIterator<'a>>

Returns an iterator over a list term. See documentation for ListIterator for more information.

Returns None if the term is not a list.

pub fn list_length(self) -> NifResult<usize>

Returns the length of a list term.

Returns None if the term is not a list.

Elixir equivalent

length(self_term)

pub fn list_get_cell(self) -> NifResult<(Term<'a>, Term<'a>)>

Unpacks a single cell at the head of a list term, and returns the result as a tuple of (head, tail).

Returns None if the term is not a list.

Elixir equivalent

[head, tail] = self_term
{head, tail}

pub fn list_reverse(self) -> NifResult<Term<'a>>

Makes a copy of the self list term and reverses it.

Returns Err(Error::BadArg) if the term is not a list.

pub fn list_prepend(self, head: impl Encoder) -> Term<'a>

Adds head in a list cell with self as tail.

impl<'a> Term<'a>

Map terms

pub fn map_new(env: Env<'a>) -> Term<'a>

Constructs a new, empty map term.

Elixir equivalent

%{}

pub fn map_from_arrays( env: Env<'a>, keys: &[impl Encoder], values: &[impl Encoder] ) -> NifResult<Term<'a>>

Construct a new map from two vectors

Elixir equivalent

keys = ["foo", "bar"]
values = [1, 2]
Enum.zip(keys, values) |> Map.new()

pub fn map_from_term_arrays( env: Env<'a>, keys: &[Term<'a>], values: &[Term<'a>] ) -> NifResult<Term<'a>>

Construct a new map from two vectors of terms.

It is identical to map_from_arrays, but requires the keys and values to be encoded already - this is useful for constructing maps whose values or keys are different Rust types, with the same performance as map_from_arrays.

pub fn map_from_pairs( env: Env<'a>, pairs: &[(impl Encoder, impl Encoder)] ) -> NifResult<Term<'a>>

Construct a new map from pairs of terms

It is similar to map_from_arrays but receives only one vector with the pairs of (key, value).

Elixir equivalent

Map.new([{"foo", 1}, {"bar", 2}])

pub fn map_get(self, key: impl Encoder) -> NifResult<Term<'a>>

Gets the value corresponding to a key in a map term.

Returns Err(Error::BadArg) if the term is not a map or if key doesn’t exist in the map.

Elixir equivalent

Map.get(self_term, key)

pub fn map_size(self) -> NifResult<usize>

Gets the size of a map term.

Returns Err(Error::BadArg) if the term is not a map.

Elixir equivalent

map_size(self_term)

pub fn map_put( self, key: impl Encoder, value: impl Encoder ) -> NifResult<Term<'a>>

Makes a copy of the self map term and sets key to value. If the value already exists, it is overwritten.

Returns Err(Error::BadArg) if the term is not a map.

Elixir equivalent

Map.put(self_term, key, value)

pub fn map_remove(self, key: impl Encoder) -> NifResult<Term<'a>>

Makes a copy of the self map term and removes key. If the key doesn’t exist, the original map is returned.

Returns Err(Error::BadArg) if the term is not a map.

Elixir equivalent

Map.delete(self_term, key)

pub fn map_update( self, key: impl Encoder, new_value: impl Encoder ) -> NifResult<Term<'a>>

Makes a copy of the self map term where key is set to value.

Returns Err(Error::BadArg) if the term is not a map of if key doesn’t exist.

impl<'a> Term<'a>

pub unsafe fn new(env: Env<'a>, inner: NIF_TERM) -> Self

Create a Term from a raw NIF_TERM.

Unsafe

The caller must ensure that env is the environment that inner belongs to, unless inner is an atom term.

pub fn as_c_arg(&self) -> NIF_TERM

This extracts the raw term pointer. It is usually used in order to obtain a type that can be passed to calls into the erlang vm.

pub fn get_env(self) -> Env<'a>

pub fn in_env<'b>(&self, env: Env<'b>) -> Term<'b>

Returns a representation of self in the given Env.

If the term is already is in the provided env, it will be directly returned. Otherwise the term will be copied over.

pub fn decode<T>(self) -> NifResult<T>

where T: Decoder<'a>,

Decodes the Term into type T.

This should be used as the primary method of extracting the value from a Term.

Examples

let term: Term = ...;
let number: i32 = term.decode()?;

pub fn decode_as_binary(self) -> NifResult<Binary<'a>>

Decodes the Term into Binary

This could be used as a replacement for decode when decoding Binary from an iolist is needed.

pub fn to_binary(self) -> OwnedBinary

pub fn hash_internal(&self, salt: u32) -> u32

Non-portable hash function that only guarantees the same hash for the same term within one Erlang VM instance.

It takes 32-bit salt values and generates hashes within 0..2^32-1.

pub fn hash_phash2(&self) -> u32

Portable hash function that gives the same hash for the same Erlang term regardless of machine architecture and ERTS version.

It generates hashes within 0..2^27-1.

pub fn get_erl_type(&self) -> ErlNifTermType

impl<'a> Term<'a>

Type checks

pub fn get_type(self) -> TermType

Returns an enum representing which type the term is. Note that using the individual is_* functions is more efficient for checking a single type.

pub fn is_atom(self) -> bool

pub fn is_binary(self) -> bool

pub fn is_empty_list(self) -> bool

pub fn is_fun(self) -> bool

pub fn is_list(self) -> bool

pub fn is_map(self) -> bool

pub fn is_number(self) -> bool

pub fn is_pid(self) -> bool

pub fn is_port(self) -> bool

pub fn is_ref(self) -> bool

pub fn is_tuple(self) -> bool

pub fn is_float(self) -> bool

pub fn is_integer(self) -> bool

Trait Implementations

impl<'a> Clone for Term<'a>

fn clone(&self) -> Term<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Term<'a>

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

Formats the value using the given formatter.

impl<'a> Decoder<'a> for Term<'a>

fn decode(term: Term<'a>) -> NifResult<Self>

impl<'a> Encoder for Term<'a>

fn encode<'b>(&self, env: Env<'b>) -> Term<'b>

impl<'a> From<NewBinary<'a>> for Term<'a>

fn from(new_binary: NewBinary<'a>) -> Self

Converts to this type from the input type.

impl<'a> Hash for Term<'a>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> Ord for Term<'a>

fn cmp(&self, other: &Term<'_>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<'a> PartialEq<Term<'a>> for Atom

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<'a> PartialEq for Term<'a>

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<'a> PartialOrd for Term<'a>

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<'a> Copy for Term<'a>

impl<'a> Eq for Term<'a>

impl<'a> Send for Term<'a>

impl<'a> Sync for Term<'a>