Export number_hdx for users

NAMESPACE

@@ -20,6 +20,7 @@ export(hdx_pal_sapphire)
 export(hdx_pal_tomato)
 export(label_number_hdx)
 export(load_source_sans_3)
+export(number_hdx)
 export(scale_color_gradient2_hdx)
 export(scale_color_gradient_hdx)
 export(scale_color_gradient_hdx_mint)

NEWS.md

@@ -1,5 +1,8 @@
 # gghdx (development version)
 
+- Export `number_hdx()` to provide users simple access to number formatting
+outside the labeling use case.
+
 # gghdx 0.1.3
 
 - Implement `label_number_hdx()` function to improve numeric scales labeling

R/label_number_hdx.R

@@ -1,4 +1,10 @@
-#' Label numbers in HDX key figures style
+#' Format and labels numbers in HDX key figures style
+#'
+#' Use `number_hdx()` directly on numeric vectors, and use `label_number_hdx()`
+#' in the same way as the `scales::` family of label functions. The return value of
+#' `label_number_hdx()` is a function, based on the `additional_prefix`. So you
+#' should pass it in to `scales_...()` `labels` parameter in the same way as
+#' `scales_...()`
 #'
 #' Formats numeric vector in the Centre style for key figures, which abbreviates
 #' numbers 1,000 and above to X.YK, 10,000 and above to XYK, 100,000 and above
@@ -14,20 +20,17 @@
 #' manners. Also ensures that rounding is performed so numbers look correct.
 #' Not to be used for percents, which should just use [scales::label_percent()].
 #'
-#' Designed like the `scales::` family of label functions, the return value of
-#' `label_number_hdx` is a function, based on the `additional_prefix`. So you
-#' should pass it in to `scales_...()` `labels` parameter in the same way as
-#' `scales_...()`
-#'
 #' @param additional_prefix Additional prefix to add to string, that will come
 #'     between `sign_prefix` and the number. For example, `"$"` could produce a
 #'     return value of `-$1.1K`.
 #'
-#' @returns Returns a "labelling" function, in the same way as `scales::label_...()`
+#' @returns `label_number_hdx()`: "labelling" function, in the same way as `scales::label_...()`
 #'     functions work, i.e. a function that takes `x` and returns a labelled character
 #'     vector of `length(x)`.
 #'
 #' @examples
+#' # label_number_hdx()
+#'
 #' library(ggplot2)
 #'
 #' # discrete scaling
@@ -49,6 +52,8 @@
 #'     labels = label_number_hdx()
 #'   )
 #'
+#' @rdname number_hdx
+#'
 #' @export
 label_number_hdx <- function(additional_prefix = "") {
   if (!is.character(additional_prefix) || length(additional_prefix) > 1) {
@@ -60,19 +65,28 @@ label_number_hdx <- function(additional_prefix = "") {
     )
   }
 
-  function(x) format_number_hdx(x = x, additional_prefix = additional_prefix)
+  function(x) number_hdx(x = x, additional_prefix = additional_prefix)
 }
 
 #' Format numbers in HDX style
 #'
-#' Does the formatting found in `label_number_hdx`.
-#'
-#' @inherit label_number_hdx params description details
+#' @inherit label_number_hdx  description details
 #'
 #' @param x Numeric vector to format
 #'
-#' @returns Character vector of formatted strings
-format_number_hdx <- function(x, additional_prefix) {
+#' @returns `number_hdx()`: Character vector of formatted strings
+#'
+#' @examples
+#' # number_hdx()
+#'
+#' x <- c(1234, 7654321)
+#' number_hdx(x)
+#' number_hdx(x, "$")
+#'
+#' @rdname number_hdx
+#'
+#' @export
+number_hdx <- function(x, additional_prefix = "") {
   if (!is.numeric(x)) {
     stop(
       "`x` must be numeric, not class ",

README.Rmd

@@ -41,7 +41,7 @@ starting from the y-axis.
 * `gghdx()` ensures plot for the session use HDX defaults for color and fill
 scales, uses `theme_hdx()` for all plots, and applies `scale_color_hdx_...()` and
 `scale_fill_hdx_...()`
-* `label_number_hdx()` supplements the `scales::label_...()` series of functions
+* `label_number_hdx()` and `number_hdx()` supplement the `scales::label_...()` series of functions
 to create labels for numbers in the HDX style.
 
 ## Installation

README.md

@@ -31,8 +31,9 @@ features. The key functionalities are:
 - `gghdx()` ensures plot for the session use HDX defaults for color and
   fill scales, uses `theme_hdx()` for all plots, and applies
   `scale_color_hdx_...()` and `scale_fill_hdx_...()`
-- `label_number_hdx()` supplements the `scales::label_...()` series of
-  functions to create labels for numbers in the HDX style.
+- `label_number_hdx()` and `number_hdx()` supplement the
+  `scales::label_...()` series of functions to create labels for numbers
+  in the HDX style.
 
 ## Installation