Expose vec_names2(), vec_names() and vec_set_names()

NAMESPACE

@@ -517,6 +517,8 @@ export(vec_list_cast)
 export(vec_match)
 export(vec_math)
 export(vec_math_base)
+export(vec_names)
+export(vec_names2)
 export(vec_order)
 export(vec_proxy)
 export(vec_proxy_compare)
@@ -555,6 +557,7 @@ export(vec_rep_each)
 export(vec_repeat)
 export(vec_restore)
 export(vec_seq_along)
+export(vec_set_names)
 export(vec_size)
 export(vec_size_common)
 export(vec_slice)

R/names.R

@@ -193,15 +193,47 @@ detect_dot_dot <- function(names) {
   grep("^[.][.](?:[.]|[1-9][0-9]*)$", names)
 }
 
-#' Extract repaired names from a vector
+#' Get or set the names of a vector
 #'
-#' Returns the repaired names from a vector, even if the vector is unnamed.
+#' @description
+#' These functions work like [rlang::names2()], [names()] and [names<-()],
+#' except that they return or modify the conceptual names of the vector.
+#' This is different for data frames and matrices (here, row names are used),
+#' and arrays (here, the dimension names of the first dimension are used).
+#'
+#' `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.
 #'
 #' @param x A vector with names
 #' @inheritParams vec_as_names
 #'
-#' @return The names of x, repaired
-#' @noRd
+#' @return
+#'   `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.
+#'
+#' @name vec_names
+#' @export
+#' @examples
+#' vec_names2(1:3)
+#' vec_names2(1:3, repair = "unique")
+#' vec_names2(c(a = 1, b = 2))
+#'
+#' # `vec_names()` is different from `names()`:
+#' 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])
 vec_names2 <- function(x,
                        ...,
                        repair = c("minimal", "unique", "universal", "check_unique"),
@@ -247,6 +279,8 @@ unique_names <- function(x, quiet = FALSE) {
   .Call(vctrs_unique_names, x, quiet)
 }
 
+#' @rdname vec_names
+#' @export
 vec_names <- function(x) {
   .Call(vctrs_names, x)
 }
@@ -433,6 +467,8 @@ set_names_fallback <- function(x, names) {
   x
 }
 
+#' @rdname vec_names
+#' @export
 vec_set_names <- function(x, names) {
   .Call(vctrs_set_names, x, names)
 }