Struct REvalError 

pub struct REvalError {
    message: String,
    classes: Vec<String>,
    roots: Preserved,
}

An R error caught by RCall::eval / RCall::eval_base, r_eval_str, the helpers built on them (REnv::package_namespace, RCall::namespaced, dollar_extract), and try_eval_with_handlers / RCall::try_eval_with_handlers.

It holds R’s condition object, rooted while this value lives, and what R reports about it:

• message: conditionMessage(cond), the text R prints after Error in <call> :, without that prefix and without the Calls: traceback line of a non-interactive session;
• call: conditionCall(cond), None when it is NULL;
• classes: the class vector, most specific first;
• condition: the condition object itself.

Display writes the message alone. Every value holds a condition: a parse failure in r_eval_str and an evaluation under RCall::eval that jumps to the top level without an error (an interrupt) come back as a simpleError built for them, with no call.

Raising your own condition with it

The condition macros take the message through Display, and reraise_class puts the package’s own classes ahead of the caught ones:

use miniextendr_api::rust_error;

match RCall::new("print").arg(x).named_arg("na.print", na).eval_base() {
    Ok(_) => {}
    // The package's own class with R's message:
    //   class = "pkg_print_error"
    // or with the caught classes kept after it, so a handler for those
    // still matches:
    Err(e) => rust_error!(class = e.reraise_class("pkg_print_error"), "{e}"),
}

reraise raises the caught condition itself instead, as R raised it.

A #[miniextendr] function returning Result<T, REvalError> raises the caught message with the caught specific classes (REvalError implements RConditionData). For a Result<T, condition::RError> return, RError::from(e) takes the message (it is a std::error::Error) and .class(...) adds the classes.

Threads

!Send + !Sync: dropping the value releases its root on R’s precious list, which is R main-thread state, and condition / call hand out SEXPs. To carry the failure to another thread or into a Send error type (anyhow::Error, Box<dyn Error + Send>), take message or convert into condition::RError.

Fields

message: String

conditionMessage(cond).

classes: Vec<String>

class(cond).

roots: Preserved

list(cond, call), on R’s precious list while this value lives, where call is conditionCall(cond) or NULL (see REvalError::call). Its handle makes the value !Send + !Sync, see the type docs.

Implementations

impl REvalError

pub fn message(&self) -> &str

The condition’s message (conditionMessage(cond)), without R’s Error in <call> : prefix and Calls: line.

pub fn call(&self) -> Option<SEXP>

The condition’s call (conditionCall(cond)), None when it is NULL.

Also None for an error raised at the top of the evaluated expression (stop() called directly rather than from a function): R gives such an error the call of the tryCatch() frame the evaluation runs in, doTryCatch(return(expr), name, parentenv, handler), which is no call of the evaluated code. The condition object keeps what R recorded.

The SEXP is rooted while this value lives; protect it to keep it longer.

pub fn classes(&self) -> &[String]

The condition’s class vector, most specific first: for stop("boom"), ["simpleError", "error", "condition"].

pub fn inherits(&self, class: &str) -> bool

Whether the condition’s class vector contains class.

pub fn specific_classes(&self) -> &[String]

The classes ahead of the base layers: the class vector without its trailing rust_error, simpleError, error and condition, which the condition macros add again. Empty for stop("boom"); ["my_class"] for stop(errorCondition("boom", class = "my_class")) or for a miniextendr function’s error!(class = "my_class", "boom").

pub fn reraise_class(&self, own: impl ConditionClass) -> Vec<String>

The class vector for raising this error again as the package’s own condition: own first (one class or several, most specific first), then the caught specific classes not already in own.

// stop(errorCondition("boom", class = "vctrs_error")) caught as `e`:
rust_error!(class = e.reraise_class(["pkg_print_error", "pkg_error"]), "{e}");
// class: pkg_print_error, pkg_error, vctrs_error, rust_error,
//        simpleError, error, condition

pub fn condition(&self) -> SEXP

The condition object.

The SEXP is rooted while this value lives; protect it to keep it longer.

pub unsafe fn reraise(self) -> !

Raise the caught condition again, as R raised it: its classes, message and fields are unchanged, and its call is call. So an error raised at the top of the evaluated expression reports no call, not R’s doTryCatch(...) frame.

Use it for the errors a body doesn’t explain itself, next to a package’s own condition for the ones it does (Quoted::try_eval_in has an example). Unlike rust_error!(class = e.reraise_class(..), "{e}"), the condition gets no rust_error class and keeps R’s call, not the wrapper’s.

The condition is signalled by base stop(cond), evaluated as eval_with_handlers evaluates: the caller’s handlers see it, and the exit stops at that evaluation’s R_UnwindProtect frame and leaves as a Rust unwind. The frames up to the #[miniextendr] boundary drop their values, and the boundary hands the exit back to R, which goes on to the caller’s handler or to the top level. The same rules hold as for eval_with_handlers: don’t catch the unwind with std::panic::catch_unwind, and don’t call this from a Drop implementation.

Safety

As eval_with_handlers: R’s main thread, inside a miniextendr boundary (a #[miniextendr] function body, a with_r_unwind_protect closure, …).

unsafe fn from_condition(cond: SEXP) -> Self

Take a caught condition: read its classes, message and call, and root the condition with its call.

Safety

R’s main thread; cond is rooted by the caller for the call.

unsafe fn simple_error(message: &str) -> Self

A simpleError with message and no call, for a failure that raised no R condition (a parse failure, a jump to the top level, a result RCall::eval_as can’t read).

Safety

R’s main thread.

unsafe fn adopt( cond: SEXP, call: SEXP, message: String, classes: Vec<String>, ) -> Self

Root cond and call together for the value’s lifetime.

Safety

R’s main thread; cond and call are rooted by the caller for the call.

Trait Implementations

impl Debug for REvalError

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

Formats the value using the given formatter.

impl Display for REvalError

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

Formats the value using the given formatter.

impl Error for REvalError

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

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

#[doc(hidden)]

fn type_id(&self, _: Internal) -> TypeId

where Self: 'static,

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

Gets the TypeId of self.

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 RConditionData for REvalError

Returned as a #[miniextendr] function’s Err, the caught error is raised again with its message and its specific classes, ahead of the rust_error layers; the call is the function’s own.

fn message(&self) -> String

The condition message (conditionMessage(e)).

fn class(&self) -> Vec<String>

User classes, most specific first; empty for none.

fn data(&self) -> Option<ConditionData>

Structured fields spliced into the condition object (e$<name>).

fn call(&self) -> ConditionCall

Whether the condition reports a call. ConditionCall::None makes conditionCall() NULL, like R’s call. = FALSE, for a condition about the data rather than the call; the default keeps the call the transport captured. Honoured by defer_* and by Result returns; an argument-conversion error always keeps the call (see conversion_err_parts). #[condition(call = none)] on a derived type or variant overrides this.

fn argument_message(&self) -> Option<String>

The whole message when this error refuses an argument, or None.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 56 bytes