From 2e8d601254395454f30267c247d8707278d604d1 Mon Sep 17 00:00:00 2001
From: Thomas Lin Pedersen <thomasp85@gmail.com>
Date: Thu, 2 Nov 2023 08:28:48 +0100
Subject: [PATCH] Fix #344

---
 NAMESPACE                                     |  1 +
 NEWS.md                                       |  1 +
 R/{label-dollar.R => label-currency.R}        | 99 +++++++++++++------
 man/dollar_format.Rd                          | 28 ++++--
 man/label_bytes.Rd                            |  2 +-
 man/{label_dollar.Rd => label_currency.Rd}    | 47 +++++----
 man/label_number_auto.Rd                      |  2 +-
 man/label_number_si.Rd                        |  2 +-
 man/label_ordinal.Rd                          |  2 +-
 man/label_parse.Rd                            |  2 +-
 man/label_percent.Rd                          |  2 +-
 man/label_pvalue.Rd                           |  2 +-
 man/label_scientific.Rd                       |  2 +-
 ...t-label-dollar.R => test-label-currency.R} | 12 +--
 14 files changed, 126 insertions(+), 78 deletions(-)
 rename R/{label-dollar.R => label-currency.R} (57%)
 rename man/{label_dollar.Rd => label_currency.Rd} (73%)
 rename tests/testthat/{test-label-dollar.R => test-label-currency.R} (58%)

diff --git a/NAMESPACE b/NAMESPACE
index f6964735..50dbb621 100644
--- a/NAMESPACE
+++ b/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)
diff --git a/NEWS.md b/NEWS.md
index 85eb828c..b5e686c0 100644
--- a/NEWS.md
+++ b/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
 
diff --git a/R/label-dollar.R b/R/label-currency.R
similarity index 57%
rename from R/label-dollar.R
rename to R/label-currency.R
index 25485eaa..84561463 100644
--- a/R/label-dollar.R
+++ b/R/label-currency.R
@@ -1,26 +1,25 @@
-#' 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 = ".",
@@ -28,32 +27,31 @@
 #' )
 #' 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
diff --git a/man/dollar_format.Rd b/man/dollar_format.Rd
index fdf73383..fc65b2df 100644
--- a/man/dollar_format.Rd
+++ b/man/dollar_format.Rd
@@ -1,9 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/label-dollar.R
+% Please edit documentation in R/label-currency.R
 \name{dollar_format}
 \alias{dollar_format}
 \alias{dollar}
-\title{Superseded interface to \code{label_dollar()}}
+\alias{label_dollar}
+\title{Superseded interface to \code{label_currency()}}
 \usage{
 dollar_format(
   accuracy = NULL,
@@ -33,13 +34,21 @@ dollar(
   scale_cut = NULL,
   ...
 )
+
+label_dollar(
+  accuracy = NULL,
+  scale = 1,
+  prefix = "$",
+  suffix = "",
+  big.mark = ",",
+  decimal.mark = ".",
+  trim = TRUE,
+  largest_with_cents = 1e+05,
+  negative_parens = deprecated(),
+  ...
+)
 }
 \arguments{
-\item{accuracy, largest_with_cents}{Number to round to. If \code{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 \code{largest_with_cents} which by default is 100,000.}
-
 \item{scale}{A scaling factor: \code{x} will be multiplied by \code{scale} before
 formatting. This is useful if the underlying data is very small or very
 large.}
@@ -54,6 +63,9 @@ decimal point.}
 \item{trim}{Logical, if \code{FALSE}, values are right-justified to a common
 width (see \code{\link[base:format]{base::format()}}).}
 
+\item{largest_with_cents}{Like \code{largest_with_fractional()} in
+\code{\link[=label_currency]{label_currency()}}}
+
 \item{negative_parens}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use
 \code{style_negative = "parens"} instead.}
 
@@ -65,6 +77,6 @@ width (see \code{\link[base:format]{base::format()}}).}
 \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
 
 These functions are kept for backward compatibility; you should switch
-to \code{\link[=label_dollar]{label_dollar()}} for new code.
+to \code{\link[=label_currency]{label_currency()}} for new code.
 }
 \keyword{internal}
