extendr-api
extendr-api
is an opinionated, ergonomic, and safe interface to R API.
Installation
Simply add this line to the [dependencies]
section of your Cargo.toml
.
You will then be able to call R code from Rust.
[]
= "0.8.0"
About
On the extendr homepage there is a comprehensive user-guide.
The API documentation on doc.rs, and for development API documentation.
Overview
See Robj
for much of the content of this crate.
Robj
provides a safe wrapper for the R object type.
Use attributes and macros to export to R.
For a module named mymodule
(typically in a file named mymodule.rs
)
use *;
// Export a function or impl to R.
// define exports using extendr_module
extendr_module!
In R:
result <- fred
Robj
is a wrapper for R objects.
The r!()
and R!()
macros let you build R objects
using Rust and R syntax respectively.
use *;
test!
In Rust, we prefer to use iterators rather than loops.
use *;
test!
To index a vector, first convert it to a slice and then remember to use 0-based indexing. In Rust, going out of bounds will cause and error (a panic) unlike C++ which may crash.
use *;
test!
Much slower, but more general are these methods:
use *;
test!
The R!
macro lets you embed R code in Rust
and takes Rust expressions in {{ }}
pairs.
The Rraw!
macro will not expand the {{ }}
pairs.
use *;
test!
The r!
macro converts a rust object to an R object
and takes parameters.
use *;
test!
You can call R functions and primitives using the call!
macro.
use *;
test!
Rust has a concept of "Owned" and "Borrowed" objects.
Owned objects, such as Vec
and String
allocate memory
which is released when the object lifetime ends.
Borrowed objects such as &[i32]
and &str
are fat pointers
to another object's memory and can't live longer than the
object they reference.
Borrowed objects are much faster than owned objects and use less memory but are used only for temporary access.
When we take a slice of an R vector, for example, we need the original R object to be alive or the data will be corrupted.
use *;
test!
Feature gates
extendr-api has some optional features behind these feature gates:
ndarray
: provides the conversion between R's matrices andndarray
.num-complex
: provides the conversion between R's complex numbers andnum-complex
.serde
: provides theserde
support.graphics
: provides the functionality to control or implement graphics devices.either
: provides implementation of type conversion traits forEither<L, R>
fromeither
ifL
andR
both implement those traits.faer
: provides conversion between R's matrices andfaer
.
extendr-api has different encodings (conversions) of a Result<T,E>
into an Robj
.
In below x_ok
represents an R variable on R side which was returned from rust via T::into_robj()
or similar.
Likewise x_err
was returned to R side from rust via E::into_robj()
or similar.
extendr-api
result_list'
Ok(T)
is encoded aslist(ok = x_ok, err = NULL)
andErr
aslist(ok = NULL, err = e_err)
result_condition'
Ok(T)
is encoded asx_ok
andErr(E)
ascondition(msg="extendr_error", value = x_err, class=c("extendr_error", "error", "condition"))
- Multiple of above result feature gates. Only one result feature gate will take effect, the precedence is currently [
result_list
,result_condition
, ... ].
Finally, there are parts of R's API that are deemed non-API, in that R packages
on CRAN are recommended not to have these available in packages. If you want
to have access to them, you may use the non-api
feature to expose them.
License
MIT