Struct extendr_api::wrapper::list::List[][src]

pub struct List { /* fields omitted */ }

Implementations

Create a new, empty list.

use extendr_api::prelude::*;
test! {
    let list = List::new();
    assert_eq!(list.is_list(), true);
    assert_eq!(list.len(), 0);
}

Wrapper for creating list (VECSXP) objects.

use extendr_api::prelude::*;
test! {
    let list = r!(List::from_values(&[r!(0), r!(1), r!(2)]));
    assert_eq!(list.is_list(), true);
    assert_eq!(list.len(), 3);
}

Return an iterator over the values of this list.

use extendr_api::prelude::*;
test! {
    let mut robj = list!(1, 2, 3);
    let objects : Vec<_> = robj.as_list().unwrap().values().collect();
    assert_eq!(objects, vec![r!(1), r!(2), r!(3)]);
}

Return an iterator over the names and values of this list.

use extendr_api::prelude::*;
test! {
    let mut robj = list!(a=1, 2);
    let names_and_values : Vec<_> = robj.as_list().unwrap().iter().collect();
    assert_eq!(names_and_values, vec![("a", r!(1)), ("", r!(2))]);
}

Methods from Deref<Target = Robj>

Get an iterator over a string vector. Returns None if the object is not a string vector but works for factors.

use extendr_api::prelude::*;

test! {
    let obj = Robj::from(vec!["a", "b", "c"]);
    assert_eq!(obj.as_str_iter().unwrap().collect::<Vec<_>>(), vec!["a", "b", "c"]);

    let factor = factor!(vec!["abcd", "def", "fg", "fg"]);
    assert_eq!(factor.levels().unwrap().collect::<Vec<_>>(), vec!["abcd", "def", "fg"]);
    assert_eq!(factor.as_integer_vector().unwrap(), vec![1, 2, 3, 3]);
    assert_eq!(factor.as_str_iter().unwrap().collect::<Vec<_>>(), vec!["abcd", "def", "fg", "fg"]);
    assert_eq!(factor.as_str_iter().unwrap().collect::<Vec<_>>(), vec!["abcd", "def", "fg", "fg"]);

    let obj = Robj::from(vec![Some("a"), Some("b"), None]);
    assert_eq!(obj.as_str_iter().unwrap().map(|s| s.is_na()).collect::<Vec<_>>(), vec![false, false, true]);

    let obj = Robj::from(vec!["a", "b", <&str>::na()]);
    assert_eq!(obj.as_str_iter().unwrap().map(|s| s.is_na()).collect::<Vec<_>>(), vec![false, false, true]);

    let obj = Robj::from(vec!["a", "b", "NA"]);
    assert_eq!(obj.as_str_iter().unwrap().map(|s| s.is_na()).collect::<Vec<_>>(), vec![false, false, false]);
}

Do the equivalent of x$y

use extendr_api::prelude::*;
test! {
let env = Environment::from_pairs(global_env(),
   vec![("a".to_string(), r!(1)), ("b".to_string(), r!(2))]);
assert_eq!(env.dollar("a").unwrap(), r!(1));
assert_eq!(env.dollar("b").unwrap(), r!(2));
}

Do the equivalent of x[y]

use extendr_api::prelude::*;
test! {
let vec = r!([10, 20, 30]);
assert_eq!(vec.slice(2).unwrap(), r!(20));
assert_eq!(vec.slice(2..=3).unwrap(), r!([20, 30]));
}

Do the equivalent of x[[y]]

use extendr_api::prelude::*;
test! {
let vec = r!([10, 20, 30]);
assert_eq!(vec.index(2).unwrap(), r!(20));
assert_eq!(vec.index(2..=3).is_err(), true);
}

Do the equivalent of x ~ y

use extendr_api::prelude::*;
test! {
    let x = r!(Symbol::from_string("x"));
    let y = r!(Symbol::from_string("y"));
    let tilde = x.tilde(y).unwrap();
    assert_eq!(tilde.inherits("formula"), true);
}

Do the equivalent of x :: y

use extendr_api::prelude::*;
test! {
    let base = r!(Symbol::from_string("base"));
    let list = r!(Symbol::from_string("list"));
    let base_list = base.double_colon(list).unwrap();
    assert_eq!(base_list.is_function(), true);
}

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

use extendr_api::prelude::*;
test! {
    let function = R!("function(a, b) a + b").unwrap();
    assert_eq!(function.is_function(), true);
    assert_eq!(function.call(pairlist!(a=1, b=2)).unwrap(), r!(3));
}

Return true if this is the null object.

Return true if this is a symbol.

