org.rosuda.JRclient
Class REXP

java.lang.Object
  org.rosuda.JRclient.REXP

All Implemented Interfaces:

java.io.Serializable

public class REXP
extends java.lang.Object
implements java.io.Serializable

representation of R-eXpressions in Java

Version:

$Id: REXP.java 2746 2007-05-10 17:14:14Z urbanek $

See Also:

Serialized Form

Field Summary

static int	XT_ARRAY_BOOL xpression type: RBool[]
static int	XT_ARRAY_BOOL_UA internal use only!
static int	XT_ARRAY_CPLX xpression type: Complex[]
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_LANG_NOTAG xpression type: language list (w/o tags)
static int	XT_LANG_TAG xpression type: language list (w tags)
static int	XT_LIST xpression type: dotted-pair list (RList)
static int	XT_LIST_NOTAG xpression type: dotted-pair list (w/o tags)
static int	XT_LIST_TAG xpression type: dotted-pair list (w tags)
static int	XT_NULL xpression type: NULL
static int	XT_RAW xpression type: raw (byte[])
static int	XT_S4 xpression type: S4 object
static int	XT_STR xpression type: String
static int	XT_SYM xpression type: symbol (content is symbol name: String)
static int	XT_SYMNAME xpression type: symbol name
static int	XT_UNKNOWN xpression type: unknown; no assumptions can be made about the content
static int	XT_VECTOR xpression type: generic vector (RList)
static int	XT_VECTOR_EXP xpression type: expression vector
static int	XT_VECTOR_STR xpression type: string vector

Constructor Summary

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

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(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 it is one)
double[][]	asMatrix() this is just an alias for asDoubleMatrix().
java.lang.String	asString() get content of the REXP as string (if it is either a string or a symbol name).
java.lang.String[]	asStringArray() get content of the REXP as an array of strings (if it is a character vector).
RList	asVector() Deprecated. use asList instead
static REXP	createDataFrame(RList l)
REXP	getAttribute(java.lang.String name) get a certain attribute
RList	getAttributes() get all attributes of the REXP in the form of a list or null if the object has no attributes.
int	getBinaryLength() Calculates the length of the binary representation of the REXP including all headers.
int	getBinaryRepresentation(byte[] buf, int off) Stores the REXP in its binary (ready-to-send) representation including header into a buffer and returns the index of the byte behind the REXP.
java.lang.Object	getContent() Deprecated. please use corresponding as... accessor methods
static int	getStringBinaryRepresentation(byte[] buf, int off, java.lang.String s)
int	getType() Deprecated. please use corresponding is... test methods
boolean	isCharacter() tests whether this REXP is a character vector (aka string array)
boolean	isComplex() tests whether this REXP is a vector of complex numbers
boolean	isFactor() tests whether this REXP is a factor
boolean	isFalse() returns true if the value is boolean and false
boolean	isList() tests whether this REXP is a list (any type, i.e. dotted-pair list or generic vector)
boolean	isLogical() tests whether this REXP is a logical vector (aka boolean array or scalar)
boolean	isNull() tests whether this REXP is NULL (either a literal nil object or the payload is null)
boolean	isNumeric() tests whether this REXP is a numeric vector (double or integer array or scalar)
boolean	isRaw() tests whether this REXP is a raw vector
boolean	isSymbol() tests whether this REXP is a symbol
boolean	isTrue() returns true if the value is boolean and true
int	length() return the length on the REXP.
static int	parseREXP(REXP x, byte[] buf, int o) parses byte buffer for binary representation of xpressions - read one xpression slot (descends recursively for aggregated xpressions such as lists, vectors etc.)
static java.lang.String	quoteString(java.lang.String s)
void	setAttribute(java.lang.String name, REXP value) set an attribute value.
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, finalize, 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_S4

public static final int XT_S4

xpression type: S4 object

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_VECTOR

public static final int XT_VECTOR

xpression type: generic vector (RList)

See Also:

Constant Field Values

XT_LIST

public static final int XT_LIST

