Trait Context

pub trait Context {
    type Mode: 'static;
    type Error: 'static;
    type Mark: Copy + Default;
    type Allocator: ?Sized + Allocator;
    type String<'this>: AsRef<str>
       where Self: 'this;

    // Required methods
    fn clear(&self);
    fn alloc(&self) -> &Self::Allocator;
    fn collect_string<T>(
        &self,
        value: &T,
    ) -> Result<Self::String<'_>, Self::Error>
       where T: ?Sized + Display;
    fn custom<T>(&self, error: T) -> Self::Error
       where T: 'static + Send + Sync + Error;
    fn message<T>(&self, message: T) -> Self::Error
       where T: Display;

    // Provided methods
    fn decode<'de, T, D>(&self, decoder: D) -> Result<T, Self::Error>
       where T: Decode<'de, Self::Mode>,
             D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error> { ... }
    fn decode_unsized<'de, T, D, F, O>(
        &self,
        decoder: D,
        f: F,
    ) -> Result<O, Self::Error>
       where T: ?Sized + DecodeUnsized<'de, Self::Mode>,
             D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>,
             F: FnOnce(&T) -> Result<O, D::Error> { ... }
    fn decode_bytes<'de, T, D>(&self, decoder: D) -> Result<T, Self::Error>
       where T: DecodeBytes<'de, Self::Mode>,
             D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error> { ... }
    fn decode_unsized_bytes<'de, T, D, F, O>(
        &self,
        decoder: D,
        f: F,
    ) -> Result<O, Self::Error>
       where T: ?Sized + DecodeUnsizedBytes<'de, Self::Mode>,
             D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>,
             F: FnOnce(&T) -> Result<O, D::Error> { ... }
    fn map<T>(&self) -> impl FnOnce(T) -> Self::Error + '_
       where T: 'static + Send + Sync + Error { ... }
    fn map_message<T>(&self) -> impl FnOnce(T) -> Self::Error + '_
       where T: Display { ... }
    fn marked_message<T>(&self, mark: Self::Mark, message: T) -> Self::Error
       where T: Display { ... }
    fn marked_custom<T>(&self, mark: Self::Mark, message: T) -> Self::Error
       where T: 'static + Send + Sync + Error { ... }
    fn advance(&self, n: usize) { ... }
    fn mark(&self) -> Self::Mark { ... }
    fn invalid_variant_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error
       where T: ?Sized + Debug { ... }
    fn expected_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error
       where T: ?Sized + Debug { ... }
    fn uninhabitable(&self, _: &'static str) -> Self::Error { ... }
    fn invalid_field_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error
       where T: ?Sized + Debug { ... }
    fn expected_field_adjacent<T, C>(
        &self,
        _: &'static str,
        tag: &T,
        content: &C,
    ) -> Self::Error
       where T: ?Sized + Debug,
             C: ?Sized + Debug { ... }
    fn missing_adjacent_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error
       where T: ?Sized + Debug { ... }
    fn invalid_field_string_tag(
        &self,
        _: &'static str,
        field: Self::String<'_>,
    ) -> Self::Error { ... }
    fn missing_variant_field<T>(
        &self,
        name: &'static str,
        tag: &T,
    ) -> Self::Error
       where T: ?Sized + Debug { ... }
    fn missing_variant_tag(&self, name: &'static str) -> Self::Error { ... }
    fn invalid_variant_field_tag<V, T>(
        &self,
        name: &'static str,
        variant: &V,
        tag: &T,
    ) -> Self::Error
       where V: ?Sized + Debug,
             T: ?Sized + Debug { ... }
    fn alloc_failed(&self) -> Self::Error { ... }
    fn enter_struct(&self, name: &'static str) { ... }
    fn leave_struct(&self) { ... }
    fn enter_enum(&self, name: &'static str) { ... }
    fn leave_enum(&self) { ... }
    fn enter_named_field<T>(&self, name: &'static str, tag: &T)
       where T: ?Sized + Display { ... }
    fn enter_unnamed_field<T>(&self, index: u32, name: &T)
       where T: ?Sized + Display { ... }
    fn leave_field(&self) { ... }
    fn enter_variant<T>(&self, name: &'static str, tag: T)
       where T: Display { ... }
    fn leave_variant(&self) { ... }
    fn enter_map_key<T>(&self, field: T)
       where T: 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 Mode: 'static

Mode of the context.

type Error: 'static

Error produced by context.

type Mark: Copy + Default

A mark during processing.

type Allocator: ?Sized + Allocator

The allocator associated with the context.

type String<'this>: AsRef<str> where Self: 'this

An allocated buffer containing a valid string.

Required Methods

fn clear(&self)

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

fn alloc(&self) -> &Self::Allocator

Access the underlying allocator.

fn collect_string<T>(&self, value: &T) -> Result<Self::String<'_>, Self::Error>

where T: ?Sized + Display,

Collect and allocate a string from a Display implementation.

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

where T: '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<T>(&self, message: T) -> Self::Error

where T: 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 decode<'de, T, D>(&self, decoder: D) -> Result<T, Self::Error>

where T: Decode<'de, Self::Mode>, D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>,

Decode the given input using the associated mode.

fn decode_unsized<'de, T, D, F, O>( &self, decoder: D, f: F, ) -> Result<O, Self::Error>

where T: ?Sized + DecodeUnsized<'de, Self::Mode>, D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>, F: FnOnce(&T) -> Result<O, D::Error>,

Decode the given unsized value using the associated mode.

fn decode_bytes<'de, T, D>(&self, decoder: D) -> Result<T, Self::Error>

where T: DecodeBytes<'de, Self::Mode>, D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>,

Decode the given input as bytes using the associated mode.

fn decode_unsized_bytes<'de, T, D, F, O>( &self, decoder: D, f: F, ) -> Result<O, Self::Error>

where T: ?Sized + DecodeUnsizedBytes<'de, Self::Mode>, D: Decoder<'de, Cx = Self, Mode = Self::Mode, Error = Self::Error>, F: FnOnce(&T) -> Result<O, D::Error>,

Decode the given unsized value as bytes using the associated mode.

fn map<T>(&self) -> impl FnOnce(T) -> Self::Error + '_

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

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

fn map_message<T>(&self) -> impl FnOnce(T) -> Self::Error + '_

where T: Display,

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

fn marked_message<T>(&self, mark: Self::Mark, message: T) -> Self::Error

where T: Display,

Report an error based on a mark.

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

fn marked_custom<T>(&self, mark: Self::Mark, message: T) -> Self::Error

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

Report an error based on a mark.

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

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 marked_message to report a spanned error.

fn invalid_variant_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error

where T: ?Sized + Debug,

Report that an invalid variant tag was encountered.

fn expected_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error

where T: ?Sized + Debug,

The value for the given tag could not be collected.

fn uninhabitable(&self, _: &'static str) -> Self::Error

Trying to decode an uninhabitable type.

fn invalid_field_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error

where T: ?Sized + Debug,

Encountered an unsupported field tag.

fn expected_field_adjacent<T, C>( &self, _: &'static str, tag: &T, content: &C, ) -> Self::Error

where T: ?Sized + Debug, C: ?Sized + Debug,

Expected another field to decode.

fn missing_adjacent_tag<T>(&self, _: &'static str, tag: &T) -> Self::Error

where T: ?Sized + Debug,

Missing adjacent tag when decoding.

fn invalid_field_string_tag( &self, _: &'static str, field: Self::String<'_>, ) -> Self::Error

Encountered an unsupported field tag.

fn missing_variant_field<T>(&self, name: &'static str, tag: &T) -> Self::Error

where T: ?Sized + Debug,

Missing variant field required to decode.

fn missing_variant_tag(&self, name: &'static str) -> Self::Error

Indicate that a variant tag could not be determined.

fn invalid_variant_field_tag<V, T>( &self, name: &'static str, variant: &V, tag: &T, ) -> Self::Error

where V: ?Sized + Debug, T: ?Sized + Debug,

Encountered an unsupported variant field.

fn alloc_failed(&self) -> Self::Error

Missing variant field required to decode.

fn enter_struct(&self, 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, 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<T>(&self, name: &'static str, tag: &T)

where T: ?Sized + 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<T>(&self, index: u32, name: &T)

where T: ?Sized + 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<T>(&self, name: &'static str, tag: T)

where T: 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<T>(&self, field: T)

where T: 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