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::with_position(ErrorKind::InvalidType, "unexpected string", 12, 2, 5);
assert_eq!(
    err.to_string(),
    "InvalidType: 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 mut err = Error::from_errors([
    Error::with_offset(ErrorKind::MissingField, "missing field `a`", 0),
    Error::with_offset(ErrorKind::InvalidType, "unexpected string", 9),
])
.unwrap();
err.resolve_position(b"{\n  \"b\": \"x\"}");
assert_eq!(err.errors().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\
     InvalidType: 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 with_offset<M: Into<Cow<'static, str>>>( kind: ErrorKind, msg: M, offset: usize, ) -> Error

Creates a new error at a byte offset in the input (see set_offset).

pub fn with_position<M: Into<Cow<'static, str>>>( kind: ErrorKind, msg: M, offset: usize, line: usize, column: usize, ) -> Error

Creates a new error at a byte offset with its line and column (see set_position).

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

Combines errors into one.

Errors that hold multiple errors are flattened: errors do not nest (see errors). 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 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 set_source<E: Error + Send + Sync + 'static>(&mut self, source: E)

Attaches another error as source to this error.

pub fn is_raw_request(&self) -> bool

Returns true if this requests the next value as raw value.

This is not an error: sinks return it from the event before a value that deserializes into a Raw value of the format that is parsed (see State::declare_raw_format). Deserializers of formats with raw values check the errors of events with this. If it’s true, the event was accepted and the format passes on the input of the next value as RawInput rather than its events. Other formats never see it.

pub fn kind(&self) -> ErrorKind

Returns the kind of the error.

pub fn category(&self) -> ErrorCategory

Returns the category of the error.

The category follows from the kind. The exception are errors of the kind Custom: they are in the Data category if a value failed with them while it was deserialized or serialized (the driver attached the context of the event to them, see Error), and in the Syntax category otherwise (the format failed with them).

For an error that holds multiple errors this is the category of the first one.

use deser::{Error, ErrorCategory, ErrorKind};

let err = Error::new(ErrorKind::Syntax, "expected a comma");
assert_eq!(err.category(), ErrorCategory::Syntax);
let err = Error::new(ErrorKind::InvalidType, "unexpected string");
assert_eq!(err.category(), ErrorCategory::Data);

pub fn message(&self) -> &str

Returns the message of the error (without context).

pub fn set_offset(&mut self, offset: usize)

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

A previously set line and column are discarded.

pub fn set_position(&mut self, offset: usize, line: usize, column: usize)

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

pub fn resolve_position(&mut self, source: &[u8])

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 mut err = Error::with_offset(ErrorKind::InvalidValue, "bad value", 7);
err.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 set_attachment<T: ErrorAttachment>(&mut self, value: T)

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.