Return true if this is a boolean (logical) vector

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

Return true if this is a complex vector.

Return true if this is an expression.

Return true if this is an environment.

Return true if this is an environment.

Return true if this is a string.

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

Return true if this is a S4 object.

Return true if this is an expression.

Get the source filename.

Convert to a string vector.

Convert to vectors of many kinds.

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

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

Convert a factor to a string vector.

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

Find a function in an environment ignoring other variables.

This evaulates promises if they are found.

See also global_function().

use extendr_api::prelude::*;
test! {
   let my_fun = base_env().find_function(sym!(ls)).unwrap();
   assert_eq!(my_fun.is_function(), true);

   // Note: this may crash on some versions of windows which don't support unwinding.
   // assert!(base_env().find_function(sym!(qwertyuiop)).is_none());
}

Find a variable in an environment.

See also global_var().

Note that many common variables and functions are contained in promises which must be evaluated and this function may throw an R error.

use extendr_api::prelude::*;
test! {
   let iris_dataframe = global_env()
       .find_var(sym!(iris)).unwrap().eval_promise().unwrap();
   assert_eq!(iris_dataframe.is_frame(), true);
   assert_eq!(iris_dataframe.len(), 5);

   // Note: this may crash on some versions of windows which don't support unwinding.
   //assert_eq!(global_env().find_var(sym!(imnotasymbol)), None);
}

If this object is a promise, evaluate it, otherwise return the object.

use extendr_api::prelude::*;
test! {
   let iris_promise = global_env().find_var(sym!(iris)).unwrap();
   let iris_dataframe = iris_promise.eval_promise().unwrap();
   assert_eq!(iris_dataframe.is_frame(), true);
}

Number of columns of a matrix

Number of rows of a matrix

Return true if this is an array.

Return true if this is factor.

Return true if this is a data frame.

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

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

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

Return true if this is NILSXP or LISTSXP.

Return true if this is a matrix.

Return true if this is NILSXP or VECSXP.

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

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

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

Return true if this is a user defined binop.

Return true if this is a valid string.

Return true if this is a valid string.

Return true if this is a vector.

Return true if this is an atomic vector.

Return true if this is a vector list.

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

Return true if this is RAWSXP.

Return true if this is CHARSXP.

Returns true if this is an ALTREP object.

Returns true if this is an integer ALTREP object.

Returns true if this is an real ALTREP object.

Returns true if this is an logical ALTREP object.

Returns true if this is a raw ALTREP object.

Returns true if this is an integer ALTREP object.

Generate a text representation of this object.

Get the type of an R object.

use extendr_api::prelude::*;
test! {
    assert_eq!(r!(NULL).rtype(), RType::Null);
    assert_eq!(sym!(xyz).rtype(), RType::Symbol);
    assert_eq!(r!(Pairlist::from_pairs(vec![("a", r!(1))])).rtype(), RType::Pairlist);
    assert_eq!(R!("function() {}")?.rtype(), RType::Function);
    assert_eq!(Environment::new_with_parent(global_env()).rtype(), RType::Environment);
    assert_eq!(lang!("+", 1, 2).rtype(), RType::Language);
    assert_eq!(r!(Primitive::from_string("if")).rtype(), RType::Special);
    assert_eq!(r!(Primitive::from_string("+")).rtype(), RType::Builtin);
    assert_eq!(r!(Rstr::from_string("hello")).rtype(), RType::Rstr);
    assert_eq!(r!(TRUE).rtype(), RType::Logical);
    assert_eq!(r!(1).rtype(), RType::Integer);
    assert_eq!(r!(1.0).rtype(), RType::Real);
    assert_eq!(r!("1").rtype(), RType::String);
    assert_eq!(r!(List::from_values(&[1, 2])).rtype(), RType::List);
    assert_eq!(parse("x + y")?.rtype(), RType::Expression);
    assert_eq!(r!(Raw::from_bytes(&[1_u8, 2, 3])).rtype(), RType::Raw);
}

Get the extended length of the object.

use extendr_api::prelude::*;
test! {

let a : Robj = r!(vec![1., 2., 3., 4.]);
assert_eq!(a.len(), 4);
}

Returns true if the Robj contains no elements.

use extendr_api::prelude::*;
test! {

let a : Robj = r!(vec![0.; 0]); // length zero of numeric vector
assert_eq!(a.is_empty(), true);
}

Is this object is an NA scalar? Works for character, integer and numeric types.

use extendr_api::prelude::*;
test! {

assert_eq!(r!(NA_INTEGER).is_na(), true);
assert_eq!(r!(NA_REAL).is_na(), true);
assert_eq!(r!(NA_STRING).is_na(), true);
}

