names

0th

Percentile

The Names of an Object

Functions to get or set the names of an object.

Keywords
attribute
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.

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

If value is shorter than x, it is extended by character NAs 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.

Both are primitive functions.

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 an environment, the length is the number of objects in the environment but the order of the names is arbitrary.

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]].

Formally classed aka “S4” objects typically have slotNames() (and no names()).

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

See Also

slotNames, dimnames.

Aliases
  • names
  • names.default
  • names<-
  • names<-.default
Examples
library(base) # NOT RUN { # 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 # }
Documentation reproduced from package base, version 3.4.3, License: Part of R 3.4.3

Community examples

richie@datacamp.com at Jan 17, 2017 base v3.3.2

A better way to remove the `names` attribute is to use [`unname()`](https://www.rdocumentation.org/packages/base/topics/unname). ```{r} unname(islands) ``` The main advantage of having names is that it gives you an easy-to-read way of subsetting. ```{r} islands[c("South America", "Southampton")] ``` Or, more fancily, you can use a regular expression to extract all islands with names begining with `"A"`, for example. ```{r} islands[grepl("^A", names(islands))] ``` Lists can also have names. ```{r} (l <- list(a = 1, b = letters[1:5], c = list(d = 1:3))) names(l) # only the top level element names, not "d" names(unlist(l)) # unlist gives a name for every element ``` You can overwrite all the names. ```{r} (l <- list(a = 1, b = letters[1:5], c = list(d = 1:3))) names(l) <- LETTERS[1:3] l ``` … or just some of them. ```{r} (l <- list(a = 1, b = letters[1:5], c = list(d = 1:3))) names(l)[1:2] <- c("Alpha", "Beta") l ``` Setting names on an object, then returning that object can be done in a single step using [`setNames()`](https://www.rdocumentation.org/packages/stats/topics/setNames). ```{r} (l <- list(a = 1, b = letters[1:5], c = list(d = 1:3))) setNames(l, c("Alef", "Bet", "Gimel")) ``` If an object has no names, then the `names()` function returns `NULL`. ```{r} v <- 1:3 names(v) ``` If an object has some names, then the names function returns a character vector with missing values where there are no names. ```{r} v <- 1:3 names(v)[2] <- "2nd" names(v) v ```