Struct Error 

#[non_exhaustive]
pub struct Error {
    pub kind: ErrorKind,
    /* private fields */
}

Error returned by every crate::Engine operation.

The kind field carries the failure category and any variant-specific payload. operator and node_ids are populated by the public evaluate* entry points: operator names the outermost operator that produced the error, and node_ids is a breadcrumb of compiled-node ids from the failure site toward the root (leaf-to-root). Use Error::resolve_path to translate the ids into structured crate::PathSteps callers can act on.

Wire format

Error serialises as: {"type": <kind tag>, "message": <Display>, ...kind-extras, "operator"?, "node_ids"?}. operator is omitted when None; node_ids is omitted when empty. JS consumers can JSON.parse(err) and switch on err.type.

Source chains

std::error::Error::source returns Some only for ErrorKind::Custom — the variant produced by Error::wrap. Every other variant carries a flat string or structured payload, not a typed cause. To attach a typed source error, wrap it via Error::wrap instead of constructing e.g. Error::invalid_arguments("...") directly.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

kind: ErrorKind

What went wrong. Pattern-matched by callers; stays public.

Implementations

impl Error

pub fn new(kind: ErrorKind) -> Self

Construct an Error with the given kind and no contextual metadata.

pub fn operator(&self) -> Option<&str>

Outermost operator that produced this error, when known. Returns None for parse/compile errors and for raw constructor sites that didn’t call Self::with_operator.

pub fn node_ids(&self) -> &[u32]

Breadcrumb of compiled-node ids from the failure site toward the root (leaf-to-root). Returns an empty slice when the error came from parse/compile or wasn’t routed through the public evaluate* path. Use Self::resolve_path to convert ids into named crate::PathSteps.

pub fn tag(&self) -> &'static str

Get a stable string tag for the error kind. Stable across releases.

pub fn with_operator(self, operator: impl Into<Cow<'static, str>>) -> Self

Attach the outermost operator name and return self.

Accepts anything convertible to Cow<'static, str> — passing a &'static str literal stays zero-allocation; a String becomes Cow::Owned (one move, no copy).

pub fn with_node_ids(self, ids: Vec<u32>) -> Self

Attach the breadcrumb path and return self.

Takes a Vec<u32> of compiled-node ids (leaf-to-root). The internal storage is currently a plain Vec<u32>; future versions may swap to an inline-buffer / smallvec layout without an API change.

pub fn resolve_path(&self, compiled: &Logic) -> Vec<PathStep>

Resolve the raw Self::node_ids breadcrumb into structured crate::PathSteps (root-to-leaf). Walks the compiled tree once.

Returns an empty vector when self.node_ids is empty. Ids absent from the compiled tree (e.g. when the error came from compile-time, before evaluation populated the breadcrumb) are skipped.

Why on demand: an earlier design eagerly cached the resolved steps on Error so callers could read them without holding the Logic. That walk allocates a HashMap of every node + a String JSON pointer per node, and paying it on every boundary error inflated error-heavy benchmark suites by 17×. Resolving on demand at the catch site puts the cost where the caller actually needs the data — and most callers either inspect raw Self::node_ids only, or already hold the compiled Logic at the catch site.

pub fn invalid_operator(name: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::InvalidOperator(name).into().

pub fn invalid_arguments(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::InvalidArguments(msg).into().

pub fn variable_not_found(name: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::VariableNotFound(name).into().

pub fn invalid_context_level(level: isize) -> Self

Shorthand for ErrorKind::InvalidContextLevel(level).into().

pub fn type_error(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::TypeError(msg).into().

pub fn arithmetic_error(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::ArithmeticError(msg).into().

pub fn custom_message(msg: impl Into<String>) -> Self

Shorthand for a message-only ErrorKind::Custom. Equivalent to Self::wrap with a string-shaped error inside. Reach for Self::wrap directly when you have a typed std::error::Error to preserve.

pub fn wrap<E: Error + Send + Sync + 'static>(err: E) -> Self

Wrap any std::error::Error + Send + Sync + 'static into an ErrorKind::Custom, preserving the source chain so consumers can walk it via std::error::Error::source:

some_io_call().map_err(Error::wrap)?;

The original error stays inspectable: error.source() returns Some(&original). Standard chain-walking via std::error::Error::source applies all the way down.

Wrapping an existing Error is a no-op — the input is returned unchanged rather than producing Custom(Custom(...)).

pub fn parse_error(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::ParseError(msg).into().

pub fn thrown(value: OwnedDataValue) -> Self

Shorthand for ErrorKind::Thrown(value).into().

pub fn thrown_value(&self) -> Option<&OwnedDataValue>

If this is an ErrorKind::Thrown, return its payload. Convenience accessor so consumers (loggers, structured-error walkers, the test runner) don’t have to pattern-match on the kind themselves.

pub fn format_error(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::FormatError(msg).into().

pub fn index_out_of_bounds(index: isize, length: usize) -> Self

Shorthand for ErrorKind::IndexOutOfBounds { index, length }.into().

pub fn configuration_error(msg: impl Into<Cow<'static, str>>) -> Self

Shorthand for ErrorKind::ConfigurationError(msg).into().

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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 wrapped source error, but only for ErrorKind::Custom.

All other ErrorKind variants carry a flat Cow<'static, str> payload (or a structured value, in Thrown / IndexOutOfBounds) rather than a typed cause, so they have no dyn Error to chain to. To attach a typed source, wrap your error via Error::wrap — that produces an ErrorKind::Custom whose source() returns Some(&original) and whose Display matches the original.

use datalogic_rs::Error;
use std::error::Error as _;

fn read_config() -> std::io::Result<String> {
    Err(std::io::Error::other("disk fell off the cliff"))
}

let err = read_config().map_err(Error::wrap).unwrap_err();
// The original io::Error survives the wrap and can be walked.
let source = err.source().unwrap();
assert!(source.to_string().contains("disk"));

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 serde_json only.

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<ErrorKind> for Error

fn from(kind: ErrorKind) -> Self

Converts to this type from the input type.

impl From<ParseError> for Error

fn from(err: ParseError) -> Self

Converts to this type from the input type.

impl Serialize for Error

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.