Trait Visitor

pub trait Visitor<'de>: Sized {
    type Value;

    // Required method
    fn expecting(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>;

    // Provided methods
    fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_i8<E>(self, v: i8) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_i16<E>(self, v: i16) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_i32<E>(self, v: i32) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_i128<E>(self, v: i128) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_u8<E>(self, v: u8) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_u16<E>(self, v: u16) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_u32<E>(self, v: u32) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_u128<E>(self, v: u128) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_f32<E>(self, v: f32) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_f64<E>(self, v: f64) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_char<E>(self, v: char) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_borrowed_str<E>(self, v: &'de str) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_string<E>(self, v: String) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_borrowed_bytes<E>(self, v: &'de [u8]) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_byte_buf<E>(self, v: Vec<u8>) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_none<E>(self) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_some<D>(
        self,
        deserializer: D,
    ) -> Result<Self::Value, <D as Deserializer<'de>>::Error>
       where D: Deserializer<'de> { ... }
    fn visit_unit<E>(self) -> Result<Self::Value, E>
       where E: Error { ... }
    fn visit_newtype_struct<D>(
        self,
        deserializer: D,
    ) -> Result<Self::Value, <D as Deserializer<'de>>::Error>
       where D: Deserializer<'de> { ... }
    fn visit_seq<A>(
        self,
        seq: A,
    ) -> Result<Self::Value, <A as SeqAccess<'de>>::Error>
       where A: SeqAccess<'de> { ... }
    fn visit_map<A>(
        self,
        map: A,
    ) -> Result<Self::Value, <A as MapAccess<'de>>::Error>
       where A: MapAccess<'de> { ... }
    fn visit_enum<A>(
        self,
        data: A,
    ) -> Result<Self::Value, <A as EnumAccess<'de>>::Error>
       where A: EnumAccess<'de> { ... }
}

This trait represents a visitor that walks through a deserializer.

Lifetime

The 'de lifetime of this trait is the requirement for lifetime of data that may be borrowed by Self::Value. See the page Understanding deserializer lifetimes for a more detailed explanation of these lifetimes.

Example

/// A visitor that deserializes a long string - a string containing at least
/// some minimum number of bytes.
struct LongString {
    min: usize,
}

impl<'de> Visitor<'de> for LongString {
    type Value = String;

    fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
        write!(formatter, "a string containing at least {} bytes", self.min)
    }

    fn visit_str<E>(self, s: &str) -> Result<Self::Value, E>
    where
        E: de::Error,
    {
        if s.len() >= self.min {
            Ok(s.to_owned())
        } else {
            Err(de::Error::invalid_value(Unexpected::Str(s), &self))
        }
    }
}

Required Associated Types

type Value

The value produced by this visitor.

Required Methods

fn expecting(&self, formatter: &mut Formatter<'_>) -> Result<(), Error>

Format a message stating what data this Visitor expects to receive.

This is used in error messages. The message should complete the sentence “This Visitor expects to receive …”, for example the message could be “an integer between 0 and 64”. The message should not be capitalized and should not end with a period.

fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
    write!(formatter, "an integer between 0 and {}", self.max)
}

Provided Methods

fn visit_bool<E>(self, v: bool) -> Result<Self::Value, E>

where E: Error,

The input contains a boolean.

The default implementation fails with a type error.

fn visit_i8<E>(self, v: i8) -> Result<Self::Value, E>

where E: Error,

The input contains an i8.

The default implementation forwards to visit_i64.

fn visit_i16<E>(self, v: i16) -> Result<Self::Value, E>

where E: Error,

The input contains an i16.

The default implementation forwards to visit_i64.

fn visit_i32<E>(self, v: i32) -> Result<Self::Value, E>

where E: Error,

The input contains an i32.

The default implementation forwards to visit_i64.

fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>

where E: Error,

The input contains an i64.

The default implementation fails with a type error.

fn visit_i128<E>(self, v: i128) -> Result<Self::Value, E>

where E: Error,

The input contains a i128.

The default implementation fails with a type error.

fn visit_u8<E>(self, v: u8) -> Result<Self::Value, E>

where E: Error,

The input contains a u8.

The default implementation forwards to visit_u64.

fn visit_u16<E>(self, v: u16) -> Result<Self::Value, E>

where E: Error,

The input contains a u16.

The default implementation forwards to visit_u64.

fn visit_u32<E>(self, v: u32) -> Result<Self::Value, E>

where E: Error,

The input contains a u32.

The default implementation forwards to visit_u64.

fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E>

where E: Error,

The input contains a u64.

The default implementation fails with a type error.

fn visit_u128<E>(self, v: u128) -> Result<Self::Value, E>

where E: Error,

The input contains a u128.

The default implementation fails with a type error.

fn visit_f32<E>(self, v: f32) -> Result<Self::Value, E>

