extendr - A safe and user friendly R extension interface using Rust

Welcome

extendR is a suite of software packages, see the website extendR for an overview.

This repository is for the rust crates that are part of extendR, see also {rextendr} for the R-package that facilitates using extendR.

A complete user guide detailing how to use extendR is available here.

The main crate extendr-api is published on crates.io.

Getting started

There are many ways to use extendR from R. In an interactive R session one may use rextendr::rust_function and friends to quickly prototype Rust code.

In an R package context, one may use rextendr::use_extendr() to setup a Rust powered R-package. See also vignette on R-packages.

It is also possible to inline Rust code in RMarkdown/knitr, see vignette on extendr knitr-engine.

See rextendr package for more information on the available functionality from an R session.

Overview

It is intended to be easier to use than the C interface and Rcpp as Rust gives type safety and freedom from segfaults.

The following code illustrates a simple structure trait which is written in Rust. The data is defined in the struct declaration and the methods in the impl.

use extendr_api::prelude::*;

#[extendr]
struct Person {
    pub name: String,
}

#[extendr]
impl Person {
    fn new() -> Self {
        Self { name: "".to_string() }
    }

    fn set_name(&mut self, name: &str) {
        self.name = name.to_string();
    }

    fn name(&self) -> &str {
        self.name.as_str()
    }
}

#[extendr]
fn aux_func() {
}


// Macro to generate exports
extendr_module! {
    mod classes;
    impl Person;
    fn aux_func;
}

The #[extendr] attribute causes the compiler to generate wrapper and registration functions for R which are called when the package is loaded.

The extendr_module! macro lists the module name and exported functions and interfaces.

This library aims to provide an interface that will be familiar to first-time users of Rust or indeed any compiled language.

Goals of the project

Instead of wrapping R objects, we convert to Rust native objects on entry to a function. This makes the wrapped code clean and dependency free. The ultimate goal is to allow the wrapping of existing Rust libraries without markup, but in the meantime, the markup is as light as possible.

#[extendr]
pub fn my_sum(v: &[f64]) -> f64 {
    v.iter().sum()
}

You can interact in more detail with R objects using the Robj type which wraps the native R object type. This supports a large subset of the R internals functions, but wrapped to prevent accidental segfaults and failures.

Contributing

We are happy about any contributions!

To get started you can take a look at our Github issues.

You can also get in contact via our Discord server!

Development

The documentation for the latest development version of extendr-api is available here: https://extendr.github.io/extendr/extendr_api/