index.qmd

---
title: ""
---

::: {style="margin:0; width: 100%;"}
::: {style="margin:0; width: 81%; float: left;"}

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

:::

::: {style="margin: 0.25rem 0 0 0; width: 19%; float: right;"}
![](images/extendr-logo-256.png){width="100%" fig-alt="rextendr logo"}
:::
:::

[![Github Actions Build
Status](https://github.com/extendr/extendr/workflows/Tests/badge.svg)](https://github.com/extendr/extendr/actions)
[![Crates.io](https://img.shields.io/crates/v/extendr-api.svg)](https://crates.io/crates/extendr-api)
[![Documentation](https://docs.rs/extendr-api/badge.svg)](https://docs.rs/extendr-api)
[![License:
MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The extendr suite of software packages provides a Rust extension mechanism for
R, thus bringing the computing power of Rust to the statistical programming
environment of R. The following code provides a simple illustration of how
extendr achieves this.

``` rust
use extendr_api::prelude::*;

#[derive(Debug)]
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 my_function() { }

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

The `#[extendr]` attribute causes the compiler to generate wrapper and
registration functions for R which are called when the package is loaded, thus
allowing one to access Rust functions and structures in an R session:

``` r
# call function
my_function()

# create Person object
p <- Person$new()
p$set_name("foo")
p$name()   # "foo" is returned
```

This, of course, is just the tip of the iceberg, for there are many ways to use
extendr in R:

- In an interactive R session one may use [`rextendr::rust_function` and
    friends](https://extendr.github.io/rextendr/reference/rust_source.html) to
    quickly prototype Rust code.

- In an R package context, one may use
    [`rextendr::use_extendr()`](https://extendr.github.io/rextendr/reference/use_extendr.html)
    to setup a Rust powered R-package. See also the [vignette on
    R-packages](https://extendr.github.io/rextendr/articles/package.html).

- It is also possible to inline Rust code in `Quarto` documents, see
    [vignette on extendr
    `knitr-engine`](https://extendr.github.io/rextendr/articles/rmarkdown.html).

## Software Overview

The software packages that make up extendr include:

- Rust crates:
  - [`extendr-api`](https://extendr.github.io/extendr/extendr_api) -
        provides the ergonomic, opinionated, and safe interface to R in Rust
  - [`extendr-macros`](https://extendr.github.io/extendr/extendr_macros) -
        crate responsible generation of wrappers, derive macros for conversion to R, etc.
  - [`extendr-engine`](https://extendr.github.io/extendr/extendr_engine) -
        crate that enables launching R sessions from Rust code;
- An R package [`rextendr`](https://extendr.github.io/rextendr) that helps
    scaffolding extendr-enabled packages or compiling Rust code interactively; and
- [`libR-sys`](https://extendr.github.io/libR-sys/libR_sys) - provides
    auto-generated bindings to R's C-facilities (or C-API) in Rust