Trait Context 

pub trait Context: Copy {
    type Error;
    type Mark;
    type Allocator: Allocator;

    // Required methods
    fn clear(self);
    fn advance(self, n: usize);
    fn mark(self) -> Self::Mark;
    fn restore(self, mark: &Self::Mark);
    fn alloc(self) -> Self::Allocator;
    fn custom<E>(self, error: E) -> Self::Error
       where E: 'static + Send + Sync + Error;
    fn message<M>(self, message: M) -> Self::Error
       where M: Display;

    // Provided methods
    fn map<E>(self) -> impl FnOnce(E) -> Self::Error
       where E: 'static + Send + Sync + Error { ... }
    fn message_at<M>(self, mark: &Self::Mark, message: M) -> Self::Error
       where M: Display { ... }
    fn custom_at<E>(self, mark: &Self::Mark, message: E) -> Self::Error
       where E: 'static + Send + Sync + Error { ... }
    fn enter_struct(self, type_name: &'static str) { ... }
    fn leave_struct(self) { ... }
    fn enter_enum(self, type_name: &'static str) { ... }
    fn leave_enum(self) { ... }
    fn enter_named_field<F>(self, type_name: &'static str, field: F)
       where F: Display { ... }
    fn enter_unnamed_field<F>(self, index: u32, name: F)
       where F: Display { ... }
    fn leave_field(self) { ... }
    fn enter_variant<V>(self, type_name: &'static str, tag: V)
       where V: Display { ... }
    fn leave_variant(self) { ... }
    fn enter_map_key<K>(self, field: K)
       where K: Display { ... }
    fn leave_map_key(self) { ... }
    fn enter_sequence_index(self, index: usize) { ... }
    fn leave_sequence_index(self) { ... }
}

Provides ergonomic access to the serialization context.

This is used to among other things report diagnostics.

Required Associated Types

type Error

Error produced by the context.

type Mark

A mark during processing.

type Allocator: Allocator

The allocator associated with the context.

Required Methods

fn clear(self)

Clear the state of the context, allowing it to be re-used.

fn advance(self, n: usize)

Advance the context by n bytes of input.

This is typically used to move the mark forward as produced by Context::mark.

fn mark(self) -> Self::Mark

Return a mark which acts as a checkpoint at the current encoding state.

The context is in a privileged state in that it sees everything, so a mark can be quite useful for determining the context of an error.

This typically indicates a byte offset, and is used by message_at to report a spanned error.

fn restore(self, mark: &Self::Mark)

Restore the state of the context to the specified mark.

fn alloc(self) -> Self::Allocator

Access the underlying allocator.

fn custom<E>(self, error: E) -> Self::Error

where E: 'static + Send + Sync + Error,

Report a custom error, which is not encapsulated by the error type expected by the context. This is essentially a type-erased way of reporting error-like things out from the context.

fn message<M>(self, message: M) -> Self::Error

where M: Display,

Report a message as an error.

This is made available to format custom error messages in no_std environments. The error message is to be collected by formatting T.

Provided Methods

fn map<E>(self) -> impl FnOnce(E) -> Self::Error

where E: 'static + Send + Sync + Error,

Generate a map function which maps an error using the custom function.

fn message_at<M>(self, mark: &Self::Mark, message: M) -> Self::Error

where M: Display,

Report an error based on a mark.

A mark is generated using Context::mark and indicates a prior state.

fn custom_at<E>(self, mark: &Self::Mark, message: E) -> Self::Error

where E: 'static + Send + Sync + Error,

Report an error based on a mark.

A mark is generated using Context::mark and indicates a prior state.

fn enter_struct(self, type_name: &'static str)

Indicate that we’ve entered a struct with the given name.

The name variable corresponds to the identifiers of the struct.

This will be matched with a corresponding call to leave_struct.

fn leave_struct(self)

Trace that we’ve left the last struct that was entered.

fn enter_enum(self, type_name: &'static str)

Indicate that we’ve entered an enum with the given name.

The name variable corresponds to the identifiers of the enum.

This will be matched with a corresponding call to leave_enum.

fn leave_enum(self)

Trace that we’ve left the last enum that was entered.

fn enter_named_field<F>(self, type_name: &'static str, field: F)

where F: Display,

Trace that we’ve entered the given named field.

A named field is part of a regular struct, where the literal field name is the name argument below, and the musli tag being used for the field is the second argument.

This will be matched with a corresponding call to leave_field.

Here name is "field" and tag is "string".

use musli::{Decode, Encode};

#[derive(Decode, Encode)]
#[musli(name_all = "name")]
struct Struct {
    #[musli(name = "string")]
    field: String,
}

fn enter_unnamed_field<F>(self, index: u32, name: F)

where F: Display,

Trace that we’ve entered the given unnamed field.

An unnamed field is part of a tuple struct, where the field index is the index argument below, and the musli tag being used for the field is the second argument.

This will be matched with a corresponding call to leave_field.

Here index is 0 and name is "string".

use musli::{Decode, Encode};

#[derive(Decode, Encode)]
#[musli(name_all = "name")]
struct Struct(#[musli(name = "string")] String);

fn leave_field(self)

Trace that we’ve left the last field that was entered.

The marker argument will be the same as the one returned from enter_named_field or enter_unnamed_field.

fn enter_variant<V>(self, type_name: &'static str, tag: V)

where V: Display,

Trace that we’ve entered the given variant in an enum.

A named variant is part of an enum, where the literal variant name is the name argument below, and the musli tag being used to decode the variant is the second argument.

This will be matched with a corresponding call to leave_variant with the same marker provided as an argument as the one returned here.

Here name is "field" and tag is "string".

use musli::{Decode, Encode};

#[derive(Decode, Encode)]
#[musli(name_all = "name")]
struct Struct {
    #[musli(name = "string")]
    field: String,
}

fn leave_variant(self)

Trace that we’ve left the last variant that was entered.

The marker argument will be the same as the one returned from enter_variant.

fn enter_map_key<K>(self, field: K)

where K: Display,

Trace a that a map key has been entered.

fn leave_map_key(self)

Trace that we’ve left the last map field that was entered.

The marker argument will be the same as the one returned from enter_map_key.

fn enter_sequence_index(self, index: usize)

Trace a sequence field.

fn leave_sequence_index(self)

Trace that we’ve left the last sequence index that was entered.

The marker argument will be the same as the one returned from enter_sequence_index.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors