Trait Error

pub trait Error:
    Sized
    + Debug
    + Display {
    // Required method
    fn custom<T>(msg: T) -> Self
       where T: Display;

    // Provided methods
    fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self { ... }
    fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self { ... }
    fn invalid_length(len: usize, exp: &dyn Expected) -> Self { ... }
    fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self { ... }
    fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self { ... }
    fn missing_field(field: &'static str) -> Self { ... }
    fn duplicate_field(field: &'static str) -> Self { ... }
}

The Error trait allows Deserialize implementations to create descriptive error messages belonging to the Deserializer against which they are currently running.

Every Deserializer declares an Error type that encompasses both general-purpose deserialization errors as well as errors specific to the particular deserialization format. For example the Error type of serde_json can represent errors like an invalid JSON escape sequence or an unterminated string literal, in addition to the error cases that are part of this trait.

Most deserializers should only need to provide the Error::custom method and inherit the default behavior for the other methods.

Example implementation

The example data format presented on the website shows an error type appropriate for a basic JSON data format.

Required Methods

fn custom<T>(msg: T) -> Self

where T: Display,

Raised when there is general error when deserializing a type.

The message should not be capitalized and should not end with a period.

use serde::de::{self, Deserialize, Deserializer};

impl<'de> Deserialize<'de> for IpAddr {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(de::Error::custom)
    }
}

Provided Methods

fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a type different from what it was expecting.

The unexp argument provides information about what type was received. This is the type that was present in the input file or other source data of the Deserializer.

The exp argument provides information about what type was being expected. This is the type that is written in the program.

For example if we try to deserialize a String out of a JSON file containing an integer, the unexpected type is the integer and the expected type is the string.

fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Self

Raised when a Deserialize receives a value of the right type but that is wrong for some other reason.

The unexp argument provides information about what value was received. This is the value that was present in the input file or other source data of the Deserializer.

The exp argument provides information about what value was being expected. This is the type that is written in the program.

For example if we try to deserialize a String out of some binary data that is not valid UTF-8, the unexpected value is the bytes and the expected value is a string.

fn invalid_length(len: usize, exp: &dyn Expected) -> Self

Raised when deserializing a sequence or map and the input data contains too many or too few elements.

The len argument is the number of elements encountered. The sequence or map may have expected more arguments or fewer arguments.

The exp argument provides information about what data was being expected. For example exp might say that a tuple of size 6 was expected.

fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize enum type received a variant with an unrecognized name.

fn unknown_field(field: &str, expected: &'static [&'static str]) -> Self

Raised when a Deserialize struct type received a field with an unrecognized name.

fn missing_field(field: &'static str) -> Self

Raised when a Deserialize struct type expected to receive a required field with a particular name but that field was not present in the input.

fn duplicate_field(field: &'static str) -> Self

Raised when a Deserialize struct type received more than one of the same field.

Object Safety

This trait is not object safe.

Implementors

impl Error for Error