Fix #344

NAMESPACE

@@ -86,6 +86,7 @@ export(identity_trans)
 export(is.trans)
 export(label_bytes)
 export(label_comma)
+export(label_currency)
 export(label_date)
 export(label_date_short)
 export(label_dollar)

NEWS.md

@@ -10,6 +10,7 @@
 * Add a rescale method for `difftime` objects (#382)
 * The `scale_cut` argument in `number()` now works as advertised for values 
   below the lowest cut value (#346)
+* `label_dollar()` has been superseeded by `label_currency()` for clarity (#344)
 
 # scales 1.2.1
 

R/label-dollar.R → R/label-currency.R

@@ -1,59 +1,57 @@
-#' Label currencies ($100, $2.50, etc)
+#' Label currencies ($100, €2.50, etc)
 #'
-#' Format numbers as currency, rounding values to dollars or cents using
-#' a convenient heuristic.
+#' Format numbers as currency, rounding values to monetary or fractional
+#' monetary using unit a convenient heuristic.
 #'
 #' @inherit label_number return params
-#' @param accuracy,largest_with_cents Number to round to. If `NULL`, the default,
-#'   values will be rounded to the nearest integer, unless any of the
-#'   values has non-zero fractional component (e.g. cents) and the largest
-#'   value is less than `largest_with_cents` which by default is 100,000.
+#' @param accuracy,largest_with_fractional Number to round
+#'   to. If `NULL`, the default, values will be rounded to the nearest integer,
+#'   unless any of the values has non-zero fractional component (e.g. cents) and
+#'   the largest value is less than `largest_with_fractional` which by default
+#'   is 100,000.
 #' @param prefix,suffix Symbols to display before and after value.
-#' @param negative_parens `r lifecycle::badge("deprecated")` Use
-#'   `style_negative = "parens"` instead.
 #' @inheritDotParams number
 #' @export
 #' @family labels for continuous scales
 #' @examples
-#' demo_continuous(c(0, 1), labels = label_dollar())
-#' demo_continuous(c(1, 100), labels = label_dollar())
+#' demo_continuous(c(0, 1), labels = label_currency())
+#' demo_continuous(c(1, 100), labels = label_currency())
 #'
 #' # Customise currency display with prefix and suffix
-#' demo_continuous(c(1, 100), labels = label_dollar(prefix = "USD "))
-#' euro <- label_dollar(
+#' demo_continuous(c(1, 100), labels = label_currency(prefix = "USD "))
+#' euro <- label_currency(
 #'   prefix = "",
 #'   suffix = "\u20ac",
 #'   big.mark = ".",
 #'   decimal.mark = ","
 #' )
 #' demo_continuous(c(1000, 1100), labels = euro)
 #'
-#' # Use negative_parens = TRUE for finance style display
-#' demo_continuous(c(-100, 100), labels = label_dollar(style_negative = "parens"))
+#' # Use style_negative = "parens" for finance style display
+#' demo_continuous(c(-100, 100), labels = label_currency(style_negative = "parens"))
 #'
 #' # Use scale_cut to use K/M/B where appropriate
 #' demo_log10(c(1, 1e16),
 #'   breaks = log_breaks(7, 1e3),
-#'   labels = label_dollar(scale_cut = cut_short_scale())
+#'   labels = label_currency(scale_cut = cut_short_scale())
 #' )
 #' # cut_short_scale() uses B = one thousand million
 #' # cut_long_scale() uses B = one million million
 #' demo_log10(c(1, 1e16),
 #'   breaks = log_breaks(7, 1e3),
-#'   labels = label_dollar(scale_cut = cut_long_scale())
+#'   labels = label_currency(scale_cut = cut_long_scale())
 #' )
 #'
 #' # You can also define your own breaks
-#' gbp <- label_dollar(
+#' gbp <- label_currency(
 #'   prefix = "\u00a3",
 #'   scale_cut = c(0, k = 1e3, m = 1e6, bn = 1e9, tn = 1e12)
 #' )
 #' demo_log10(c(1, 1e12), breaks = log_breaks(5, 1e3), labels = gbp)
-label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
-                         suffix = "", big.mark = ",", decimal.mark = ".",
-                         trim = TRUE, largest_with_cents = 100000,
-                         negative_parens = deprecated(),
-                         ...) {
+label_currency <- function(accuracy = NULL, scale = 1, prefix = "$",
+                           suffix = "", big.mark = ",", decimal.mark = ".",
+                           trim = TRUE, largest_with_fractional = 100000,
+                           ...) {
   force_all(
     accuracy,
     scale,
@@ -62,8 +60,7 @@ label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
     big.mark,
     decimal.mark,
     trim,
-    largest_with_cents,
-    negative_parens,
+    largest_with_fractional,
     ...
   )
   function(x) {
@@ -76,8 +73,7 @@ label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
       big.mark = big.mark,
       decimal.mark = decimal.mark,
       trim = trim,
-      largest_with_cents = largest_with_cents,
-      negative_parens = negative_parens,
+      largest_with_cents = largest_with_fractional,
       ...
     )
   }
@@ -95,18 +91,55 @@ needs_cents <- function(x, threshold) {
   !all(x == floor(x), na.rm = TRUE)
 }
 
-#' Superseded interface to `label_dollar()`
+#' Superseded interface to `label_currency()`
 #'
 #' @description
 #' `r lifecycle::badge("superseded")`
 #'
 #' These functions are kept for backward compatibility; you should switch
-#' to [label_dollar()] for new code.
+#' to [label_currency()] for new code.
 #'
 #' @keywords internal
 #' @export
-#' @inheritParams label_dollar
-dollar_format <- label_dollar
+#' @inheritParams label_currency
+#' @param largest_with_cents Like `largest_with_fractional()` in
+#'   [label_currency()]
+#' @param negative_parens `r lifecycle::badge("deprecated")` Use
+#'   `style_negative = "parens"` instead.
+dollar_format <- function(accuracy = NULL, scale = 1, prefix = "$",
+                          suffix = "", big.mark = ",", decimal.mark = ".",
+                          trim = TRUE, largest_with_cents = 100000,
+                          negative_parens = deprecated(),
+                          ...) {
+  force_all(
+    accuracy,
+    scale,
+    prefix,
+    suffix,
+    big.mark,
+    decimal.mark,
+    trim,
+    largest_with_cents,
+    negative_parens,
+    ...
+  )
+  function(x) {
+    dollar(
+      x,
+      accuracy = accuracy,
+      scale = scale,
+      prefix = prefix,
+      suffix = suffix,
+      big.mark = big.mark,
+      decimal.mark = decimal.mark,
+      trim = trim,
+      largest_with_cents = largest_with_cents,
+      negative_parens = negative_parens,
+      ...
+    )
+  }
+}
+
 
 #' @export
 #' @rdname dollar_format
@@ -151,3 +184,7 @@ dollar <- function(x, accuracy = NULL, scale = 1, prefix = "$",
     ...
   )
 }
+
+#' @export
+#' @rdname dollar_format
+label_dollar <- dollar_format