xpression type: dotted-pair list (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_SYMNAME

public static final int XT_SYMNAME

xpression type: symbol name

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_LIST_NOTAG

public static final int XT_LIST_NOTAG

xpression type: dotted-pair list (w/o tags)

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_LIST_TAG

public static final int XT_LIST_TAG

xpression type: dotted-pair list (w tags)

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_LANG_NOTAG

public static final int XT_LANG_NOTAG

xpression type: language list (w/o tags)

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_LANG_TAG

public static final int XT_LANG_TAG

xpression type: language list (w tags)

Since:

Rserve 0.5

See Also:

Constant Field Values

XT_VECTOR_EXP

public static final int XT_VECTOR_EXP

xpression type: expression vector

See Also:

Constant Field Values

XT_VECTOR_STR

public static final int XT_VECTOR_STR

xpression type: string vector

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_RAW

public static final int XT_RAW

xpression type: raw (byte[])

Since:

Rserve 0.4-?

See Also:

Constant Field Values

XT_ARRAY_CPLX

public static final int XT_ARRAY_CPLX

xpression type: Complex[]

Since:

Rserve 0.5

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_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

Constructor Detail

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

Method Detail

getAttributes

public RList getAttributes()

get all attributes of the REXP in the form of a list or null if the object has no attributes.

Returns:

attribute xpression or null if there is none associated

getAttribute

public REXP getAttribute(java.lang.String name)

get a certain attribute

Parameters:

name - name of the attribute

Returns:

null if the attribute doesn't exist or the attribute.

setAttribute

public void setAttribute(java.lang.String name,
                         REXP value)

set an attribute value. The attributes list is created if necessary.

Parameters:

name - attribute name

value - attribute value

getContent

public java.lang.Object getContent()

Deprecated. please use corresponding as... accessor methods

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

Returns:

content of the REXP

getType

public int getType()

Deprecated. please use corresponding is... test methods

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

Returns:

xpression type

length

public int length()

return the length on the REXP. If the REXP is scalar, the length is 1, for array and vector types the length is the number of elements. For all other types the length is zero.

Returns:

length of the REXP

parseREXP

public static int parseREXP(REXP x,
                            byte[] buf,
                            int o)

parses byte buffer for binary representation of xpressions - read one xpression slot (descends recursively for aggregated xpressions such as lists, vectors etc.)

Parameters:

x - xpression object to store the parsed xpression in

buf - buffer containing the binary representation

o - offset in the buffer to start at

Returns:

position just behind the parsed xpression. Can be use for successive calls to parseREXP(org.rosuda.JRclient.REXP, byte[], int) if more than one expression is stored in the binary array.

getBinaryLength

public int getBinaryLength()

Calculates the length of the binary representation of the REXP including all headers. This is the amount of memory necessary to store the REXP via getBinaryRepresentation(byte[], int).

Please note that currently only XT_[ARRAY_]INT, XT_[ARRAY_]DOUBLE and XT_[ARRAY_]STR are supported! All other types will return 4 which is the size of the header.

Returns:

length of the REXP including headers (4 or 8 bytes)

getBinaryRepresentation

public int getBinaryRepresentation(byte[] buf,
                                   int off)

Stores the REXP in its binary (ready-to-send) representation including header into a buffer and returns the index of the byte behind the REXP.

Please note that currently only XT_[ARRAY_]INT, XT_[ARRAY_]DOUBLE and XT_[ARRAY_]STR are supported! All other types will be stored as SEXP of the length 0 without any contents.

Parameters:

buf - buffer to store the REXP binary into

off - offset of the first byte where to store the REXP

Returns:

the offset of the first byte behind the stored REXP

getStringBinaryRepresentation

public static int getStringBinaryRepresentation(byte[] buf,
                                                int off,
                                                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

asString

public java.lang.String asString()

get content of the REXP as string (if it is either a string or a symbol name). If the length of the character vector is more tahn one, the first element is returned.

Returns:

string content or null if the REXP is no string or symbol name

isCharacter

public boolean isCharacter()

tests whether this REXP is a character vector (aka string array)

Returns:

true if this REXP is a character vector

Since:

Rserve 0.5

isNumeric

public boolean isNumeric()

tests whether this REXP is a numeric vector (double or integer array or scalar)

Returns:

true if this REXP is a numeric vector

Since:

Rserve 0.5

isSymbol

public boolean isSymbol()

tests whether this REXP is a symbol

Returns:

true if this REXP is a symbol

Since:

Rserve 0.5

isNull

public boolean isNull()

tests whether this REXP is NULL (either a literal nil object or the payload is null)

Returns:

true if this REXP is NULL

Since:

Rserve 0.5

isLogical

public boolean isLogical()

tests whether this REXP is a logical vector (aka boolean array or scalar)

Returns:

true if this REXP is a logical vector

Since:

Rserve 0.5

isComplex

public boolean isComplex()

tests whether this REXP is a vector of complex numbers

Returns:

true if this REXP is a vector of complex numbers

Since:

Rserve 0.5

isRaw

public boolean isRaw()

tests whether this REXP is a raw vector

Returns:

true if this REXP is a raw vector

Since:

Rserve 0.5

asStringArray

public java.lang.String[] asStringArray()

get content of the REXP as an array of strings (if it is a character vector).

Returns:

string content or null if the REXP is no string or symbol name

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 NaN if the REXP is no double

asVector

public RList asVector()

Deprecated. use asList instead

synonym for asList

Returns:

a list or null

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

isList

public boolean isList()

tests whether this REXP is a list (any type, i.e. dotted-pair list or generic vector)

Returns:

true if this REXP is a list

isTrue

public boolean isTrue()

returns true if the value is boolean and true

Returns:

true if the value is boolean and true

isFalse

public boolean isFalse()

returns true if the value is boolean and false

Returns:

true if the value is boolean and false

isFactor

public boolean isFactor()

tests whether this REXP is a factor

Returns:

true if this REXP is a factor

asList

public RList asList()

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

Returns:

RList content or null if the REXP is no list

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.

Returns:

double[] 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)

createDataFrame

public static REXP createDataFrame(RList l)