\name{jcastToArray}

\alias{.jcastToArray}

\title{

Ensures that a given object is an array reference

}

\description{

\code{.jcastToArray} takes a Java object reference of any kind and

returns Java array reference if the given object is a reference to an

array.

}

\usage{

.jcastToArray(obj, signature=NULL, class="", quiet=FALSE)

}

\arguments{

\item{obj}{Java object reference to cast or a scalar vector}

\item{signature}{array signature in JNI notation (e.g. \code{"[I"} for

an array of integers). If set to \code{NULL} (the default),

the signature is automatically determined from the object's class.}

\item{class}{force the result to pose as a particular Java

class. This has the same effect as using \code{\link{.jcast}} on the

result and is provided for convenience only.}

\item{quiet}{if set to \code{TRUE}, no failures are reported and the

original object is returned unmodified.}

}

\value{

Returns a Java array reference (\code{jarrayRef}) on success. If

\code{quiet} is \code{TRUE} then the result can also be the original

object in the case of failure.

}

\details{

Sometimes a result of a method is by definition of the class

\code{java.lang.Object}, but the actual referenced object may be an

array. In that case the method returns a Java object reference instead

of an array reference. In order to obtain an array reference, it is

necessary to cast such an object to an array reference - this is done

using the above \code{.jcastToArray} function.

The input is an object reference that points to an array. Usually the

signature should be left at \code{NULL} such that it is determined

from the object's class. This is also a check, because if the object's

class is not an array, then the functions fails either with an error

(when \code{quiet=FALSE}) or by returning the original object (when

\code{quiet=TRUE}). If the signature is set to anything else, it is

not verified and the array reference is always created, even if it may

be invalid and unusable.

For convenience \code{.jcastToArray} also accepts non-references in

which case it simply calls \code{\link{.jarray}}, ignoring all other

parameters.

}

\examples{

\dontrun{

a <- .jarray(1:10)

print(a)

# let's create an array containing the array

aa <- .jarray(list(a))

print(aa)

ba <- .jevalArray(aa)[[1]]

# it is NOT the inverse, because .jarray works on a list of objects

print(ba)

# so we need to cast the object into an array

b <- .jcastToArray(ba)

# only now a and b are the same array reference

print(b)

# for convenience .jcastToArray behaves like .jarray for non-references

print(.jcastToArray(1:10/2))

}

}

\keyword{interface}