names                  package:base                  R Documentation

The Names of an Object

Description:

     Functions to get or set the names of an object.

Usage:

     names(x)
     names(x) <- value

Arguments:

       x: an R object.

   value: a character vector of up to the same length as 'x', or
          'NULL'.

Details:

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

     If 'value' is shorter than 'x', it is extended by character 'NA's
     to the length of '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 'z <- "names<-"(z,
     "[<-"(names(z), 3, "c2"))'.

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

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

Value:

     For 'names', 'NULL' or a character vector of the same length as
     'x'.  ('NULL' is given if the object has no names, including for
     objects of types which cannot have names.)

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

Note:

     For vectors, the names are one of the 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 'names' attribute really is
     'dimnames[[1]]'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _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