where E: Error,

The input contains an f32.

The default implementation forwards to visit_f64.

fn visit_f64<E>(self, v: f64) -> Result<Self::Value, E>

where E: Error,

The input contains an f64.

The default implementation fails with a type error.

fn visit_char<E>(self, v: char) -> Result<Self::Value, E>

where E: Error,

The input contains a char.

The default implementation forwards to visit_str as a one-character string.

fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>

where E: Error,

The input contains a string. The lifetime of the string is ephemeral and it may be destroyed after this method returns.

This method allows the Deserializer to avoid a copy by retaining ownership of any buffered data. Deserialize implementations that do not benefit from taking ownership of String data should indicate that to the deserializer by using Deserializer::deserialize_str rather than Deserializer::deserialize_string.

It is never correct to implement visit_string without implementing visit_str. Implement neither, both, or just visit_str.

fn visit_borrowed_str<E>(self, v: &'de str) -> Result<Self::Value, E>

where E: Error,

The input contains a string that lives at least as long as the Deserializer.

This enables zero-copy deserialization of strings in some formats. For example JSON input containing the JSON string "borrowed" can be deserialized with zero copying into a &'a str as long as the input data outlives 'a.

The default implementation forwards to visit_str.

fn visit_string<E>(self, v: String) -> Result<Self::Value, E>

where E: Error,

The input contains a string and ownership of the string is being given to the Visitor.

This method allows the Visitor to avoid a copy by taking ownership of a string created by the Deserializer. Deserialize implementations that benefit from taking ownership of String data should indicate that to the deserializer by using Deserializer::deserialize_string rather than Deserializer::deserialize_str, although not every deserializer will honor such a request.

It is never correct to implement visit_string without implementing visit_str. Implement neither, both, or just visit_str.

The default implementation forwards to visit_str and then drops the String.

fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>

where E: Error,

The input contains a byte array. The lifetime of the byte array is ephemeral and it may be destroyed after this method returns.

This method allows the Deserializer to avoid a copy by retaining ownership of any buffered data. Deserialize implementations that do not benefit from taking ownership of Vec<u8> data should indicate that to the deserializer by using Deserializer::deserialize_bytes rather than Deserializer::deserialize_byte_buf.

It is never correct to implement visit_byte_buf without implementing visit_bytes. Implement neither, both, or just visit_bytes.

fn visit_borrowed_bytes<E>(self, v: &'de [u8]) -> Result<Self::Value, E>

where E: Error,

The input contains a byte array that lives at least as long as the Deserializer.

This enables zero-copy deserialization of bytes in some formats. For example Postcard data containing bytes can be deserialized with zero copying into a &'a [u8] as long as the input data outlives 'a.

The default implementation forwards to visit_bytes.

fn visit_byte_buf<E>(self, v: Vec<u8>) -> Result<Self::Value, E>

where E: Error,

The input contains a byte array and ownership of the byte array is being given to the Visitor.

This method allows the Visitor to avoid a copy by taking ownership of a byte buffer created by the Deserializer. Deserialize implementations that benefit from taking ownership of Vec<u8> data should indicate that to the deserializer by using Deserializer::deserialize_byte_buf rather than Deserializer::deserialize_bytes, although not every deserializer will honor such a request.

It is never correct to implement visit_byte_buf without implementing visit_bytes. Implement neither, both, or just visit_bytes.

The default implementation forwards to visit_bytes and then drops the Vec<u8>.

fn visit_none<E>(self) -> Result<Self::Value, E>

where E: Error,

The input contains an optional that is absent.

The default implementation fails with a type error.

fn visit_some<D>( self, deserializer: D, ) -> Result<Self::Value, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

The input contains an optional that is present.

The default implementation fails with a type error.

fn visit_unit<E>(self) -> Result<Self::Value, E>

where E: Error,

The input contains a unit ().

The default implementation fails with a type error.

fn visit_newtype_struct<D>( self, deserializer: D, ) -> Result<Self::Value, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

The input contains a newtype struct.

The content of the newtype struct may be read from the given Deserializer.

The default implementation fails with a type error.

fn visit_seq<A>( self, seq: A, ) -> Result<Self::Value, <A as SeqAccess<'de>>::Error>

where A: SeqAccess<'de>,

The input contains a sequence of elements.

The default implementation fails with a type error.

fn visit_map<A>( self, map: A, ) -> Result<Self::Value, <A as MapAccess<'de>>::Error>

where A: MapAccess<'de>,

The input contains a key-value map.

The default implementation fails with a type error.

fn visit_enum<A>( self, data: A, ) -> Result<Self::Value, <A as EnumAccess<'de>>::Error>

where A: EnumAccess<'de>,

The input contains an enum.

The default implementation fails with a type error.

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

impl<'de> Visitor<'de> for IgnoredAny

type Value = IgnoredAny