Trait TLVWrite 

pub trait TLVWrite {
    type Position: PartialEq + Copy;

    // Required method
    fn write(&mut self, byte: u8) -> Result<(), Error>;

    // Provided methods
    fn write_ctx<T>(&mut self, ctx: u8, value: &T) -> Result<(), Error>
       where T: ToTLV,
             Self: Sized { ... }
    fn tlv(&mut self, tag: &TLVTag, value: &TLVValue<'_>) -> Result<(), Error> { ... }
    fn i8(&mut self, tag: &TLVTag, data: i8) -> Result<(), Error> { ... }
    fn u8(&mut self, tag: &TLVTag, data: u8) -> Result<(), Error> { ... }
    fn i16(&mut self, tag: &TLVTag, data: i16) -> Result<(), Error> { ... }
    fn u16(&mut self, tag: &TLVTag, data: u16) -> Result<(), Error> { ... }
    fn i32(&mut self, tag: &TLVTag, data: i32) -> Result<(), Error> { ... }
    fn u32(&mut self, tag: &TLVTag, data: u32) -> Result<(), Error> { ... }
    fn i64(&mut self, tag: &TLVTag, data: i64) -> Result<(), Error> { ... }
    fn u64(&mut self, tag: &TLVTag, data: u64) -> Result<(), Error> { ... }
    fn f32(&mut self, tag: &TLVTag, data: f32) -> Result<(), Error> { ... }
    fn f64(&mut self, tag: &TLVTag, data: f64) -> Result<(), Error> { ... }
    fn str(&mut self, tag: &TLVTag, data: &[u8]) -> Result<(), Error> { ... }
    fn str_cb(
        &mut self,
        _tag: &TLVTag,
        _cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>,
    ) -> Result<(), Error> { ... }
    fn stri<I>(
        &mut self,
        tag: &TLVTag,
        len: usize,
        data: I,
    ) -> Result<(), Error>
       where I: IntoIterator<Item = u8> { ... }
    fn utf8(&mut self, tag: &TLVTag, data: &str) -> Result<(), Error> { ... }
    fn utf8i<I>(
        &mut self,
        tag: &TLVTag,
        len: usize,
        data: I,
    ) -> Result<(), Error>
       where I: IntoIterator<Item = u8> { ... }
    fn utf8_cb(
        &mut self,
        _tag: &TLVTag,
        _cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>,
    ) -> Result<(), Error> { ... }
    fn start_struct(&mut self, tag: &TLVTag) -> Result<(), Error> { ... }
    fn start_array(&mut self, tag: &TLVTag) -> Result<(), Error> { ... }
    fn start_list(&mut self, tag: &TLVTag) -> Result<(), Error> { ... }
    fn start_container(
        &mut self,
        tag: &TLVTag,
        container_type: TLVValueType,
    ) -> Result<(), Error> { ... }
    fn end_container(&mut self) -> Result<(), Error> { ... }
    fn null(&mut self, tag: &TLVTag) -> Result<(), Error> { ... }
    fn bool(&mut self, tag: &TLVTag, val: bool) -> Result<(), Error> { ... }
    fn raw_value(
        &mut self,
        tag: &TLVTag,
        value_type: TLVValueType,
        value_payload: &[u8],
    ) -> Result<(), Error> { ... }
    fn write_raw_data<I>(&mut self, bytes: I) -> Result<(), Error>
       where I: IntoIterator<Item = u8> { ... }
    fn get_tail(&self) -> Self::Position { ... }
    fn rewind_to(&mut self, _pos: Self::Position) { ... }
    fn available_space(&mut self) -> &mut [u8]  { ... }
}

A trait representing a storage where data can be serialized as a TLV stream. by synchronously emitting bytes to the storage.

The one method that needs to be implemented by user code is write.

The trait operates in an append-only manner without requiring access to the serialized TLV data, so it can be implemented with an in-memory storage, or a file storage, or anything that can output a byte to somewhere (like the Write Rust traits).

With that said, the trait has two additional methods that (optionally) allow for “rewinding” the storage. Implementing these is optional, and they currently exist only for backwards compatibility with code implemented prior to the introduction of this trait.

For iterator-style TLV serialization look at the ToTLVIter trait.

Required Associated Types

type Position: PartialEq + Copy

Required Methods

fn write(&mut self, byte: u8) -> Result<(), Error>

Append a single byte to the TLV stream.

Provided Methods

fn write_ctx<T>(&mut self, ctx: u8, value: &T) -> Result<(), Error>

where T: ToTLV, Self: Sized,

Write value under a context tag.

Taking the tag as a runtime argument rather than baking it into the caller is what keeps this cheap in code size: the generated per-field builder setters are otherwise structurally identical yet monomorphise separately - and, because the builders carry both the parent chain and the field index in their type, once per (field, parent, index) rather than once per type.

fn tlv(&mut self, tag: &TLVTag, value: &TLVValue<'_>) -> Result<(), Error>

Write a TLV tag and value to the TLV stream.

fn i8(&mut self, tag: &TLVTag, data: i8) -> Result<(), Error>

Write a tag and a TLV S8 value to the TLV stream.

fn u8(&mut self, tag: &TLVTag, data: u8) -> Result<(), Error>

Write a tag and a TLV U8 value to the TLV stream.

fn i16(&mut self, tag: &TLVTag, data: i16) -> Result<(), Error>

Write a tag and a TLV S16 or (if the data is small enough) S8 value to the TLV stream.

fn u16(&mut self, tag: &TLVTag, data: u16) -> Result<(), Error>

Write a tag and a TLV U16 or (if the data is small enough) U8 value to the TLV stream.

fn i32(&mut self, tag: &TLVTag, data: i32) -> Result<(), Error>

Write a tag and a TLV S32 or (if the data is small enough) S16 or S8 value to the TLV stream.

fn u32(&mut self, tag: &TLVTag, data: u32) -> Result<(), Error>

Write a tag and a TLV U32 or (if the data is small enough) U16 or U8 value to the TLV stream.

fn i64(&mut self, tag: &TLVTag, data: i64) -> Result<(), Error>

Write a tag and a TLV S64 or (if the data is small enough) S32, S16, or S8 value to the TLV stream.

fn u64(&mut self, tag: &TLVTag, data: u64) -> Result<(), Error>

Write a tag and a TLV U64 or (if the data is small enough) U32, U16, or U8 value to the TLV stream.

fn f32(&mut self, tag: &TLVTag, data: f32) -> Result<(), Error>

Write a tag and a TLV F32 to the TLV stream.

fn f64(&mut self, tag: &TLVTag, data: f64) -> Result<(), Error>

Write a tag and a TLV F64 to the TLV stream.

fn str(&mut self, tag: &TLVTag, data: &[u8]) -> Result<(), Error>

Write a tag and a TLV Octet String to the TLV stream, where the Octet String is a slice of u8 bytes.

The exact octet string type (Str8l, Str16l, Str32l, or Str64l) is chosen based on the length of the data, whereas the smallest type filling the provided data length is chosen.

fn str_cb( &mut self, _tag: &TLVTag, _cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>, ) -> Result<(), Error>

Write a tag and a TLV Octet String to the TLV stream, where the Octet String is a slice of u8 bytes.

The writing is done via a user-supplied callback cb, that is expected to fill the provided buffer with the data and to return the length of the written data.

This method is useful when the data to be written needs to be computed first, and the computation needs a buffer where to operate.

Note that this method always uses a Str16l value type to write the data, which restricts the data length to no more than 65535 bytes.

Note also that this method might not be supported by all TLVWrite implementations.

fn stri<I>(&mut self, tag: &TLVTag, len: usize, data: I) -> Result<(), Error>

where I: IntoIterator<Item = u8>,

Write a tag and a TLV Octet String to the TLV stream, where the Octet String is anything that can be turned into an iterator of u8 bytes.

The exact octet string type (Str8l, Str16l, Str32l, or Str64l) is chosen based on the length of the data, whereas the smallest type filling the provided data length is chosen.

NOTE: The length of the Octet String must be provided by the user and it must match the number of bytes returned by the provided iterator, or else the generated TLV stream will be invalid.

fn utf8(&mut self, tag: &TLVTag, data: &str) -> Result<(), Error>

Write a tag and a TLV UTF-8 String to the TLV stream, where the UTF-8 String is a str.

The exact UTF-8 string type (Utf8l, Utf16l, Utf32l, or Utf64l) is chosen based on the length of the data, whereas the smallest type filling the provided data length is chosen.

fn utf8i<I>(&mut self, tag: &TLVTag, len: usize, data: I) -> Result<(), Error>

where I: IntoIterator<Item = u8>,

Write a tag and a TLV UTF-8 String to the TLV stream, where the UTF-8 String is anything that can be turned into an iterator of u8 bytes.

The exact UTF-8 string type (Utf8l, Utf16l, Utf32l, or Utf64l) is chosen based on the length of the data, whereas the smallest type filling the provided data length is chosen.

NOTE 1: The length of the UTF-8 String must be provided by the user and it must match the number of bytes returned by the provided iterator, or else the generated TLV stream will be invalid.

NOTE 2: The provided iterator must return valid UTF-8 bytes, or else the generated TLV stream will be invalid.

fn utf8_cb( &mut self, _tag: &TLVTag, _cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>, ) -> Result<(), Error>

Write a tag and a TLV UTF-8 String to the TLV stream, where the UTF-8 String is a str.

The writing is done via a user-supplied callback cb, that is expected to fill the provided buffer with the data and to return the length of the written data.

This method is useful when the data to be written needs to be computed first, and the computation needs a buffer where to operate.

Note that this method always uses a Utf16l value type to write the data, which restricts the data length to no more than 65535 bytes.

Note also that this method might not be supported by all TLVWrite implementations.

fn start_struct(&mut self, tag: &TLVTag) -> Result<(), Error>

Write a tag and a value indicating the start of a Struct TLV container.

NOTE: The user must call end_container after writing all the Struct fields to close the Struct container or else the generated TLV stream will be invalid.

fn start_array(&mut self, tag: &TLVTag) -> Result<(), Error>

Write a tag and a value indicating the start of an Array TLV container.

NOTE: The user must call end_container after writing all the Array elements to close the Array container or else the generated TLV stream will be invalid.

fn start_list(&mut self, tag: &TLVTag) -> Result<(), Error>

Write a tag and a value indicating the start of a List TLV container.

NOTE: The user must call end_container after writing all the List elements to close the List container or else the generated TLV stream will be invalid.

fn start_container( &mut self, tag: &TLVTag, container_type: TLVValueType, ) -> Result<(), Error>

Write a tag and a value indicating the start of a Struct TLV container.

NOTE: The user must call end_container after writing all the Struct fields to close the Struct container or else the generated TLV stream will be invalid.

fn end_container(&mut self) -> Result<(), Error>

Write a value indicating the end of a Struct, Array, or List TLV container.

NOTE: This method must be called only when the corresponding container has been opened using start_struct, start_array, or start_list, or else the generated TLV stream will be invalid.

fn null(&mut self, tag: &TLVTag) -> Result<(), Error>

Write a tag and a TLV Null value to the TLV stream.

fn bool(&mut self, tag: &TLVTag, val: bool) -> Result<(), Error>

Write a tag and a TLV True or False value to the TLV stream.

fn raw_value( &mut self, tag: &TLVTag, value_type: TLVValueType, value_payload: &[u8], ) -> Result<(), Error>

Write a tag and a raw, already-encoded TLV value represented as a byte slice.

fn write_raw_data<I>(&mut self, bytes: I) -> Result<(), Error>

where I: IntoIterator<Item = u8>,

Append multiple raw bytes to the TLV stream.

fn get_tail(&self) -> Self::Position

Get the current position in the TLV stream.

NOTE: This method might not be supported by all implementations and therefore it might panic.

fn rewind_to(&mut self, _pos: Self::Position)

Rewind the TLV stream to a previous position.

NOTE: This method might not be supported by all implementations and therefore it might panic.

fn available_space(&mut self) -> &mut [u8]

Get a mutable slice of the available space in the TLV stream.

NOTE: This method assumes that the TLV write implementation is writing to a buffer, which might not be the case for all implementations. Therefore, this method might panic if the implementation does not support it.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<T> TLVWrite for &mut T

where T: TLVWrite,

type Position = <T as TLVWrite>::Position

fn write(&mut self, byte: u8) -> Result<(), Error>

fn get_tail(&self) -> <&mut T as TLVWrite>::Position

fn rewind_to(&mut self, pos: <&mut T as TLVWrite>::Position)

fn available_space(&mut self) -> &mut [u8]

fn str_cb( &mut self, tag: &TLVTag, cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>, ) -> Result<(), Error>

fn utf8_cb( &mut self, tag: &TLVTag, cb: impl FnOnce(&mut [u8]) -> Result<usize, Error>, ) -> Result<(), Error>

Implementors

impl TLVWrite for EventTLVWrite<'_>

type Position = usize

impl TLVWrite for WriteBuf<'_>

type Position = usize

impl<'a> TLVWrite for InvokeSenderSlot<'a>

type Position = usize

impl<'a> TLVWrite for ReadSenderSlot<'a>

type Position = usize

impl<'a> TLVWrite for SubscribeSenderSlot<'a>

type Position = usize

impl<'a> TLVWrite for WriteSenderSlot<'a>

type Position = usize