Struct Quoted 

pub struct Quoted<'a> {
    expr: SEXP,
    env: SEXP,
    _arg: PhantomData<&'a SEXP>,
    _not_send: PhantomData<*const ()>,
}

An argument passed unevaluated: its expression and the environment it was written in, as base R’s substitute(x) and parent.frame() give them.

Take it as a #[miniextendr] parameter. The generated wrapper keeps the parameter as an R formal and passes if (missing(x)) quote(expr=) else list(substitute(x), parent.frame()), which never forces the argument. See the module docs.

use miniextendr_api::{miniextendr, Quoted, SEXP};

#[miniextendr]
pub fn column_name(col: Quoted) -> Option<String> {
    col.as_name().map(str::to_owned)   // column_name(TIME), column_name("TIME")
}

#[miniextendr]
pub fn evaluate(expr: Quoted) -> SEXP {
    expr.eval()                          // eval(expr, env)
}

parent.frame() is the environment of the function that called the wrapper, which is where the expression was written when the user calls the wrapper directly or through UseMethod(). A wrapper reached through a function that forwards its own argument (g <- function(y) f(y)) receives y and g’s frame, as subset() does. To resolve forwarding, {{ x }} and !!x, take a Quosure.

Fields

expr: SEXP

env: SEXP

_arg: PhantomData<&'a SEXP>

Borrows the .Call() argument that roots expr and env.

_not_send: PhantomData<*const ()>

R objects stay on R’s main thread.

Implementations

impl<'a> Quoted<'a>

#[doc(hidden)]

pub unsafe fn from_wrapper_arg(arg: &'a SEXP) -> Option<Self>

Read the argument a generated wrapper passed for a Quoted parameter: None when the argument is missing (quote(expr=)). Generated code calls this; user code has no reason to.

Panics

When arg is not the wrapper’s list(<expr>, <environment>).

Safety

R’s main thread; arg stays rooted for 'a.

#[doc(hidden)]

pub unsafe fn missing_from_wrapper_arg(arg: &'a SEXP) -> Missing<Self>

Self::from_wrapper_arg for a Missing<Quoted> parameter.

Safety

As Self::from_wrapper_arg.

pub fn expr(&self) -> SEXP

The expression as written: a symbol, a call, or a constant (substitute(x)).

pub fn env(&self) -> SEXP

The environment the expression was written in (parent.frame()).

pub fn as_name(&self) -> Option<&'a str>

The name the argument stands for: TIME and "TIME" both give "TIME". None for any other expression (a call, a number, NA).

pub fn eval(&self) -> SEXP

Evaluate the expression in its environment, eval(expr, env), keeping the caller’s condition handlers (eval_with_handlers).

The value is unprotected: protect it before the next allocation.

pub fn eval_in(&self, data: SEXP) -> SEXP

Evaluate the expression with data as a data mask, like eval(expr, data, env): the elements of a list or the columns of a data frame are visible by name, ahead of the expression’s environment. The first of two elements with one name wins, and unnamed elements are not visible. An environment is used as is (env is not consulted), and NULL evaluates in the expression’s environment.

The value is unprotected: protect it before the next allocation.

Panics

When data is not a list, a data frame, an environment or NULL.

pub fn try_eval_in(&self, data: SEXP) -> Result<SEXP, REvalError>

eval_in with an R error returned as Err, as try_eval_with_handlers returns it: the caller’s handlers still see the expression’s warnings and messages. The mask and the rules for data are eval_in’s.

A subset() method can explain a column that doesn’t exist and leave every other error as R raised it (REvalError::reraise):

let keep = match subset.try_eval_in(table) {
    Ok(keep) => keep,
    // `unknown_column` compares the expression's names with the table's.
    Err(e) if unknown_column(&subset, table) => {
        rust_error!(class = "pkg_unknown_column", "{e}; the columns are ...")
    }
    // SAFETY: inside the `#[miniextendr]` call.
    Err(e) => unsafe { e.reraise() },
};

The value is unprotected: protect it before the next allocation.

Panics

When data is not a list, a data frame, an environment or NULL.

unsafe fn eval_masked<R>( &self, data: SEXP, eval: unsafe fn(SEXP, SEXP) -> R, ) -> R

Evaluate the expression with data as a mask, as eval_in describes, through eval.

Safety

As eval’s: R’s main thread, inside a miniextendr boundary; data rooted by the caller.

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: 16 bytes