8. Renjin Java API specification¶

This chapter includes a selection of public classes and methods in some of Renjin’s Java packages which are most useful to users of Renjin looking to exchange data between Java and R code. The java docs for renjin is available as http://javadoc.renjin.org/.

8.1. org.renjin.sexp¶

The org.renjin.sexp package contains Renjin’s classes that represent the different object types in R.

8.1.1. AttributeMap¶

class AttributeMap¶

Renjin’s implementation to store object attributes. See the Attributes section for a short introduction to attributes on objects in R.

SEXP getClassVector()¶

See hasClass for an example.

Returns:	a character vector of classes or `null` if no `class` attribute is defined

Vector getDim()¶

Returns:	the `dim` attribute as a `Vector` or `null` if no dimension is defined

AtomicVector getNamesOrNull()¶

Returns:	the `names` attribute as a `AtomicVector` or `null` if no names are defined

boolean hasClass()¶

Returns:	`true` if the `class` attribute exists, `false` otherwise

Example:

Vector df = (Vector)engine.eval("df <- data.frame(x = seq(5), y = runif(5))");
AttributeMap attributes = df.getAttributes();
if (attributes.hasClass()) {
    System.out.println("Classes defined on 'df': " +
        (Vector)attributes.getClassVector());
}

Output:

Classes defined on 'df': "data.frame"

ListVector toVector()¶

Convert the object’s attributes to a list.

Returns:	attributes as a `ListVector`

8.1.2. ListVector¶

class ListVector extends AbstractVector¶

Renjin’s class that represent R lists and data frames. Data frames are lists with the restriction that all elements, which are atomic vectors, have the same length.

SEXP getElementAsSEXP(int index)¶

Parameters:	index – zero-based index
Returns:	a `SEXP` that can be cast to a vector type

Vector getElementAsVector(String name)¶

Convenience method to get the named element of a list. See the section Dealing with lists and data frames for an example.

Parameters:	name – element name as string
Returns:	a `Vector`

int indexOfName(String name)¶

Parameters:	name – element name as string
Returns:	zero-based index of `name` in the names attribute, -1 if `name` is not present in the names attribute or if the names attribute is not set

boolean isElementNA(int index)¶

Check if an element of a list is NA.

Parameters:	index – zero-based index
Returns:	`true` if the element at position `index` is an `NA`, false otherwise

8.1.3. Logical¶

enum Logical¶

A logical value in R can be TRUE, FALSE, or the logical NA.

static Logical valueOf(boolean b)¶

Turn a Java boolean into an R logical value.

Parameters:	b – `true` or `false`
Returns:	R’s `TRUE` or `FALSE` as Renjin’s representation of a logical value

static Logical valueOf(int i)¶

Turn an integer into an R logical value.

Parameters:	i – an integer value
Returns:	`TRUE` if `i` is 1, `FALSE` if `i` is 0, or (logical) `NA` otherwise

8.1.4. SEXP¶

interface SEXP¶

Renjin’s superclass for all objects that are mapped from R’s object types.

AttributeMap getAttributes()¶

Get the attributes of an object as a AttributeMap which is Renjin’s way of working with object attributes. R stores attributes as pairlists which are essentially the same as generic lists, therefore these attributes can safely be stored in a list. Renjin provides a toVector() method to do just that.

Returns:	the attributes for the object as a, possibly empty, `AttributeMap`

Example:

ListVector res = (ListVector)engine.eval(
        "list(name = \"Jane\", age = 23, scores = c(6, 7, 8, 9))");
    // use ListVector.toString() method to display the list:
    System.out.println(res);
    if (res.hasAttributes()) {
        AttributeMap attributes = res.getAttributes();
        // convert the attribute map to something more convenient:
        ListVector attributeList = attributes.toVector();
        System.out.println("The list has "
            + attributeList.length() + " attribute(s)");
    }

Output:

list(name = "Jane", age = 23.0, scores = c(6, 7, 8, 9))
The list has 1 attribute(s)

String getTypeName()¶

Get the type of the object as it is known in R, i.e. the result of R’s typeof() function.

Returns:	the object type as a string

Example:

Vector x = (Vector)engine.eval("NA");
System.out.println("typeof(NA) = " + x.getTypeName());

Output:

typeof(NA) = logical

boolean hasAttributes()¶

Check for the presence of attributes. See getAttributes for an example.

Returns:	`true` if the object has at least one attribute, `false` otherwise

int length()¶

Get the length of the object. All objects in R have a length and this method gives the same result as R’s length() function. Functions always have length 1 and the NULL object always has length 0. The length of an environment is equal to the number of objects inside the environment.

Returns:	length of the vector as an integer

8.1.5. Vector¶

interface Vector extends SEXP ¶

An interface which represents all vector object types in R: atomic vectors and generic vectors (i.e. Lists).

double getElementAsDouble(int index)¶

Parameters:	index – zero-based index
Returns:	the element at `index` as a double, converting if necessary; `NaN` if no conversion is possible

Example:

// create a string vector in R:
Vector x = (Vector)engine.eval("c(\"foo\", \"bar\")");
double x1 = x.getElementAsDouble(0);
if (Double.isNaN(x1)) {
    System.out.println("Result is NaN");
}
String s = x.getElementAsString(0);
System.out.println("First element of result is " + s);
// call the toString() method of the underlying StringArrayVector:
System.out.println("Vector as defined in R: " + x);

Output:

Result is NaN
First element of result is foo
Vector as defined in R: c(foo, bar)

Note

All of the classes that implement the Vector interface have a toString() method that will display (a short form of) the content of the vector. This method is provided for debugging purposes only.

int getElementAsInt(int index)¶

Parameters:	index – zero-based index
Returns:	the element at `index` as an integer, converting if necessary; `NaN` if no conversion is possible

String getElementAsString(int index)¶

Parameters:	index – zero-based index
Returns:	the element at `index` as a string

Logical getElementAsLogical(int index)¶

Parameters:	index – zero-based index
Returns:	the element at `index` as Renjin’s representation of a boolean value

8.2. org.renjin.primitives.matrix¶

8.2.1. Matrix¶

class Matrix¶

Wrapper class for a Vector with two dimensions. Simplifies interaction with R matrices from Java code.

Matrix(Vector vector)¶

Constructor for creating a matrix from a Vector. Checks if the dimension attribute is present and has length 2, throws an IllegalArgumentException if not. See the section Dealing with matrices for an example.

Parameters:	vector – a vector with two dimensions
Throws:	IllegalArgumentException – if the `dim` attribute of `vector` does not have length 2

int getNumRows()¶

Returns:	number of rows in the matrix

int getNumCols()¶

Returns:	number of columns in the matrix

8.3. Exceptions¶

class ParseException extends RuntimeException ¶: An exception thrown by Renjin’s parser when there is an error in parsing R code, usually due to a syntax error. See Handling errors generated by the R code for an example that catches this exception.

class EvalException extends RuntimeException ¶

An exception thrown by Renjin’s interpreter when the R code generates an error condition, e.g. by the stop() function. See Handling errors generated by the R code for an example that catches this exception.

SEXP getCondition()¶

Returns:	a `SEXP` that is a list with a single named element `message`. Use `getElementAsString()` to obtain the actual error message.