embedr.r

This module provides an interface to the R API. It allows you to write D functions that can be called from R and also provides support for embedding an R interpreter inside a D program. That means you have access to all R libraries from within a D program. Data is passed between the two languages using pointers. This modules defines structs that handle protecting/unprotecting data from the R garbage collector.

This file contains everything you need to create a shared library on Linux or Mac that can be called from R. On Windows, you will also need the R.lib file provided inside the repo.

Members

Aliases

Robj
alias Robj = sexprec*

All data in R is stored in an opaque struct called sexprec. Data is passed around as pointers to sexprec structs called SEXP. That's an unfortunate name (it stands for s-expression because R started out as a Scheme dialect) so I use Robj instead.

Functions

assertR
void assertR(bool test, string msg)

For use inside D functions called from R.

createRLibrary
string createRLibrary(string name)

This function adds the boilerplate needed inside a shared library that will be called from R.

dbeta
double dbeta(double x, double shape1, double shape2, int give_log)

Unless otherwise noted from here down, if the argument * name is the same as it is in R, the argument is the same. * Some R arguments are not available in C

dexp
double dexp(double x, double scale, int give_log)

scale = 1/rate

dgamma
double dgamma(double x, double shape, double scale, int give_log)

These do not allow for passing argument rate as in R Confirmed that otherwise you call them the same as in R

dnbeta
double dnbeta(double x, double shape1, double shape2, double ncp, int give_log)

Use these if you want to set ncp as in R

dnorm4
double dnorm4(double x, double mu, double sigma, int give_log)

Same arguments as the R functions

dunif
double dunif(double x, double a, double b, int give_log)

Same arguments as the R functions

dup
RMatrix dup(RMatrix rm)

Create a copy of a matrix.

evalR
Robj evalR(string cmd)

For embedding an R interpreter inside D.

evalRQ
void evalRQ(string cmd)

For embedding an R interpreter inside D.

evalRQ
void evalRQ(string[] cmds)

For embedding an R interpreter inside D.

expm1
double expm1(double)

Calculate exp(x)-1 for small x

fprec
double fprec(double x, double digits)

R's signif() function

fromLast
double fromLast(RVector rv, int ii)

Returns element ii from the bottom.

fround
double fround(double x, double digits)

R's round() function

fsign
double fsign(double x, double y)

|x|*sign(y) Gives x the same sign as y

ftrunc
double ftrunc(double x)

Truncate towards zero

getAttrib
Robj getAttrib(Robj x, string attr)
Robj getAttrib(ProtectedRObject x, string attr)
Robj getAttrib(Robj x, RString attr)
Robj getAttrib(ProtectedRObject x, RString attr)

Not normally called unless you're working on the embedr library itself.

isInteger
bool isInteger(Robj x)

Returns true if x holds a vector of integers.

isMatrix
bool isMatrix(Robj x)

Returns true if x holds a matrix.

isNumeric
bool isNumeric(Robj x)

Returns true if x holds a vector of integers or doubles.

isVector
bool isVector(Robj x)

Returns true if x is a vector object.

last
double last(RVector rv)

Returns the last element of an RVector.

length
int length(Robj x)

All R objects have a length attribute. You can call this function on any R object and it will return a value. The most common usage is to get the length of a vector, but it can be called on anything.

log1p
double log1p(double)

Calculate log(1+x) for small x

names
string[] names(Robj x)

If x has a names attribute attached to it, this function will copy the names into a string[].

print
void print(RMatrix m, string msg = "")

Print a matrix, with an optional message.

printR
void printR(Robj x)
void printR(ProtectedRObject x)
void printR(string s)

Tells the R interpreter to print something out. This is generally useful only if you want to use the formatting provided by R. Most of the time, want to do your printing from D.

robj
Robj robj(double x)

Creates a new R object with room for one double value and copies x into it.

robj
Robj robj(double[] v)

Creates a new R object with room to hold v.length double values and copies v into it.

robj
Robj robj(int x)

Creates a new R object with room for one int value and copies x into it.

