Enum IoTypeMetadataKind 

#[repr(u8)]
pub enum IoTypeMetadataKind {
    Unit = 0,
    Bool = 1,
    U8 = 2,
    U16 = 3,
    U32 = 4,
    U64 = 5,
    U128 = 6,
    I8 = 7,
    I16 = 8,
    I32 = 9,
    I64 = 10,
    I128 = 11,
    Struct = 12,
    Enum = 13,
    Array = 14,
    MaybeData = 15,
    VariableElements = 16,
    FixedCapacityElements = 17,
    FixedCapacityString = 18,
    Unaligned = 19,
}

Metadata types contained in TrivialType::METADATA and IoType::METADATA.

Metadata encoding consists of this enum variant treated as u8 followed by optional metadata encoding rules specific to metadata type variant (see variant’s description).

This metadata is enough to fully reconstruct the hierarchy of the type to generate language bindings, auto-generate UI forms, etc.

Variants

Unit = 0

()

Bool = 1

bool

U8 = 2

u8

U16 = 3

u16

U32 = 4

u32

U64 = 5

u64

U128 = 6

u128

I8 = 7

i8

I16 = 8

i16

I32 = 9

i32

I64 = 10

i64

I128 = 11

i128

Struct = 12

struct S {..}, struct S(..); or struct S;

Structs are encoded as follows:

• Length of struct name in bytes (u8)
• Struct name as UTF-8 bytes
• Number of fields (u8)

Each field is encoded as follows:

• Length of the field name in bytes (u8), zero for fields of tuple structs
• Field name as UTF-8 bytes
• Recursive metadata of the field’s type

Fields are laid out like in a #[repr(C)] struct. Decoders reject structs that have both fields with names and fields with zero-length names, and layouts with padding.

Enum = 13

enum E { A, B {..}, C(..) }

Enums are encoded as follows:

• Length of enum name in bytes (u8)
• Enum name as UTF-8 bytes
• Number of variants (u8)

Each variant is encoded as follows:

• Length of the variant name in bytes (u8)
• Variant name as UTF-8 bytes
• Number of fields (u8), zero for variants without fields
• Fields, each encoded like a field of Self::Struct, with zero-length names for fields of tuple variants

Each variant is a 1-byte discriminant followed by its fields laid out like in a #[repr(u8)] enum, all variants must have the same size. Decoders reject enums without variants, variants that have both fields with names and fields with zero-length names, and layouts with padding.

Array = 14

Array [T; N].

Encoded as follows:

• 4 bytes number of elements (little-endian)
• Recursive metadata of a contained type

MaybeData = 15

MaybeData.

Encoded as follows:

• Recursive metadata of a contained type

Decoders only accept it as the outermost type.

VariableElements = 16

VariableElements.

Encoded as follows:

• 4 bytes recommended allocation in elements (little-endian)
• Recursive metadata of a contained type

Decoders only accept it as the outermost type.

FixedCapacityElements = 17

FixedCapacityElements.

Encoded as follows:

• 4 bytes capacity in elements (little-endian)
• Recursive metadata of a contained type

Elements follow a little-endian u32 length, padded with zeroes to the alignment of elements if it is larger.

FixedCapacityString = 18

FixedCapacityString.

This is a string only by convention, there is no runtime verification done, contents is treated as regular bytes.

Encoded as follows:

• 4 bytes capacity in bytes (little-endian)

Bytes follow a little-endian u32 length.

Unaligned = 19

Unaligned wrapper over another TrivialType.

Encoded as follows:

• Recursive metadata of a contained type

Implementations

impl IoTypeMetadataKind

pub const fn compact<'i, 'o, const MAX_DEPTH: usize>( input: &'i [u8], output: &'o mut [u8], ) -> Option<(&'i [u8], &'o mut [u8])>

Produce compact metadata.

Compact metadata retains the layout, but throws some details. Specifically:

• Names of structs, fields, enums and enum variants are replaced with zero-length names, so a struct with named fields has the same compact metadata as a tuple struct with fields of the same types
• A struct with a single field is replaced with compact metadata of the type of the field and a struct without fields with (), so a newtype like struct Wrapper(u64); has the same compact metadata as u64, also when contained in other types

Enums are retained, even with a single variant or a single field, since the discriminant is a part of their layout.

Compact metadata of valid metadata is valid metadata too, it decodes into the same capacity and alignment (see Self::type_details()), and compacting it again doesn’t change it.

This is typically called by higher-level functions and doesn’t need to be used directly.

This function takes an input that starts with metadata defined in IoTypeMetadataKind and output where compact metadata must be written. Since input might have other data past the data structure to be processed, the remainder of input and output are returned to the caller.

None is returned for an unexpected metadata kind, metadata nested deeper than MAX_DEPTH (see Self::type_details()), truncated metadata and output that is too small for compact metadata. Metadata is not validated otherwise, Self::type_details() does that.

pub const fn type_name(metadata: &[u8]) -> Option<&[u8]>

Decode type name.

Expected to be UTF-8, but must be parsed before printed as text, which is somewhat costly.

pub const fn type_details<const MAX_DEPTH: usize>( metadata: &[u8], ) -> Option<(IoTypeDetails, &[u8])>

Decode type, return its recommended capacity that should be allocated by the host.

If actual data is larger, it will be passed down to the guest as it is, if smaller than host should allocate recommended capacity for guest anyway.

Returns type details and whatever slice of bytes from metadata that is left after type decoding. Invalid metadata and metadata nested deeper than MAX_DEPTH result in None being returned.

MAX_DEPTH is the max nesting depth of compound types (structs, enums, arrays, MaybeData, VariableElements, FixedCapacityElements and Unaligned), like 2 for Unaligned<[u8; 4]>. Variants of an enum don’t count, only types of their fields do. There is no recursion, so stack usage grows with MAX_DEPTH, but doesn’t depend on metadata.

Trait Implementations

impl Clone for IoTypeMetadataKind

fn clone(&self) -> IoTypeMetadataKind

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for IoTypeMetadataKind

impl Debug for IoTypeMetadataKind

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

Formats the value using the given formatter.

impl Eq for IoTypeMetadataKind

impl PartialEq for IoTypeMetadataKind

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for IoTypeMetadataKind

impl TryFrom<u8> for IoTypeMetadataKind

type Error = ()

The type returned in the event of a conversion error.

fn try_from(byte: u8) -> Result<Self, Self::Error>

Performs the conversion.