pub struct Error {
pub code: ErrorCode,
pub index: usize,
pub key: Option<&'static str>,
}Expand description
A parse or serialization failure, located within the input.
The location is an offset, not a copy of anything: it indexes the buffer
you handed the parser, and it means nothing once that buffer is gone. A
caller that converts this into its own error type and drops the input
should render it first, with display_with, and
carry the String. See docs/errors.md for the shape that has.
Fields§
§code: ErrorCodeWhat went wrong.
index: usizeByte offset into the input where the failure was detected.
key: Option<&'static str>The key the code is about, where the crate knows one, and None where
it does not.
The offset answers “where”, and for a text document read next to
display_with that is usually the whole answer.
It is a poor answer for a member that is not in the document, which
has no position of its own, and a thin answer for BEVE, a byte offset
into a binary document being nearly unreadable. So the one code that
fills this in is MissingKey, whose offset is
the enclosing object’s first byte and whose name is the absent key.
Every other code leaves it empty, UnknownKey
and UnknownVariant included: the cursor
is already wound back to the offending name, so the offset points at it
and a copy here would say the same thing twice.
&'static str, so an Error still outlives the document and stays
Copy. Everything nameable here is a constant of the destination type
rather than a run of input bytes, which is what makes that possible.
Option rather than an empty string, which would cost nothing here
– the two are the same 32 bytes, the reference being niche-packed –
and would conflate two different answers. An empty key is legal JSON,
so #[required] "" => field is a schema whose missing key really is
named "", and Some("") says that where "" alone could not.
A hand-written reader sets it with json::Parser::set_error_key or
beve::Reader::set_error_key.
use structio::ErrorCode;
#[derive(Debug, Default)]
struct Accessor { byte_offset: u32, component_type: u32 }
structio::object!(Accessor as "camelCase" {
#[required] byte_offset,
#[required] "type" => component_type,
});
let e = structio::from_str::<Accessor>(r#"{"type":5}"#).unwrap_err();
assert_eq!(e.code, ErrorCode::MissingKey);
// The key the document uses, not the Rust field.
assert_eq!(e.key, Some("byteOffset"));
// And the offset is the object, which is all an absent member has.
assert_eq!(e.to_string(), r#"missing object key "byteOffset" at byte 0"#);Implementations§
Source§impl Error
impl Error
Sourcepub const fn new(code: ErrorCode, index: usize) -> Self
pub const fn new(code: ErrorCode, index: usize) -> Self
A failure at an offset, about no key in particular.
Sourcepub const fn with_key(
code: ErrorCode,
index: usize,
key: Option<&'static str>,
) -> Self
pub const fn with_key( code: ErrorCode, index: usize, key: Option<&'static str>, ) -> Self
A failure at an offset, about a key the reader named.
Option rather than &'static str, because this is what an entry
point composes with json::Parser::error_key and its BEVE twin,
which have a key only sometimes. See key.
Sourcepub fn display_with(&self, input: &str) -> String
pub fn display_with(&self, input: &str) -> String
Render the failure with the surrounding input, for diagnostics.
Shows the line and column plus a caret under the offending byte, and
the key where there is one.
The input is the one the offset indexes. Hand it a different document and you get a caret under an unrelated byte, which is why this is worth calling at the parse site rather than remembering the offset for later.
Trait Implementations§
impl Copy for Error
impl Eq for Error
Source§impl Error for Error
impl Error for Error
1.30.0 · Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()