names.Rd 2.74 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/names.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2010 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
% 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
Radford Neal's avatar
Radford Neal committed
22
    \code{NULL}.}
Radford Neal's avatar
Radford Neal committed
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
}
\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 \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.

  If \code{value} is shorter than \code{x}, it is extended by character
  \code{NA}s to the length of \code{x}.
Radford Neal's avatar
Radford Neal committed
41

Radford Neal's avatar
Radford Neal committed
42 43 44 45 46 47 48 49 50 51 52
  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.
Radford Neal's avatar
Radford Neal committed
53

Radford Neal's avatar
Radford Neal committed
54 55 56 57 58 59 60 61 62
  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]]}.
Radford Neal's avatar
Radford Neal committed
63 64 65 66 67 68

  Formally classed aka \dQuote{S4} objects typically have
  \code{\link{slotNames}()} (and no \code{names()}).
}
\seealso{
  \code{\link{slotNames}}, \code{\link{dimnames}}.
Radford Neal's avatar
Radford Neal committed
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
}
\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
}
\keyword{attribute}