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 innermost operator that failed, 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>

The operator that failed, when known: the innermost operator on Self::node_ids, so a failing custom operator nested inside built-ins is named itself. The same on every evaluation path, traced or not. When no node on the path has an operator name, the rule’s root operator stands in.

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. The name of Self::code.

pub fn code(&self) -> ErrorCode

What kind of error this is, without its payload. See ErrorCode.

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

Attach the name of the operator that failed and return self. An error that leaves an evaluation already named keeps that name.

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 private; future versions may swap its 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) -> Self

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.