Get a read-only reference to the content of an integer vector.

use extendr_api::prelude::*;
test! {

let robj = r!([1, 2, 3]);
assert_eq!(robj.as_integer_slice().unwrap(), [1, 2, 3]);
}

Convert an Robj into Integers.

Get a Vec copied from the object.

use extendr_api::prelude::*;
test! {

let robj = r!([1, 2, 3]);
assert_eq!(robj.as_integer_slice().unwrap(), vec![1, 2, 3]);
}

Get a read-only reference to the content of a logical vector using the tri-state Bool. Returns None if not a logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE, NA_LOGICAL]);
    assert_eq!(robj.as_logical_slice().unwrap(), [TRUE, FALSE, NA_LOGICAL]);
}

Get a Vec copied from the object using the tri-state Bool. Returns None if not a logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE, NA_LOGICAL]);
    assert_eq!(robj.as_logical_vector().unwrap(), vec![TRUE, FALSE, NA_LOGICAL]);
}

Get an iterator over logical elements of this slice.

use extendr_api::prelude::*;
test! {
    let robj = r!([TRUE, FALSE, NA_LOGICAL]);
    let (mut nt, mut nf, mut nna) = (0, 0, 0);
    for val in robj.as_logical_iter().unwrap() {
      match *val {
        TRUE => nt += 1,
        FALSE => nf += 1,
        NA_LOGICAL => nna += 1,
        _ => ()
      }
    }
    assert_eq!((nt, nf, nna), (1, 1, 1));
}

Get a read-only reference to the content of a double vector. Note: the slice may contain NaN or NA values. We may introduce a “Real” type to handle this like the Bool type.

use extendr_api::prelude::*;
test! {
    let robj = r!([Some(1.), None, Some(3.)]);
    let mut tot = 0.;
    for val in robj.as_real_slice().unwrap() {
      if !val.is_na() {
        tot += val;
      }
    }
    assert_eq!(tot, 4.);
}

Get an iterator over real elements of this slice.

use extendr_api::prelude::*;
test! {
    let robj = r!([1., 2., 3.]);
    let mut tot = 0.;
    for val in robj.as_real_iter().unwrap() {
      if !val.is_na() {
        tot += val;
      }
    }
    assert_eq!(tot, 6.);
}

Get a Vec copied from the object.

use extendr_api::prelude::*;
test! {
    let robj = r!([1., 2., 3.]);
    assert_eq!(robj.as_real_vector().unwrap(), vec![1., 2., 3.]);
}

Get a read-only reference to the content of an integer or logical vector.

use extendr_api::prelude::*;
test! {
    let robj = r!(Raw::from_bytes(&[1, 2, 3]));
    assert_eq!(robj.as_raw_slice().unwrap(), &[1, 2, 3]);
}

Get a read-write reference to the content of an integer or logical vector. Note that rust slices are 0-based so slice[1] is the middle value.

use extendr_api::prelude::*;
test! {
    let mut robj = r!([1, 2, 3]);
    let slice : & mut [i32] = robj.as_integer_slice_mut().unwrap();
    slice[1] = 100;
    assert_eq!(robj, r!([1, 100, 3]));
}

Get a read-write reference to the content of a double vector. Note that rust slices are 0-based so slice[1] is the middle value.

use extendr_api::prelude::*;
test! {
    let mut robj = r!([1.0, 2.0, 3.0]);
    let slice = robj.as_real_slice_mut().unwrap();
    slice[1] = 100.0;
    assert_eq!(robj, r!([1.0, 100.0, 3.0]));
}

Get a read-write reference to the content of a raw vector.

use extendr_api::prelude::*;
test! {
    let mut robj = r!(Raw::from_bytes(&[1, 2, 3]));
    let slice = robj.as_raw_slice_mut().unwrap();
    slice[1] = 100;
    assert_eq!(robj, r!(Raw::from_bytes(&[1, 100, 3])));
}

Get a vector of owned strings. Owned strings have long lifetimes, but are much slower than references.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   assert_eq!(robj1.as_string_vector(), Some(vec!["xyz".to_string()]));
   let robj2 = Robj::from(1);
   assert_eq!(robj2.as_string_vector(), None);
}

Get a vector of string references. String references (&str) are faster, but have short lifetimes.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   assert_eq!(robj1.as_str_vector(), Some(vec!["xyz"]));
   let robj2 = Robj::from(1);
   assert_eq!(robj2.as_str_vector(), None);
}

Get a read-only reference to a scalar string type.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   let robj2 = Robj::from(1);
   assert_eq!(robj1.as_str(), Some("xyz"));
   assert_eq!(robj2.as_str(), None);
}

