org.rosuda.REngine
Class REXP

java.lang.Object
  org.rosuda.REngine.REXP

Direct Known Subclasses:

REXPEnvironment, REXPJavaReference, REXPNull, REXPReference, REXPS4, REXPSymbol, REXPUnknown, REXPVector

public class REXP
extends java.lang.Object

Basic class representing an object of any type in R. Each type in R in represented by a specific subclass.

This class defines basic accessor methods (asXXX), type check methods (isXXX), gives access to attributes (getAttribute(java.lang.String), hasAttribute(java.lang.String)) as well as several convenience methods. If a given method is not applicable to a particular type, it will throw the REXPMismatchException exception.

This root class will throw on any accessor call and returns false for all type methods. This allows subclasses to override accessor and type methods selectively.

Field Summary

protected REXPList	attr attribute list.
static int	maxDebugItems specifies how many items of a vector or list will be displayed in toDebugString()

Constructor Summary

REXP()
public root contrsuctor, same as new REXP(null)

REXP(REXPList attr)
public root constructor

Method Summary

REXPList	_attr() this method allows a limited access to object's attributes - getAttribute(java.lang.String) should be used instead to access specific attributes!.
byte[]	asBytes() returns the contents as an array of bytes (if supported by the represented object)
double	asDouble() convenience method corresponding to asDoubles()[0]
double[][]	asDoubleMatrix() returns the content of the REXP as a matrix of doubles (2D-array: m[rows][cols]).
double[]	asDoubles() returns the contents as an array of doubles (if supported by the represented object)
RFactor	asFactor() returns the contents as a factor (if supported by the represented object)
int	asInteger() convenience method corresponding to asIntegers()[0]
int[]	asIntegers() returns the contents as an array of integers (if supported by the represented object)
RList	asList() returns the contents as a (named) list (if supported by the represented object)
java.lang.Object	asNativeJavaObject() attempt to represent the REXP by a native Java object and return it.
java.lang.String	asString() convenience method corresponding to asStrings()[0]
java.lang.String[]	asStrings() returns the contents as an array of Strings (if supported by the represented object)
static REXP	createDataFrame(RList l) creates a data frame object from a list object using integer row names
static REXP	createDoubleMatrix(double[][] matrix) creates a REXP that represents a double matrix in R based on matrix of doubles (2D-array: m[rows][cols]).
int[]	dim() returns dimensions of the object (as determined by the "dim" attribute)
REXP	getAttribute(java.lang.String name) retrieve an attribute of the given name from this object
boolean	hasAttribute(java.lang.String name) checks whether this obejct has a given attribute
boolean	inherits(java.lang.String klass) determines whether this object inherits from a given class in the same fashion as the inherits() function in R does (i.e. ignoring S4 inheritance)
boolean	isComplex() check whether the REXP object is a complex vector
boolean	isEnvironment() check whether the REXP object is an environment
boolean	isExpression() check whether the REXP object is an expression vector
boolean	isFactor() check whether the REXP object is a factor
boolean	isInteger() check whether the REXP object is an integer vector
boolean	isLanguage() check whether the REXP object is a language object
boolean	isList() check whether the REXP object is a list (either generic vector or a pairlist - i.e.
boolean	isLogical() check whether the REXP object is a logical vector
boolean[]	isNA() returns a boolean vector of the same length as this vector with true for NA values and false for any other values
boolean	isNull() check whether the REXP object is NULL
boolean	isNumeric() check whether the REXP object is a numeric vector
boolean	isPairList() check whether the REXP object is a pair-list
boolean	isRaw() check whether the REXP object is a raw vector
boolean	isRecursive() check whether the REXP object is a recursive obejct
boolean	isReference() check whether the REXP object is a reference to an R object
boolean	isString() check whether the REXP object is a character vector (string)
boolean	isSymbol() check whether the REXP object is a symbol
boolean	isVector() check whether the REXP object is a vector
int	length() returns the length of a vector object.
java.lang.String	toDebugString() returns representation that it useful for debugging (e.g. it includes attributes and may include vector values -- see maxDebugItems)
java.lang.String	toString() returns a string description of the object

Methods inherited from class java.lang.Object

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

Field Detail

attr

protected REXPList attr

attribute list. This attribute should never be accessed directly.

maxDebugItems

public static int maxDebugItems

specifies how many items of a vector or list will be displayed in toDebugString()

Constructor Detail

REXP

public REXP()

public root contrsuctor, same as new REXP(null)

REXP

public REXP(REXPList attr)

public root constructor

Parameters:

attr - attribute list object (can be null

Method Detail

isString

public boolean isString()

check whether the REXP object is a character vector (string)

Returns:

true if the receiver is a character vector, false otherwise

isNumeric

public boolean isNumeric()

check whether the REXP object is a numeric vector

Returns:

true if the receiver is a numeric vector, false otherwise

isInteger

public boolean isInteger()

check whether the REXP object is an integer vector

Returns:

true if the receiver is an integer vector, false otherwise

isNull

public boolean isNull()

check whether the REXP object is NULL

Returns:

true if the receiver is NULL, false otherwise

isFactor

public boolean isFactor()

check whether the REXP object is a factor

Returns:

true if the receiver is a factor, false otherwise

isList

public boolean isList()

check whether the REXP object is a list (either generic vector or a pairlist - i.e. asList() will succeed)

Returns:

true if the receiver is a generic vector or a pair-list, false otherwise

isPairList

public boolean isPairList()

check whether the REXP object is a pair-list

Returns:

true if the receiver is a pair-list, false otherwise

isLogical

public boolean isLogical()

check whether the REXP object is a logical vector

Returns:

true if the receiver is a logical vector, false otherwise

isEnvironment

public boolean isEnvironment()

check whether the REXP object is an environment

Returns:

true if the receiver is an environment, false otherwise

isLanguage

public boolean isLanguage()

check whether the REXP object is a language object

Returns:

true if the receiver is a language object, false otherwise

isExpression

public boolean isExpression()

check whether the REXP object is an expression vector

Returns:

true if the receiver is an expression vector, false otherwise

isSymbol

public boolean isSymbol()

check whether the REXP object is a symbol

Returns:

true if the receiver is a symbol, false otherwise

isVector

public boolean isVector()

check whether the REXP object is a vector

Returns:

true if the receiver is a vector, false otherwise

isRaw

public boolean isRaw()

check whether the REXP object is a raw vector

Returns:

true if the receiver is a raw vector, false otherwise

isComplex

public boolean isComplex()

check whether the REXP object is a complex vector

Returns:

true if the receiver is a complex vector, false otherwise

isRecursive

public boolean isRecursive()

check whether the REXP object is a recursive obejct

Returns:

true if the receiver is a recursive object, false otherwise

isReference

public boolean isReference()

check whether the REXP object is a reference to an R object

Returns:

true if the receiver is a reference, false otherwise

asStrings

public java.lang.String[] asStrings()
                             throws REXPMismatchException

returns the contents as an array of Strings (if supported by the represented object)

Throws:

REXPMismatchException

asIntegers

public int[] asIntegers()
                 throws REXPMismatchException

returns the contents as an array of integers (if supported by the represented object)

Throws:

REXPMismatchException

asDoubles

public double[] asDoubles()
                   throws REXPMismatchException

returns the contents as an array of doubles (if supported by the represented object)

Throws:

REXPMismatchException

asBytes

public byte[] asBytes()
               throws REXPMismatchException

returns the contents as an array of bytes (if supported by the represented object)

Throws:

REXPMismatchException

asList

public RList asList()
             throws REXPMismatchException

returns the contents as a (named) list (if supported by the represented object)

Throws:

REXPMismatchException

asFactor

public RFactor asFactor()
                 throws REXPMismatchException

returns the contents as a factor (if supported by the represented object)

Throws:

REXPMismatchException

asNativeJavaObject

public java.lang.Object asNativeJavaObject()
                                    throws REXPMismatchException

attempt to represent the REXP by a native Java object and return it. Note that this may lead to loss of information (e.g., factors may be returned as a string array) and attributes are ignored. Not all R types can be converted to native Java objects. Also note that R has no concept of scalars, so vectors of length 1 will always be returned as an arrays (i.e., int[1] and not Integer).

Throws:

REXPMismatchException

length

public int length()
           throws REXPMismatchException

returns the length of a vector object. Note that we use R semantics here, i.e. a matrix will have a length of m * n since it is represented by a single vector (see dim() for retrieving matrix and multidimentional-array dimensions).

Returns:

length (number of elements) in a vector object

Throws:

REXPMismatchException - if this is not a vector object

isNA

public boolean[] isNA()
               throws REXPMismatchException

returns a boolean vector of the same length as this vector with true for NA values and false for any other values

Returns:

a boolean vector of the same length as this vector with true for NA values and false for any other values

Throws:

REXPMismatchException - if this is not a vector object

asInteger

public int asInteger()
              throws REXPMismatchException

convenience method corresponding to asIntegers()[0]

Returns:

first entry returned by asInteger()

Throws:

REXPMismatchException

asDouble

public double asDouble()
                throws REXPMismatchException

convenience method corresponding to asDoubles()[0]

Returns:

first entry returned by asDoubles()

Throws:

REXPMismatchException

asString

public java.lang.String asString()
                          throws REXPMismatchException

convenience method corresponding to asStrings()[0]

Returns:

first entry returned by asStrings()

Throws:

REXPMismatchException

getAttribute

public REXP getAttribute(java.lang.String name)

retrieve an attribute of the given name from this object

Parameters:

name - attribute name

Returns:

attribute value or null if the attribute does not exist

hasAttribute

public boolean hasAttribute(java.lang.String name)

checks whether this obejct has a given attribute

Parameters:

name - attribute name

Returns:

true if the attribute exists, false otherwise

dim

public int[] dim()

returns dimensions of the object (as determined by the "dim" attribute)

Returns:

an array of integers with corresponding dimensions or null if the object has no dimension attribute

inherits

public boolean inherits(java.lang.String klass)

determines whether this object inherits from a given class in the same fashion as the inherits() function in R does (i.e. ignoring S4 inheritance)

Parameters:

klass - class name

Returns:

true if this object is of the class klass, false otherwise

_attr

public REXPList _attr()

this method allows a limited access to object's attributes - getAttribute(java.lang.String) should be used instead to access specific attributes!. Note that the attr attribute should never be used directly incase the REXP implements a lazy access (e.g. via a reference)

Returns:

list of attributes or null if the object has no attributes

toString

public java.lang.String toString()

returns a string description of the object

Overrides:

toString in class java.lang.Object

Returns:

string describing the object - it can be of an arbitrary form and used only for debugging (do not confuse with asString() for accessing string REXPs)

toDebugString

public java.lang.String toDebugString()

returns representation that it useful for debugging (e.g. it includes attributes and may include vector values -- see maxDebugItems)

Returns:

extended description of the obejct -- it may include vector values

asDoubleMatrix

public double[][] asDoubleMatrix()
                          throws REXPMismatchException

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

Throws:

REXPMismatchException

createDoubleMatrix

public static REXP createDoubleMatrix(double[][] matrix)

creates a REXP that represents a double matrix in R based on matrix of doubles (2D-array: m[rows][cols]). This is the same form as used by popular math packages for Java, such as JAMA. The result of this function can be used in REngine.assign to store a matrix in R.

Parameters:

matrix - array double[rows][colums] containing the matrix to convert into a REXP. If matrix is null or either of the dimensions is 0 then the resulting matrix will have the dimensions 0 x 0 (Note: Java cannot represent 0 x n matrices for n > 0, so special matrices with one dimension of 0 can only be created by setting dimensions directly).

Returns:

REXPDouble with "dim" attribute which constitutes a matrix in R

createDataFrame

public static REXP createDataFrame(RList l)
                            throws REXPMismatchException

creates a data frame object from a list object using integer row names

Parameters:

l - a (named) list of vectors (REXPVector subclasses), each element corresponds to a column and all elements must have the same length

Returns:

a data frame object

Throws:

REXPMismatchException - if the list is empty or any of the elements is not a vector