src/library/base/man/names.Rd

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

\name{names}
\alias{names}
\alias{names.default}
\alias{names<-}
\alias{names<-.default}
\title{The Names of an Object}
\description{
  Functions to get or set the names of an object.
}
\usage{
names(x)
names(x) <- value
}
\arguments{
  \item{x}{an \R object.}
  \item{value}{a character vector of up to the same length as \code{x}, or
    \code{NULL}.}
}

\value{
  For \code{names}, \code{NULL} or a character vector of the same length
  as \code{x}.  (\code{NULL} is given if the object has no names,
  including for objects of types which cannot have names.)  For an
  environment, the length is the number of objects in the environment
  but the order of the names is arbitrary.

  For \code{names<-}, the updated object.  (Note that the value of
  \code{names(x) <- value} is that of the assignment, \code{value}, not
  the return value from the left-hand side.)
}

\details{
  \code{names} is a generic accessor function, and \code{names<-} is a
  generic replacement function.  The default methods get and set
  the \code{"names"} attribute of a vector (including a list) or
  pairlist.

  For an \code{\link{environment}} \code{env}, \code{names(env)} gives
  the names of the corresponding list, i.e.,
  \code{names(as.list(env, all.names = TRUE))} which are also given by
  \code{\link{ls}(env, all.names = TRUE, sorted = FALSE)}.  If the
  environment is used as a hash table, \code{names(env)} are its
  \dQuote{keys}.

  If \code{value} is shorter than \code{x}, it is extended by character
  \code{NA}s to the length of \code{x}.

  It is possible to update just part of the names attribute via the
  general rules: see the examples.  This works because the expression
  there is evaluated as \code{z <- "names<-"(z, "[<-"(names(z), 3, "c2"))}.

  The name \code{""} is special: it is used to indicate that there is no
  name associated with an element of a (atomic or generic) vector.
  Subscripting by \code{""} will match nothing (not even elements which
  have no name).

  A name can be character \code{NA}, but such a name will never be
  matched and is likely to lead to confusion.

  Both are \link{primitive} functions.
}
\note{
  For vectors, the names are one of the \link{attributes} with
  restrictions on the possible values.  For pairlists, the names are the
  tags and converted to and from a character vector.

  For a one-dimensional array the \code{names} attribute really is
  \code{\link{dimnames}[[1]]}.

  Formally classed aka \dQuote{S4} objects typically have
  \code{\link{slotNames}()} (and no \code{names()}).
}
\seealso{
  \code{\link{slotNames}}, \code{\link{dimnames}}.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\examples{
# print the names attribute of the islands data set
names(islands)

# remove the names attribute
names(islands) <- NULL
islands
rm(islands) # remove the copy made

z <- list(a = 1, b = "c", c = 1:3)
names(z)
# change just the name of the third element.
names(z)[3] <- "c2"
z

z <- 1:3
names(z)
## assign just one name
names(z)[2] <- "b"
z

\dontshow{## "show" the equivalence claimed above:
  for(e in c(baseenv(), globalenv()))
  stopifnot(identical(names(e), ls(e, all.names=TRUE, sorted=FALSE)),
            identical(names(e), names(as.list(e, all.names=TRUE))))
}
}
\keyword{attribute}