\HeaderA{dimnames}{Dimnames of an Object}{dimnames}
\methaliasA{dimnames.data.frame}{dimnames}{dimnames.data.frame}
\aliasA{dimnames<\Rdash}{dimnames}{dimnames<.Rdash.}
\methaliasA{dimnames<\Rdash.data.frame}{dimnames}{dimnames<.Rdash..data.frame}
\keyword{array}{dimnames}
\keyword{manip}{dimnames}
\begin{Description}\relax
Retrieve or set the dimnames of an object.
\end{Description}
\begin{Usage}
\begin{verbatim}
dimnames(x)
dimnames(x) <- value
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an \R{} object, for example a matrix, array or data frame.
\item[\code{value}] a possible value for \code{dimnames(x)}: see the
\sQuote{Value} section.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The functions \code{dimnames} and \code{dimnames<-} are generic.

For an \code{\LinkA{array}{array}} (and hence in particular, for a
\code{\LinkA{matrix}{matrix}}), they retrieve or set the \code{dimnames}
attribute (see \LinkA{attributes}{attributes}) of the object.  A list
\code{value} can have names, and these will be used to label the
dimensions of the array where appropriate.

The replacement method for arrays/matrices coerces vector and factor
elements of \code{value} to character, but does not dispatch methods for
\code{as.character}.  It coerces zero-length elements to \code{NULL},
and a zero-length list to \code{NULL}.  If \code{value} is a list
shorter than the number of dimensions, as from \R{} 2.8.0 it is extended
with \code{NULL}s to the needed length.

Both have methods for data frames.  The dimnames of a data frame are
its \code{\LinkA{row.names}{row.names}} and its \code{\LinkA{names}{names}}.  For the
replacement method each component of \code{value} will be coerced by
\code{\LinkA{as.character}{as.character}}.

For a 1D matrix the \code{\LinkA{names}{names}} are the same thing as the
(only) component of the \code{dimnames}.

These functions are \LinkA{primitive}{primitive}, so argument names are ignored
(but this might not be true of their methods).
\end{Details}
\begin{Value}
The dimnames of a matrix or array can be \code{NULL} or a list of the
same length as \code{dim(x)}.  If a list, its components are either
\code{NULL} or a character vector with positive length of the
appropriate dimension of \code{x}.  The list can be named.

For the \code{"data.frame"} method both dimnames are character
vectors, and the rownames must contain no duplicates nor missing values.
\end{Value}
\begin{Note}\relax
Setting components of the dimnames, e.g.
\code{dimnames(A)[[1]] <- value} is a common paradigm, but note that
it will not work if the value assigned is \code{NULL}.  Use
\code{\LinkA{rownames}{rownames}} instead, or (as it does) manipulate the whole
dimnames list.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{rownames}{rownames}}, \code{\LinkA{colnames}{colnames}};
\code{\LinkA{array}{array}}, \code{\LinkA{matrix}{matrix}}, \code{\LinkA{data.frame}{data.frame}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## simple versions of rownames and colnames
## could be defined as follows
rownames0 <- function(x) dimnames(x)[[1]]
colnames0 <- function(x) dimnames(x)[[2]]
\end{ExampleCode}
\end{Examples}