robj
Robj robj(string s)

Creates a new R object with room for one string and copies s into it.

robj
Robj robj(string[] sv)

Creates a new R object with room to hold sv.length strings and copies sv into it.

scalar
double scalar(Robj rx)
double scalar(Robj rx)

Pull the value out of an R object holding one double value.

scalar
int scalar(Robj rx)

Pull the value out of an R object holding one int value.

scalar
long scalar(Robj rx)

Pull the value out of an R object holding one int value.

scalar
ulong scalar(Robj rx)

Pull the value out of an R object holding one int value.

scalar
string scalar(Robj rx)

Pull the value out of an R object holding one string.

scalar
double scalar(string name)
double scalar(string name)

Convenience function to pull a double value out of R. Only used when embedding an R interpreter inside a D program.

scalar
int scalar(string name)

Convenience function to pull an int value out of R. Only used when embedding an R interpreter inside a D program.

scalar
long scalar(string name)

Convenience function to pull an int value out of R. Only used when embedding an R interpreter inside a D program.

scalar
ulong scalar(string name)

Convenience function to pull an int value out of R. Only used when embedding an R interpreter inside a D program.

scalar
string scalar(string name)

Convenience function to pull a string out of R. Only used when embedding an R interpreter inside a D program.

setAttrib
void setAttrib(Robj x, string attr, ProtectedRObject val)
void setAttrib(Robj x, RString attr, ProtectedRObject val)
void setAttrib(Robj x, string attr, Robj val)
void setAttrib(Robj x, RString attr, Robj val)

Not normally called unless you're working on the embedr library itself.

sign
double sign(double x)

Returns 1 for positive, 0 for zero, -1 for negative

source
void source(string s)

Tells R to source the file s.

stringArray
string[] stringArray(Robj sv)

Copies a string array from a character vector in R into a D string array.

stringArray
string[] stringArray(string name)

Convenience function to pull the character vector name from R into D.

toR
void toR(T x, string name)
void toR(Robj x, string name)
void toR(string[] s, string name)

When embedding an R interpreter inside D, this function passes data from D to R, copying as necessary.

toString
string toString(Robj cstr)

Copies a string allocated in R into a D string.

toString
string toString(Robj sv, int ii)

Copies a string allocated in R from a character vector into a D string.

tsp
ulong[3] tsp(Robj rv)

Returns the time series properties of an R object. If rv is not a ts object, will throw an error.

Structs

ProtectedRObject
struct ProtectedRObject

Enables reference counting of objects allocated by R. It takes care of protecting and unprotecting objects from the R garbage collector.

RIntVector
struct RIntVector

Same as RVector, but holds a vector of integers instead of a vector of doubles.

RList
struct RList

The most common way to pass multiple pieces of data in R is by putting them into a list. If you pass a list from R to D, you need some way to work with that data. If you want to return multiple items from D to R, the only way to do that is with a list.

RMatrix
struct RMatrix

This struct is used to work with a matrix that has been allocated in R. A pointer to the data is held, along with the dimensions. An RMatrix struct is reference counted to take care of protecting it from the R garbage collector while in use, and unprotecting when it is no longer used, as necessary.

RObjectStorage
struct RObjectStorage

Enables reference counting of objects allocated by R. It takes care of protecting and unprotecting objects from the R garbage collector.

RString
struct RString

Support for passing strings from D to R and vice versa.

RVector
struct RVector

This struct is used to work with a vector that has been allocated in R. A pointer to the data is held, along with the dimensions. An RVector struct is reference counted to take care of protecting it from the R garbage collector while in use, and unprotecting when it is no longer used, as necessary.

sexprec
struct sexprec

All data in R is stored in an opaque struct called sexprec. Data is passed around as pointers to sexprec structs called SEXP. That's an unfortunate name (it stands for s-expression because R started out as a Scheme dialect) so I use Robj instead.

Variables

M_E
double M_E;

Constants pulled from the R API, for compatibility

Meta

Authors

Lance Bachmeier