Struct Error 

pub struct Error { /* private fields */ }

An error for deser.

Besides a kind and a message an error can carry context: the location in the input it refers to (see offset, line and column) and typed attachments (see ErrorAttachment). The context is part of the Display output:

use deser::{Error, ErrorKind};

let err = Error::new(ErrorKind::Unexpected, "unexpected string")
    .with_position(12, 2, 5);
assert_eq!(
    err.to_string(),
    "Unexpected: unexpected string at line 2 column 5"
);

Errors raised while deserializing a value (for instance by a Sink) get the context attached by the DeserializeDriver: the start of the input range of the event (see State::input_range) and the context of the types registered with State::add_error_context. Formats resolve the offsets into lines and columns.

Multiple Errors

An error can hold multiple errors, for instance if deserialization continued after an error to report all problems of the input at once (see State::set_collect_errors). The accessors (kind, message, the location and the attachments) refer to the first of them, all of them are iterated with errors. The Display output mentions how many more errors there are, with the alternate flag ({:#}) it lists all of them, one per line:

use deser::{Error, ErrorKind};

let err = Error::from_errors([
    Error::new(ErrorKind::MissingField, "missing field `a`")
        .with_offset(0),
    Error::new(ErrorKind::Unexpected, "unexpected string")
        .with_offset(9),
])
.unwrap()
.resolve_position(b"{\n  \"b\": \"x\"}");
assert_eq!(err.error_count(), 2);
assert_eq!(err.kind(), ErrorKind::MissingField);
assert_eq!(
    err.to_string(),
    "MissingField: missing field `a` at line 1 column 1 \
     (and 1 more error)"
);
assert_eq!(
    format!("{:#}", err),
    "MissingField: missing field `a` at line 1 column 1\n\
     Unexpected: unexpected string at line 2 column 8"
);

Implementations

impl Error

pub fn new<M: Into<Cow<'static, str>>>(kind: ErrorKind, msg: M) -> Error

Creates a new error.

pub fn from_errors<I: IntoIterator<Item = Error>>(errors: I) -> Option<Error>

Combines errors into one.

Errors that hold multiple errors are flattened (see push_error). Returns None if there are no errors.

pub fn in_progress() -> Error

Creates the error for a value that is serialized while another one is only partially written.

Stream serializers return this once they are in progress and are asked to serialize another value.

pub fn push_error(&mut self, err: Error)

Adds an error to this error.

If the error that is added holds multiple errors, they are added individually: errors do not nest (see errors).

pub fn errors(&self) -> impl Iterator<Item = &Error>

Iterates over the errors this error holds.

For an error that holds a single error, this is the error itself. The errors that are returned hold a single error each.

pub fn error_count(&self) -> usize

Returns the number of errors this error holds.

pub fn with_source<E: Error + Send + Sync + 'static>(self, source: E) -> Self

Attaches another error as source to this error.

pub fn kind(&self) -> ErrorKind

Returns the kind of the error.

pub fn message(&self) -> &str

Returns the message of the error (without context).

pub fn with_offset(self, offset: usize) -> Self

Sets the byte offset in the input the error refers to.

A previously set line and column are discarded.

pub fn with_position(self, offset: usize, line: usize, column: usize) -> Self

Sets the byte offset together with its line and column (1-based).

pub fn resolve_position(self, source: &[u8]) -> Self

Resolves the offset into line and column.

The source is the input the offset refers to. Columns are counted in characters (bytes that are not UTF-8 continuation bytes). If the error has no offset or already has a line and column, it’s returned unchanged. Text formats call this for the errors they return.

use deser::{Error, ErrorKind};

let err = Error::new(ErrorKind::Unexpected, "bad value")
    .with_offset(7)
    .resolve_position(b"[1,\n  x]");
assert_eq!((err.line(), err.column()), (Some(2), Some(4)));

The positions of further errors (see errors) are resolved as well.

pub fn offset(&self) -> Option<usize>

Returns the byte offset in the input the error refers to.

pub fn line(&self) -> Option<usize>

Returns the line (1-based) the error refers to.

pub fn column(&self) -> Option<usize>

Returns the column (1-based, in characters) the error refers to.

pub fn with_attachment<T: ErrorAttachment>(self, value: T) -> Self

Attaches a value to the error.

An attachment of the same type is replaced but keeps its position in the Display output. See ErrorAttachment.

pub fn attachment<T: ErrorAttachment>(&self) -> Option<&T>

Returns the attachment of the given type.

pub fn attachment_mut<T: ErrorAttachment>(&mut self) -> Option<&mut T>

Returns the attachment of the given type mutably.

pub fn attachments(&self) -> impl Iterator<Item = &dyn ErrorAttachment>

Iterates over the attachments in the order they were attached.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

Available on crate feature std only.

fn from(err: Error) -> Error

Converts to this type from the input type.