Enum rust_eterm::terms::TermTag

#[repr(u8)]
pub enum TermTag {
    AtomCacheRef,
    SmallInteger,
    Integer,
    Float,
    Port,
    NewPort,
    Pid,
    NewPid,
    SmallTuple,
    LargeTuple,
    Map,
    Nil,
    String,
    List,
    Binary,
    SmallBig,
    LargeBig,
    Reference,
    NewReference,
    NewerReference,
    Fun,
    NewFun,
    Export,
    BitBinary,
    NewFloat,
    AtomUtf8,
    SmallAtomUtf8,
    Atom,
    SmallAtom,
}

Variants

AtomCacheRef

Refers to the atom with AtomCacheReferenceIndex in the distribution header.

Binary representation

1 byte	1 byte
82	AtomCacheReferenceIndex

String representation

This string is represented just like an atom. The value of this atom is looked up in the distribution header.

SmallInteger

Unsigned 8-bit integer.

Binary representation

1 byte	1 byte
97	u8

String representation

Represent the value of this 2's complement 8-bit signed integer as either:

• Simple decimal
• An ASCII character Z in the form $Z
• Any other base B in 2..36 in the form B#N

The recommendation is to always output like a simple decimal, as it is the simplest and most portable.

Integer

Signed 32-bit integer.

Binary layout

1 byte	4 bytes
98	i32

String representation

The representations of this 2's complement 32-bit signed integer are:

• Simple decimal
• An ASCII character Z in the form $Z
• Any other base B in 2..36 in the form B#N

The recommendation is to always output like a simple decimal, as it is the simplest and most portable.

Float

A finite float (i.e. not inf, -inf or NaN) is stored in string format.

This term is used in minor version 0 of the external format; it has been superseded by NewFloat.

Binary representation

1 byte	31 bytes
99	Float as string

The format used in sprintf to format the float is %.20e (there are more bytes allocated than necessary).

String representation

