Struct Environment 

pub struct Environment {
    pub(crate) robj: Robj,
}

Fields

robj: Robj

Implementations

impl Environment

pub fn new_with_parent(parent: Environment) -> Self

Create a new, empty environment.

use extendr_api::prelude::*;
test! {
    let env = Environment::new_with_parent(Environment::global());
    assert_eq!(env.len(), 0);
}

pub fn new_with_capacity(parent: Environment, capacity: usize) -> Self

Create a new, empty environment with a reserved size.

This function will guess the hash table size if required. Use the Env{} wrapper for more detail.

use extendr_api::prelude::*;
test! {
    let env = Environment::new_with_capacity(Environment::global(), 5);
    env.set_local(sym!(a), 1);
    env.set_local(sym!(b), 2);
    assert_eq!(env.len(), 2);
}

pub fn from_pairs<NV>(parent: Environment, names_and_values: NV) -> Self

where NV: IntoIterator, NV::Item: SymPair,

Make an R environment object.

use extendr_api::prelude::*;
use std::convert::TryInto;
test! {
    let names_and_values = (0..100).map(|i| (format!("n{}", i), i));
    let mut env = Environment::from_pairs(Environment::global(), names_and_values);
    assert_eq!(env.len(), 100);
}

pub fn current() -> Self

Get the current evaluation environment.

pub fn global() -> Self

Get the global environment.

pub fn base() -> Self

Get the base environment.

pub fn empty() -> Self

Get the empty environment.

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

Get the call associated with this environment. Mimics rlang’s frame_call(): evaluates sys.frames() in self, finds the matching frame index, then returns sys.call(i). Returns None if not called from a function frame or if the call cannot be determined.

pub fn caller() -> Self

Get the caller’s environment (i.e. parent.frame()).

pub fn parent(&self) -> Option<Environment>

Get the enclosing (parent) environment.

pub fn names(&self) -> impl Iterator<Item = &'static str>

Get the names in an environment, sorted.

use extendr_api::prelude::*;
test! {
   let names_and_values : std::collections::HashMap<_, _> = (0..4).map(|i| (format!("n{}", i), r!(i))).collect();
   let env = Environment::from_pairs(Environment::global(), names_and_values);
   assert_eq!(env.names().collect::<Vec<_>>(), vec!["n0", "n1", "n2", "n3"]);
}

pub fn keys(&self) -> impl Iterator<Item = &'static str>

An alias for Environment::names.

pub fn values(&self) -> impl Iterator<Item = Robj> + '_

Get the values in an environment, ordered by name.

use extendr_api::prelude::*;
test! {
   let env = Environment::from_pairs(Environment::global(), vec![("b", r!(2)), ("a", r!(1))]);
   assert_eq!(env.values().collect::<Vec<_>>(), vec![r!(1), r!(2)]);
}

pub fn contains_key<K: AsRef<str>>(&self, key: K) -> bool

Returns true if the environment, but not its ancestors, has a binding for key.

use extendr_api::prelude::*;
test! {
    let mut env = Environment::new_with_parent(Environment::global());
    env.insert("x", 1)?;
    assert!(env.contains_key("x"));
    assert!(!env.contains_key("y"));
}

pub fn insert<K: AsRef<str>, V: Into<Robj>>( &mut self, key: K, value: V, ) -> Result<Option<Robj>>

Bind value to key in the environment, returning the previous value if there was one.

Fails if the binding is locked, or if the environment is locked and key is new.

use extendr_api::prelude::*;
test! {
    let mut env = Environment::new_with_parent(Environment::global());
    assert_eq!(env.insert("x", "harry"), Ok(None));
    assert_eq!(env.insert("x", "fred"), Ok(Some(r!("harry"))));
    assert_eq!(env.local(sym!(x)), Ok(r!("fred")));
}

pub fn remove<K: AsRef<str>>(&mut self, key: K) -> Result<Option<Robj>>

Remove key from the environment, returning its value if there was one.

Fails if the environment is locked.

use extendr_api::prelude::*;
test! {
    let mut env = Environment::new_with_parent(Environment::global());
    env.insert("x", 1)?;
    assert_eq!(env.remove("x"), Ok(Some(r!(1))));
    assert_eq!(env.remove("x"), Ok(None));
}

pub fn set_local<K: Into<Robj>, V: Into<Robj>>(&self, key: K, value: V)

Set or define a variable in an environment.

use extendr_api::prelude::*;
test! {
    let env = Environment::new_with_parent(Environment::global());
    env.set_local(sym!(x), "harry");
    env.set_local(sym!(x), "fred");
    assert_eq!(env.local(sym!(x)), Ok(r!("fred")));
}

