Enum Definition

pub enum Definition {
    Primitive(u8),
    Sequence {
        length_width: u8,
        length_range: RangeInclusive<u64>,
        elements: Declaration,
    },
    Tuple {
        elements: Vec<Declaration>,
    },
    Enum {
        tag_width: u8,
        variants: Vec<(DiscriminantValue, VariantName, Declaration)>,
    },
    Struct {
        fields: Fields,
    },
}

The type that we use to represent the definition of the Borsh type.

Description of data encoding on the wire.

Variants

Primitive(u8)

A fixed-size type, which is considered undivisible

Sequence

A sequence of homogeneous elements.

If length_width is non-zero, the sequence is tagged, i.e. prefixed by the number of elements in the sequence. In that case, the length is encoded as a length_width-byte wide little-endian unsigned integer.

If length_width is zero, the sequence is untagged. In that case, if length_range contains a single number, the sequence is fixed-sized with the range determining number of elements. Otherwise, knowledge of the type is necessary to be able to decode the number of elements.

Prototypical examples of the use of this definitions are:

• [T; N] → length_width: 0, length_range: N..=N, elements: "T" and
• Vec<T> → length_width: 4, length_range: 0..=u32::MAX, elements: "T".

With length_width and length_range other custom encoding formats can also be expressed. For example:

• BoundedVec<LO, HI, T> → length_width: 4, length_range: LO..=HI;
• PascalString → length_width: 1, length_range: 0..=255;
• Ipv4Packet → length_width: 0, length_range: 20..=65536 or
• VarInt<u32> → length_width: 0, length_range: 1..=5.

Fields

length_width: u8

How many bytes does the length tag occupy.

Zero if this is fixed-length array or the length must be determined by means not specified in the schema. The schema is invalid if the value is greater than eight.

length_range: RangeInclusive<u64>

Bounds on the possible lengths of the sequence.

Note: The schema is invalid if the range is empty or length_width is non-zero and either bound of the range cannot be represented as length_width-byte-wide unsigned integer.

elements: Declaration

Type of each element of the sequence.

Tuple

A fixed-size tuple with the length known at the compile time and the elements of different types.

Fields

elements: Vec<Declaration>

Enum

A possibly tagged union, a.k.a enum.

Tagged unions are prefixed by a tag identifying encoded variant followed by encoding of that variant. The tag is tag_width-byte wide little-endian number.

Untagged unions don’t have a separate tag which means that knowledge of the type is necessary to fully analyse the binary. Variants may still be used to list possible values or determine the longest possible encoding.

Fields

tag_width: u8

Width in bytes of the discriminant tag.

Zero indicates this is an untagged union. In standard borsh encoding this is one. Custom encoding formats may use larger width if they need to encode more than 256 variants. The schema is invalid if the value is greater than eight.

variants: Vec<(DiscriminantValue, VariantName, Declaration)>

Possible variants of the enumeration. VariantName is metadata, not present in a type’s serialized representation.

Struct

A structure, structurally similar to a tuple.

Fields

fields: Fields

Implementations

impl Definition

pub const ARRAY_LENGTH_WIDTH: u8 = 0u8

Array length isn’t present in payload, it’s determined by type of data serialized.

pub const DEFAULT_LENGTH_WIDTH: u8 = 4u8

Convenience constant representing the length width of a standard borsh sequence.

Can be used for Definition::Sequence::length_width.

pub const DEFAULT_LENGTH_RANGE: RangeInclusive<u64>

Convenience constant representing the length range of a standard borsh sequence.

It equals 0..=u32::MAX. Can be used with Definition::Sequence::length_range.

Trait Implementations

impl BorshDeserialize for Definition

fn deserialize_reader<__R: Read>(reader: &mut __R) -> Result<Self, Error>

fn deserialize(buf: &mut &[u8]) -> Result<Self>

Deserializes this instance from a given slice of bytes. Updates the buffer to point at the remaining bytes.

fn try_from_slice(v: &[u8]) -> Result<Self>

Deserialize this instance from a slice of bytes.

fn try_from_reader<R: Read>(reader: &mut R) -> Result<Self>

impl BorshSchema for Definition

fn declaration() -> Declaration

Get the name of the type without brackets.

fn add_definitions_recursively( definitions: &mut BTreeMap<Declaration, Definition>, )

Recursively, using DFS, add type definitions required for this type. Type definition partially explains how to serialize/deserialize a type.

impl BorshSerialize for Definition

fn serialize<__W: Write>(&self, writer: &mut __W) -> Result<(), Error>

impl Clone for Definition

fn clone(&self) -> Definition

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Definition

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

Formats the value using the given formatter.

impl EnumExt for Definition

fn deserialize_variant<__R: Read>( reader: &mut __R, variant_tag: u8, ) -> Result<Self, Error>

Deserialises given variant of an enum from the reader.

impl PartialEq for Definition

fn eq(&self, other: &Definition) -> 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 Eq for Definition

impl StructuralPartialEq for Definition