Get a scalar integer.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from("xyz");
   let robj2 = Robj::from(1);
   let robj3 = Robj::from(NA_INTEGER);
   assert_eq!(robj1.as_integer(), None);
   assert_eq!(robj2.as_integer(), Some(1));
   assert_eq!(robj3.as_integer(), None);
}

Get a scalar real.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(1);
   let robj2 = Robj::from(1.);
   let robj3 = Robj::from(NA_REAL);
   assert_eq!(robj1.as_real(), None);
   assert_eq!(robj2.as_real(), Some(1.));
   assert_eq!(robj3.as_real(), None);
}

Get a scalar rust boolean.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(TRUE);
   let robj2 = Robj::from(1.);
   let robj3 = Robj::from(NA_LOGICAL);
   assert_eq!(robj1.as_bool(), Some(true));
   assert_eq!(robj2.as_bool(), None);
   assert_eq!(robj3.as_bool(), None);
}

Get a scalar boolean as a tri-boolean Bool value.

use extendr_api::prelude::*;
test! {
   let robj1 = Robj::from(TRUE);
   let robj2 = Robj::from([TRUE, FALSE]);
   let robj3 = Robj::from(NA_LOGICAL);
   assert_eq!(robj1.as_logical(), Some(TRUE));
   assert_eq!(robj2.as_logical(), None);
   assert_eq!(robj3.as_logical(), Some(NA_LOGICAL));
}

Evaluate the expression in R and return an error or an R object.

use extendr_api::prelude::*;
test! {

   let add = lang!("+", 1, 2);
   assert_eq!(add.eval().unwrap(), r!(3));
}

Evaluate the expression in R and return an error or an R object.

use extendr_api::prelude::*;
test! {

   let add = lang!("+", 1, 2);
   assert_eq!(add.eval_with_env(&global_env()).unwrap(), r!(3));
}

Evaluate the expression and return NULL or an R object.

use extendr_api::prelude::*;
test! {
   let bad = lang!("imnotavalidfunctioninR", 1, 2);
   assert_eq!(bad.eval_blind(), r!(NULL));
}

Get a specific attribute as a borrowed robj if it exists.

use extendr_api::prelude::*;
test! {

   let mut robj = r!("hello");
   robj.set_attrib(sym!(xyz), 1);
   assert_eq!(robj.get_attrib(sym!(xyz)), Some(r!(1)));
}

Set a specific attribute and return the object.

Note that some combinations of attributes are illegal and this will return an error.

use extendr_api::prelude::*;
test! {

   let mut robj = r!("hello").set_attrib(sym!(xyz), 1)?;
   assert_eq!(robj.get_attrib(sym!(xyz)), Some(r!(1)));
}

Get the names attribute as a string iterator if one exists.

use extendr_api::prelude::*;
test! {
   let list = list!(a = 1, b = 2, c = 3);
   let names : Vec<_> = list.names().unwrap().collect();
   assert_eq!(names, vec!["a", "b", "c"]);
}

Set the names attribute from a string iterator.

Returns Error::NamesLengthMismatch if the length of the names does not match the length of the object.

use extendr_api::prelude::*;
test! {
    let mut obj = r!([1, 2, 3]).set_names(&["a", "b", "c"]).unwrap();
    assert_eq!(obj.names().unwrap().collect::<Vec<_>>(), vec!["a", "b", "c"]);
    assert_eq!(r!([1, 2, 3]).set_names(&["a", "b"]), Err(Error::NamesLengthMismatch(r!(["a", "b"]))));
}

Get the dim attribute as an integer iterator if one exists.