pub fn local<K: Into<Robj>>(&self, key: K) -> Result<Robj>

Get a variable from an environment, but not its ancestors.

use extendr_api::prelude::*;
test! {
    let env = Environment::new_with_parent(Environment::global());
    env.set_local(sym!(x), "fred");
    assert_eq!(env.local(sym!(x)), Ok(r!("fred")));
}

Trait Implementations

impl Clone for Environment

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Conversions for Environment

as_*()

fn as_symbol(&self) -> Option<Symbol>

Convert a symbol object to a Symbol wrapper.

fn as_char(&self) -> Option<Rstr>

Convert a CHARSXP object to a Rstr wrapper.

fn as_raw(&self) -> Option<Raw>

Convert a raw object to a Rstr wrapper.

fn as_language(&self) -> Option<Language>

Convert a language object to a Language wrapper.

fn as_pairlist(&self) -> Option<Pairlist>

Convert a pair list object (LISTSXP) to a Pairlist wrapper.

fn as_list(&self) -> Option<List>

Convert a list object (VECSXP) to a List wrapper.

fn as_expressions(&self) -> Option<Expressions>

Convert an expression object (EXPRSXP) to a Expr wrapper.

fn as_environment(&self) -> Option<Environment>

Convert an environment object (ENVSXP) to a Env wrapper.

fn as_function(&self) -> Option<Function>

Convert a function object (CLOSXP) to a Function wrapper.

fn as_promise(&self) -> Option<Promise>

Get a wrapper for a promise.

impl Debug for Environment

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

Formats the value using the given formatter.

impl From<&Environment> for Robj

fn from(val: &Environment) -> Self

Make an robj from a wrapper.

impl From<Environment> for Robj

fn from(val: Environment) -> Self

Make an robj from a wrapper.

impl GetSexp for Environment

unsafe fn get(&self) -> SEXP

Get a copy of the underlying SEXP.

unsafe fn get_mut(&mut self) -> SEXP

Safety

fn as_robj(&self) -> &Robj

Get a reference to a Robj for this type.

fn as_robj_mut(&mut self) -> &mut Robj

Get a mutable reference to a Robj for this type.

impl Length for Environment

len() and is_empty()

fn len(&self) -> usize

Get the extended length of the object.

fn is_empty(&self) -> bool

Returns true if the Robj contains no elements.

impl Operators for Environment

dollar() etc.

fn dollar<T>(&self, symbol: T) -> Result<Robj>

where T: AsRef<str>,

Do the equivalent of x$y

fn slice<T>(&self, rhs: T) -> Result<Robj>

where T: Into<Robj>,

Do the equivalent of x[y]

fn index<T>(&self, rhs: T) -> Result<Robj>

where T: Into<Robj>,

Do the equivalent of x[[y]]

fn tilde<T>(&self, rhs: T) -> Result<Robj>

where T: Into<Robj>,

Do the equivalent of x ~ y

fn double_colon<T>(&self, rhs: T) -> Result<Robj>

where T: Into<Robj>,

Do the equivalent of x :: y

fn call(&self, args: Pairlist) -> Result<Robj>

Do the equivalent of x(a, b, c)

impl PartialEq for Environment

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Rinternals for Environment

find_var() etc.

fn is_null(&self) -> bool

Return true if this is the null object.

fn is_symbol(&self) -> bool

Return true if this is a symbol.

fn is_logical(&self) -> bool

Return true if this is a boolean (logical) vector

fn is_real(&self) -> bool

Return true if this is a real (f64) vector.

fn is_complex(&self) -> bool

Return true if this is a complex vector.

fn is_expressions(&self) -> bool

Return true if this is an expression.

fn is_environment(&self) -> bool

Return true if this is an environment.

fn is_promise(&self) -> bool

Return true if this is an environment.

fn is_string(&self) -> bool

Return true if this is a string.

fn is_object(&self) -> bool

Return true if this is an object (ie. has a class attribute).

fn is_s4(&self) -> bool

Return true if this is a S4 object.

fn is_external_pointer(&self) -> bool

Return true if this is an expression.

fn get_current_srcref(val: i32) -> Robj

Get the source ref.

fn get_src_filename(&self) -> Robj

Get the source filename.

fn as_character_vector(&self) -> Robj

Convert to a string vector.

fn coerce_vector(&self, sexptype: SEXPTYPE) -> Robj

Convert to vectors of many kinds.

fn pair_to_vector_list(&self) -> Robj

Convert a pairlist (LISTSXP) to a vector list (VECSXP).

