names.Rd 2.74 KB
 Radford Neal committed May 18, 2013 1 2 % File src/library/base/man/names.Rd % Part of the R package, http://www.R-project.org  Radford Neal committed Aug 26, 2016 3 % Copyright 1995-2010 R Core Team  Radford Neal committed May 18, 2013 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 committed May 18, 2013 22  \code{NULL}.}  Radford Neal committed May 18, 2013 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 committed May 18, 2013 41   Radford Neal committed May 18, 2013 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 committed May 18, 2013 53   Radford Neal committed May 18, 2013 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 committed May 18, 2013 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 committed May 18, 2013 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}