\name{ArrayAndMatrix-class}
\docType{class}
\alias{ArrayAndMatrix-class}
\alias{RawMatrix-class}
\alias{CharMatrix-class}
\alias{LogicalMatrix-class}
\alias{IntegerMatrix-class}
\alias{NumericMatrix-class}
\alias{ComplexMatrix-class}
\alias{RawArray-class}
\alias{CharArray-class}
\alias{LogicalArray-class}
\alias{IntegerArray-class}
\alias{NumericArray-class}
\alias{ComplexArray-class}
\alias{RawMatrix}
\alias{CharMatrix}
\alias{LogicalMatrix}
\alias{IntegerMatrix}
\alias{NumericMatrix}
\alias{ComplexMatrix}
\alias{RawArray}
\alias{CharArray}
\alias{LogicalArray}
\alias{IntegerArray}
\alias{NumericArray}
\alias{ComplexArray}

\title{Class "NumericMatrix" and friends}
\description{
  Classes providing \code{\link{matrix}} and \code{\link{array}}
  functionality, but allowing stronger type specification, e.g.,
  \code{NumericMatrix} is a \code{matrix} whose members must be of type
  "numeric". A "matrix" is two-dimensional; an "array" is any
  dimensions, but R treats two-dimensional arrays as "matrix" and
  one-dimensional arrays as "vector" so "XxxArray" is most useful for
  specifying arrays with greater than 2 dimensions.

  Available classes are "RawMatrix" "CharMatrix" "LogicalMatrix"
  "IntegerMatrix" "NumericMatrix" "ComplexMatrix" "RawArray" "CharArray"
  "LogicalArray" "IntegerArray" "NumericArray" "ComplexArray".
}
\details{
  The following illustrates how to use these classes in R and Java, using
  \code{NumericMatrix} as an example.

  The examples assume that mapping between R and Java uses the
	\dQuote{javalib} type mode.

  Suppose you would like an R function to return a matrix of numeric
  (double) values, and that you are using the \dQuote{javalib} mode for
  mapping between R and Java (\code{typeMode="javalib"} in
  \code{\link{createMap}}, or \code{typemode=javalib} in the ant
  configuration file \code{RWebServicesTuning.properties}). For this
  type mode, specifying \dQuote{matrix} as a return type is
  insufficient: a matrix could contain any basic type (raw, character,
  integer, double, complex, etc.), so there is not enough information to
  map to a Java object. The solution is to specify more clearly what the
  type of the return value is, for instance, if the return type is a
  matrix of numeric (double) values, then arrange for the function to
  return an object of class \code{NumericMatrix}.

  In R the basic properties of \code{NumericMatrix} can be seen here:
  \preformatted{        > nm=new("NumericMatrix", matrix(as.double(50:1),10,5))
    > dim(nm)
    [1] 10  5
    > nm[7,3]
    [1] 24
    > as.vector(nm)
     [1] 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33
    [19] 32 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15
    [37] 14 13 12 11 10  9  8  7  6  5  4  3  2  1
    > as.vector(nm)[(3-1)*nrow(nm)+7]
    [1] 24
  }
  The last line is meant to illustrate that the 'matrix' data in R is
  stored as a single vector, in 'column-major' order, i.e., elements
  \code{1:nrow(nm)} are the first column,
  \code{(nrow(nm)+1):(2*nrow(nm))} are the second column, etc.

  In Java, \code{dim=getDim()} returns an \code{int[]}, containing the number of rows and
  the number of columns, e.g., \code{int[] = {10, 5}} for the example above of
  columns in the matrix (like \code{dim()} would do on a matrix in R).

  \code{value=getValue()} will return \code{double[]}, containing all the data, like the
  result of as.vector above. Remembering that Java starts indexing at 0,
  we can get the element in row i and column j as
  \preformatted{value[i * dim[0] + j]}
  We (or you) could write methods getMatrix / setMatrix returning /
  taking double[][] to do this, or getElement / setElement to access specific
  elements; it's worthwhile remembering that this does require quite a
  bit of memory allocation (for big arrays), so in some ways it's better
  to force the client to just give the data in the expected format anyway.
}

\section{Objects from the Class}{
Objects can be created by calls of the form \code{new("NumericMatrix",
...)}.  To create an instance from an existing, untyped, "matrix" or
"array", use forms like \code{new("NumericMatrix", m)} or unclass and
update the \code{mode} of the object. See examples for additional
detail.
}
\section{Slots}{None.}
\section{Extends}{
Class \code{"matrix"}, from data part.
Class \code{"structure"}, by class "matrix", distance 2.
Class \code{"array"}, by class "matrix", distance 2.
Class \code{"vector"}, by class "matrix", distance 3, with explicit coerce.
Class \code{"vector"}, by class "matrix", distance 4, with explicit coerce.
}
\section{Methods}{Use "NumericMatrix" and friends as replacements for "matrix" or "array".}
\author{Martin Morgan <mtmorgan@fhcrc.rog}
\examples{
## creating an empty instance
obj <- new("ComplexMatrix")
obj
mode(obj)
## Converting between array and typed Array
new("RawArray", array(raw(), dim=c(5,2,3)))

## Converting between types
obj <- new("NumericMatrix", matrix(numeric()))
obj <- unclass(obj)                     # retrieve underlying matrix
mode(obj) <- "raw"
obj <- new("RawMatrix", obj)
validObject(obj)
obj
}
\keyword{classes}