The parsable values should be a decimal integer with either an exponent or a trailing dot with 1 or more numbers behind it. An optional base can also be specified in front of it, separating the value and base with an octothorpe (#).

The recommendation is to output with the format being %.20e as it is guaranteed not to lose precision.

Port

Same as NewPort except the Creation field is only one byte and only two bits are significant, the rest are to be 0.

Binary representation

1 byte	N bytes	4 bytes	1 byte
102	Node	ID	Creation

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.
• ID is a 32-bit big endian unsigned integer. Only 15 bits are significant; the rest are to be 0.
• Creation is a 8-bit unsigned integer. All ports originating from the same node incarnation must have identical Creation values. This makes it possible to separate identifiers from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

String representation

There is not actually a good way to represent a port as a string because the Node value may not be known. A representation of #Port<0.{id}.{creation}> can be used as a means to visualize the value of a port regardless.

NewPort

Encodes a port identifier (obtained from erlang:open_port/2).

Introduced in OTP 19, but only to be decoded and echoed back. Not encoded for local ports. Planned to supersede PORT_EXT in OTP 23 when DFLAG_BIG_CREATON becomes mandatory.

Binary representation

1 byte	N bytes	4 bytes	4 bytes
89	Node	ID	Creation

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.
• ID is a 32-bit big endian unsigned integer. Only 15 bits are significant; the rest are to be 0.
• Creation is a 32-bit big endian unsigned integer. All ports originating from the same node incarnation must have identical Creation values. This makes it possible to separate identifiers from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

String representation

There is not actually a good way to represent a port as a string because the Node value may not be known. A representation of #Port<0.{id}.{creation}> can be used as a means to visualize the value of a port regardless.

Pid

Same as NewPid except the Creation field is only one byte and only two bits are significant, the rest are to be 0.

Binary representation

1 byte	N bytes	4 bytes	4 bytes	1 byte
103	Node	ID	Serial	Creation

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.
• ID is a 32-bit big endian unsigned integer. Only 15 bits are significant; the rest are to be 0.
• Serial is a 32-bit big endian unsigned integer. Only 13 bits are significant; the rest are to be 0.
• Creation is a 8-bit unsigned integer. All identifiers originating from the same node incarnation must have identical Creation values. This makes it possible to separate identifiers from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

String representation

There is not actually a good way to represent a pid as a string because the Node value may not be known. A representation of <0.{id}.{creation}> can be used as a means to visualize the value of a pid regardless.

NewPid

Encodes an Erlang process identifier object.

Introduced in OTP 19, but only to be decoded and echoed back. Not encoded for local processes. Planned to supersede Pid in OTP 23 when DFLAG_BIG_CREATON becomes mandatory.

Binary representation

1 byte	N bytes	4 bytes	4 bytes	4 bytes
88	Node	ID	Serial	Creation

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.
• ID is a 32-bit big endian unsigned integer. Only 15 bits are significant; the rest are to be 0.
• Serial is a 32-bit big endian unsigned integer. Only 13 bits are significant; the rest are to be 0.
• Creation is a 32-bit big endian unsigned integer. All identifiers originating from the same node incarnation must have identical Creation values. This makes it possible to separate identifiers from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

String representation

There is not actually a good way to represent a pid as a string because the Node value may not be known. A representation of <0.{id}.{creation}> can be used as a means to visualize the value of a pid regardless.

SmallTuple

Encodes a tuple.

Binary representation

1 byte	1 byte	N bytes
104	Arity	Elements

• Arity is an unsigned 8-bit integer.
• Elements are each encoded terms. There are Arity amount of elements.

String representation

The string representation is simply a comma-separated list of stringified terms completely wrapped with curly braces.

LargeTuple

Same as SmallTuple except that Arity is an unsigned 4 byte integer.

Binary representation

1 byte	4 bytes	N bytes
105	Arity	Elements

• Arity is an unsigned 32-bit big-endian integer.
• Elements are each encoded terms. There are Arity amount of elements.

String representation

The string representation is simply a comma-separated list of stringified terms completely wrapped with curly braces.

Map

Encodes a map.

Binary representation

1 byte	4 bytes	N bytes
116	Arity	Pairs

• Arity is the amount of key-value pairs in this map.
• Pairs are each two encoded terms. There are Arity amount of pairs. There are no duplicate keys.

String representation

A map is represented like this:

#{ key0 => value0 (, keyN => valueN )* }

Nil

The representation for an empty list, that is, the Erlang syntax [].

Binary representation

1 byte
106

String representation

[].

String

String does not have a corresponding Erlang representation, but is an optimization for sending lists of bytes (integer in the range 0-255) more efficiently over the distribution.

As field Length is an unsigned 2 byte integer (big-endian), implementations must ensure that lists longer than 65535 elements are encoded as List.

Binary representation

1 byte	2 bytes	Length bytes
107	Length	Characters

The characters are UTF-8 encoded characters. There are a maximum of 65535 bytes, however many characters that turns out to be. It is not a maximum of 65535 characters!

String representation

Place the string between double quotes, and apply the following escape sequences:

Actual character	Escape sequence
backspace	\b
delete	\d
escape	\e
form feed	\f
newline	\n
carriage return	\r
tab	\t
vertical tab	\v
double qoute (")	\"

List

The representation for a non-empty list.

Binary representation

1 byte	4 bytes	N bytes	M bytes
108	Length	Elements	Tail

• Length is a 32-bit big-endian unsigned number that is the number of elements that follows in section Elements.
• Elements are each encoded terms.
• Tail is the final tail of the list; it is Nil for a proper list, but can be any type if the list is improper (for example, [a|b]).

String representation

Place a comma-separated list of stringified terms between block-quotes.

Binary

Binaries are byte-arrays. They are represented as bitstrings or binaries in the Erlang language.

Binary representation

1 byte	4 bytes	Len bytes
109	Len	Data

• The Len length field is an unsigned 4 byte integer (big-endian).

String representation

The output format is simply to convert each byte to a decimal number and print them as a comma-separated list between a pair of double angle brackets (<<, >>).

For reading, the values should be any of:

• A number according to Integer

SmallBig

Integer representation of an integer N where -2^256 < N < 2^256.

Binary representation

1 byte	1 byte	1 byte	Len bytes
110	Len	Sign	d0..d(Len - 1)

Bignums are stored in unary form with a Sign byte, that is, 0 if the bignum is positive and 1 if it is negative. The digits are stored with the least significant byte stored first. To calculate the integer, the following formula can be used:

B = 256
(d0*B^0 + d1*B^1 + d2*B^2 + ... d(N-1)*B^(n-1))

String representation

The representations of this 2's complement 32-bit signed integer are:

• Simple decimal
• An ASCII character Z in the form $Z
• Any other base B in 2..36 in the form B#N

The recommendation is to always output like a simple decimal, as it is the simplest and most portable.

LargeBig

Integer representation of an integer N where -2^(2^32) < N < 2^(2^32).

Binary representation

1 byte	4 bytes	1 byte	Len bytes
111	Len	Sign	d0..d(Len - 1)

Bignums are stored in unary form with a Sign byte, that is, 0 if the bignum is positive and 1 if it is negative. The digits are stored with the least significant byte stored first. To calculate the integer, the following formula can be used:

B = 256
(d0*B^0 + d1*B^1 + d2*B^2 + ... d(N-1)*B^(n-1))

String representation

The representations of this 2's complement 32-bit signed integer are:

• Simple decimal
• An ASCII character Z in the form $Z
• Any other base B in 2..36 in the form B#N

The recommendation is to always output like a simple decimal, as it is the simplest and most portable.

Reference

Deprecated method for encoding a reference term.

Binary representation

1 byte	N bytes	4 bytes	1 byte
101	Node	ID	Creation

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.
• Creation is a 8-bit unsigned integer. All references originating from the same node incarnation must have identical Creation values. This makes it possible to separate references from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).
• ID is a node-unique number that describes this reference uniquely.

NewReference

Deprecated method for encoding a reference term.

Binary representation

1 byte	2 bytes	N bytes	1 byte	Len * 4 bytes
101	Len	Node	Creation	ID

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.

• Creation is a 8-bit unsigned integer. All references originating from the same node incarnation must have identical Creation values. This makes it possible to separate references from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

• Len describes how many 32-bit values are contained within ID.

• ID is a series of 32-bit unsigned integers. The erlang docs state:

  A sequence of Len big-endian unsigned integers (4 bytes each, so N' = 4 * Len), but is to be regarded as uninterpreted data.

  I am having trouble interpreting this statement, so the assumption is that only the first is interpreted, and only the 18 least-significant bits of that value are interpreted, and that the rest are to be 0.

NewerReference

Encodes a reference term.

Binary representation

1 byte	2 bytes	N bytes	4 bytes	Len * 4 bytes
90	Len	Node	Creation	ID

• Node is the name of the originating node, encoded using AtomUtf8, SmallAtomUtf8 or AtomCacheRef.

• Creation is a 32-bit big-endian unsigned integer. All references originating from the same node incarnation must have identical Creation values. This makes it possible to separate references from old (crashed) nodes from a new one. The value zero should be avoided for normal operations as it is used as a wild card for debug purpose (like a pid returned by [erlang:list_to_pid/1]).

• Len describes how many 32-bit values are contained within ID.

• ID is a series of 32-bit unsigned integers. The erlang docs state:

  A sequence of Len big-endian unsigned integers (4 bytes each, so N' = 4 * Len), but is to be regarded as uninterpreted data.

  I am having trouble interpreting this statement, so the assumption is that only the first is interpreted, and only the 18 least-significant bits of that value are interpreted, and that the rest are to be 0.

Fun

Old encoding of internal functions: fun F/A and fun(Arg1,..) -> ... end.

Binary representation

1 byte	4 bytes	N bytes	N' bytes	N'' bytes	N''' bytes	N'''' bytes
117	NumFree	Pid	Module	Index	Uniq	Free vars...

• NumFree is a 32-bit big-endian unsigned integer is the number of free variables (Free vars).
• Pid is a process identifier as in Pid. Represents the process in which the fun was created.
• Module, encoded as an atom using AtomUtf8, SmallAtomUtf8, or AtomCacheRef, is the module that the fun is implemented in.
• Index, encoded as an integer using SmallInteger or Integer is typically a small index into the module's fun table.
• Uniq, encoded as an integer using SmallInteger or Integer is the hash value of the parse for the fun.
• Free vars are NumFree amount of terms, each one encoded according to its type.

NewFun

Encoding of internal functions: fun F/A and fun(Arg1,..) -> ... end.

Binary representation

1 byte	4 bytes	1 byte	16 bytes	4 bytes	4 bytes	N bytes	N' bytes	N'' bytes	N''' bytes	N'''' bytes
112	Size	Arity	Uniq	Index	NumFree	Module	OldIndex	OldUniq	Pid	Free vars...

• Size is the total number of bytes, including field Size.
• Arity is the arity of the function implementing the fun, as an 8-bit unsigned number.
• Uniq is a 16 bytes MD5 of the significant parts of the Beam file.
• Index is a 32-bit big endian unsigned index number. Each fun within a module has an unique index.
• NumFree is the number of free variables, stored as a 32-bit big endian unsigned integer.
• Module, encoded as an atom using AtomUtf8, SmallAtomUtf8, or AtomCacheRef, is the module that the fun is implemented in.
• OldIndex, encoded as an integer encoded using SmallInteger or Integer, is typically a small index into the module's fun table.
• OldUniq, encoded as an integer using using SmallInteger or Integer, is the hash value of the parse tree for the fun.
• Pid, encoded using Pid, represnts the process in which the fun was created.
• Free vars are NumFree amount of terms, each one encoded according to its type.

Export

Encodes functions of the shape fun M:F/A.

Binary representation

1 byte	N bytes	N' bytes	N'' bytes
113	Module	Function	Arity

• Module, encoded using AtomUtf8, SmallAtomUtf8, or AtomCacheRef, is the module that exports this function.
• Function, encoded using AtomUtf8, SmallAtomUtf8, or AtomCacheRef, is the name of this function.
• Arity, encoded using SmallInteger, is the arity of this function.

BitBinary

This term represents a bitstring whose length in bits does not have to be a multiple of 8.

Binary representation

1 byte	4 bytes	1 byte	Len bytes
77	Len	Bits	Data

• Len, encoded as a 32-bit big endian unsigned integer, is the amount of Data bytes.
• Bits, encoded as an 8-bit number N, where 1 >= N >= 8, is the amount of bits that are used in the last data byte, counting from most significant to least significant.
• Data is the actual binary data in this bitstring.

NewFloat

This term represents a float

Binary representation

1 byte	8 bytes
70	Float

• Float is an 32-bit IEEE floating point number stored in big-endian format.

AtomUtf8

This term represents an atom.

Binary representation

1 byte	2 bytes	Len bytes
118	Len	AtomName

• Len, represented as a 16-bit big-endian unsigned integer, is the amount of bytes the atom name takes.
• AtomName is an unescaped UTF8 string of Len bytes long representing the name of this atom.

SmallAtomUtf8

This term represents an atom that takes up at most 255 bytes (which may be less than 255 characters as UTF-8 can have multi-byte characters).

Binary representation

1 byte	1 byte	Len bytes
118	Len	AtomName

• Len, represented as an 8-bit unsigned integer, is the amount of bytes the atom name takes.
• AtomName is an unescaped UTF8 string of Len bytes long representing the name of this atom.

Atom

This represents a LATIN-1 atom, but should not be encoded anymore.

Binary representation

1 byte	2 bytes	Len bytes
118	Len	AtomName

• Len, represented as an 16-bit big endian unsigned integer, is the amount of bytes the atom name takes.
• AtomName is an unescaped LATIN-1 string of Len bytes long representing the name of this atom.

SmallAtom

This represents a LATIN-1 atom, but should not be encoded anymore.

Binary representation

1 byte	byte	Len bytes
118	Len	AtomName

• Len, represented as an 8-bit unsigned integer, is the amount of bytes the atom name takes.
• AtomName is an unescaped LATIN-1 string of Len bytes long representing the name of this atom.

Trait Implementations

impl TryFrom<u8> for TermTag

type Error = ()

The type returned in the event of a conversion error.

fn try_from(from: u8) -> Result<TermTag, ()>

Performs the conversion.