vctrs: vec_names – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

vec_names

Get or set the names of a vector

Description

These functions work like rlang::names2(), names() and names<-(), except that they return or modify the the rowwise names of the vector. These are:

The usual names() for atomic vectors and lists
The row names for data frames and matrices
The names of the first dimension for arrays Rowwise names are size consistent: the length of the names always equals vec_size().

vec_names2() returns the repaired names from a vector, even if it is unnamed. See vec_as_names() for details on name repair.

vec_names() is a bare-bones version that returns NULL if the vector is unnamed.

vec_set_names() sets the names or removes them.

Usage

vec_names2(
  x,
  ...,
  repair = c("minimal", "unique", "universal", "check_unique"),
  quiet = FALSE
)

vec_names(x)

vec_set_names(x, names)

Arguments

`x`	A vector with names
`...`	These dots are for future extensions and must be empty.
`repair`	Either a string or a function. If a string, it must be one of `"check_unique"`, `"minimal"`, `"unique"`, or `"universal"`. If a function, it is invoked with a vector of minimal names and must return minimal names, otherwise an error is thrown. Minimal names are never `NULL` or `NA`. When an element doesn't have a name, its minimal name is an empty string. Unique names are unique. A suffix is appended to duplicate names to make them unique. Universal names are unique and syntactic, meaning that you can safely use the names as variables without causing a syntax error. The `"check_unique"` option doesn't perform any name repair. Instead, an error is raised if the names don't suit the `"unique"` criteria.
`quiet`	By default, the user is informed of any renaming caused by repairing the names. This only concerns unique and universal repairing. Set `quiet` to `TRUE` to silence the messages.
`names`	A character vector, or `NULL`.

Value

vec_names2() returns the names of x, repaired. vec_names() returns the names of x or NULL if unnamed. vec_set_names() returns x with names updated.

Examples

vec_names2(1:3)
vec_names2(1:3, repair = "unique")
vec_names2(c(a = 1, b = 2))

# `vec_names()` consistently returns the rowwise names of data frames and arrays:
vec_names(data.frame(a = 1, b = 2))
names(data.frame(a = 1, b = 2))
vec_names(mtcars)
names(mtcars)
vec_names(Titanic)
names(Titanic)

vec_set_names(1:3, letters[1:3])
vec_set_names(data.frame(a = 1:3), letters[1:3])

vctrs

Vector Helpers

v0.3.8

MIT + file LICENSE

Authors

Hadley Wickham [aut], Lionel Henry [aut, cre], Davis Vaughan [aut], data.table team [cph] (Radix sort based on data.table's forder() and their contribution to R's order()), RStudio [cph]

Initial release