org.rosuda.JRI
Class REXP

java.lang.Object
  extended by 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