From 1f8f97b66b6715a49839af7683ae151c75b4067f Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 17 Apr 2019 22:53:49 -0400 Subject: [PATCH] Make several refactoring improvements to some `format_*()` functions (#244) * Add comment with a TODO * Refactor stmt in `fmt_percent()` * Remove unneeded stmt * Use different function call * Remove unneeded util function * Remove unneeded components in `switch()` * Remove unneeded util function * Remove extra space * Update several testthat tests * Make handling of parentheses consistent * Rename `paste_currency_str()` to be general * Use the `paste_symbol_str()` util fcn * Create a common `symbol_str` variable * Modify several testthat tests * Add the `perform_negative_formatting()` fcn * Simplify negative value formatting * Modify the `to_latex_math_mode()` fcn * Modify calls to `to_latex_math_mode()` * Incorporate `minus_mark` in `paste_symbol_str()` * Add a function factory for some `format_*()` fcns * Define the formatter `type` for some `format_*()` fcns * Remove `negative_val` arg in some `format_*()` fcns * Use the `num_formatter_factory()` fcn factory * Update help files using roxygen * Remove several unneeded testthat tests * Modify argument name * Update repeated function calls * Modify function name * Modify comment * Modify conditional statement * Update argument in function signature * Modify variable assignment * Modify function called * Update help file using roxygen * Update several testthat tests * Remove `x` from fcn signature * Modify roxygen documentation * Set default values * Reverse order of args in fcn signature * Update help file using roxygen * Add argument to fcn signature * Remove unneeded util function * Return early in certain circumstances * Reverse order of args in fcn signature * Use `x` in fcn body instead of `x_str_vals` * Add the `prettify_scientific_notation()` util fcn * Add a `force()` call for each arg * Refactor the `num_formatter_factory()` fcn * Avoid assigning the `type` variable * Call the `normalize_suffixing_inputs()` fcn * Modify all `num_formatter_factory()` calls * Modify two testthat tests * Modify roxygen documentation * Update help files using roxygen * Remove default `NULL` values in fcn signature * Apply series of transformations with `%>%` * Assign logical vector `x_vals_lt0` for reuse * Force all arguments using a list * Move references of `currency` to `symbol` * Use `symbol` in place of `currency` * Add roxygen documentation and comments * Modify roxygen documentation * Update help files using roxygen * Validate a non-NULL locale right away * Modify function name * Simplify signature of `num_fmt_factory()` * Extract variables from `var_list` * Add the `create_var_list()` util fcn * Remove unneeded code * Simplify transformations in function factory * Modify function signatures * Generate `sep|dec_mark` within function factory * Refactor several `fmt_*()` functions * Modify function signature * Use `num_fmt_factory_multi()` throughout * Add roxygen documentation * Remove the `contexts` arg * Refactor `fmt_*()` fcns * Refactor `fmt_*()` fcns * Tidy code and add roxygen documentation * Additional refactoring for `format_*()` functions (#260) * Get `minus_mark` just before usage * Get `parens_marks` just before usage * Get `symbol_str` just before usage --- R/format_data.R | 622 +++++++++++---------------- R/utils.R | 8 +- R/utils_formatters.R | 449 ++++++++++++++----- R/utils_general_str_formatting.R | 3 + man/data_color.Rd | 2 +- man/fmt.Rd | 10 +- man/fmt_currency.Rd | 47 +- man/fmt_date.Rd | 10 +- man/fmt_datetime.Rd | 12 +- man/fmt_markdown.Rd | 8 +- man/fmt_missing.Rd | 10 +- man/fmt_number.Rd | 44 +- man/fmt_passthrough.Rd | 12 +- man/fmt_percent.Rd | 39 +- man/fmt_scientific.Rd | 28 +- man/fmt_time.Rd | 11 +- man/tab_footnote.Rd | 2 +- man/tab_header.Rd | 2 +- man/tab_options.Rd | 2 +- man/tab_row_group.Rd | 2 +- man/tab_source_note.Rd | 2 +- man/tab_spanner.Rd | 2 +- man/tab_stubhead_label.Rd | 2 +- man/tab_style.Rd | 2 +- tests/testthat/test-fmt_currency.R | 6 +- tests/testthat/test-fmt_number.R | 9 - tests/testthat/test-fmt_percent.R | 14 +- tests/testthat/test-l_fmt_currency.R | 8 +- tests/testthat/test-l_fmt_number.R | 11 - tests/testthat/test-l_fmt_percent.R | 13 +- 30 files changed, 733 insertions(+), 659 deletions(-) diff --git a/R/format_data.R b/R/format_data.R index 1d6b566b36..9ff58d01ed 100644 --- a/R/format_data.R +++ b/R/format_data.R @@ -7,8 +7,6 @@ #' \itemize{ #' \item decimals: choice of the number of decimal places, option to drop #' trailing zeros, and a choice of the decimal symbol -#' \item negative values: choice of a negative sign or parentheses for values -#' less than zero #' \item digit grouping separators: options to enable/disable digit separators #' and provide a choice of separator symbol #' \item scaling: we can choose to scale targeted values by a multiplier value @@ -27,15 +25,15 @@ #' expression to the \code{rows} argument. See the Arguments section for more #' information on this. #' -#' @param data a table object that is created using the \code{\link{gt}()} +#' @param data A table object that is created using the \code{\link{gt}()} #' function. -#' @param columns the columns to format. Can either be a series of column names +#' @param columns The columns to format. Can either be a series of column names #' provided in \code{vars()}, a vector of column indices, or a helper function #' focused on selections. The select helper functions are: #' \code{\link{starts_with}()}, \code{\link{ends_with}()}, #' \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, #' and \code{\link{everything}()}. -#' @param rows optional rows to format. Not providing any value results in all +#' @param rows Optional rows to format. Not providing any value results in all #' rows in \code{columns} being formatted. Can either be a vector of row #' captions provided \code{c()}, a vector of row indices, or a helper function #' focused on selections. The select helper functions are: @@ -43,18 +41,18 @@ #' \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, #' and \code{\link{everything}()}. We can also use expressions to filter down #' to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}). -#' @param decimals an option to specify the exact number of decimal places to +#' @param decimals An option to specify the exact number of decimal places to #' use. The default number of decimal places is \code{2}. -#' @param drop_trailing_zeros a logical value that allows for removal of +#' @param drop_trailing_zeros A logical value that allows for removal of #' trailing zeros (those redundant zeros after the decimal mark). -#' @param negative_val the formatting to use for negative values. With -#' \code{signed} (the default), negative values will be shown with a negative -#' sign. Using \code{parens} will show the negative value in parentheses. -#' @param use_seps an option to use digit group separators. The type of digit +#' @param use_seps An option to use digit group separators. The type of digit #' group separator is set by \code{sep_mark} and overridden if a locale ID is #' provided to \code{locale}. This setting is \code{TRUE} by default. -#' @param scale_by a value to scale the input. The default is \code{1.0}. -#' @param suffixing an option to scale and apply suffixes to larger numbers +#' @param scale_by A value to scale the input. The default is \code{1.0}. All +#' numeric values will be multiplied by this value first before undergoing +#' formatting. This value will be ignored if using any of the \code{suffixing} +#' options (i.e., where \code{suffixing} is not set to \code{FALSE}). +#' @param suffixing An option to scale and apply suffixes to larger numbers #' (e.g., \code{1924000} can be transformed to \code{1.92M}). This option can #' accept a logical value, where \code{FALSE} (the default) will not perform #' this transformation and \code{TRUE} will apply thousands (\code{K}), @@ -69,21 +67,22 @@ #' numbers in the range of millions and billions will be in terms of #' millions). Any use of \code{suffixing} (where not \code{FALSE}) means that #' any value provided to \code{scale_by} will be ignored. -#' @param pattern a formatting pattern that allows for decoration of the +#' @param pattern A formatting pattern that allows for decoration of the #' formatted value. The value itself is represented by \code{{x}} and all #' other characters are taken to be string literals. -#' @param sep_mark the mark to use as a separator between groups of digits +#' @param sep_mark The mark to use as a separator between groups of digits #' (e.g., using \code{sep_mark = ","} with \code{1000} would result in a #' formatted value of \code{1,000}). -#' @param dec_mark the character to use as a decimal mark (e.g., using +#' @param dec_mark The character to use as a decimal mark (e.g., using #' \code{dec_mark = ","} with \code{0.152} would result in a formatted value #' of \code{0,152}). -#' @param locale an optional locale ID that can be used for formatting the value +#' @param locale An optional locale ID that can be used for formatting the value #' according the locale's rules. Examples include \code{"en_US"} for English #' (United States) and \code{"fr_FR"} for French (France). The use of a valid #' locale ID will override any values provided in \code{sep_mark} and -#' \code{dec_mark}. -#' @return an object of class \code{gt_tbl}. +#' \code{dec_mark}. We can use the \code{\link{info_locales}()} function as a +#' useful reference for all of the locales that are supported. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # format the `num` column as numeric @@ -132,7 +131,6 @@ fmt_number <- function(data, rows = NULL, decimals = 2, drop_trailing_zeros = FALSE, - negative_val = "signed", use_seps = TRUE, scale_by = 1.0, suffixing = FALSE, @@ -145,83 +143,13 @@ fmt_number <- function(data, sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps) dec_mark <- get_locale_dec_mark(locale, dec_mark) + # Stop function if `locale` does not have a valid value + validate_locale(locale) + # Normalize the `suffixing` input to either return a character vector # of suffix labels, or NULL (the case where `suffixing` is FALSE) suffix_labels <- normalize_suffixing_inputs(suffixing, scale_by) - # Create a function factory for the `fmt_number()` function - fmt_number_factory <- function(context = "html") { - - function(x) { - - # Define the marks by context - minus_mark <- context_minus_mark(context) - parens_marks <- context_parens_marks_number(context) - - # Determine which of `x` are not NA - non_na_x <- !is.na(x) - - # Create a possibly shorter vector of non-NA `x` values - x_vals <- x[non_na_x] - - # Create a tibble with scaled values for `x[non_na_x]` - # and the suffix labels to use for character formatting - suffix_df <- - num_suffix( - round(x_vals, decimals), - suffixes = suffix_labels, - scale_by = scale_by - ) - - # Scale the `x_vals` by the `scale_by` value - x_vals <- scale_x_values(x_vals, scale_by = suffix_df$scale_by) - - # Format all non-NA x values - x_str_vals <- - format_num_to_str( - x_vals, decimals, sep_mark, dec_mark, drop_trailing_zeros - ) - - # Paste vector of suffixes to the right of the `x_str_vals` - x_str_vals <- paste_right(x_str_vals, suffix_df$suffix) - - # Perform negative value formatting - if (any(x_vals < 0)) { - - # Handle replacement of the minus mark - x_str_vals <- - x_str_vals %>% - tidy_gsub("-", minus_mark, fixed = TRUE) - - # Handle case where negative values are to be placed within parentheses - if (negative_val == "parens") { - - # Selectively remove minus sign and paste between parentheses - x_str_vals[x_vals < 0] <- - paste_between( - x = gsub(paste0("^", minus_mark), "", x_str_vals[x_vals < 0]), - x_2 = parens_marks - ) - } - } - - # If in a LaTeX context, remove any double negative - # signs in the exponent - if (context == "latex") { - x_str_vals <- to_latex_math_mode(x_str_vals) - } - - # Handle formatting of pattern - x_str_vals <- apply_pattern_fmt_x(pattern, x_str_vals) - - # Create `x_str` with the same length as `x`; place the - # `x_str_vals` into `str` (at the non-NA indices) - x_str <- rep(NA_character_, length(x)) - x_str[non_na_x] <- x_str_vals - x_str - } - } - # Capture expression in `rows` and `columns` rows <- rlang::enquo(rows) columns <- rlang::enquo(columns) @@ -232,10 +160,27 @@ fmt_number <- function(data, data = data, columns = !!columns, rows = !!rows, - fns = list( - html = fmt_number_factory(context = "html"), - latex = fmt_number_factory(context = "latex"), - default = fmt_number_factory(context = "default") + fns = num_fmt_factory_multi( + pattern = pattern, + format_fn = function(x, context) { + + x_str <- character(length(x)) + + # Create the `suffix_df` object + suffix_df <- create_suffix_df(x, decimals, suffix_labels, scale_by) + + x %>% + # Scale the `x_vals` by the `scale_by` values + scale_x_values(suffix_df$scale_by) %>% + # Format numeric values to character-based numbers + format_num_to_str( + context = context, decimals = decimals, sep_mark = sep_mark, + dec_mark = dec_mark, drop_trailing_zeros = drop_trailing_zeros + ) %>% + # With large-number suffixing support, we paste the + # vector of suffixes to the right of the values + paste_right(suffix_df$suffix) + } ) ) } @@ -263,7 +208,7 @@ fmt_number <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # format the `num` column as partially @@ -302,82 +247,120 @@ fmt_scientific <- function(data, dec_mark = ".", locale = NULL) { + # Set default values + suffixing <- FALSE + use_seps <- TRUE + # Use locale-based marks if a locale ID is provided - sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps = TRUE) + sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps) dec_mark <- get_locale_dec_mark(locale, dec_mark) - # Create a function factory for the `fmt_scientific()` function - fmt_scientific_factory <- function(context = "html") { + # Stop function if `locale` does not have a valid value + validate_locale(locale) - function(x) { + # Normalize the `suffixing` input to either return a character vector + # of suffix labels, or NULL (the case where `suffixing` is FALSE) + suffix_labels <- normalize_suffixing_inputs(suffixing, scale_by) - # Define the marks by context - minus_mark <- context_minus_mark(context) - exp_marks <- context_exp_marks(context) + # Capture expression in `rows` and `columns` + rows <- rlang::enquo(rows) + columns <- rlang::enquo(columns) - # Determine which of `x` are not NA - non_na_x <- !is.na(x) + # Pass `data`, `columns`, `rows`, and the formatting + # functions as a function list to `fmt()` + fmt( + data = data, + columns = !!columns, + rows = !!rows, + fns = num_fmt_factory_multi( + pattern = pattern, + format_fn = function(x, context) { - # Create a possibly shorter vector of non-NA `x` values - x_vals <- x[non_na_x] + # Define the marks by context + exp_marks <- context_exp_marks(context) + minus_mark <- context_minus_mark(context) - # Scale the `x_vals` by the `scale_by` value - x_vals <- scale_x_values(x_vals, scale_by) + # Define the `replace_minus()` function + replace_minus <- function(x) { + x %>% tidy_gsub("-", minus_mark, fixed = TRUE) + } - # Determine which of `x` don't require the (x 10^n) - # since their order would be zero - small_pos <- has_order_zero(x_vals) + # Create the `suffix_df` object + suffix_df <- create_suffix_df(x, decimals, suffix_labels, scale_by) - # Format all non-NA x values - x_str_vals <- - format_num_to_str_e( - x_vals, decimals, sep_mark, dec_mark, - drop_trailing_zeros - ) + # Scale the `x_vals` by the `scale_by` values + x <- x %>% scale_x_values(suffix_df$scale_by) - # For any numbers that shouldn't have an exponent, remove - # that portion from the character version - if (any(small_pos)) { + x_str <- + x %>% + # Format numeric values to character-based numbers + format_num_to_str( + context = context, decimals = decimals, sep_mark = sep_mark, + dec_mark = dec_mark, drop_trailing_zeros = drop_trailing_zeros, + format = "e", replace_minus_mark = FALSE + ) - x_str_vals[small_pos] <- - split_scientific_notn(x_str_vals[small_pos])$num - } + # # Determine which values don't require the (x 10^n) + # # for scientific foramtting since their order would be zero + small_pos <- has_order_zero(x) - # For any non-NA numbers that do have an exponent, format - # those according to the output context - if (any(!small_pos)) { + # For any numbers that shouldn't have an exponent, remove + # that portion from the character version + x_str[small_pos] <- + split_scientific_notn(x_str[small_pos])$num %>% + replace_minus() - sci_parts <- split_scientific_notn(x_str_vals[!small_pos]) + # For any non-NA numbers that do have an exponent, format + # those according to the output context + sci_parts <- split_scientific_notn(x_str[!small_pos]) - x_str_vals[!small_pos] <- + x_str[!small_pos] <- paste0( - sci_parts$num, exp_marks[1], - sci_parts$exp, exp_marks[2] + sci_parts$num %>% replace_minus(), + exp_marks[1], + sci_parts$exp %>% replace_minus(), + exp_marks[2] ) + + x_str } + ) + ) +} - # Handle replacement of the minus mark in number - # and exponent parts - x_str_vals <- - x_str_vals %>% - tidy_gsub("-", minus_mark, fixed = TRUE) +#' Format values to take a predefined symbol +#' +#' @inheritParams fmt_number +#' @inheritParams fmt_currency +#' @return An object of class \code{gt_tbl}. +#' @noRd +fmt_symbol <- function(data, + columns, + rows = NULL, + symbol = "*", + accounting = FALSE, + decimals = NULL, + drop_trailing_zeros = FALSE, + use_seps = TRUE, + scale_by = 1.0, + suffixing = FALSE, + pattern = "{x}", + sep_mark = ",", + dec_mark = ".", + placement = "left", + incl_space = FALSE, + locale = NULL) { - # If in a LaTeX context, put formatted numbers - # in math mode - if (context == "latex") { - x_str_vals <- to_latex_math_mode(x_str_vals) - } + # Use locale-based marks if a locale ID is provided + sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps) + dec_mark <- get_locale_dec_mark(locale, dec_mark) - # Handle formatting of pattern - x_str_vals <- apply_pattern_fmt_x(pattern, x_str_vals) + # Stop function if `locale` does not have a valid value + validate_locale(locale) - # Create `x_str` with the same length as `x`; place the - # `x_str_vals` into `str` (at the non-NA indices) - x_str <- rep(NA_character_, length(x)) - x_str[non_na_x] <- x_str_vals - x_str - } - } + # Normalize the `suffixing` input to either return a character vector + # of suffix labels, or NULL (the case where `suffixing` is FALSE) + suffix_labels <- normalize_suffixing_inputs(suffixing, scale_by) # Capture expression in `rows` and `columns` rows <- rlang::enquo(rows) @@ -389,10 +372,64 @@ fmt_scientific <- function(data, data = data, columns = !!columns, rows = !!rows, - fns = list( - html = fmt_scientific_factory(context = "html"), - latex = fmt_scientific_factory(context = "latex"), - default = fmt_scientific_factory(context = "default") + fns = num_fmt_factory_multi( + pattern = pattern, + format_fn = function(x, context) { + + # Create the `x_str` vector + x_str <- character(length(x)) + + # Create the `suffix_df` object + suffix_df <- create_suffix_df(x, decimals, suffix_labels, scale_by) + + # Scale the `x_vals` by the `scale_by` value + x <- x %>% scale_x_values(suffix_df$scale_by) + + is_negative_x <- x < 0 + is_not_negative_x <- !is_negative_x + + if (any(is_not_negative_x)) { + + x_str[is_not_negative_x] <- + x[is_not_negative_x] %>% + # Format numeric values to character-based numbers + format_num_to_str_c( + context = context, decimals = decimals, sep_mark = sep_mark, + dec_mark = dec_mark, drop_trailing_zeros = drop_trailing_zeros + ) + } + + x_abs_str <- x_str + + if (any(is_negative_x)) { + + x_abs_str[is_negative_x] <- + x[is_negative_x] %>% + abs() %>% + # Format numeric values to character-based numbers + format_num_to_str_c( + context = context, decimals = decimals, sep_mark = sep_mark, + dec_mark = dec_mark, drop_trailing_zeros = drop_trailing_zeros + ) + } + + x_str <- + # Format values with a symbol string + format_symbol_str( + context = context, x_abs_str = x_abs_str, x = x, + symbol = symbol, incl_space = incl_space, + placement = placement + ) %>% + # Format values in accounting style + format_as_accounting( + x = x, context = context, accounting = accounting + ) %>% + # With large-number suffixing support, we paste the + # vector of suffixes to the right of the values + paste_right(suffix_df$suffix) + + x_str + } ) ) } @@ -410,8 +447,6 @@ fmt_scientific <- function(data, #' value. #' \item decimals: choice of the number of decimal places, option to drop #' trailing zeros, and a choice of the decimal symbol -#' \item negative values: choice of a negative sign or parentheses for values -#' less than zero #' \item digit grouping separators: options to enable/disable digit separators #' and provide a choice of separator symbol #' \item pattern: option to use a text pattern for decoration of the formatted @@ -428,9 +463,9 @@ fmt_scientific <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param incl_space an option on whether to include a space between the value +#' @param incl_space An option for whether to include a space between the value #' and the percent sign. The default is to not introduce a space character. -#' @param placement the placement of the percent sign. This can be either be +#' @param placement The placement of the percent sign. This can be either be #' \code{right} (the default) or \code{left}. #' @return an object of class \code{gt_tbl}. #' @examples @@ -459,7 +494,6 @@ fmt_percent <- function(data, rows = NULL, decimals = 2, drop_trailing_zeros = FALSE, - negative_val = "signed", use_seps = TRUE, pattern = "{x}", sep_mark = ",", @@ -468,103 +502,27 @@ fmt_percent <- function(data, placement = "right", locale = NULL) { - # Use locale-based marks if a locale ID is provided - sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps) - dec_mark <- get_locale_dec_mark(locale, dec_mark) - - # Create a function factory for the `fmt_percent()` function - fmt_percent_factory <- function(context = "html") { - - function(x) { - - # Define the marks by context - minus_mark <- context_minus_mark(context) - percent_mark <- context_percent_mark(context) - parens_marks <- context_parens_marks(context) - - # Determine which of `x` are not NA - non_na_x <- !is.na(x) - - # Create a possibly shorter vector of non-NA `x` values - x_vals <- x[non_na_x] - - # Scale the `x_vals` by the `scale_by` value - x_vals <- scale_x_values(x_vals, scale_by = 100) - - # Format all non-NA x values - x_str_vals <- - format_num_to_str( - x_vals, decimals, sep_mark, dec_mark, drop_trailing_zeros - ) - - # Handle placement of the percent symbol - x_str_vals <- - x_str_vals %>% - paste_on_side( - x_side = ifelse(incl_space, " ", ""), - direction = placement - ) %>% - paste_on_side( - x_side = percent_mark, - direction = placement - ) %>% - swap_adjacent_text_groups( - pattern_1 = percent_mark, - pattern_2 = "-" - ) - - # Perform negative value formatting - if (any(x_vals < 0)) { - - # Handle replacement of the minus mark - x_str_vals <- - x_str_vals %>% - tidy_gsub("-", minus_mark, fixed = TRUE) - - # Handle case where negative values are to be placed within parentheses - if (negative_val == "parens") { - - # Selectively remove minus sign and paste between parentheses - x_str_vals[x_vals < 0] <- - paste_between( - x = gsub(paste0("^", minus_mark), "", x_str_vals[x_vals < 0]), - x_2 = parens_marks - ) - } - } - - # If in a LaTeX context, remove any double negative - # signs in the exponent - if (context == "latex") { - x_str_vals <- to_latex_math_mode(x_str_vals) - } - - # Handle formatting of pattern - x_str_vals <- apply_pattern_fmt_x(pattern, x_str_vals) - - # Create `x_str` with the same length as `x`; place the - # `x_str_vals` into `str` (at the non-NA indices) - x_str <- rep(NA_character_, length(x)) - x_str[non_na_x] <- x_str_vals - x_str - } - } - # Capture expression in `rows` and `columns` rows <- rlang::enquo(rows) columns <- rlang::enquo(columns) - # Pass `data`, `columns`, `rows`, and the formatting - # functions as a function list to `fmt()` - fmt( + fmt_symbol( data = data, columns = !!columns, rows = !!rows, - fns = list( - html = fmt_percent_factory(context = "html"), - latex = fmt_percent_factory(context = "latex"), - default = fmt_percent_factory(context = "default") - ) + symbol = "%", + accounting = FALSE, + decimals = decimals, + drop_trailing_zeros = drop_trailing_zeros, + use_seps = use_seps, + scale_by = 100, + suffixing = FALSE, + pattern = pattern, + sep_mark = sep_mark, + dec_mark = dec_mark, + placement = placement, + incl_space = incl_space, + locale = locale ) } @@ -607,7 +565,7 @@ fmt_percent <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param currency the currency to use for the numeric value. This input can be +#' @param currency The currency to use for the numeric value. This input can be #' supplied as a 3-letter currency code (e.g., \code{"USD"} for U.S. Dollars, #' \code{"EUR"} for the Euro currency). Use \code{\link{info_currencies}()} to #' get an information table with all of the valid currency codes and examples @@ -617,13 +575,17 @@ fmt_percent <- function(data, #' "symbol"} option to view an information table with all of the supported #' currency symbol names along with examples. If nothing is provided then #' \code{"USD"} will be used. -#' @param use_subunits an option for whether the subunits portion of a currency +#' @param use_subunits An option for whether the subunits portion of a currency #' value should be displayed. -#' @param placement the placement of the currency symbol. This can be either be +#' @param accounting An option to use accounting style for currency values. With +#' \code{FALSE} (the default), negative values will be shown with a negative +#' sign. Using \code{accounting = TRUE} will put negative values in +#' parentheses. +#' @param placement The placement of the currency symbol. This can be either be #' \code{left} (the default) or \code{right}. -#' @param incl_space an option on whether to include a space between the value +#' @param incl_space An option for whether to include a space between the value #' and the currency symbol. The default is to not introduce a space character. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # format the `currency` column to have @@ -666,7 +628,7 @@ fmt_currency <- function(data, rows = NULL, currency = "USD", use_subunits = TRUE, - negative_val = "signed", + accounting = FALSE, decimals = NULL, use_seps = TRUE, scale_by = 1.0, @@ -678,118 +640,33 @@ fmt_currency <- function(data, incl_space = FALSE, locale = NULL) { - # Use locale-based marks if a locale ID is provided - sep_mark <- get_locale_sep_mark(locale, sep_mark, use_seps) - dec_mark <- get_locale_dec_mark(locale, dec_mark) + # Capture expression in `rows` and `columns` + rows <- rlang::enquo(rows) + columns <- rlang::enquo(columns) # Stop function if `currency` does not have a valid value - validate_currency(currency) + validate_currency(currency = currency) # Get the number of decimal places - decimals <- get_currency_decimals(currency, decimals, use_subunits) - - # Normalize the `suffixing` input to either return a character vector - # of suffix labels, or NULL (the case where `suffixing` is FALSE) - suffix_labels <- normalize_suffixing_inputs(suffixing, scale_by) - - # Create a function factory for the `fmt_currency()` function - fmt_currency_factory <- function(context = "html") { - - function(x) { - - # Define the marks by context - negative_currency_mark <- context_negative_currency_mark(context) - currency_str <- context_currency_str(context, currency) - currency_str_regex <- context_currency_str_regex(context) - parens_marks <- context_parens_marks(context) - - # Determine which of `x` are not NA - non_na_x <- !is.na(x) - - # Create a possibly shorter vector of non-NA `x` values - x_vals <- x[non_na_x] - - # Create a tibble with scaled values for `x[non_na_x]` - # and the suffix labels to use for character formatting - suffix_df <- - num_suffix( - round(x_vals, decimals), - suffixes = suffix_labels, - scale_by = scale_by - ) - - # Scale the `x_vals` by the `scale_by` value - x_vals <- scale_x_values(x_vals, scale_by = suffix_df$scale_by) - - # Format all non-NA x values - x_str_vals <- format_num_to_str_c(x_vals, decimals, sep_mark, dec_mark) - - # Paste vector of suffixes to the right of the `x_str_vals` - x_str_vals <- paste_right(x_str_vals, suffix_df$suffix) - - # Handle placement of the currency symbol - x_str_vals <- - x_str_vals %>% - paste_currency_str(currency_str, incl_space, placement) - - # Perform negative value formatting - if (any(x_vals < 0)) { - - # Handle replacement of the minus mark - x_str_vals <- - x_str_vals %>% - tidy_gsub("-", negative_currency_mark, fixed = TRUE) - - # Handle case where negative values are to be placed within parentheses - if (negative_val == "parens") { - - # Selectively remove minus sign and paste between parentheses - x_str_vals[x_vals < 0] <- - paste_between( - x = x_str_vals[x_vals < 0] %>% - tidy_gsub( - negative_currency_mark, "", - fixed = TRUE - ), - x_2 = parens_marks - ) - } - } - - # If in a LaTeX context, wrap values in math mode - if (context == "latex") { - - x_str_vals <- - x_str_vals %>% - to_latex_math_mode() - } - - # Handle formatting of pattern - x_str_vals <- apply_pattern_fmt_x(pattern, x_str_vals) + decimals <- get_currency_decimals(currency = currency, decimals, use_subunits) - # Create `x_str` with the same length as `x`; place the - # `x_str_vals` into `str` (at the non-NA indices) - x_str <- rep(NA_character_, length(x)) - x_str[non_na_x] <- x_str_vals - x_str - } - } - - # Capture expression in `rows` and `columns` - rows <- rlang::enquo(rows) - columns <- rlang::enquo(columns) - - # Pass `data`, `columns`, `rows`, and the formatting - # functions as a function list to `fmt()` - fmt( + fmt_symbol( data = data, columns = !!columns, rows = !!rows, - fns = list( - html = fmt_currency_factory(context = "html"), - latex = fmt_currency_factory(context = "latex"), - default = fmt_currency_factory(context = "default") - ) + symbol = currency, + accounting = accounting, + decimals = decimals, + drop_trailing_zeros = FALSE, + use_seps = use_seps, + scale_by = scale_by, + suffixing = suffixing, + pattern = pattern, + sep_mark = sep_mark, + dec_mark = dec_mark, + placement = placement, + incl_space = incl_space, + locale = locale ) } @@ -833,11 +710,11 @@ fmt_currency <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param date_style the date style to use. Supply a number (from \code{1} to +#' @param date_style The date style to use. Supply a number (from \code{1} to #' \code{14}) that corresponds to the preferred date style. Use #' \code{\link{info_date_style}()} to see the different numbered and named date #' presets. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `date` and `time` columns; @@ -948,10 +825,11 @@ fmt_date <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param time_style the time style to use. Supply a number (from \code{1} to +#' @param time_style The time style to use. Supply a number (from \code{1} to #' \code{5}) that corresponds to the preferred time style. Use #' \code{\link{info_time_style}()} to see the different numbered and named time #' presets. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `date` and `time` columns; @@ -1082,7 +960,7 @@ fmt_time <- function(data, #' @inheritParams fmt_number #' @inheritParams fmt_date #' @inheritParams fmt_time -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `datetime` column; @@ -1155,7 +1033,7 @@ fmt_datetime <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Create a few Markdown-based #' # text snippets @@ -1257,13 +1135,13 @@ fmt_markdown <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param escape an option to escape text according to the final output format +#' @param escape An option to escape text according to the final output format #' of the table. For example, if a LaTeX table is to be generated then LaTeX #' escaping would be performed during rendering. By default this is set to #' \code{TRUE} and setting to \code{FALSE} is useful in the case where #' LaTeX-formatted text should be passed through to the output LaTeX table #' unchanged. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # keep only the `char` column; @@ -1373,9 +1251,9 @@ fmt_passthrough <- function(data, #' information on this. #' #' @inheritParams fmt_number -#' @param missing_text the text to be used in place of \code{NA} values in the +#' @param missing_text The text to be used in place of \code{NA} values in the #' rendered table. -#' @return an object of class \code{gt_tbl}. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # NA values in different columns will @@ -1470,8 +1348,8 @@ fmt_missing <- function(data, #' \code{rows} argument. See the Arguments section for more information on this. #' #' @inheritParams fmt_number -#' @param fns a single formatting function or a named list of functions. -#' @return an object of class \code{gt_tbl}. +#' @param fns Either a single formatting function or a named list of functions. +#' @return An object of class \code{gt_tbl}. #' @examples #' # Use `exibble` to create a gt table; #' # format the numeric values in the `num` diff --git a/R/utils.R b/R/utils.R index 5ac18e838e..07c31f5c27 100644 --- a/R/utils.R +++ b/R/utils.R @@ -372,13 +372,13 @@ markdown_to_text <- function(text) { #' final decoration of the formatted values. We use \pkg{glue}'s semantics here #' and reserve \code{x} to be the formatted values, and, we can use \code{x} #' multiple times in the pattern. -#' @param pattern A formatting pattern that allows for decoration of the -#' formatted value (defined here as \code{x}). #' @param values The values (as a character vector) that are formatted within #' the \code{fmt_*()} function. +#' @param pattern A formatting pattern that allows for decoration of the +#' formatted value (defined here as \code{x}). #' @noRd -apply_pattern_fmt_x <- function(pattern, - values) { +apply_pattern_fmt_x <- function(values, + pattern) { vapply( values, diff --git a/R/utils_formatters.R b/R/utils_formatters.R index 99c548b363..352ec85b03 100644 --- a/R/utils_formatters.R +++ b/R/utils_formatters.R @@ -2,11 +2,13 @@ #' #' @param table The table to filter down to one row. #' @param column The column from which the single value should be obtained. -#' @param ... The arguments passed to `dplyr::filter()` +#' @param ... The arguments passed to `dplyr::filter()`. #' @import rlang #' @importFrom dplyr filter #' @noRd -filter_table_to_value <- function(table, column, ...) { +filter_table_to_value <- function(table, + column, + ...) { filter_args_enquos <- rlang::enquos(...) column_enquo <- rlang::enquo(column) @@ -33,7 +35,7 @@ validate_locale <- function(locale) { # Stop function if the `locale` provided # isn't a valid one - if (!(locale %in% locales$base_locale_id)) { + if (!is.null(locale) && !(locale %in% locales$base_locale_id)) { stop("The supplied `locale` is not available in the list of supported locales.\n", " * Use the `info_locales()` function to see which locales can be used.", call. = FALSE) @@ -66,7 +68,6 @@ validate_currency <- function(currency) { #' functions. This is expected as `NULL` if not supplied by the user. #' @param default The default value for the `sep_mark`. #' @param use_seps A logical value for whether to use separators at all. -#' @importFrom dplyr filter pull #' @noRd get_locale_sep_mark <- function(locale = NULL, default, @@ -84,10 +85,6 @@ get_locale_sep_mark <- function(locale = NULL, return(default) } - # Stop function if the `locale` provided - # isn't a valid one - validate_locale(locale) - # Get the correct `group_sep` value from the # `gt:::locales` lookup table sep_mark <- @@ -106,7 +103,6 @@ get_locale_sep_mark <- function(locale = NULL, #' @param locale The user-supplied `locale` value, found in several `fmt_*()` #' functions. This is expected as `NULL` if not supplied by the user. #' @param default The default value for the `dec_mark`. -#' @importFrom dplyr filter pull #' @noRd get_locale_dec_mark <- function(locale = NULL, default) { @@ -117,10 +113,6 @@ get_locale_dec_mark <- function(locale = NULL, return(default) } - # Stop function if the `locale` provided - # isn't a valid one - validate_locale(locale) - # Get the correct `dec_sep` value from the # `gt:::locales` lookup table filter_table_to_value(locales, dec_sep, base_locale_id == locale) @@ -137,6 +129,12 @@ has_order_zero <- function(x) { ) & !is.na(x) } +#' Get the correct number of decimal places for a specified currency +#' +#' @param currency The currency to use for the numeric value. +#' @param decimals The request number of decimal places. +#' @param use_subunits An option for whether the subunits portion of a currency +#' value should be displayed. #' @noRd get_currency_decimals <- function(currency, decimals, @@ -191,47 +189,40 @@ scale_x_values <- function(x, #' A `formatC()` call for `fmt_number()` and `fmt_percent()` #' #' @param x A vector of numeric values. +#' @param context The output context. #' @param decimals The number of decimal places (`digits`). #' @param sep_mark The separator for number groups (`big.mark`). #' @param dec_mark The decimal separator mark (`decimal.mark`). -#' @param format The numeric format for `formatC()`. #' @param drop_trailing_zeros Option to exclude trailing decimal zeros. +#' @param format The numeric format for `formatC()`. +#' @param replace_minus_mark An option for whether the minus sign should be +#' replaced with the minus mark. #' @noRd format_num_to_str <- function(x, + context, decimals, sep_mark, dec_mark, drop_trailing_zeros, - format = "f") { - - formatC( - x = x, - digits = decimals, - mode = "double", - big.mark = sep_mark, - decimal.mark = dec_mark, - format = format, - drop0trailing = drop_trailing_zeros - ) -} - -#' A `formatC()` call for `fmt_scientific()` -#' -#' @inheritParams format_num_to_str -#' @noRd -format_num_to_str_e <- function(x, - decimals, - sep_mark, - dec_mark, - drop_trailing_zeros) { + format = "f", + replace_minus_mark = TRUE) { + + x_str <- + formatC( + x = x, + digits = decimals, + mode = "double", + big.mark = sep_mark, + decimal.mark = dec_mark, + format = format, + drop0trailing = drop_trailing_zeros + ) + + if (replace_minus_mark) { + x_str <- format_minus(x_str = x_str, x = x, context = context) + } - format_num_to_str( - x, - decimals, - sep_mark, - dec_mark, - format = "e", - drop_trailing_zeros) + x_str } #' A `formatC()` call for `fmt_currency()` @@ -239,28 +230,42 @@ format_num_to_str_e <- function(x, #' @inheritParams format_num_to_str #' @noRd format_num_to_str_c <- function(x, + context, decimals, sep_mark, - dec_mark) { + dec_mark, + drop_trailing_zeros = FALSE) { format_num_to_str( - x, - decimals, - sep_mark, - dec_mark, - format = "f", - drop_trailing_zeros = FALSE) + x = x, + context = context, + decimals = decimals, + sep_mark = sep_mark, + dec_mark = dec_mark, + drop_trailing_zeros = drop_trailing_zeros, + format = "f" + ) } #' Surround formatted values with `$`s for LaTeX #' +#' @param x Numeric values in `character` form. +#' @param context The output context. #' @noRd -to_latex_math_mode <- function (x) { +to_latex_math_mode <- function(x, + context) { - x %>% - paste_between(x_2 = c("$", "$")) + if (context != "latex") { + return(x) + } else { + return(x %>% paste_between(x_2 = c("$", "$"))) + } } +#' Obtain the contextually correct minus mark +#' +#' @param context The output context. +#' @noRd context_minus_mark <- function(context) { switch(context, @@ -268,29 +273,33 @@ context_minus_mark <- function(context) { "-") } -context_negative_currency_mark <- function(context) { +#' Obtain the contextually correct percent mark +#' +#' @param context The output context. +#' @noRd +context_percent_mark <- function(context) { switch(context, - html = "−", - "-") + html = "%", + latex = "\\%", + "%") } +#' Obtain the contextually correct pair of parentheses +#' +#' @param context The output context. +#' @noRd context_parens_marks <- function(context) { switch(context, - html = c("(", ")"), - latex = c("\\left(", "\\right)"), - c("(", ")")) -} - -context_parens_marks_number <- function(context) { - - switch(context, - html = c("(", ")"), latex = c("(", ")"), c("(", ")")) } +#' Obtain the contextually correct pair of opening/closing exponential strings +#' +#' @param context The output context. +#' @noRd context_exp_marks <- function(context) { switch(context, @@ -299,71 +308,293 @@ context_exp_marks <- function(context) { c(" x 10(", ")")) } -context_percent_mark <- function(context) { - switch(context, - html = "%", - latex = "\\%", - "%") -} - -context_currency_str_regex <- function(context) { +#' Obtain the contextually correct symbol string +#' +#' @param context The output context. +#' @param symbol A symbol, which could be empty (NULL), a percent sign (`%`), or +#' a currency symbol. +#' @noRd +context_symbol_str <- function(context, + symbol) { - switch(context, - latex = "\\\\$", - "\\$") -} + # If we supply `NULL` as `symbol`, then + # return an empty string + if (is.null(symbol)) { + return("") + } -context_currency_str <- function(context, currency) { + # If we supply a percent sign as `symbol`, + # get the contextually correct percent mark + if (symbol == "%") { + return(context_percent_mark(context)) + } + # Get the contextually correct currency string switch(context, html = { - get_currency_str(currency) + symbol %>% + get_currency_str() }, latex = { - currency %>% + symbol %>% get_currency_str(fallback_to_code = TRUE) %>% markdown_to_latex() %>% paste_between(x_2 = c("\\text{", "}")) }, { - currency %>% + symbol %>% get_currency_str(fallback_to_code = TRUE) }) } -paste_currency_str <- function(x, - currency_str, - incl_space, - placement) { - - vapply(FUN.VALUE = character(1), USE.NAMES = FALSE, x, function(x) { +#' Paste a symbol string to a formatted number +#' +#' @param x_abs_str Absolute numeric values in `character` form. +#' @param x Numeric values in `numeric` form. +#' @param context The output context. +#' @param symbol The symbol. +#' @param incl_space A logical value indicating whether a single space character +#' should separate the symbols and the formatted values. +#' @param placement Either `left` or `right` (this is the placement of the +#' symbol string relative to the formatted, numeric values). +#' @noRd +format_symbol_str <- function(x_abs_str, + x, + context, + symbol, + incl_space, + placement) { - if (grepl("^-", x)) { - x %>% - tidy_gsub("^-", "") %>% - paste_on_side( - x_side = ifelse(incl_space, " ", ""), - direction = placement - ) %>% - paste_on_side( - x_side = currency_str, - direction = placement - ) %>% - paste_left("-") + symbol_str <- context_symbol_str(context, symbol) - } else { + if (symbol_str == "") { + return(x_abs_str) + } - x %>% - paste_on_side( - x_side = ifelse(incl_space, " ", ""), - direction = placement - ) %>% - paste_on_side( - x_side = currency_str, - direction = placement - ) + vapply(FUN.VALUE = character(1), USE.NAMES = FALSE, seq_along(x), function(i) { + + # Using absolute value format, the minus mark will + # be added later + x_i <- x[i] + x_str_i <- x_abs_str[i] + + # Place possible space and symbol on correct side of value + x_str_i <- + x_str_i %>% + paste_on_side( + x_side = ifelse(incl_space, " ", ""), + direction = placement + ) %>% + paste_on_side( + x_side = symbol_str, + direction = placement + ) + + # Create the minus mark for the context + minus_mark <- context_minus_mark(context) + + # Place the `minus_mark` onto the formatted strings + if (x_i < 0) { + x_str_i <- + x_str_i %>% + paste_left(minus_mark) } + + x_str_i }) } + +#' Transform currency values to accounting style +#' +#' @param x_str Numeric values in `character` form. +#' @param x Numeric values in `numeric` form. +#' @param context The output context. +#' @noRd +format_minus <- function(x_str, + x, + context) { + + # Store logical vector of `x_vals` < 0 + x_lt0 <- x < 0 + + # Return values unchanged if there are no negative values + if (!any(x_lt0)) { + return(x_str) + } + + # Create the minus mark for the context + minus_mark <- context_minus_mark(context) + + # Handle replacement of the minus mark + x_str %>% tidy_gsub("-", minus_mark, fixed = TRUE) +} + +#' Transform currency values to accounting style +#' +#' @param x_str Numeric values in `character` form. +#' @param x Numeric values in `numeric` form. +#' @param context The output context. +#' @param accounting A logical value that indicates whether accounting style +#' should be used. +#' @noRd +format_as_accounting <- function(x_str, + x, + context, + accounting) { + + # TODO: Handle using `x_abs_str` instead + + # Store logical vector of `x` < 0 + x_lt0 <- x < 0 + + # Return values unchanged if there are no negative values + if (!any(x_lt0)) { + return(x_str) + } + + # Handle case where negative values are to be placed within parentheses + if (accounting) { + + # Create the minus and parens marks for the context + minus_mark <- context_minus_mark(context) + parens_marks <- context_parens_marks(context) + + # Selectively remove minus sign and paste between parentheses + x_str[x_lt0] <- + x_str[x_lt0] %>% + tidy_gsub(minus_mark, "", fixed = TRUE) %>% + paste_between(x_2 = parens_marks) + } + + x_str +} + +#' Provide a nicer format for numbers in scientific notation +#' +#' @param x Numeric values in `character` form. +#' @param context The output context. +#' @param small_pos A logical vector the length of `x` that indicates whether +#' values should be decorated. +#' @param exp_marks A character vector (length of two) that encloses the +#' exponential power value. +#' @noRd +prettify_scientific_notation <- function(x, + context, + small_pos, + exp_marks) { + + if (!any(grepl("e|E", x))) { + return(x) + } + + # For any numbers that shouldn't have an exponent, remove + # that portion from the character version + x[small_pos] <- + split_scientific_notn(x[small_pos])$num + + # For any non-NA numbers that do have an exponent, format + # those according to the output context + sci_parts <- split_scientific_notn(x[!small_pos]) + + x[!small_pos] <- + paste0( + sci_parts$num, exp_marks[1], + sci_parts$exp, exp_marks[2] + ) + + # Create the minus mark for the context + minus_mark <- context_minus_mark(context) + + # Handle replacement of the minus mark in number + # and exponent parts + x %>% + tidy_gsub("-", minus_mark, fixed = TRUE) +} + +#' Create the data frame with suffixes and scaling values +#' +#' @param x Numeric values in `numeric` form. +#' @param decimals The exact number of decimal places to be used in the +#' formatted numeric value. +#' @param suffix_labels The vector of suffix labels to use. +#' @param scale_by A value to scale the input. +#' @noRd +create_suffix_df <- function(x, + decimals, + suffix_labels, + scale_by) { + + # Create a tibble with scaled values for `x` and the + # suffix labels to use for character formatting + num_suffix( + round(x, decimals), + suffixes = suffix_labels, + scale_by = scale_by + ) +} + +#' Create a list of function calls for all numeric `fmt_*()` functions +#' +#' @param pattern The user-defined formatting pattern that allows for decoration +#' of the formatted value. +#' @param format_fn A function for formatting the numeric values. +#' @noRd +num_fmt_factory_multi <- function(pattern, + format_fn) { + + # Define the contexts + contexts <- c("html", "latex", "default") + + # Upgrade `contexts` to have names + names(contexts) <- contexts + + # Generate a named list of factory functions, with one + # component per context + lapply(contexts, function(x) { + num_fmt_factory(context = x, pattern = pattern, format_fn = format_fn) + }) +} + +#' A factory function used for all numeric `fmt_*()` functions +#' +#' @param context The output context. +#' @param pattern The user-defined formatting pattern that allows for decoration +#' of the formatted value. +#' @param format_fn A function for formatting the numeric values. +#' @noRd +num_fmt_factory <- function(context, + pattern, + format_fn) { + + # Force all arguments + force(context) + force(pattern) + force(format_fn) + + function(x) { + + # Determine which of `x` are not NA + non_na_x <- !is.na(x) + + # Create a possibly shorter vector of non-NA `x` values + x_vals <- x[non_na_x] + + # Apply a series of transformations to `x_str_vals` + x_str_vals <- + x_vals %>% + # Format all non-NA x values with a formatting function + format_fn(context) %>% + # If in a LaTeX context, wrap values in math mode + to_latex_math_mode(context) %>% + # Handle formatting of pattern + apply_pattern_fmt_x(pattern) + + # Create `x_str` with the same length as `x`; place the + # `x_str_vals` into `str` (at the non-NA indices) + x_str <- rep(NA_character_, length(x)) + x_str[non_na_x] <- x_str_vals + x_str + } +} diff --git a/R/utils_general_str_formatting.R b/R/utils_general_str_formatting.R index d35dfde4c8..404900324f 100644 --- a/R/utils_general_str_formatting.R +++ b/R/utils_general_str_formatting.R @@ -14,6 +14,9 @@ split_string_2 <- function(x, before = NULL, after = NULL) { + # TODO: use `split` instead of before/after and include + # a `dir` option (for "before" or "after" splitting) + # Stop function if `x` is not of class character if (!inherits(x, "character")) { stop("Internal error in `gt:::paste_within()`:\n", diff --git a/man/data_color.Rd b/man/data_color.Rd index 4afacd0416..69e8d5c709 100644 --- a/man/data_color.Rd +++ b/man/data_color.Rd @@ -8,7 +8,7 @@ data_color(data, columns, colors, alpha = NULL, apply_to = "bkgd", autocolor_text = TRUE) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{columns}{the columns wherein changes to cell data colors should occur.} diff --git a/man/fmt.Rd b/man/fmt.Rd index c168e3988c..7b3fc6fe21 100644 --- a/man/fmt.Rd +++ b/man/fmt.Rd @@ -7,17 +7,17 @@ fmt(data, columns = NULL, rows = NULL, fns) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -26,10 +26,10 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{fns}{a single formatting function or a named list of functions.} +\item{fns}{Either a single formatting function or a named list of functions.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ The \code{fmt()} function provides greater control in formatting raw data diff --git a/man/fmt_currency.Rd b/man/fmt_currency.Rd index 024cc14fe0..e828856699 100644 --- a/man/fmt_currency.Rd +++ b/man/fmt_currency.Rd @@ -5,23 +5,23 @@ \title{Format values as currencies} \usage{ fmt_currency(data, columns, rows = NULL, currency = "USD", - use_subunits = TRUE, negative_val = "signed", decimals = NULL, + use_subunits = TRUE, accounting = FALSE, decimals = NULL, use_seps = TRUE, scale_by = 1, suffixing = FALSE, pattern = "{x}", sep_mark = ",", dec_mark = ".", placement = "left", incl_space = FALSE, locale = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -30,7 +30,7 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{currency}{the currency to use for the numeric value. This input can be +\item{currency}{The currency to use for the numeric value. This input can be supplied as a 3-letter currency code (e.g., \code{"USD"} for U.S. Dollars, \code{"EUR"} for the Euro currency). Use \code{\link{info_currencies}()} to get an information table with all of the valid currency codes and examples @@ -41,23 +41,27 @@ process. Use \code{\link{info_currencies}()} with the \code{type == currency symbol names along with examples. If nothing is provided then \code{"USD"} will be used.} -\item{use_subunits}{an option for whether the subunits portion of a currency +\item{use_subunits}{An option for whether the subunits portion of a currency value should be displayed.} -\item{negative_val}{the formatting to use for negative values. With -\code{signed} (the default), negative values will be shown with a negative -sign. Using \code{parens} will show the negative value in parentheses.} +\item{accounting}{An option to use accounting style for currency values. With +\code{FALSE} (the default), negative values will be shown with a negative +sign. Using \code{accounting = TRUE} will put negative values in +parentheses.} -\item{decimals}{an option to specify the exact number of decimal places to +\item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} -\item{use_seps}{an option to use digit group separators. The type of digit +\item{use_seps}{An option to use digit group separators. The type of digit group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} -\item{scale_by}{a value to scale the input. The default is \code{1.0}.} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All +numeric values will be multiplied by this value first before undergoing +formatting. This value will be ignored if using any of the \code{suffixing} +options (i.e., where \code{suffixing} is not set to \code{FALSE}).} -\item{suffixing}{an option to scale and apply suffixes to larger numbers +\item{suffixing}{An option to scale and apply suffixes to larger numbers (e.g., \code{1924000} can be transformed to \code{1.92M}). This option can accept a logical value, where \code{FALSE} (the default) will not perform this transformation and \code{TRUE} will apply thousands (\code{K}), @@ -73,32 +77,33 @@ numbers in the range of millions and billions will be in terms of millions). Any use of \code{suffixing} (where not \code{FALSE}) means that any value provided to \code{scale_by} will be ignored.} -\item{pattern}{a formatting pattern that allows for decoration of the +\item{pattern}{A formatting pattern that allows for decoration of the formatted value. The value itself is represented by \code{{x}} and all other characters are taken to be string literals.} -\item{sep_mark}{the mark to use as a separator between groups of digits +\item{sep_mark}{The mark to use as a separator between groups of digits (e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value of \code{1,000}).} -\item{dec_mark}{the character to use as a decimal mark (e.g., using +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} -\item{placement}{the placement of the currency symbol. This can be either be +\item{placement}{The placement of the currency symbol. This can be either be \code{left} (the default) or \code{right}.} -\item{incl_space}{an option on whether to include a space between the value +\item{incl_space}{An option for whether to include a space between the value and the currency symbol. The default is to not introduce a space character.} -\item{locale}{an optional locale ID that can be used for formatting the value +\item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}.} +\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a +useful reference for all of the locales that are supported.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ With numeric values in a \pkg{gt} table, we can perform currency-based diff --git a/man/fmt_date.Rd b/man/fmt_date.Rd index 23cadcce35..413237405a 100644 --- a/man/fmt_date.Rd +++ b/man/fmt_date.Rd @@ -7,17 +7,17 @@ fmt_date(data, columns, rows = NULL, date_style = 2) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -26,13 +26,13 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{date_style}{the date style to use. Supply a number (from \code{1} to +\item{date_style}{The date style to use. Supply a number (from \code{1} to \code{14}) that corresponds to the preferred date style. Use \code{\link{info_date_style}()} to see the different numbered and named date presets.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Format input date values that are either of the \code{Date} type, or, are diff --git a/man/fmt_datetime.Rd b/man/fmt_datetime.Rd index e8d6984224..b778472de9 100644 --- a/man/fmt_datetime.Rd +++ b/man/fmt_datetime.Rd @@ -8,17 +8,17 @@ fmt_datetime(data, columns, rows = NULL, date_style = 2, time_style = 2) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -27,18 +27,18 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{date_style}{the date style to use. Supply a number (from \code{1} to +\item{date_style}{The date style to use. Supply a number (from \code{1} to \code{14}) that corresponds to the preferred date style. Use \code{\link{info_date_style}()} to see the different numbered and named date presets.} -\item{time_style}{the time style to use. Supply a number (from \code{1} to +\item{time_style}{The time style to use. Supply a number (from \code{1} to \code{5}) that corresponds to the preferred time style. Use \code{\link{info_time_style}()} to see the different numbered and named time presets.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Format input date-time values that are character-based and expressed diff --git a/man/fmt_markdown.Rd b/man/fmt_markdown.Rd index aa2cbd6cb6..c5b6e6acbb 100644 --- a/man/fmt_markdown.Rd +++ b/man/fmt_markdown.Rd @@ -7,17 +7,17 @@ fmt_markdown(data, columns, rows = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -27,7 +27,7 @@ and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Any Markdown-formatted text in the incoming cells will be transformed to the diff --git a/man/fmt_missing.Rd b/man/fmt_missing.Rd index cc0a1e0281..ad231fcdd7 100644 --- a/man/fmt_missing.Rd +++ b/man/fmt_missing.Rd @@ -7,17 +7,17 @@ fmt_missing(data, columns, rows = NULL, missing_text = "---") } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -26,11 +26,11 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{missing_text}{the text to be used in place of \code{NA} values in the +\item{missing_text}{The text to be used in place of \code{NA} values in the rendered table.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Wherever there is missing data (i.e., \code{NA} values) a customizable mark diff --git a/man/fmt_number.Rd b/man/fmt_number.Rd index 8deed2e2ed..da2129b4fe 100644 --- a/man/fmt_number.Rd +++ b/man/fmt_number.Rd @@ -5,22 +5,22 @@ \title{Format numeric values} \usage{ fmt_number(data, columns, rows = NULL, decimals = 2, - drop_trailing_zeros = FALSE, negative_val = "signed", - use_seps = TRUE, scale_by = 1, suffixing = FALSE, - pattern = "{x}", sep_mark = ",", dec_mark = ".", locale = NULL) + drop_trailing_zeros = FALSE, use_seps = TRUE, scale_by = 1, + suffixing = FALSE, pattern = "{x}", sep_mark = ",", + dec_mark = ".", locale = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -29,23 +29,22 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{decimals}{an option to specify the exact number of decimal places to +\item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} -\item{drop_trailing_zeros}{a logical value that allows for removal of +\item{drop_trailing_zeros}{A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).} -\item{negative_val}{the formatting to use for negative values. With -\code{signed} (the default), negative values will be shown with a negative -sign. Using \code{parens} will show the negative value in parentheses.} - -\item{use_seps}{an option to use digit group separators. The type of digit +\item{use_seps}{An option to use digit group separators. The type of digit group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} -\item{scale_by}{a value to scale the input. The default is \code{1.0}.} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All +numeric values will be multiplied by this value first before undergoing +formatting. This value will be ignored if using any of the \code{suffixing} +options (i.e., where \code{suffixing} is not set to \code{FALSE}).} -\item{suffixing}{an option to scale and apply suffixes to larger numbers +\item{suffixing}{An option to scale and apply suffixes to larger numbers (e.g., \code{1924000} can be transformed to \code{1.92M}). This option can accept a logical value, where \code{FALSE} (the default) will not perform this transformation and \code{TRUE} will apply thousands (\code{K}), @@ -61,26 +60,27 @@ numbers in the range of millions and billions will be in terms of millions). Any use of \code{suffixing} (where not \code{FALSE}) means that any value provided to \code{scale_by} will be ignored.} -\item{pattern}{a formatting pattern that allows for decoration of the +\item{pattern}{A formatting pattern that allows for decoration of the formatted value. The value itself is represented by \code{{x}} and all other characters are taken to be string literals.} -\item{sep_mark}{the mark to use as a separator between groups of digits +\item{sep_mark}{The mark to use as a separator between groups of digits (e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value of \code{1,000}).} -\item{dec_mark}{the character to use as a decimal mark (e.g., using +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} -\item{locale}{an optional locale ID that can be used for formatting the value +\item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}.} +\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a +useful reference for all of the locales that are supported.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ With numeric values in a \pkg{gt} table, we can perform number-based @@ -90,8 +90,6 @@ over numeric formatting with the following options: \itemize{ \item decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol -\item negative values: choice of a negative sign or parentheses for values -less than zero \item digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol \item scaling: we can choose to scale targeted values by a multiplier value diff --git a/man/fmt_passthrough.Rd b/man/fmt_passthrough.Rd index ccc171b502..889865bd27 100644 --- a/man/fmt_passthrough.Rd +++ b/man/fmt_passthrough.Rd @@ -8,17 +8,17 @@ fmt_passthrough(data, columns, rows = NULL, escape = TRUE, pattern = "{x}") } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -27,19 +27,19 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{escape}{an option to escape text according to the final output format +\item{escape}{An option to escape text according to the final output format of the table. For example, if a LaTeX table is to be generated then LaTeX escaping would be performed during rendering. By default this is set to \code{TRUE} and setting to \code{FALSE} is useful in the case where LaTeX-formatted text should be passed through to the output LaTeX table unchanged.} -\item{pattern}{a formatting pattern that allows for decoration of the +\item{pattern}{A formatting pattern that allows for decoration of the formatted value. The value itself is represented by \code{{x}} and all other characters are taken to be string literals.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ Format by passing data through no other transformation other than: (1) diff --git a/man/fmt_percent.Rd b/man/fmt_percent.Rd index e6722a6032..8a99e6969d 100644 --- a/man/fmt_percent.Rd +++ b/man/fmt_percent.Rd @@ -5,22 +5,22 @@ \title{Format values as a percentage} \usage{ fmt_percent(data, columns, rows = NULL, decimals = 2, - drop_trailing_zeros = FALSE, negative_val = "signed", - use_seps = TRUE, pattern = "{x}", sep_mark = ",", dec_mark = ".", - incl_space = FALSE, placement = "right", locale = NULL) + drop_trailing_zeros = FALSE, use_seps = TRUE, pattern = "{x}", + sep_mark = ",", dec_mark = ".", incl_space = FALSE, + placement = "right", locale = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -29,43 +29,40 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{decimals}{an option to specify the exact number of decimal places to +\item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} -\item{drop_trailing_zeros}{a logical value that allows for removal of +\item{drop_trailing_zeros}{A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).} -\item{negative_val}{the formatting to use for negative values. With -\code{signed} (the default), negative values will be shown with a negative -sign. Using \code{parens} will show the negative value in parentheses.} - -\item{use_seps}{an option to use digit group separators. The type of digit +\item{use_seps}{An option to use digit group separators. The type of digit group separator is set by \code{sep_mark} and overridden if a locale ID is provided to \code{locale}. This setting is \code{TRUE} by default.} -\item{pattern}{a formatting pattern that allows for decoration of the +\item{pattern}{A formatting pattern that allows for decoration of the formatted value. The value itself is represented by \code{{x}} and all other characters are taken to be string literals.} -\item{sep_mark}{the mark to use as a separator between groups of digits +\item{sep_mark}{The mark to use as a separator between groups of digits (e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value of \code{1,000}).} -\item{dec_mark}{the character to use as a decimal mark (e.g., using +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} -\item{incl_space}{an option on whether to include a space between the value +\item{incl_space}{An option for whether to include a space between the value and the percent sign. The default is to not introduce a space character.} -\item{placement}{the placement of the percent sign. This can be either be +\item{placement}{The placement of the percent sign. This can be either be \code{right} (the default) or \code{left}.} -\item{locale}{an optional locale ID that can be used for formatting the value +\item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}.} +\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a +useful reference for all of the locales that are supported.} } \value{ an object of class \code{gt_tbl}. @@ -82,8 +79,6 @@ before the values and a space can be inserted between the symbol and the value. \item decimals: choice of the number of decimal places, option to drop trailing zeros, and a choice of the decimal symbol -\item negative values: choice of a negative sign or parentheses for values -less than zero \item digit grouping separators: options to enable/disable digit separators and provide a choice of separator symbol \item pattern: option to use a text pattern for decoration of the formatted diff --git a/man/fmt_scientific.Rd b/man/fmt_scientific.Rd index 458ad5823f..28d7aa20f1 100644 --- a/man/fmt_scientific.Rd +++ b/man/fmt_scientific.Rd @@ -9,17 +9,17 @@ fmt_scientific(data, columns, rows = NULL, decimals = 2, sep_mark = ",", dec_mark = ".", locale = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -28,34 +28,38 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{decimals}{an option to specify the exact number of decimal places to +\item{decimals}{An option to specify the exact number of decimal places to use. The default number of decimal places is \code{2}.} -\item{drop_trailing_zeros}{a logical value that allows for removal of +\item{drop_trailing_zeros}{A logical value that allows for removal of trailing zeros (those redundant zeros after the decimal mark).} -\item{scale_by}{a value to scale the input. The default is \code{1.0}.} +\item{scale_by}{A value to scale the input. The default is \code{1.0}. All +numeric values will be multiplied by this value first before undergoing +formatting. This value will be ignored if using any of the \code{suffixing} +options (i.e., where \code{suffixing} is not set to \code{FALSE}).} -\item{pattern}{a formatting pattern that allows for decoration of the +\item{pattern}{A formatting pattern that allows for decoration of the formatted value. The value itself is represented by \code{{x}} and all other characters are taken to be string literals.} -\item{sep_mark}{the mark to use as a separator between groups of digits +\item{sep_mark}{The mark to use as a separator between groups of digits (e.g., using \code{sep_mark = ","} with \code{1000} would result in a formatted value of \code{1,000}).} -\item{dec_mark}{the character to use as a decimal mark (e.g., using +\item{dec_mark}{The character to use as a decimal mark (e.g., using \code{dec_mark = ","} with \code{0.152} would result in a formatted value of \code{0,152}).} -\item{locale}{an optional locale ID that can be used for formatting the value +\item{locale}{An optional locale ID that can be used for formatting the value according the locale's rules. Examples include \code{"en_US"} for English (United States) and \code{"fr_FR"} for French (France). The use of a valid locale ID will override any values provided in \code{sep_mark} and -\code{dec_mark}.} +\code{dec_mark}. We can use the \code{\link{info_locales}()} function as a +useful reference for all of the locales that are supported.} } \value{ -an object of class \code{gt_tbl}. +An object of class \code{gt_tbl}. } \description{ With numeric values in a \pkg{gt} table, we can perform formatting so that the diff --git a/man/fmt_time.Rd b/man/fmt_time.Rd index f3d52ecce9..7569b2af22 100644 --- a/man/fmt_time.Rd +++ b/man/fmt_time.Rd @@ -7,17 +7,17 @@ fmt_time(data, columns, rows = NULL, time_style = 2) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} -\item{columns}{the columns to format. Can either be a series of column names +\item{columns}{The columns to format. Can either be a series of column names provided in \code{vars()}, a vector of column indices, or a helper function focused on selections. The select helper functions are: \code{\link{starts_with}()}, \code{\link{ends_with}()}, \code{\link{contains}()}, \code{\link{matches}()}, \code{\link{one_of}()}, and \code{\link{everything}()}.} -\item{rows}{optional rows to format. Not providing any value results in all +\item{rows}{Optional rows to format. Not providing any value results in all rows in \code{columns} being formatted. Can either be a vector of row captions provided \code{c()}, a vector of row indices, or a helper function focused on selections. The select helper functions are: @@ -26,11 +26,14 @@ focused on selections. The select helper functions are: and \code{\link{everything}()}. We can also use expressions to filter down to the rows we need (e.g., \code{[colname_1] > 100 & [colname_2] < 50}).} -\item{time_style}{the time style to use. Supply a number (from \code{1} to +\item{time_style}{The time style to use. Supply a number (from \code{1} to \code{5}) that corresponds to the preferred time style. Use \code{\link{info_time_style}()} to see the different numbered and named time presets.} } +\value{ +An object of class \code{gt_tbl}. +} \description{ Format input time values that are character-based and expressed according to the ISO 8601 time format (\code{HH:MM:SS}). Once the appropriate data cells diff --git a/man/tab_footnote.Rd b/man/tab_footnote.Rd index 12e3aa46ca..d9644360da 100644 --- a/man/tab_footnote.Rd +++ b/man/tab_footnote.Rd @@ -7,7 +7,7 @@ tab_footnote(data, footnote, locations) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{footnote}{the text to be used in the footnote. We can optionally use diff --git a/man/tab_header.Rd b/man/tab_header.Rd index 32b6b29d35..9c76a43d97 100644 --- a/man/tab_header.Rd +++ b/man/tab_header.Rd @@ -7,7 +7,7 @@ tab_header(data, title, subtitle = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{title, subtitle}{text to be used in the table title and, optionally, for diff --git a/man/tab_options.Rd b/man/tab_options.Rd index 478e48f6ac..d7e22f59ec 100644 --- a/man/tab_options.Rd +++ b/man/tab_options.Rd @@ -35,7 +35,7 @@ tab_options(data, table.width = NULL, table.font.size = NULL, row.striping.include_table_body = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{table.width}{the width of the table. Can be specified as a diff --git a/man/tab_row_group.Rd b/man/tab_row_group.Rd index e8b82fde89..43c897fb26 100644 --- a/man/tab_row_group.Rd +++ b/man/tab_row_group.Rd @@ -7,7 +7,7 @@ tab_row_group(data, group = NULL, rows = NULL, others = NULL) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{group}{the name of the row group. This text will also serve as the row diff --git a/man/tab_source_note.Rd b/man/tab_source_note.Rd index 71a2f0f328..00467ad610 100644 --- a/man/tab_source_note.Rd +++ b/man/tab_source_note.Rd @@ -7,7 +7,7 @@ tab_source_note(data, source_note) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{source_note}{text to be used in the source note. We can optionally use diff --git a/man/tab_spanner.Rd b/man/tab_spanner.Rd index 9bd2ac9893..ccf94a1d4b 100644 --- a/man/tab_spanner.Rd +++ b/man/tab_spanner.Rd @@ -7,7 +7,7 @@ tab_spanner(data, label, columns, gather = TRUE) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{label}{the text to use for the spanner column label.} diff --git a/man/tab_stubhead_label.Rd b/man/tab_stubhead_label.Rd index c33bf45902..9e1156e9ad 100644 --- a/man/tab_stubhead_label.Rd +++ b/man/tab_stubhead_label.Rd @@ -7,7 +7,7 @@ tab_stubhead_label(data, label) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{label}{the text to be used as the stubhead label We can optionally diff --git a/man/tab_style.Rd b/man/tab_style.Rd index f9e70af555..5d0f9d6584 100644 --- a/man/tab_style.Rd +++ b/man/tab_style.Rd @@ -7,7 +7,7 @@ tab_style(data, style, locations) } \arguments{ -\item{data}{a table object that is created using the \code{\link{gt}()} +\item{data}{A table object that is created using the \code{\link{gt}()} function.} \item{style}{a vector of styles to use. The \code{\link{cells_styles}()} diff --git a/tests/testthat/test-fmt_currency.R b/tests/testthat/test-fmt_currency.R index bf41ff1f4f..a67d2e698a 100644 --- a/tests/testthat/test-fmt_currency.R +++ b/tests/testthat/test-fmt_currency.R @@ -141,10 +141,10 @@ test_that("the `fmt_currency()` function works correctly", { expect_equal( (tab %>% fmt_currency( - columns = "num_1", currency = "USD", negative_val = "parens") %>% + columns = "num_1", currency = "USD", accounting = TRUE) %>% render_formats_test("html"))[["num_1"]], c("$1,836.23", "$2,763.39", "$937.29", "$643.00", "$212.23", - "$0.00", "($23.24)") + "$0.00", "($23.24)") ) # Format the `num_1` column as USD, apply parentheses to all negative @@ -153,7 +153,7 @@ test_that("the `fmt_currency()` function works correctly", { expect_equal( (tab %>% fmt_currency( - columns = "num_1", currency = "USD", negative_val = "parens") %>% + columns = "num_1", currency = "USD", accounting = TRUE) %>% render_formats_test("default"))[["num_1"]], c("$1,836.23", "$2,763.39", "$937.29", "$643.00", "$212.23", "$0.00", "($23.24)") diff --git a/tests/testthat/test-fmt_number.R b/tests/testthat/test-fmt_number.R index f0541371b3..ceb126556e 100644 --- a/tests/testthat/test-fmt_number.R +++ b/tests/testthat/test-fmt_number.R @@ -110,15 +110,6 @@ test_that("the `fmt_number()` function works correctly", { render_formats_test("html"))[["num_1"]], c("1.836,23", "2.763,39", "937,29", "643,00", "212,23", "0,00", "−23,24")) - # Format the `num_1` column to 2 decimal places, apply parentheses to - # all negative values, use all other defaults; extract `output_df` and - # compare to expected values - expect_equal( - (tab %>% - fmt_number(columns = "num_1", decimals = 2, negative_val = "parens") %>% - render_formats_test("html"))[["num_1"]], - c("1,836.23", "2,763.39", "937.29", "643.00", "212.23", "0.00", "(23.24)")) - # Format the `num_1` column to 4 decimal places, scale all values by # 1/1000, use all other defaults; extract `output_df` and compare # to expected values diff --git a/tests/testthat/test-fmt_percent.R b/tests/testthat/test-fmt_percent.R index feb7f42f19..1264b17e2b 100644 --- a/tests/testthat/test-fmt_percent.R +++ b/tests/testthat/test-fmt_percent.R @@ -103,18 +103,6 @@ test_that("the `fmt_percent()` function works correctly", { "−2.324,00%") ) - # Format the `num_1` column to 2 decimal places, apply parentheses to - # all negative values, use all other defaults; extract `output_df` and - # compare to expected values - expect_equal( - (tab %>% - fmt_percent(columns = "num_1", decimals = 2, negative_val = "parens") %>% - render_formats_test("html"))[["num_1"]], - c("183,623.00%", "276,339.00%", "93,729.00%", - "64,300.00%", "21,223.20%", "0.00%", - "(2,324.00%)") - ) - # Format the `num_1` column to 2 decimal places, prepend and append # all values by 2 different literals, use all other defaults; extract # `output_df` and compare to expected values @@ -151,7 +139,7 @@ test_that("the `fmt_percent()` function works correctly", { render_formats_test("html"))[["num_1"]], c("% 183,623", "% 276,339", "% 93,729", "% 64,300", "% 21,223", "% 0", - "% −2,324") + "−% 2,324") ) # Format the `num_1` column to 2 decimal places, apply the `en_US` diff --git a/tests/testthat/test-l_fmt_currency.R b/tests/testthat/test-l_fmt_currency.R index 8fe17bbdeb..32f0994fb4 100644 --- a/tests/testthat/test-l_fmt_currency.R +++ b/tests/testthat/test-l_fmt_currency.R @@ -98,11 +98,11 @@ test_that("the `fmt_currency()` function works correctly", { expect_equal( (tbl_latex %>% fmt_currency( - columns = "num_1", currency = "USD", negative_val = "parens") %>% + columns = "num_1", currency = "USD", accounting = TRUE) %>% render_formats_test("latex"))[["num_1"]], c("$\\text{\\$}1,836.23$", "$\\text{\\$}2,763.39$", "$\\text{\\$}937.29$", "$\\text{\\$}643.00$", "$\\text{\\$}212.23$", "$\\text{\\$}0.00$", - "$\\left(\\text{\\$}23.24\\right)$") + "$(\\text{\\$}23.24)$") ) # Format the `num_1` column as USD, apply parentheses to all negative @@ -111,11 +111,11 @@ test_that("the `fmt_currency()` function works correctly", { expect_equal( (tbl_latex %>% fmt_currency( - columns = "num_1", currency = "USD", negative_val = "parens") %>% + columns = "num_1", currency = "USD", accounting = TRUE) %>% render_formats_test("latex"))[["num_1"]], c("$\\text{\\$}1,836.23$", "$\\text{\\$}2,763.39$", "$\\text{\\$}937.29$", "$\\text{\\$}643.00$", "$\\text{\\$}212.23$", "$\\text{\\$}0.00$", - "$\\left(\\text{\\$}23.24\\right)$") + "$(\\text{\\$}23.24)$") ) # Format the `num_1` column as USD to 4 decimal places, scale all values by diff --git a/tests/testthat/test-l_fmt_number.R b/tests/testthat/test-l_fmt_number.R index bb980cafc9..cdef2ddc33 100644 --- a/tests/testthat/test-l_fmt_number.R +++ b/tests/testthat/test-l_fmt_number.R @@ -89,17 +89,6 @@ test_that("the `fmt_number()` function works correctly", { "$212,23$", "$0,00$", "$-23,24$") ) - # Format the `num_1` column to 2 decimal places, apply parentheses to - # all negative values, use all other defaults; extract `output_df` and - # compare to expected values - expect_equal( - (tbl_latex %>% - fmt_number(columns = "num_1", decimals = 2, negative_val = "parens") %>% - render_formats_test("latex"))[["num_1"]], - c("$1,836.23$", "$2,763.39$", "$937.29$", "$643.00$", - "$212.23$", "$0.00$", "$(23.24)$") - ) - # Format the `num_1` column to 4 decimal places, scale all values by # 1/1000, use all other defaults; extract `output_df` and compare # to expected values diff --git a/tests/testthat/test-l_fmt_percent.R b/tests/testthat/test-l_fmt_percent.R index 20d7d4c8e5..8f841ad68e 100644 --- a/tests/testthat/test-l_fmt_percent.R +++ b/tests/testthat/test-l_fmt_percent.R @@ -90,17 +90,6 @@ test_that("the `fmt_percent()` function works correctly", { "$21.223,20\\%$", "$0,00\\%$", "$-2.324,00\\%$") ) - # Format the `num_1` column to 2 decimal places, apply parentheses to - # all negative values, use all other defaults; extract `output_df` and - # compare to expected values - expect_equal( - (tbl_latex %>% - fmt_percent(columns = "num_1", decimals = 2, negative_val = "parens") %>% - render_formats_test("latex"))[["num_1"]], - c("$183,623.00\\%$", "$276,339.00\\%$", "$93,729.00\\%$", "$64,300.00\\%$", - "$21,223.20\\%$", "$0.00\\%$", "$\\left(2,324.00\\%\\right)$") - ) - # Format the `num_1` column to 2 decimal places, prepend and append # all values by 2 different literals, use all other defaults; extract # `output_df` and compare to expected values @@ -138,7 +127,7 @@ test_that("the `fmt_percent()` function works correctly", { ) %>% render_formats_test("latex"))[["num_1"]], c("$\\% 183,623$", "$\\% 276,339$", "$\\% 93,729$", "$\\% 64,300$", - "$\\% 21,223$", "$\\% 0$", "$\\% -2,324$") + "$\\% 21,223$", "$\\% 0$", "$-\\% 2,324$") ) # Format the `num_1` column to 2 decimal places, apply the `en_US`