document

DESCRIPTION

@@ -39,4 +39,4 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyLoad: yes
 Roxygen: list(markdown = TRUE, r6 = FALSE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2

NAMESPACE

@@ -117,6 +117,7 @@ export(label_date)
 export(label_date_short)
 export(label_dollar)
 export(label_log)
+export(label_lut)
 export(label_math)
 export(label_number)
 export(label_number_auto)

NEWS.md

@@ -1,5 +1,7 @@
 # scales (development version)
 
+* New `label_lut()` for named lookup of labels (#458).
+
 # scales 1.3.0
 
 ## Better type support

R/label-lut.R

@@ -1,4 +1,35 @@
 
+#' Labels from lookup tables
+#'
+#' Use `label_lut()` for looking up succinct breaks in a named character vector
+#' giving complete labels.
+#'
+#' @param lut A named character vector of labels. The names are expected to
+#'   match the breaks, and the values become the labels.
+#' @param nomatch A string to label breaks that do not match any name in `lut`.
+#'  When `NULL` (default), the breaks are not translated but are kept as-is.
+#'
+#' @return A labeller function that takes a character vector of breaks and
+#'   returns a character vector of labels.
+#' @export
+#' @family labels for discrete scales
+#' @examples
+#' # Example lookup table
+#' lut <- c(
+#'   "4" = "four wheel drive",
+#'   "r" = "rear wheel drive",
+#'   "f" = "front wheel drive"
+#' )
+#'
+#' # Typical usage
+#' demo_discrete(c("4", "r", "f"), labels = label_lut(lut))
+#' # By default, extra values ('w') will remain as-is
+#' demo_discrete(c("4", "r", "f", "w"), labels = label_lut(lut))
+#' # Alternatively, you can relabel extra values
+#' demo_discrete(
+#'   c("4", "r", "f", "w"),
+#'   labels = label_lut(lut, nomatch = "unknown")
+#' )
 label_lut <- function(lut = character(), nomatch = NULL) {
 
   if (!is.character(lut)) {