% File src/library/base/man/dimnames.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2015 R Core Team
% Distributed under GPL 2 or later

\name{dimnames}
\title{Dimnames of an Object}
\alias{dimnames}
\alias{dimnames<-}
\alias{dimnames.data.frame}
\alias{dimnames<-.data.frame}
\alias{provideDimnames}
\description{
  Retrieve or set the dimnames of an object.
}
\usage{
dimnames(x)
dimnames(x) <- value

provideDimnames(x, sep = "", base = list(LETTERS), unique = TRUE)
}
\arguments{
  \item{x}{an \R object, for example a matrix, array or data frame.}
  \item{value}{a possible value for \code{dimnames(x)}: see the
    \sQuote{Value} section.}
  \item{sep}{a character string, used to separate \code{base}
    symbols and digits in the constructed dimnames.}
  \item{base}{a non-empty \code{\link{list}} of character vectors.  The
    list components are used in turn (and recycled when needed) to
    construct replacements for empty dimnames components.  See also the
    examples.}
  \item{unique}{logical indicating that the dimnames constructed are
    unique within each dimension in the sense of \code{\link{make.unique}}.}
}
\details{
  The functions \code{dimnames} and \code{dimnames<-} are generic.

  For an \code{\link{array}} (and hence in particular, for a
  \code{\link{matrix}}), they retrieve or set the \code{dimnames}
  attribute (see \link{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, 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{\link{row.names}} and its \code{\link{names}}.  For the
  replacement method each component of \code{value} will be coerced by
  \code{\link{as.character}}.

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

  Both are \link{primitive} functions.

  \code{provideDimnames(x)} provides \code{dimnames} where
  \dQuote{missing}, such that its result has \code{\link{character}}
  dimnames for each component.  If \code{unique} is true as by default,
  they are unique within each component via \code{\link{make.unique}(*,
    sep=sep)}.
}
\value{
  The dimnames of a matrix or array can be \code{NULL} (which is not
  stored) 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 have
  names.  It is possible that all components are \code{NULL}: such
  dimnames may get converted to \code{NULL}.

  For the \code{"data.frame"} method both dimnames are character
  vectors, and the rownames must contain no duplicates nor missing
  values.

  \code{provideDimnames(x)} returns \code{x}, with \dQuote{\code{NULL} -
    free} \code{dimnames}, i.e.\sspace{}each component a character vector of
  correct length.
}
\note{
  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{\link{rownames}} instead, or (as it does) manipulate the whole
  dimnames list.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{rownames}}, \code{\link{colnames}};
  \code{\link{array}}, \code{\link{matrix}}, \code{\link{data.frame}}.
}
\examples{
## simple versions of rownames and colnames
## could be defined as follows
rownames0 <- function(x) dimnames(x)[[1]]
colnames0 <- function(x) dimnames(x)[[2]]

(dn <- dimnames(A <- provideDimnames(N <- array(1:24, dim = 2:4))))
A0 <- A; dimnames(A)[2:3] <- list(NULL)
stopifnot(identical(A0, provideDimnames(A)))
strd <- function(x) utils::str(dimnames(x))
strd(provideDimnames(A, base= list(letters[-(1:9)], tail(LETTERS))))
strd(provideDimnames(N, base= list(letters[-(1:9)], tail(LETTERS)))) # recycling
strd(provideDimnames(A, base= list(c("AA","BB")))) # recycling on both levels
## set "empty dimnames":
provideDimnames(rbind(1, 2:3), base = list(""), unique=FALSE)
}
\keyword{array}
\keyword{manip}