use extendr_api::prelude::*;
test! {

   let array = R!(r#"array(data = c(1, 2, 3, 4), dim = c(2, 2), dimnames = list(c("x", "y"), c("a","b")))"#).unwrap();
   let dim : Vec<_> = array.dim().unwrap().iter().collect();
   assert_eq!(dim, vec![2, 2]);
}

Get the dimnames attribute as a list iterator if one exists.

use extendr_api::prelude::*;
test! {
   let array = R!(r#"array(data = c(1, 2, 3, 4), dim = c(2, 2), dimnames = list(c("x", "y"), c("a","b")))"#).unwrap();
   let names : Vec<_> = array.dimnames().unwrap().collect();
   assert_eq!(names, vec![r!(["x", "y"]), r!(["a", "b"])]);
}

Get the class attribute as a string iterator if one exists.

use extendr_api::prelude::*;
test! {
   let formula = R!("y ~ A * x + b").unwrap();
   let class : Vec<_> = formula.class().unwrap().collect();
   assert_eq!(class, ["formula"]);
}

Set the class attribute from a string iterator, returning a new object.

May return an error for some class names.

use extendr_api::prelude::*;
test! {
    let mut obj = r!([1, 2, 3]).set_class(&["a", "b", "c"])?;
    assert_eq!(obj.class().unwrap().collect::<Vec<_>>(), vec!["a", "b", "c"]);
    assert_eq!(obj.inherits("a"), true);
}

Return true if this class inherits this class.

use extendr_api::prelude::*;
test! {
   let formula = R!("y ~ A * x + b").unwrap();
   assert_eq!(formula.inherits("formula"), true);
}

Get the levels attribute as a string iterator if one exists.

use extendr_api::prelude::*;
test! {
   let factor = factor!(vec!["abcd", "def", "fg", "fg"]);
   let levels : Vec<_> = factor.levels().unwrap().collect();
   assert_eq!(levels, vec!["abcd", "def", "fg"]);
}

Convert a symbol object to a Symbol wrapper.

use extendr_api::prelude::*;
test! {
    let fred = sym!(fred);
    assert_eq!(fred.as_symbol(), Some(Symbol::from_string("fred")));
}

Convert a CHARSXP object to a Rstr wrapper.

use extendr_api::prelude::*;
test! {
    let fred = r!(Rstr::from_string("fred"));
    assert_eq!(fred.as_char(), Some(Rstr::from_string("fred")));
}

Convert a raw object to a Rstr wrapper.

use extendr_api::prelude::*;
test! {
    let bytes = r!(Raw::from_bytes(&[1, 2, 3]));
    assert_eq!(bytes.len(), 3);
    assert_eq!(bytes.as_raw(), Some(Raw::from_bytes(&[1, 2, 3])));
}

Convert a language object to a Language wrapper.

use extendr_api::prelude::*;
test! {
    let call_to_xyz = r!(Language::from_values(&[r!(Symbol::from_string("xyz")), r!(1), r!(2)]));
    assert_eq!(call_to_xyz.is_language(), true);
    assert_eq!(call_to_xyz.len(), 3);
    assert_eq!(format!("{:?}", call_to_xyz), r#"r!(Language::from_values([sym!(xyz), r!(1), r!(2)]))"#);
}

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

use extendr_api::prelude::*;
test! {
    let names_and_values = vec![("a", r!(1)), ("b", r!(2)), ("", r!(3))];
    let pairlist = Pairlist::from_pairs(names_and_values);
    let robj = r!(pairlist.clone());
    assert_eq!(robj.as_pairlist().unwrap(), pairlist);
}

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

use extendr_api::prelude::*;
test! {
    let list = r!(List::from_values(&[r!(0), r!(1), r!(2)]));
    assert_eq!(list.is_list(), true);
    assert_eq!(format!("{:?}", list), r#"r!(List::from_values([r!(0), r!(1), r!(2)]))"#);
}

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

use extendr_api::prelude::*;
test! {
    let expr = r!(Expression::from_values(&[r!(0), r!(1), r!(2)]));
    assert_eq!(expr.is_expression(), true);
    assert_eq!(expr.as_expression(), Some(Expression::from_values(vec![r!(0), r!(1), r!(2)])));
    assert_eq!(format!("{:?}", expr), r#"r!(Expression::from_values([r!(0), r!(1), r!(2)]))"#);
}

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

use extendr_api::prelude::*;
test! {
    let names_and_values = (0..100).map(|i| (format!("n{}", i), i));
    let env = Environment::from_pairs(global_env(), names_and_values);
    let expr = env.clone();
    assert_eq!(expr.len(), 100);
    let env2 = expr.as_environment().unwrap();
    assert_eq!(env2.len(), 100);
}

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

use extendr_api::prelude::*;
test! {
    let func = R!("function(a,b) a + b").unwrap();
    println!("{:?}", func.as_function());
}

Get a wrapper for a promise.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Make a wrapper behave like an Robj.

The resulting type after dereferencing.

Make a wrapper behave like a writable Robj.

Make an robj from a wrapper.

Convert a List into an interator, consuming the list.

use extendr_api::prelude::*;
test! {
    let list = list!(a=1, 2).as_list().unwrap();
    let vec : Vec<_> = list.into_iter().collect();
    assert_eq!(vec, vec![("a", r!(1)), ("", r!(2))]);
}

Which kind of iterator are we turning this into?

The type of the elements being iterated over.

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. Read more

Make a wrapper from a robj if it matches.

The type returned in the event of a conversion error.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

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

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.