diff --git a/man/label_bytes.Rd b/man/label_bytes.Rd
index 35120545..d25cae27 100644
--- a/man/label_bytes.Rd
+++ b/man/label_bytes.Rd
@@ -97,7 +97,7 @@ demo_continuous(c(1, 1024^2),
 }
 \seealso{
 Other labels for continuous scales: 
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
diff --git a/man/label_dollar.Rd b/man/label_currency.Rd
similarity index 73%
rename from man/label_dollar.Rd
rename to man/label_currency.Rd
index ef5cee8b..d7a6e128 100644
--- a/man/label_dollar.Rd
+++ b/man/label_currency.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/label-dollar.R
-\name{label_dollar}
-\alias{label_dollar}
-\title{Label currencies ($100, $2.50, etc)}
+% Please edit documentation in R/label-currency.R
+\name{label_currency}
+\alias{label_currency}
+\title{Label currencies ($100, €2.50, etc)}
 \usage{
-label_dollar(
+label_currency(
   accuracy = NULL,
   scale = 1,
   prefix = "$",
@@ -12,16 +12,16 @@ label_dollar(
   big.mark = ",",
   decimal.mark = ".",
   trim = TRUE,
-  largest_with_cents = 1e+05,
-  negative_parens = deprecated(),
+  largest_with_fractional = 1e+05,
   ...
 )
 }
 \arguments{
-\item{accuracy, largest_with_cents}{Number to round to. If \code{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 \code{largest_with_cents} which by default is 100,000.}
+\item{accuracy, largest_with_fractional}{Number to round
+to. If \code{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 \code{largest_with_fractional} which by default
+is 100,000.}
 
 \item{scale}{A scaling factor: \code{x} will be multiplied by \code{scale} before
 formatting. This is useful if the underlying data is very small or very
@@ -37,9 +37,6 @@ decimal point.}
 \item{trim}{Logical, if \code{FALSE}, values are right-justified to a common
 width (see \code{\link[base:format]{base::format()}}).}
 
-\item{negative_parens}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use
-\code{style_negative = "parens"} instead.}
-
 \item{...}{
   Arguments passed on to \code{\link[=number]{number}}
   \describe{
@@ -81,16 +78,16 @@ they work similarly for all scales, including those that generate legends
 rather than axes.
 }
 \description{
-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.
 }
 \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 = ".",
@@ -98,23 +95,23 @@ euro <- label_dollar(
 )
 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)
 )
diff --git a/man/label_number_auto.Rd b/man/label_number_auto.Rd
index 220dfe55..a660cbec 100644
--- a/man/label_number_auto.Rd
+++ b/man/label_number_auto.Rd
@@ -29,7 +29,7 @@ demo_log10(c(1, 1e7), labels = label_number_auto())
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
 \code{\link{label_parse}()},
diff --git a/man/label_number_si.Rd b/man/label_number_si.Rd
index df2d0d57..85019af4 100644
--- a/man/label_number_si.Rd
+++ b/man/label_number_si.Rd
@@ -94,7 +94,7 @@ demo_continuous(c(1, 1e9), labels = label_number(scale_cut = cut_short_scale()))
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_ordinal}()},
 \code{\link{label_parse}()},
diff --git a/man/label_ordinal.Rd b/man/label_ordinal.Rd
index 68be92f5..62945380 100644
--- a/man/label_ordinal.Rd
+++ b/man/label_ordinal.Rd
@@ -110,7 +110,7 @@ demo_continuous(c(1, 10),
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_parse}()},
diff --git a/man/label_parse.Rd b/man/label_parse.Rd
index 5636233c..7dd7d29d 100644
--- a/man/label_parse.Rd
+++ b/man/label_parse.Rd
@@ -47,7 +47,7 @@ demo_continuous(c(1, 5), labels = label_math())
 
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
diff --git a/man/label_percent.Rd b/man/label_percent.Rd
index ffb018ea..ffef1e54 100644
--- a/man/label_percent.Rd
+++ b/man/label_percent.Rd
@@ -98,7 +98,7 @@ demo_continuous(c(0, .01), labels = french_percent)
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
diff --git a/man/label_pvalue.Rd b/man/label_pvalue.Rd
index 1cff3fce..ae9e2b83 100644
--- a/man/label_pvalue.Rd
+++ b/man/label_pvalue.Rd
@@ -54,7 +54,7 @@ demo_continuous(c(0, 1), labels = label_pvalue(prefix = prefix))
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
diff --git a/man/label_scientific.Rd b/man/label_scientific.Rd
index 0447c010..97db3367 100644
--- a/man/label_scientific.Rd
+++ b/man/label_scientific.Rd
@@ -54,7 +54,7 @@ demo_log10(c(1, 1e9))
 \seealso{
 Other labels for continuous scales: 
 \code{\link{label_bytes}()},
-\code{\link{label_dollar}()},
+\code{\link{label_currency}()},
 \code{\link{label_number_auto}()},
 \code{\link{label_number_si}()},
 \code{\link{label_ordinal}()},
diff --git a/tests/testthat/test-label-dollar.R b/tests/testthat/test-label-currency.R
similarity index 58%
rename from tests/testthat/test-label-dollar.R
rename to tests/testthat/test-label-currency.R
index 9b804638..cdb23d7c 100644
--- a/tests/testthat/test-label-dollar.R
+++ b/tests/testthat/test-label-currency.R
@@ -1,5 +1,5 @@
 test_that("negative comes before prefix", {
-  expect_equal(label_dollar()(-1), "-$1")
+  expect_equal(label_currency()(-1), "-$1")
 })
 
 test_that("negative_parens is deprecated", {
@@ -10,21 +10,21 @@ test_that("negative_parens is deprecated", {
 })
 
 test_that("preserves NAs", {
-  expect_equal(label_dollar()(NA_real_), NA_character_)
+  expect_equal(label_currency()(NA_real_), NA_character_)
 })
 
 test_that("preserves names", {
-  expect_named(label_dollar()(c(a = 1)), "a")
+  expect_named(label_currency()(c(a = 1)), "a")
 })
 
 test_that("decimal.mark could be modified", {
-  expect_equal(label_dollar(decimal.mark = ",")(123.45), "$123,45")
+  expect_equal(label_currency(decimal.mark = ",")(123.45), "$123,45")
 })
 
 test_that("can rescale with scale_cut", {
-  lab <- label_dollar(scale_cut = cut_short_scale())
+  lab <- label_currency(scale_cut = cut_short_scale())
   expect_equal(lab(c(1, 1e3, 1e6)), c("$1", "$1K", "$1M"))
 
-  lab <- label_dollar(scale_cut = cut_short_scale(), prefix = "", suffix = " USD")
+  lab <- label_currency(scale_cut = cut_short_scale(), prefix = "", suffix = " USD")
   expect_equal(lab(c(1, 1e3, 1e6)), c("1 USD", "1K USD", "1M USD"))
 })