6. 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.

6.1. org.renjin.sexp

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

6.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

6.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

6.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:
  • btrue 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

6.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

6.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

6.2. org.renjin.primitives.matrix

6.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

6.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.