rust_source: Compile Rust code and call from R

In rextendr: Call Rust Code from R using the 'extendr' Crate

Compile Rust code and call from R

Description

rust_source() compiles and loads a single Rust file for use in R. rust_function() compiles and loads a single Rust function for use in R.

Usage

rust_source(
  file,
  code = NULL,
  module_name = "rextendr",
  dependencies = NULL,
  patch.crates_io = getOption("rextendr.patch.crates_io"),
  profile = c("dev", "release", "perf"),
  toolchain = getOption("rextendr.toolchain"),
  extendr_deps = NULL,
  features = NULL,
  env = parent.frame(),
  use_extendr_api = TRUE,
  generate_module_macro = TRUE,
  cache_build = TRUE,
  quiet = FALSE,
  use_rtools = TRUE,
  use_dev_extendr = FALSE
)

rust_function(
  code,
  extendr_fn_options = NULL,
  env = parent.frame(),
  quiet = FALSE,
  use_dev_extendr = FALSE,
  ...
)

Arguments

file	Input rust file to source.
code	Input rust code, to be used instead of file.
module_name	Name of the module defined in the Rust source via ⁠extendr_module!⁠. Default is "rextendr". If generate_module_macro is FALSE or if file is specified, should match exactly the name of the module defined in the source.
dependencies	Character vector of dependencies lines to be added to the Cargo.toml file.
patch.crates_io	Character vector of patch statements for crates.io to be added to the Cargo.toml file.
profile	Rust profile. Can be either "dev", "release" or "perf". The default, "dev", compiles faster but produces slower code.
toolchain	Rust toolchain. The default, NULL, compiles with the system default toolchain. Accepts valid Rust toolchain qualifiers, such as "nightly", or (on Windows) "stable-msvc".
extendr_deps	Versions of ⁠extendr-*⁠ crates. Defaults to rextendr.extendr_deps option (list(`extendr-api` = "*")) if use_dev_extendr is not TRUE, otherwise, uses rextendr.extendr_dev_deps option (list(`extendr-api` = list(git = "https://github.com/extendr/extendr")).
features	A vector of extendr-api features that should be enabled. Supported values are "ndarray", "num-complex", "serde", and "graphics". Unknown features will produce a warning if quiet is not TRUE.
env	The R environment in which the wrapping functions will be defined.
use_extendr_api	Logical indicating whether ⁠use extendr_api::prelude::*;⁠ should be added at the top of the Rust source provided via code. Default is TRUE. Ignored for Rust source provided via file.
generate_module_macro	Logical indicating whether the Rust module macro should be automatically generated from the code. Default is TRUE. Ignored for Rust source provided via file. The macro generation is done with make_module_macro() and it may fail in complex cases. If something doesn't work, try calling make_module_macro() on your code to see whether the generated macro code has issues.
cache_build	Logical indicating whether builds should be cached between calls to rust_source().
quiet	Logical indicating whether compile output should be generated or not.
use_rtools	Logical indicating whether to append the path to Rtools to the PATH variable on Windows using the RTOOLS40_HOME environment variable (if it is set). The appended path depends on the process architecture. Does nothing on other platforms.
use_dev_extendr	Logical indicating whether to use development version of extendr. Has no effect if extendr_deps are set.
extendr_fn_options	A list of extendr function options that are inserted into ⁠#[extendr(...)]⁠ attribute
...	Other parameters handed off to rust_source().

Value

The result from dyn.load(), which is an object of class DLLInfo. See getLoadedDLLs() for more details.

Examples

## Not run: 
# creating a single rust function
rust_function("fn add(a:f64, b:f64) -> f64 { a + b }")
add(2.5, 4.7)

# creating multiple rust functions at once
code <- r"(
#[extendr]
fn hello() -> &'static str {
    "Hello, world!"
}

#[extendr]
fn test( a: &str, b: i64) {
    rprintln!("Data sent to Rust: {}, {}", a, b);
}
)"

rust_source(code = code)
hello()
test("a string", 42)


# use case with an external dependency: a function that converts
# markdown text to html, using the `pulldown_cmark` crate.
code <- r"(
  use pulldown_cmark::{Parser, Options, html};

  #[extendr]
  fn md_to_html(input: &str) -> String {
    let mut options = Options::empty();
    options.insert(Options::ENABLE_TABLES);
    let parser = Parser::new_ext(input, options);
    let mut output = String::new();
    html::push_html(&mut output, parser);
    output
  }
)"
rust_source(
  code = code,
  dependencies = list(`pulldown-cmark` = "0.8")
)

md_text <- "# The story of the fox
The quick brown fox **jumps over** the lazy dog.
The quick *brown fox* jumps over the lazy dog."

md_to_html(md_text)

## End(Not run)

rextendr documentation built on July 9, 2023, 5:54 p.m.