The R Project SVN R

% File src/library/base/man/array.Rd

% Part of the R package, http://www.R-project.org

% Copyright 1995-2012 R Core Team

% Distributed under GPL 2 or later

\name{array}

\alias{array}

\alias{as.array}

\alias{as.array.default}

\alias{is.array}

\title{Multi-way Arrays}

\description{

  Creates or tests for arrays.

}

\usage{

array(data = NA, dim = length(data), dimnames = NULL)

as.array(x, ...)

is.array(x)

}

\arguments{

  \item{data}{a vector (including a list or \code{\link{expression}}

    vector) giving data to fill the array.  Non-atomic classed objects

    are coerced by \code{\link{as.vector}}.}

  \item{dim}{the dim attribute for the array to be created, that is an

    integer vector of length one or more giving the maximal indices in

    each dimension.}

  \item{dimnames}{either \code{NULL} or the names for the dimensions.

    This must a list (or it will be ignored) with one component for each

    dimension, either \code{NULL} or a character vector of the length

    given by \code{dim} for that dimension.  The list can be named, and

    the list names will be used as names for the dimensions.  If the

    list is shorter than the number of dimensions, it is extended by

    \code{NULL}s to the length required.}

  \item{x}{an \R object.}

  \item{\dots}{additional arguments to be passed to or from methods.}

}

\details{

  An array in \R can have one, two or more dimensions.  It is simply a

  vector which is stored with additional \link{attributes} giving the

  dimensions (attribute \code{"dim"}) and optionally names for those

  dimensions (attribute \code{"dimnames"}).

  A two-dimensional array is the same thing as a \code{\link{matrix}}.

  One-dimensional arrays often look like vectors, but may be handled

  differently by some functions: \code{\link{str}} does distinguish

  them in recent versions of \R.

  The \code{"dim"} attribute is an integer vector of length one or more

  containing non-negative values: the product of the values must match

  the length of the array.

  The \code{"dimnames"} attribute is optional: if present it is a list

  with one component for each dimension, either \code{NULL} or a

  character vector of the length given by the element of the

  \code{"dim"} attribute for that dimension.

  \code{is.array} is a \link{primitive} function.

}

\value{

  \code{array} returns an array with the extents specified in \code{dim}

  and naming information in \code{dimnames}.  The values in \code{data} are

  taken to be those in the array with the leftmost subscript moving

  fastest.  If there are too few elements in \code{data} to fill the array,

  then the elements in \code{data} are recycled.  If \code{data} has

  length zero, \code{NA} of an appropriate type is used for atomic

  vectors (\code{0} for raw vectors) and \code{NULL} for lists.

  Unlike \code{\link{matrix}}, \code{array} does not currently remove

  any attributes left by \code{as.vector} from a classed list

  \code{data}, so can return a list array with a class attribute.

  \code{as.array} is a generic function for coercing to arrays.  The

  default method does so by attaching a \code{\link{dim}} attribute to

  it.  It also attaches \code{\link{dimnames}} if \code{x} has

  \code{\link{names}}.  The sole purpose of this is to make it possible

  to access the \code{dim[names]} attribute at a later time.

  \code{is.array} returns \code{TRUE} or \code{FALSE} depending on

  whether its argument is an array (i.e., has a \code{dim} attribute of

  positive length) or not.  It is generic: you can write methods to handle

  specific classes of objects, see \link{InternalMethods}.

}

\note{

  \code{is.array} is a \link{primitive} function.

  \R 2.x.y allowed (although documented not to) a zero-length \code{dim}

  argument, and returned a vector of length one.

}

\references{

  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)

  \emph{The New S Language}.

  Wadsworth & Brooks/Cole.

}

\seealso{

  \code{\link{aperm}}, \code{\link{matrix}},

  \code{\link{dim}}, \code{\link{dimnames}}.

}

\examples{

dim(as.array(letters))

array(1:3, c(2,4)) # recycle 1:3 "2 2/3 times"

#     [,1] [,2] [,3] [,4]

#[1,]    1    3    2    1

#[2,]    2    1    3    2

}

\keyword{array}