fn vector_to_pair_list(&self) -> Robj

Convert a vector list (VECSXP) to a pair list (LISTSXP)

fn as_character_factor(&self) -> Robj

Convert a factor to a string vector.

fn alloc_matrix(sexptype: SEXPTYPE, rows: i32, cols: i32) -> Robj

Allocate a matrix object.

fn duplicate(&self) -> Robj

Do a deep copy of this object. Note that clone() only adds a reference.

fn find_function<K: TryInto<Symbol, Error = Error>>( &self, key: K, ) -> Result<Robj>

Find a function in an environment ignoring other variables.

fn find_var<K: TryInto<Symbol, Error = Error>>(&self, key: K) -> Result<Robj>

Find a variable in an environment.

fn ncols(&self) -> usize

Number of columns of a matrix

fn nrows(&self) -> usize

Number of rows of a matrix

fn xlengthgets(&self, new_len: usize) -> Result<Robj>

Copy a vector and resize it. See. https://github.com/hadley/r-internals/blob/master/vectors.md

fn alloc_vector(sexptype: SEXPTYPE, len: usize) -> Robj

Allocated an owned object of a certain type.

fn conformable(a: &Robj, b: &Robj) -> bool

Return true if two arrays have identical dims.

fn is_array(&self) -> bool

Return true if this is an array.

fn is_factor(&self) -> bool

Return true if this is factor.

fn is_frame(&self) -> bool

Return true if this is a data frame.

fn is_function(&self) -> bool

Return true if this is a function or a primitive (CLOSXP, BUILTINSXP or SPECIALSXP)

fn is_integer(&self) -> bool

Return true if this is an integer vector (INTSXP) but not a factor.

fn is_language(&self) -> bool

Return true if this is a language object (LANGSXP).

fn is_pairlist(&self) -> bool

Return true if this is NILSXP or LISTSXP.

fn is_matrix(&self) -> bool

Return true if this is a matrix.

fn is_list(&self) -> bool

Return true if this is NILSXP or VECSXP.

fn is_number(&self) -> bool

Return true if this is INTSXP, LGLSXP or REALSXP but not a factor.

fn is_primitive(&self) -> bool

Return true if this is a primitive function BUILTINSXP, SPECIALSXP.

fn is_ts(&self) -> bool

Return true if this is a time series vector (see tsp).

fn is_user_binop(&self) -> bool

Return true if this is a user defined binop.

fn is_vector(&self) -> bool

Return true if this is a vector.

fn is_vector_atomic(&self) -> bool

Return true if this is an atomic vector.

fn is_vector_list(&self) -> bool

Return true if this is a vector list.

fn is_vectorizable(&self) -> bool

Return true if this is can be made into a vector.

fn is_raw(&self) -> bool

Return true if this is RAWSXP.

fn is_char(&self) -> bool

Return true if this is CHARSXP.

fn is_missing_arg(&self) -> bool

fn is_package_env(&self) -> bool

fn package_env_name(&self) -> Robj

fn is_namespace_env(&self) -> bool

fn namespace_env_spec(&self) -> Robj

fn is_altrep(&self) -> bool

Returns true if this is an ALTREP object.

fn is_altinteger(&self) -> bool

Returns true if this is an integer ALTREP object.

fn is_altreal(&self) -> bool

Returns true if this is an real ALTREP object.

fn is_altlogical(&self) -> bool

Returns true if this is an logical ALTREP object.

fn is_altraw(&self) -> bool

Returns true if this is a raw ALTREP object.

fn is_altstring(&self) -> bool

Returns true if this is an integer ALTREP object.

fn is_altlist(&self) -> bool

Returns true if this is an integer ALTREP object.

fn deparse(&self) -> Result<String>

Generate a text representation of this object.

impl Serialize for Environment

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Slices for Environment

as_typed_slice_raw() etc.

unsafe fn as_typed_slice_raw<T>(&self) -> &[T]

Get an immutable slice to this object’s data.

unsafe fn as_typed_slice_raw_mut<T>(&mut self) -> &mut [T]

Get a mutable slice to this object’s data.

impl StructuralPartialEq for Environment

impl TryFrom<&Robj> for Environment

fn try_from(robj: &Robj) -> Result<Self>

Make a wrapper from a robj if it matches.

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<Robj> for Environment

fn try_from(robj: Robj) -> Result<Self>

Make a wrapper from a robj if it matches.

type Error = Error

The type returned in the event of a conversion error.

impl Types for Environment

rtype() and rany()

fn rtype(&self) -> Rtype

Get the type of an R object.

fn as_any(&self) -> Rany<'_>