org.rosuda.JRI
Class REXP

java.lang.Object
  org.rosuda.JRI.REXP

public class REXP
extends java.lang.Object

This class encapsulates and caches R objects as returned from R. Currently it only converts certain SEXPs references from R into Java obejcts, but eventually bi-directional support should be added. The currently supported objects are string, integer and numeric vectors. All other types can be accessed only using xp reference and RNI methods.

Field Summary

static int	ANYSXP
static int	BCODESXP
static int	BUILTINSXP
static int	CHARSXP
static int	CLOSXP
static int	CPLXSXP
static int	DOTSXP
static int	ENVSXP
static int	EXPRSXP
static int	EXTPTRSXP
static int	FUNSXP
static int	INTSXP
static int	LANGSXP
static int	LGLSXP
static int	LISTSXP
static int	NILSXP
static int	PROMSXP
static int	RAWSXP
static int	REALSXP
int	rtype native type of the represented expression (see ...SXP constants in R).
static int	S4SXP
static int	SPECIALSXP
static int	STRSXP
static int	SYMSXP
static int	VECSXP
static int	WEAKREFSXP
long	xp native reference to the SEXP represented in R.
static int	XT_ARRAY_BOOL xpression type: RBool[]
static int	XT_ARRAY_BOOL_INT xpression type: int[] to be interpreted as boolean
static int	XT_ARRAY_BOOL_UA internal use only!
static int	XT_ARRAY_DOUBLE xpression type: double[]
static int	XT_ARRAY_INT xpression type: int[]
static int	XT_ARRAY_STR xpression type: String[] (currently not used, Vector is used instead)
static int	XT_BOOL xpression type: RBool
static int	XT_CLOS xpression type: closure (there is no java class for that type (yet?).
static int	XT_DOUBLE xpression type: double
static int	XT_FACTOR xpression type: RFactor; this XT is internally generated (ergo is does not come from Rsrv.h) to support RFactor class which is built from XT_ARRAY_INT
static int	XT_INT xpression type: integer
static int	XT_LANG xpression type: language construct (currently content is same as list)
static int	XT_LIST xpression type: RList
static int	XT_NONE xpression type: pure reference, no internal type conversion performed
static int	XT_NULL xpression type: NULL
static int	XT_STR xpression type: String
static int	XT_SYM xpression type: symbol (content is symbol name: String)
static int	XT_UNKNOWN xpression type: unknown; no assumptions can be made about the content
static int	XT_VECTOR xpression type: Vector

Constructor Summary

REXP()
construct a new, empty (NULL) expression w/o attribute

REXP(boolean[] val)
construct new expression with the contents of a boolean vector

REXP(double[] val)
construct a new xpression of type XT_ARRAY_DOUBLE and content val

REXP(int[] val)
construct a new xpression of type XT_ARRAY_INT and content val

REXP(int t, java.lang.Object o)
construct a new xpression of type t and content o, but no attribute

REXP(int t, java.lang.Object o, REXP at)
construct a new xpression of type t, content o and attribute at

REXP(Rengine re, long exp)
create a REXP directly from a R SEXP reference.

REXP(Rengine re, long exp, boolean convert)

REXP(java.lang.String[] val)
construct a new xpression of type XT_ARRAY_INT and content val

Method Summary

RBool	asBool() get content of the REXP as RBool (if it is one)
double	asDouble() get content of the REXP as double (if it is one)
double[]	asDoubleArray() get content of the REXP as an array of doubles.
double[][]	asDoubleMatrix() returns the content of the REXP as a matrix of doubles (2D-array: m[rows][cols]).
RFactor	asFactor() get content of the REXP as RFactor (if it is one)
int	asInt() get content of the REXP as int (if it is one)
int[]	asIntArray() get content of the REXP as an array of integers.
RList	asList() get content of the REXP as RList if the contents is a list or a generic vector
double[][]	asMatrix() this is just an alias for asDoubleMatrix().
java.lang.String	asString() return the first element of a character vector if this REXP is a character vector of length 1 or more, return null otherwise
java.lang.String[]	asStringArray() return the contents of this REXP as an array of strings if this REXP is a character vector, return null otherwise
java.lang.String	asSymbolName() return the name of the symbol represented by this REXP if is it a symbol or null otherwise
RVector	asVector() get content of the REXP as Vector (if it is one)
protected void	finalize()
REXP	getAttribute(java.lang.String name) retrieve a specific attribute.
REXP	getAttributes() get attributes of the REXP.
java.lang.Object	getContent() get raw content.
int	getType() get xpression type (see XT_.. constants) of the content.
static java.lang.String	quoteString(java.lang.String s)
java.lang.String	toString() displayable contents of the expression.
static java.lang.String	xtName(int xt) returns human-readable name of the xpression type as string.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

XT_NULL

public static final int XT_NULL

xpression type: NULL

See Also:

Constant Field Values

XT_INT

public static final int XT_INT

xpression type: integer

See Also:

Constant Field Values

XT_DOUBLE

public static final int XT_DOUBLE

xpression type: double

See Also:

Constant Field Values

XT_STR

public static final int XT_STR

xpression type: String

See Also:

Constant Field Values

XT_LANG

public static final int XT_LANG

xpression type: language construct (currently content is same as list)

See Also:

Constant Field Values

XT_SYM

public static final int XT_SYM

xpression type: symbol (content is symbol name: String)

See Also:

Constant Field Values

XT_BOOL

public static final int XT_BOOL

xpression type: RBool

See Also:

Constant Field Values

XT_VECTOR

public static final int XT_VECTOR

xpression type: Vector

See Also:

Constant Field Values

XT_LIST

public static final int XT_LIST

xpression type: RList

See Also:

Constant Field Values

XT_CLOS

public static final int XT_CLOS

xpression type: closure (there is no java class for that type (yet?). currently the body of the closure is stored in the content part of the REXP. Please note that this may change in the future!)

See Also:

Constant Field Values

XT_ARRAY_INT

public static final int XT_ARRAY_INT

xpression type: int[]

See Also:

Constant Field Values

XT_ARRAY_DOUBLE

public static final int XT_ARRAY_DOUBLE

xpression type: double[]

See Also:

Constant Field Values

XT_ARRAY_STR

public static final int XT_ARRAY_STR

xpression type: String[] (currently not used, Vector is used instead)

See Also:

Constant Field Values

XT_ARRAY_BOOL_UA

public static final int XT_ARRAY_BOOL_UA

internal use only! this constant should never appear in a REXP

See Also:

Constant Field Values

XT_ARRAY_BOOL

public static final int XT_ARRAY_BOOL

xpression type: RBool[]

See Also:

Constant Field Values

XT_ARRAY_BOOL_INT

public static final int XT_ARRAY_BOOL_INT

xpression type: int[] to be interpreted as boolean

See Also:

Constant Field Values

XT_UNKNOWN

public static final int XT_UNKNOWN

xpression type: unknown; no assumptions can be made about the content

See Also:

Constant Field Values

XT_NONE

public static final int XT_NONE

xpression type: pure reference, no internal type conversion performed

See Also:

Constant Field Values

XT_FACTOR

public static final int XT_FACTOR

xpression type: RFactor; this XT is internally generated (ergo is does not come from Rsrv.h) to support RFactor class which is built from XT_ARRAY_INT

See Also:

Constant Field Values

NILSXP

public static final int NILSXP

See Also:

Constant Field Values

SYMSXP

public static final int SYMSXP

See Also:

Constant Field Values

LISTSXP

public static final int LISTSXP

See Also:

Constant Field Values

CLOSXP

public static final int CLOSXP

See Also:

Constant Field Values

ENVSXP

public static final int ENVSXP

See Also:

Constant Field Values

PROMSXP

public static final int PROMSXP

See Also:

Constant Field Values

LANGSXP

public static final int LANGSXP

See Also:

Constant Field Values

SPECIALSXP

public static final int SPECIALSXP

See Also:

Constant Field Values

BUILTINSXP

public static final int BUILTINSXP

See Also:

Constant Field Values

CHARSXP

public static final int CHARSXP

See Also:

Constant Field Values

LGLSXP

public static final int LGLSXP

See Also:

Constant Field Values

INTSXP

public static final int INTSXP

See Also:

Constant Field Values

REALSXP

public static final int REALSXP

See Also:

Constant Field Values

CPLXSXP

public static final int CPLXSXP

See Also:

Constant Field Values

STRSXP

public static final int STRSXP

See Also:

Constant Field Values

DOTSXP

public static final int DOTSXP

See Also:

Constant Field Values

ANYSXP

public static final int ANYSXP

See Also:

Constant Field Values

VECSXP

public static final int VECSXP

See Also:

Constant Field Values

EXPRSXP

public static final int EXPRSXP

See Also:

Constant Field Values

BCODESXP

public static final int BCODESXP

See Also:

Constant Field Values

EXTPTRSXP

public static final int EXTPTRSXP

See Also:

Constant Field Values

WEAKREFSXP

public static final int WEAKREFSXP

See Also:

Constant Field Values

RAWSXP

public static final int RAWSXP

See Also:

Constant Field Values

S4SXP

public static final int S4SXP

See Also:

Constant Field Values

FUNSXP

public static final int FUNSXP

See Also:

Constant Field Values

xp

public long xp

native reference to the SEXP represented in R. It's usually a pointer, but can be any handle obtained from the engine. This reference can be used when calling RNI commands directly.

rtype

public int rtype

native type of the represented expression (see ...SXP constants in R). Please note that this type is cached and may have changed in the meantime. If the possibility of changing type exists (mainly list/lang) then use rniExpType to make sure

Constructor Detail

REXP

public REXP(Rengine re,
            long exp)

create a REXP directly from a R SEXP reference. SEXP types STRSXP, INTSXP and REALSXP are automatically converted. All others are represented as SEXP references only.

REXP

public REXP(Rengine re,
            long exp,
            boolean convert)

REXP

public REXP()

construct a new, empty (NULL) expression w/o attribute

REXP

public REXP(int t,
            java.lang.Object o)

construct a new xpression of type t and content o, but no attribute

Parameters:

t - xpression type (XT_...)

o - content

REXP

public REXP(int t,
            java.lang.Object o,
            REXP at)

construct a new xpression of type t, content o and attribute at

Parameters:

t - xpression type

o - content

at - attribute

REXP

public REXP(double[] val)

construct a new xpression of type XT_ARRAY_DOUBLE and content val

Parameters:

val - array of doubles to store in the REXP

REXP

public REXP(int[] val)

construct a new xpression of type XT_ARRAY_INT and content val

Parameters:

val - array of integers to store in the REXP

REXP

public REXP(java.lang.String[] val)

construct a new xpression of type XT_ARRAY_INT and content val

Parameters:

val - array of integers to store in the REXP

REXP

public REXP(boolean[] val)

construct new expression with the contents of a boolean vector

Parameters:

val - contents

Since:

JRI 0.3-2

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

getAttributes

public REXP getAttributes()

get attributes of the REXP. In R every object can have attached attribute xpression. Some more complex structures such as classes are built that way.

Returns:

attribute xpression or null if there is none associated

Since:

JRI 0.3, replaces getAttribute() but should be avoided if possible - use getAttribute(String) instead.

getAttribute

public REXP getAttribute(java.lang.String name)

retrieve a specific attribute.
Note: the current representation fetches the attribute ad-hoc, so it breaks the assumption that the expression is no longer accessed after the constructor was called. This should change in the future.

Parameters:

name - name of the attribute

Returns:

REXP containing the attribute or null if the attribute doesn't exist. The conversion flag is inherited from this REXP.

Since:

JRI 0.3

getContent

public java.lang.Object getContent()

get raw content. Use as... methods to retrieve contents of known type.

Returns:

content of the REXP

getType

public int getType()

get xpression type (see XT_.. constants) of the content. It defines the type of the content object.

Returns:

xpression type

asString

public java.lang.String asString()

return the first element of a character vector if this REXP is a character vector of length 1 or more, return null otherwise

asSymbolName

public java.lang.String asSymbolName()

return the name of the symbol represented by this REXP if is it a symbol or null otherwise

asStringArray

public java.lang.String[] asStringArray()

return the contents of this REXP as an array of strings if this REXP is a character vector, return null otherwise

asInt

public int asInt()

get content of the REXP as int (if it is one)

Returns:

int content or 0 if the REXP is no integer

asDouble

public double asDouble()

get content of the REXP as double (if it is one)

Returns:

double content or 0.0 if the REXP is no double

asVector

public RVector asVector()

get content of the REXP as Vector (if it is one)

Returns:

Vector content or null if the REXP is no Vector

asFactor

public RFactor asFactor()

get content of the REXP as RFactor (if it is one)

Returns:

RFactor content or null if the REXP is no factor

asList

public RList asList()

get content of the REXP as RList if the contents is a list or a generic vector

Returns:

RList content or null if the REXP is neither a list nor a generic vector

asBool

public RBool asBool()

get content of the REXP as RBool (if it is one)

Returns:

RBool content or null if the REXP is no logical value

asDoubleArray

public double[] asDoubleArray()

get content of the REXP as an array of doubles. Array of integers, single double and single integer are automatically converted into such an array if necessary.

Returns:

double[] content or null if the REXP is not a array of doubles or integers

asIntArray

public int[] asIntArray()

get content of the REXP as an array of integers. Unlike asDoubleArray() NO automatic conversion is done if the content is not an array of the correct type, because there is no canonical representation of doubles as integers. A single integer is returned as an array of the length 1. This method can be also used to access a logical array in its integer form (0=FALSE, 1=TRUE, 2=NA).

Returns:

int[] content or null if the REXP is not a array of integers

asDoubleMatrix

public double[][] asDoubleMatrix()

returns the content of the REXP as a matrix of doubles (2D-array: m[rows][cols]). This is the same form as used by popular math packages for Java, such as JAMA. This means that following leads to desired results:
Matrix m=new Matrix(c.eval("matrix(c(1,2,3,4,5,6),2,3)").asDoubleMatrix());

Returns:

2D array of doubles in the form double[rows][cols] or null if the contents is no 2-dimensional matrix of doubles

asMatrix

public double[][] asMatrix()

this is just an alias for asDoubleMatrix().

toString

public java.lang.String toString()

displayable contents of the expression. The expression is traversed recursively if aggregation types are used (Vector, List, etc.)

Overrides:

toString in class java.lang.Object

Returns:

String descriptive representation of the xpression

quoteString

public static java.lang.String quoteString(java.lang.String s)

xtName

public static java.lang.String xtName(int xt)

returns human-readable name of the xpression type as string. Arrays are denoted by a trailing asterisk (*).

Parameters:

xt - xpression type

Returns:

name of the xpression type