Expand description
A low-level libR binding library which is kept deliberately minimal.
In particular, it has no external dependencies other that libR installed on the target.
§Synopsis
The libR-sys
crate is a low level bindgen wrapper for the R
programming language. The intention is to allow one or more extension
mechanisms to be implemented for rust.
Effort to make the extension libraries platform-independent can be concentrated here.
§Examples
use libR_sys::{Rf_initialize_R, R_CStackLimit, setup_Rmainloop};
use std::os::raw;
unsafe {
std::env::set_var("R_HOME", "/usr/lib/R");
let arg0 = "R\0".as_ptr() as *mut raw::c_char;
Rf_initialize_R(1, [arg0].as_mut_ptr());
R_CStackLimit = usize::max_value();
setup_Rmainloop();
}
§Conditional compilation depending on R installation
The libR-sys crate provides these environmental variables that you can use in build.rs
:
DEP_R_R_VERSION_MAJOR
: The major part of the R version (e.g.4
in version4.1.0
)DEP_R_R_VERSION_MINOR
: The minor part of the R version (e.g.1
in version4.1.0
)DEP_R_R_VERSION_PATCH
: The patch part of the R version (e.g.0
in version4.1.0
)DEP_R_R_VERSION_DEVEL
:true
if the R is a development version, otherwisefalse
DEP_R_R_VERSION_STRING
: The full version string (e.g.R version 4.1.0 (2021-05-18)
)DEP_R_R_HOME
: The R home directory
§Example build.rs
ⓘ
use std::env;
fn main() {
// Set R_HOME envvar, and refer to it on compile time by env!("R_HOME")
let r_home = env::var("DEP_R_R_HOME").unwrap();
println!("cargo:rustc-env=R_HOME={}", r_home);
// Enable cfg setting to conditionally compile a code using a feature
// available only on newer versions of R
let major = env::var("DEP_R_R_VERSION_MAJOR").unwrap();
let minor = env::var("DEP_R_R_VERSION_MINOR").unwrap();
if &*major >= "4" && &*minor >= "1" {
println!("cargo:rustc-cfg=use_a_feature");
}
}
Structs§
- These are very similar to those in Rdynpriv.h, but we maintain them separately to give us more freedom to do some computations on the internal versions that are derived from these definitions.
- A structure containing graphical parameters
- try to allow some type checking
- R 4.3 redefined
Rcomplex
to a union for compatibility with Fortran. But the old definition is compatible both the union version and the struct version. See: https://github.com/extendr/extendr/issues/524
Enums§
- The graphics engine will only accept locations and dimensions in native device coordinates, but it provides the following functions for converting between a couple of simple alternative coordinate systems and device coordinates: DEVICE = native units of the device NDC = Normalised device coordinates INCHES = inches (!) CM = centimetres (!!)
- Different kinds of “N(0,1)” generators :
- PARSE_NULL will not be returned by R_ParseVector
- Some line end/join constants
- These give the indices of some known keys
- These are the three possible mouse events
- —— enum_SEXPTYPE —–
- Different ways to generate discrete uniform samples
- ALTREP sorting support
- cetype_t is an identifier reseved by POSIX, but it is well established as public. Could remap by a #define though
- ../main/character.c :
Constants§
Statics§
- “as.character”
- “@”
- The base environment; formerly R_NilValue
- The (fake) namespace for base
- “base”
- “” as a STRSXP
- “” as a CHARSXP
- “{”
- “[[”
- “[”
- C stack limit
- “class”
- Use current expression (marker)
- “.Device”
- “dimnames”
- “dim”
- “$”
- “…”
- “::”
- “drop”
- An empty environment at the root of the environment tree
- “eval”
- “function”
- The “global” environment
- To be found in BC interp. state (marker)
- “.Last.value”
- “levels”
- Missing argument marker
- “mode”
- NA_INTEGER:= INT_MIN currently
- IEEE NaN
- NA_REAL: IEEE
- “na.rm”
- NA_STRING as a CHARSXP
- “name”
- “names”
- “.NAMESPACE.”
- Registry for registered namespaces
- IEEE -Inf
- The nil object
- “package”
- IEEE Inf
- “previous”
- “quote”
- Marker for restarted function calls
- “row.names”
- “.Random.seed”
- “sort.list”
- “source”
- “spec”
- Current srcref, for debuggers
- “:::”
- “tsp”
- Unbound marker
- <– backcompatible version of:
- “.Generic”
- “.Method”
- “.defined”
- “.packageName”
- “.target”
Functions§
- ALTREP support
- General Cons Cell Attributes
- BODY⚠
- CAAR⚠
- CADR⚠
- CAR⚠
- CDAR⚠
- CDDR⚠
- CDR⚠
- External pointer access macros
- Closure Access Functions
- From plotmath.c
- From plot3d.c : used in package clines
- metadata access
- S4 object testing
- Vector Access Functions
- MARK⚠
- Symbol Access Functions
- RAW⚠
- RAW0⚠
- REAL⚠
- Check for an available device slot
- ../../main/util.c and others :
- From vfonts.c
- Patterns - from ../../main/patterns.c
- Raster operations
- Convert either a name or a #RRGGBB[AA] string to internal. Because people were using it, it also converts “1”, “2” … to a colour in the palette, and “0” to transparent white.
- srcref related functions
- NA_STRING is a SEXP, so defined in Rinternals.h
- External pointer interface
- Added in R 3.4.0
- Weak reference interface
- Environment and Binding Features
- preserve objects across GCs
- Interface for exporting and importing functions from one package for use from C code in a package. The registration part probably ought to be integrated with the other registrations. The naming of these routines may be less than ideal.
- S3-S4 class (inheritance), attrib.c
- Protected evaluation
- public C interface
- These two are guaranteed to use ‘.’ as the decimal point, and to accept “NA”. Documented since 4.4.0 patched.
- supporting a C-level version of is(., .) :
- S Like Memory Management
- class definition, new objects (objects.c)
- slot management (in attrib.c)
- Shutdown actions
- Calling a function with arguments evaluated
- R_gc⚠
- To be used by applications embedding R to register their symbols that are not related to any dynamic module
- ../../main/sort.c :
- ../../appl/maxcol.c
- C version of R’s indx <- order(…, na.last, decreasing) : e.g. arglist = Rf_lang2(x,y) or Rf_lang3(x,y,z)
- C version of R’s indx <- order(x, na.last, decreasing) :
- R’s versions with !R_FINITE checks
- appl/pretty.c: for use in engine.c and util.c
- ../../main/qsort.c : / / dummy renamed to II to avoid problems with g++ on Solaris
- vectorizing function f(x[1:n], …) -> x[] {overwriting x[]}.
- Useful for devices: translates Adobe symbol encoding to UTF-8
- How many devices exist ? (>= 1)
- Convert an element of a R colour specification (which might be a number or a string) into an internal colour specification.
- this group is not API
- Other Internally Used Functions, excluding those which are inline-able
- These are the public inlinable functions that are provided in Rinlinedfuns.h It is essential that these do not appear in any other header file, with or without the Rf_ prefix.
- Type Coercions of all kinds
- Bessel Functions
- Convert an internal colour specification to/from a colour name
- Return the number of the current device.
- Beta Distribution
- Binomial Distribution
- Cauchy Distribution
- Chi-squared Distribution
- map DevDesc to enclosing GEDevDesc
- Exponential Distribution
- F Distribution
- Gamma Distribution
- Geometric Distribution
- Hypergeometric Distribution
- Lognormal Distribution
- Logistic Distribution
- Non-central Beta Distribution
- Negative Binomial Distribution
- Non-central Chi-squared Distribution
- Non-central F Distribution
- Normal Distribution
- Non-central Student t Distribution
- Poisson Distribution
- Wilcoxon Signed Rank Distribution
- Student t Distribution
- Uniform Distribution
- the next really should not be here and is also in Defn.h
- Weibull Distribution
- Wilcoxon Rank Sum Distribution
- ../main/errors.c : / / needed for R_load/savehistory handling in front ends
- Gamma and Related Functions
- General Support Functions
- Various tests with macro versions in the internal headers
- Kill device which is identified by number.
- Compute the log of a sum or difference from logs of terms, i.e.,
- Properly declared version of devNumber
- Return the number of the next device.
- Return the number of the previous device.
- Studentized Range Distribution
- Multinomial Distribution
- Make the specified device (specified by number) the current device
- Non-API, attribute_hidden and no longer used. Will be removed in R 4.5.0.
- Translates Unicode point to UTF-8
- TAG⚠
- SEXP (STRING_ELT)(SEXP x, R_xlen_t i);
- ../../appl/interv.c: first also in Applic.h
- not API, entry point no longer exists
- Random Number Generators
- Also used in packages nlme, pcaPP
Type Aliases§
- Called with a variable argument set after casting to a compatible function pointer.
- ——— New (in 1.4.0) device driver structure ——— NOTES:
- We sometimes need to coerce a protected value and place the new coerced value under protection. For these cases PROTECT_WITH_INDEX saves an index of the protection location that can be used to replace the protected value using REPROTECT.
- Finalization interface
- These are very similar to those in Rdynpriv.h, but we maintain them separately to give us more freedom to do some computations on the internal versions that are derived from these definitions.
- type for length of (standard, not long) vectors etc
- R_xlen_t is defined as int on 32-bit platforms, and that confuses Rust. Keeping it always as ptrdiff_t works fine even on 32-bit.
- type of pointer to the hessian functions
- type of pointer to the target and gradient functions
- ../../appl/integrate.c
- main/optim.c