Struct REnv 

pub struct REnv {
    sexp: SEXP,
}

Handle to a well-known R environment.

Provides access to R’s standard environments without raw FFI calls.

Fields

sexp: SEXP

Implementations

impl REnv

pub unsafe fn global() -> Self

The global environment (R_GlobalEnv).

Safety

Must be called from the R main thread.

pub unsafe fn base() -> Self

The base environment (R_BaseEnv).

Safety

Must be called from the R main thread.

pub unsafe fn empty() -> Self

The empty environment (R_EmptyEnv).

Safety

Must be called from the R main thread.

pub fn base_namespace() -> Self

The base namespace (SEXP::base_namespace()).

Unlike base() which is the base environment (exported functions visible to users), this is the base namespace (includes internal helpers). Rarely needed — prefer base() unless you specifically need unexported base internals.

Safety

Must be called from the R main thread.

pub unsafe fn package_namespace(name: &str) -> Result<Self, REvalError>

A package’s namespace environment.

Finds the namespace for a loaded package. Use this to evaluate functions that live in a specific package (e.g., slot() from methods).

This is a safe wrapper around getNamespace(name), evaluated through RCall::eval, so a missing namespace returns Err instead of longjmping through Rust frames.

Safety

Must be called from the R main thread.

Errors

R’s error when the namespace cannot be loaded (a packageNotFoundError for a package that is not installed).

pub unsafe fn caller() -> Self

The current execution environment.

Returns the environment of the innermost active closure on R’s call stack, or the global environment if no closure is active.

Useful when you need to evaluate an expression in the caller’s context rather than a fixed well-known environment.

Safety

Must be called from the R main thread.

pub unsafe fn from_sexp(sexp: SEXP) -> Self

Wrap an arbitrary environment SEXP.

Safety

sexp must be a valid ENVSXP.

pub fn as_sexp(&self) -> SEXP

Get the underlying SEXP.

pub unsafe fn get(&self, name: &str) -> Option<SEXP>

The value bound to name in this environment’s own frame, as R’s get0(name, envir = env, inherits = FALSE) reads it, or None when the frame has no such binding. The enclosing environments are not searched; get_inherits searches them.

A binding to NULL is Some of NULL. Reading a binding does what get0() does:

• A promise is forced, once, and its value is kept in the promise. A function in a lazy-loaded namespace, a delayedAssign() and an argument of an R function are promises. So this is not a check for whether a name is bound without running anything.
• An active binding (makeActiveBinding()) calls its function.
• A binding to the missing argument raises R’s error.

R 4.5 and later read the binding with R_getVarEx; R 4.4 evaluates base::get0(). Both give the same results. An R error raised while reading, such as a promise or an active binding that fails, unwinds the Rust frames up to the miniextendr boundary, which hands it back to R, as under eval_with_handlers.

Safety

R’s main thread, inside a miniextendr boundary: a #[miniextendr] function body, a with_r_unwind_protect closure, an ALTREP callback with the r_unwind or rust_unwind guard, a connection callback, a with_r_thread closure.

Returns

The value, unprotected. A plain binding, or a forced promise, keeps it reachable while the name stays bound to it. An active binding’s value is new and held by nothing. Protect the value (OwnedProtect, Preserved) before the next allocation unless the binding is known to be a plain value, and before anything that may rebind the name: R code you evaluate, or define.

Panics

Panics if name contains a null byte.

pub unsafe fn get_inherits(&self, name: &str) -> Option<SEXP>

The value bound to name in this environment or the nearest enclosing environment that binds it, as R’s get0(name, envir = env, inherits = TRUE) reads it, or None when none does.

Bindings are read as get reads them: a promise is forced, an active binding is called. The search stops at the first binding of name, whatever its value.

Safety

As get.

Returns

The value, unprotected, as get returns it.

Panics

Panics if name contains a null byte.

pub unsafe fn define(&self, name: &str, value: SEXP)

Bind name to value in this environment’s own frame, as assign(name, value, envir = env) does: a binding of name in the frame is replaced, and the enclosing environments are not touched.

R raises its error, which unwinds as under get, when the binding cannot be made: the empty environment, a locked environment that lacks the binding (a package namespace, once the package is loaded), or a locked binding. Assigning to an active binding calls its function with value.

Safety

As get. value is a valid SEXP; it needs no root of its own, and the binding keeps it reachable afterwards.

Panics

Panics if name contains a null byte.

pub(crate) unsafe fn define_symbol(&self, symbol: SEXP, value: SEXP)

define for a name already interned as a symbol.

Safety

As define; symbol is a SYMSXP.

unsafe fn lookup(&self, name: &str, inherits: bool) -> Option<SEXP>

get and get_inherits.

Safety

As get.

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