org.rosuda.REngine
Class REXP

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