New labeller: label_dictionary()

[teunbrand]

This PR aims to fix #458.

Briefly, you pass a named vector and the breaks will be matched to the names, and the value will be returned as the label.

Examples rendered:

devtools::load_all("~/packages/scales/")
#> ℹ Loading scales

# 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))
#> scale_x_discrete(labels = label_lut(lut))

# By default, extra values ('w') will remain as-is
demo_discrete(c("4", "r", "f", "w"), labels = label_lut(lut))
#> scale_x_discrete(labels = label_lut(lut))

# Alternatively, you can relabel extra values
demo_discrete(
  c("4", "r", "f", "w"),
  labels = label_lut(lut, nomatch = "unknown")
)
#> scale_x_discrete(labels = label_lut(lut, nomatch = "unknown"))

^{Created on 2024-10-07 with reprex v2.1.1}

[thomasp85]

Still on the fence about the use of "lut". I don't think many users will immediately understand what it does

Don't know if label_dict() or label_dictionary() is more apt

[teunbrand]

I'd be happy to change the name into either of these

[thomasp85]

I feel we used the dict name somewhere else recently in scales or ggplot2?

[teunbrand]

In tidyverse/ggplot2#6077, we'd allow labs(dictionary = ...) for a similar lookup.

[thomasp85]

then let's mirror that

[thomasp85]

also need to rename the test file

[teunbrand]

Good catch