From 0f76dc456b1939db7c212ff0d4162d0658acbbba Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 May 2023 20:10:09 -0400 Subject: [PATCH 01/39] Create extra.css --- pkgdown/extra.css | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 pkgdown/extra.css diff --git a/pkgdown/extra.css b/pkgdown/extra.css new file mode 100644 index 0000000000..9467b2537f --- /dev/null +++ b/pkgdown/extra.css @@ -0,0 +1,8 @@ +dt { + font-family: monospace; + border-top-style: dotted; + border-top-width: 2px; + border-top-color: lightgray; + margin-bottom: 5px; + padding-top: 5px; +} From b970ca34bd2265091afee5748d7181fa0291a45e Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:22 -0400 Subject: [PATCH 02/39] Update as_data_frame.R --- R/as_data_frame.R | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/R/as_data_frame.R b/R/as_data_frame.R index 48352e7e27..f2a5d039d2 100644 --- a/R/as_data_frame.R +++ b/R/as_data_frame.R @@ -28,8 +28,19 @@ #' #' This facilitates conversion of the `gt_tbl` object to a data frame. #' -#' @param x An object of class `gt_tbl`. -#' @param ... Any additional parameters. +#' @param x *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param ... *Optional parameters* +#' +#' `` --- (`optional`) +#' +#' Anything provided here in `...` will be passed to internal function calls +#' that can consume it. #' #' @keywords internal #' From e67c9aa715722802e3ba1f5b9772193b73500c46 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:25 -0400 Subject: [PATCH 03/39] Update data_color.R --- R/data_color.R | 234 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 169 insertions(+), 65 deletions(-) diff --git a/R/data_color.R b/R/data_color.R index 39a873e292..12b06d774b 100644 --- a/R/data_color.R +++ b/R/data_color.R @@ -66,76 +66,180 @@ #' without running into too many errors. #' #' @inheritParams fmt_number -#' @param columns,rows The columns and rows to which cell data color operations -#' are constrained. -#' @param direction Should the color computations be performed column-wise or -#' row-wise? By default this is set with the `"column"` keyword and colors -#' will be applied down columns. The alternative option with the `"row"` -#' keyword ensures that the color mapping works across rows. -#' @param target_columns For indirect column coloring treatments, we can supply -#' the columns that will receive the styling. The necessary precondition is -#' that we must use `direction = "column"`. If `columns` resolves to a single -#' column then we may use one or more columns in `target_columns`. If on the -#' other hand `columns` resolves to multiple columns, then `target_columns` -#' must resolve to the same multiple. -#' @param method A method for computing color based on the data within body -#' cells. Can be `"auto"` (the default), `"numeric"`, `"bin"`, `"quantile"`, -#' or `"factor"`. The `"auto"` method will automatically choose the -#' `"numeric"` method for numerical input data or the `"factor"` method for -#' any non-numeric inputs. -#' @param palette A vector of color names, the name of an **RColorBrewer** -#' palette, the name of a **viridis** palette, or a discrete palette -#' accessible from the **paletteer** package using the `::` -#' syntax (e.g., `"wesanderson::IsleofDogs1"`). If providing a vector of -#' colors as a palette, each color value provided must either be a color name -#' (Only R/X11 color names or CSS 3.0 color names) or a hexadecimal string in -#' the form of `"#RRGGBB"` or `"#RRGGBBAA"`. If nothing is provided here, the -#' default R color palette is used (i.e., the colors from `palette()`). -#' @param domain The possible values that can be mapped. For the `"numeric"` and -#' `"bin"` methods, this can be a numeric range specified with a length of two -#' vector. Representative numeric data is needed for the `"quantile"` method -#' and categorical data must be used for the `"factor"` method. If `NULL` (the +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns to which cell data color operations are constrained. Can either +#' be a series of column names provided in [c()], a vector of column indices, +#' or a select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' form a constraint for cell data color operations. The default +#' [everything()] results in all rows in `columns` being formatted. +#' Alternatively, we can supply a vector of row captions within [c()], a +#' vector of row indices, or a select helper function. Examples of select +#' helper functions include [starts_with()], [ends_with()], [contains()], +#' [matches()], [one_of()], [num_range()], and [everything()]. We can also use +#' expressions to filter down to the rows we need (e.g., `[colname_1] > 100 & +#' [colname_2] < 50`). +#' +#' @param direction *Color computation direction* +#' +#' `singl-kw:[column|row]` --- *default:* `"column"` +#' +#' Should the color computations be performed column-wise or row-wise? By +#' default this is set with the `"column"` keyword and colors will be applied +#' down columns. The alternative option with the `"row"` keyword ensures that +#' the color mapping works across rows. +#' +#' @param target_columns *Indirect columns to target* +#' +#' `` --- *default:* `NULL` `optional` +#' +#' For indirect column coloring treatments, we can supply the columns that +#' will receive the styling. The necessary precondition is that we must use +#' `direction = "column"`. If `columns` resolves to a single column then we +#' may use one or more columns in `target_columns`. If on the other hand +#' `columns` resolves to multiple columns, then `target_columns` must resolve +#' to the same multiple. +#' +#' @param method *Color computation method* +#' +#' `singl-kw:[auto|numeric|bin|quantile|factor]` --- *default:* `"auto"` +#' +#' A method for computing color based on the data within body cells. Can be +#' `"auto"` (the default), `"numeric"`, `"bin"`, `"quantile"`, or `"factor"`. +#' The `"auto"` method will automatically choose the `"numeric"` method for +#' numerical input data or the `"factor"` method for any non-numeric inputs. +#' +#' @param palette *Color palette* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' A vector of color names, the name of an **RColorBrewer** palette, the name +#' of a **viridis** palette, or a discrete palette accessible from the +#' **paletteer** package using the `::` syntax (e.g., +#' `"wesanderson::IsleofDogs1"`). If providing a vector of colors as a +#' palette, each color value provided must either be a color name (Only R/X11 +#' color names or CSS 3.0 color names) or a hexadecimal string in the form of +#' `"#RRGGBB"` or `"#RRGGBBAA"`. If nothing is provided here, the default R +#' color palette is used (i.e., the colors from `palette()`). +#' +#' @param domain *Value domain* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' The possible values that can be mapped. For the `"numeric"` and `"bin"` +#' methods, this can be a numeric range specified with a length of two vector. +#' Representative numeric data is needed for the `"quantile"` method and +#' categorical data must be used for the `"factor"` method. If `NULL` (the #' default value), the values in each column or row (depending on `direction`) #' value will represent the domain. -#' @param bins For `method = "bin"` this can either be a numeric vector of two -#' or more unique cut points, or, a single numeric value (greater than or -#' equal to `2`) giving the number of intervals into which the domain values -#' are to be cut. By default, this is `8`. -#' @param quantiles For `method = "quantile"` this is the number of equal-size -#' quantiles to use. By default, this is set to `4`. -#' @param levels For `method = "factor"` this allows for an alternate way of -#' specifying levels. If anything is provided here then any value supplied to -#' `domain` will be ignored. This should be a character vector of unique -#' values. -#' @param ordered For `method = "factor"`, setting this to `TRUE` means that the -#' vector supplied to `domain` will be treated as being in the correct order -#' if that vector needs to be coerced to a factor. By default, this is -#' `FALSE`. -#' @param na_color The color to use for missing values. By default (with -#' `na_color = NULL`) gray, `"#808080"`, will be used. -#' @param alpha An optional, fixed alpha transparency value that will be applied -#' to all of the `colors` provided (regardless of whether a color palette was -#' directly supplied or generated through a color mapping function). -#' @param reverse Should the colors computed operate in reverse order? -#' If `TRUE` then colors that normally change from red to blue will change in -#' the opposite direction. By default, this is `FALSE`. -#' @param fn A color-mapping function. The function should be able to take a -#' vector of data values as input and return an equal-length vector of color -#' values. The `col_*()` functions provided in the **scales** package (i.e., +#' +#' @param bins *Specification of bin number* +#' +#' `scalar` --- *default:* `8` +#' +#' For `method = "bin"` this can either be a numeric vector of two or more +#' unique cut points, or, a single numeric value (greater than or equal to +#' `2`) giving the number of intervals into which the domain values are to be +#' cut. By default, this is `8`. +#' +#' @param quantiles *Specification of quantile number* +#' +#' `scalar` --- *default:* `4` +#' +#' For `method = "quantile"` this is the number of equal-size quantiles to +#' use. By default, this is set to `4`. +#' +#' @param levels *Specification of factor levels* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' For `method = "factor"` this allows for an alternate way of specifying +#' levels. If anything is provided here then any value supplied to `domain` +#' will be ignored. This should be a character vector of unique values. +#' +#' @param ordered *Use an ordered factor* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' For `method = "factor"`, setting this to `TRUE` means that the vector +#' supplied to `domain` will be treated as being in the correct order if that +#' vector needs to be coerced to a factor. By default, this is `FALSE`. +#' +#' @param na_color *Default color for `NA` values* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The color to use for missing values. By default (with `na_color = NULL`), +#' the color gray (`"#808080"`) will be used. This option has no effect if +#' providing a color-mapping function to `fn`. +#' +#' @param alpha *Transparency value* +#' +#' `scalar(0>=val>=1)` --- *default:* `NULL` (`optional`) +#' +#' An optional, fixed alpha transparency value that will be applied to all of +#' the `colors` provided (regardless of whether a color palette was directly +#' supplied or generated through a color mapping function). +#' +#' @param reverse *Reverse order of computed colors* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the colors computed operate in the reverse order? If `TRUE` then +#' colors that normally change from red to blue will change in the opposite +#' direction. +#' +#' @param fn *Color-mapping function* +#' +#' `function` --- *default:* `NULL` (`optional`) +#' +#' A color-mapping function. The function should be able to take a vector of +#' data values as input and return an equal-length vector of color values. The +#' `col_*()` functions provided in the **scales** package (i.e., #' [scales::col_numeric()], [scales::col_bin()], and [scales::col_factor()]) #' can be invoked here with options, as those functions themselves return a #' color-mapping function. -#' @param apply_to Which style element should the colors be applied to? Options -#' include the cell background (the default, given as `"fill"`) or the cell -#' text (`"text"`). -#' @param autocolor_text An option to let **gt** modify the coloring of text -#' within cells undergoing background coloring. This will result in better -#' text-to-background color contrast. By default, this is set to `TRUE`. -#' @param contrast_algo The color contrast algorithm to use when -#' `autocolor_text = TRUE`. By default this is `"apca"` (Accessible Perceptual -#' Contrast Algorithm) and the alternative to this is `"wcag"` (Web Content -#' Accessibility Guidelines). -#' @param colors Deprecated. Use the `fn` argument instead to provide a +#' +#' @param apply_to *How to apply color* +#' +#' `singl-kw:[fill|text]` --- *default:* `"fill"` +#' +#' Which style element should the colors be applied to? Options include the +#' cell background (the default, given as `"fill"`) or the cell text +#' (`"text"`). +#' +#' @param autocolor_text *Automatically recolor text* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option to let **gt** modify the coloring of text within cells undergoing +#' background coloring. This will result in better text-to-background color +#' contrast. By default, this is set to `TRUE`. +#' +#' @param contrast_algo *Color contrast algorithm choice* +#' +#' `singl-kw:[apca|wcag]` --- *default:* `"apca"` +#' +#' The color contrast algorithm to use when `autocolor_text = TRUE`. By +#' default this is `"apca"` (Accessible Perceptual Contrast Algorithm) and the +#' alternative to this is `"wcag"` (Web Content Accessibility Guidelines). +#' +#' @param colors *[Deprecated] Color mapping function* +#' +#' `function` --- *default:* `NULL` (`optional`) +#' +#' This argument is deprecated. Use the `fn` argument instead to provide a #' **scales**-based color-mapping function. If providing a palette, use the #' `palette` argument. #' From f5e13a7089ae4fbc6ba729a80b579487cad1b522 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:27 -0400 Subject: [PATCH 04/39] Update export.R --- R/export.R | 101 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 24 deletions(-) diff --git a/R/export.R b/R/export.R index a4444ec42d..ee53086097 100644 --- a/R/export.R +++ b/R/export.R @@ -69,7 +69,13 @@ #' package needs to be installed before attempting to save any table as a #' `.docx` document. #' -#' @param data A table object that is created using the [gt()] function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' #' @param filename The file name to create on disk. Ensure that an extension #' compatible with the output types is provided (`.html`, `.tex`, `.ltx`, #' `.rtf`, `.docx`). If a custom save function is provided then the file @@ -474,7 +480,13 @@ gtsave_filename <- function(path, filename) { #' tags. This option is preferable when using the output HTML table in an #' emailing context. #' -#' @param data A table object that is created using the [gt()] function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' #' @param inline_css An option to supply styles to table elements as inlined CSS #' styles. This is useful when including the table HTML as part of an HTML #' email message body, since inlined styles are largely supported in email @@ -558,7 +570,12 @@ as_raw_html <- function( #' `as.character()` on the created object will result in a single-element vector #' containing the LaTeX code. #' -#' @param data A table object that is created using the [gt()] function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. #' #' @details #' @@ -674,7 +691,13 @@ as_latex <- function(data) { #' vector. This object can be used with `writeLines()` to generate a valid .rtf #' file that can be opened by RTF readers. #' -#' @param data A table object that is created using the `gt()` function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' #' @param incl_open,incl_close Options that govern whether the opening or #' closing `"{"` and `"}"` should be included. By default, both options are #' `TRUE`. @@ -797,7 +820,13 @@ as_rtf <- function( #' Get the Open Office XML table tag content from a `gt_tbl` object as as a #' single-element character vector. #' -#' @param data A table object that is created using the `gt()` function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' #' @param align An option for table alignment. Can either be `"center"` (the #' default), `"left"`, or `"right"`. #' @param caption_location Determines where the caption should be positioned. @@ -1010,7 +1039,12 @@ as_word_tbl_body <- function( #' contain the `group_id` and `rowname` columns, whereby `rowname` contains #' descriptive stub labels for the summary rows. #' -#' @param data A table object that is created using the [gt()] function. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. #' #' @return A list of data frames containing summary data. #' @@ -1125,24 +1159,43 @@ extract_summary <- function(data) { #' Get a vector of cell data from a `gt_tbl` object. The output vector will have #' cell data formatted in the same way as the table. #' -#' @param data A table object that is created using the [gt()] function. -#' @param columns The columns containing the cells to extract. Can either be a -#' series of column names provided in [c()], a vector of column indices, or a -#' helper function focused on selections. The select helper functions are: -#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], -#' [num_range()], and [everything()]. -#' @param rows Optional rows to limit the extraction of cells. Providing -#' [everything()] (the default) results in all rows in `columns` being -#' formatted. Alternatively, we can supply a vector of row captions within -#' [c()], a vector of row indices, or a helper function focused on selections. -#' The select helper functions are: [starts_with()], [ends_with()], -#' [contains()], [matches()], [one_of()], [num_range()], and [everything()]. -#' We can also use expressions to filter down to the rows we need (e.g., -#' `[colname_1] > 100 & [colname_2] < 50`). -#' @param output The output style of the resulting character vector. This can -#' either be `"auto"` (the default), `"plain"`, `"html"`, `"latex"`, `"rtf"`, -#' or `"word"`. In **knitr** rendering (i.e., Quarto or R Markdown), the -#' `"auto"` option will choose the correct `output` value +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' Can either be a series of column names provided in [c()], a vector of +#' column indices, or a select helper function. Examples of select helper +#' functions include [starts_with()], [ends_with()], [contains()], +#' [matches()], [one_of()], [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' form a constraint for extraction. The default [everything()] results in all +#' rows in `columns` being formatted. Alternatively, we can supply a vector of +#' row captions within [c()], a vector of row indices, or a select helper +#' function. Examples of select helper functions include [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and +#' [everything()]. We can also use expressions to filter down to the rows we +#' need (e.g., `[colname_1] > 100 & [colname_2] < 50`). +#' +#' @param output *Output format* +#' +#' `singl-kw:[auto|plain|html|latex|rtf|word]` --- *default:* `"auto"` +#' +#' The output style of the resulting character vector. This can either be +#' `"auto"` (the default), `"plain"`, `"html"`, `"latex"`, `"rtf"`, or +#' `"word"`. In **knitr** rendering (i.e., Quarto or R Markdown), the `"auto"` +#' option will choose the correct `output` value #' #' @return A vector of cell data extracted from a **gt** table. #' From 8f82e42f56767c9edbdfda4799fc5ed07ffe602f Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:29 -0400 Subject: [PATCH 05/39] Update format_data.R --- R/format_data.R | 944 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 678 insertions(+), 266 deletions(-) diff --git a/R/format_data.R b/R/format_data.R index a14f4d9389..9e103b5a09 100644 --- a/R/format_data.R +++ b/R/format_data.R @@ -43,90 +43,187 @@ #' - locale-based formatting: providing a locale ID will result in number #' formatting specific to the chosen locale #' -#' @param data A table object that is created using the [gt()] function. -#' @param columns The columns to format. Can either be a series of column names -#' provided in [c()], a vector of column indices, or a helper function -#' focused on selections. The select helper functions are: [starts_with()], +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' Can either be a series of column names provided in [c()], a vector of +#' column indices, or a select helper function. Examples of select helper +#' functions include [starts_with()], [ends_with()], [contains()], +#' [matches()], [one_of()], [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' undergo formatting. The default [everything()] results in all rows in +#' `columns` being formatted. Alternatively, we can supply a vector of row +#' captions within [c()], a vector of row indices, or a select helper +#' function. Examples of select helper functions include [starts_with()], #' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and -#' [everything()]. -#' @param rows Optional rows to format. Providing [everything()] (the -#' default) results in all rows in `columns` being formatted. Alternatively, -#' we can supply a vector of row captions within [c()], a vector of row -#' indices, or a helper function focused on selections. The select helper -#' functions are: [starts_with()], [ends_with()], [contains()], [matches()], -#' [one_of()], [num_range()], and [everything()]. We can also use expressions -#' to filter down to the rows we need (e.g., -#' `[colname_1] > 100 & [colname_2] < 50`). -#' @param decimals An option to specify the exact number of decimal places to -#' use. The default number of decimal places is `2`. -#' @param n_sigfig A option to format numbers to *n* significant figures. By -#' default, this is `NULL` and thus number values will be formatted according -#' to the number of decimal places set via `decimals`. If opting to format -#' according to the rules of significant figures, `n_sigfig` must be a number -#' greater than or equal to `1`. Any values passed to the `decimals` and -#' `drop_trailing_zeros` arguments will be ignored. -#' @param drop_trailing_zeros A logical value that allows for removal of -#' trailing zeros (those redundant zeros after the decimal mark). -#' @param drop_trailing_dec_mark A logical value that determines whether decimal -#' marks should always appear even if there are no decimal digits to display -#' after formatting (e.g, `23` becomes `23.`). The default for this is `TRUE`, -#' which means that trailing decimal marks are not shown. -#' @param use_seps An option to use digit group separators. The type of digit -#' group separator is set by `sep_mark` and overridden if a locale ID is -#' provided to `locale`. This setting is `TRUE` by default. -#' @param accounting An option to use accounting style for values. With `FALSE` -#' (the default), negative values will be shown with a minus sign. Using -#' `accounting = TRUE` will put negative values in parentheses. -#' @param scale_by A value to scale the input. The default is `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 `suffixing` options (i.e., -#' where `suffixing` is not set to `FALSE`). -#' @param suffixing An option to scale and apply suffixes to larger numbers -#' (e.g., `1924000` can be transformed to `1.92M`). This option can accept a -#' logical value, where `FALSE` (the default) will not perform this -#' transformation and `TRUE` will apply thousands (`K`), millions (`M`), -#' billions (`B`), and trillions (`T`) suffixes after automatic value scaling. -#' We can also specify which symbols to use for each of the value ranges by -#' using a character vector of the preferred symbols to replace the defaults -#' (e.g., `c("k", "Ml", "Bn", "Tr")`). +#' [everything()]. We can also use expressions to filter down to the rows we +#' need (e.g., `[colname_1] > 100 & [colname_2] < 50`). +#' +#' @param decimals *Number of decimal places* +#' +#' `scalar(val>=0)` --- *default:* `2` +#' +#' This corresponds to the exact number of decimal places to use. A value +#' such as `2.34` can, for example, be formatted with `0` decimal places and +#' it would result in `"2"`. With `4` decimal places, the formatted value +#' becomes `"2.3400"`. The trailing zeros can be removed with +#' `drop_trailing_zeros = TRUE`. If you always need `decimals = 0`, the +#' [fmt_integer()] function should be considered. +#' +#' @param n_sigfig *Number of significant figures* +#' +#' `scalar(val>=1)` --- *default:* `NULL` (`optional`) +#' +#' A option to format numbers to *n* significant figures. By default, this is +#' `NULL` and thus number values will be formatted according to the number of +#' decimal places set via `decimals`. If opting to format according to the +#' rules of significant figures, `n_sigfig` must be a number greater than or +#' equal to `1`. Any values passed to the `decimals` and `drop_trailing_zeros` +#' arguments will be ignored. +#' +#' @param drop_trailing_zeros *Drop any trailing zeros* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' A logical value that allows for removal of trailing zeros (those redundant +#' zeros after the decimal mark). +#' +#' @param drop_trailing_dec_mark *Drop the trailing decimal mark* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' A logical value that determines whether decimal marks should always appear +#' even if there are no decimal digits to display after formatting (e.g., `23` +#' becomes `23.` if `FALSE`). By default trailing decimal marks are not shown. +#' +#' @param use_seps *Use digit group separators* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option to use digit group separators. The type of digit group separator +#' is set by `sep_mark` and overridden if a locale ID is provided to `locale`. +#' This setting is `TRUE` by default. +#' +#' @param accounting *Use accounting style* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' An option to use accounting style for values. Normally, negative values +#' will be shown with a minus sign but using accounting style will instead put +#' any negative values in parentheses. +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. This value will be +#' ignored if using any of the `suffixing` options (i.e., where `suffixing` is +#' not set to `FALSE`). +#' +#' @param suffixing *Specification for large-number suffixing* +#' +#' `scalar|vector` --- *default:* `FALSE` +#' +#' The `suffixing` option allows us to scale and apply suffixes to larger +#' numbers (e.g., `1924000` can be transformed to `1.92M`). This option can +#' accept a logical value, where `FALSE` (the default) will not perform this +#' transformation and `TRUE` will apply thousands (`"K"`), millions (`"M"`), +#' billions (`"B"`), and trillions (`"T"`) suffixes after automatic value +#' scaling. +#' +#' We can alternatively provide a character vector that serves as a +#' specification for which symbols are to used for each of the value ranges. +#' These preferred symbols will replace the defaults (e.g., +#' `c("k", "Ml", "Bn", "Tr")` replaces `"K"`, `"M"`, `"B"`, and `"T"`). #' #' Including `NA` values in the vector will ensure that the particular range -#' will either not be included in the transformation (e.g, `c(NA, "M", "B", -#' "T")` won't modify numbers in the thousands range) or the range will -#' inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers -#' in the range of millions and billions will be in terms of millions). +#' will either not be included in the transformation (e.g., +#' `c(NA, "M", "B", "T")` won't modify numbers at all in the thousands range) +#' or the range will inherit a previous suffix (e.g., with +#' `c("K", "M", NA, "T")`, all numbers in the range of millions and billions +#' will be in terms of millions). #' #' Any use of `suffixing` (where it is not set expressly as `FALSE`) means #' that any value provided to `scale_by` will be ignored. #' #' If using `system = "ind"` then the default suffix set provided by -#' `suffixing = TRUE` will be `c(NA, "L", "Cr")`. This doesn't apply suffixes -#' to the thousands range, but does express values in lakhs and crores. -#' -#' @param pattern A formatting pattern that allows for decoration of the -#' formatted value. The value itself is represented by `{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 -#' (e.g., using `sep_mark = ","` with `1000` would result in a formatted value -#' of `1,000`). -#' @param dec_mark The character to use as a decimal mark (e.g., using `dec_mark -#' = ","` with `0.152` would result in a formatted value of `0,152`). -#' @param force_sign Should the positive sign be shown for positive values -#' (effectively showing a sign for all values except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative numbers will -#' display a minus sign. This option is disregarded when using accounting -#' notation with `accounting = TRUE`. -#' @param system The numbering system to use. By default, this is the -#' international numbering system (`"intl"`) whereby grouping separators -#' (i.e., `sep_mark`) are separated by three digits. The alternative system, -#' the Indian numbering system (`"ind"`) uses grouping separators that -#' correspond to thousand, lakh, crore, and higher quantities. -#' @param locale An optional locale identifier that can be used for formatting -#' the value according the locale's rules. Examples include `"en"` for English -#' (United States) and `"fr"` for French (France). The use of a locale ID will -#' override any locale-specific values provided. We can use the -#' [info_locales()] function as a useful reference for all of the locales that -#' are supported. +#' `suffixing = TRUE` will be the equivalent of `c(NA, "L", "Cr")`. This +#' doesn't apply suffixes to the thousands range, but does express values in +#' *lakhs* and *crores*. +#' +#' @param pattern *Specification of the formatting pattern* +#' +#' `scalar` --- *default:* `"{x}"` +#' +#' A formatting pattern that allows for decoration of the formatted value. The +#' formatted value is represented by the `{x}` (which can be used multiple +#' times, if needed) and all other characters will be interpreted as string +#' literals. +#' +#' @param sep_mark *Separator mark for digit grouping* +#' +#' `scalar` --- *default:* `","` +#' +#' The string to use as a separator between groups of digits. For example, +#' using `sep_mark = ","` with a value of `1000` would result in a formatted +#' value of `"1,000"`. This argument is ignored if a `locale` is supplied +#' (i.e., is not `NULL`). +#' +#' @param dec_mark *Decimal mark* +#' +#' `scalar` --- *default:* `"."` +#' +#' The string to be used as the decimal mark. For example, using +#' `dec_mark = ","` with the value `0.152` would result in a formatted value +#' of `"0,152"`). This argument is ignored if a `locale` is supplied (i.e., is +#' not `NULL`). +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive values (effectively showing +#' a sign for all values except zero)? If so, use `TRUE` for this option. The +#' default is `FALSE`, where only negative numbers will display a minus sign. +#' This option is disregarded when using accounting notation with +#' `accounting = TRUE`. +#' +#' @param system *Numbering system for grouping separators* +#' +#' `singl-kw:[intl|ind]` --- *default:* `"intl"` +#' +#' The international numbering system (keyword: `"intl"`) is widely used and +#' its grouping separators (i.e., `sep_mark`) are always separated by three +#' digits. The alternative system, the Indian numbering system (keyword: +#' `"ind"`), uses grouping separators that correspond to thousand, lakh, +#' crore, and higher quantities. +#' +#' @param locale *Locale identifier* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional locale identifier that can be used for formatting values +#' according the locale's rules. Examples include `"en"` for English (United +#' States) and `"fr"` for French (France). We can use the [info_locales()] +#' function as a useful reference for all of the locales that are supported. A +#' locale ID can be also set in the initial [gt()] function call (where it +#' would be used automatically by any function with a `locale` argument) but a +#' `locale` value provided here will override that global locale. #' #' @return An object of class `gt_tbl`. #' @@ -422,24 +519,37 @@ fmt_number <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param suffixing An option to scale and apply suffixes to larger numbers -#' (e.g., `1924000` can be transformed to `2M`). This option can accept a -#' logical value, where `FALSE` (the default) will not perform this +#' +#' @param suffixing *Specification for large-number suffixing* +#' +#' `scalar|vector` --- *default:* `FALSE` +#' +#' The `suffixing` option allows us to scale and apply suffixes to larger +#' numbers (e.g., `1924000` can be transformed to `2M`). This option can +#' accept a logical value, where `FALSE` (the default) will not perform this #' transformation and `TRUE` will apply thousands (`K`), millions (`M`), #' billions (`B`), and trillions (`T`) suffixes after automatic value scaling. -#' We can also specify which symbols to use for each of the value ranges by -#' using a character vector of the preferred symbols to replace the defaults -#' (e.g., `c("k", "Ml", "Bn", "Tr")`). +#' +#' We can alternatively provide a character vector that serves as a +#' specification for which symbols are to used for each of the value ranges. +#' These preferred symbols will replace the defaults (e.g., +#' `c("k", "Ml", "Bn", "Tr")` replaces `"K"`, `"M"`, `"B"`, and `"T"`). #' #' Including `NA` values in the vector will ensure that the particular range -#' will either not be included in the transformation (e.g, `c(NA, "M", "B", -#' "T")` won't modify numbers in the thousands range) or the range will -#' inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers -#' in the range of millions and billions will be in terms of millions). +#' will either not be included in the transformation (e.g., +#' `c(NA, "M", "B", "T")` won't modify numbers at all in the thousands range) +#' or the range will inherit a previous suffix (e.g., with +#' `c("K", "M", NA, "T")`, all numbers in the range of millions and billions +#' will be in terms of millions). #' #' Any use of `suffixing` (where it is not set expressly as `FALSE`) means #' that any value provided to `scale_by` will be ignored. #' +#' If using `system = "ind"` then the default suffix set provided by +#' `suffixing = TRUE` will be the equivalent of `c(NA, "L", "Cr")`. This +#' doesn't apply suffixes to the thousands range, but does express values in +#' *lakhs* and *crores*. +#' #' @return An object of class `gt_tbl`. #' #' @section Compatibility of formatting function with data values: @@ -597,15 +707,31 @@ fmt_integer <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param scale_by A value to scale the input. The default is `1.0`. All numeric -#' values will be multiplied by this value first before undergoing formatting. -#' @param exp_style Style of formatting to use for the scientific notation -#' formatting. By default this is `"x10n"` but other options include using -#' a single letter (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to -#' signal a minimum digit width of one, or `"low-ten"` for using a stylized -#' `"10"` marker. -#' @param force_sign_m,force_sign_n Should the plus sign be shown for positive -#' values of the mantissa (first component) or the exponent? This would +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. +#' +#' @param exp_style *Style declaration for exponent formatting* +#' +#' `scalar` --- *default:* `"x10n"` +#' +#' Style of formatting to use for the scientific notation formatting. By +#' default this is `"x10n"` but other options include using a single letter +#' (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to signal a +#' minimum digit width of one, or `"low-ten"` for using a stylized `"10"` +#' marker. +#' +#' @param force_sign_m,force_sign_n *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the plus sign be shown for positive values of the mantissa (first +#' component, `force_sign_m`) or the exponent (`force_sign_n`)? This would #' effectively show a sign for all values except zero on either of those #' numeric components of the notation. If so, use `TRUE` for either one of #' these options. The default for both is `FALSE`, where only negative numbers @@ -965,15 +1091,31 @@ fmt_scientific <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param scale_by A value to scale the input. The default is `1.0`. All numeric -#' values will be multiplied by this value first before undergoing formatting. -#' @param exp_style Style of formatting to use for the engineering notation -#' formatting. By default this is `"x10n"` but other options include using -#' a single letter (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to -#' signal a minimum digit width of one, or `"low-ten"` for using a stylized -#' `"10"` marker. -#' @param force_sign_m,force_sign_n Should the plus sign be shown for positive -#' values of the mantissa (first component) or the exponent? This would +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. +#' +#' @param exp_style *Style declaration for exponent formatting* +#' +#' `scalar` --- *default:* `"x10n"` +#' +#' Style of formatting to use for the scientific notation formatting. By +#' default this is `"x10n"` but other options include using a single letter +#' (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to signal a +#' minimum digit width of one, or `"low-ten"` for using a stylized `"10"` +#' marker. +#' +#' @param force_sign_m,force_sign_n *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the plus sign be shown for positive values of the mantissa (first +#' component, `force_sign_m`) or the exponent (`force_sign_n`)? This would #' effectively show a sign for all values except zero on either of those #' numeric components of the notation. If so, use `TRUE` for either one of #' these options. The default for both is `FALSE`, where only negative numbers @@ -1472,14 +1614,29 @@ fmt_symbol <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param scale_values Should the values be scaled through multiplication by -#' 100? By default this is `TRUE` since the expectation is that normally -#' values are proportions. Setting to `FALSE` signifies that the values are +#' +#' @param scale_values *Multiply input values by 100* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' Should the values be scaled through multiplication by 100? By default this +#' scaling is performed since the expectation is that incoming values are +#' usually proportional. Setting to `FALSE` signifies that the values are #' already scaled and require only the percent sign when formatted. -#' @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 -#' `right` (the default) or `left`. +#' +#' @param incl_space *Include a space between the value and the % sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' 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 *Percent sign placement* +#' +#' `scalar` --- *default:* `"right"` +#' +#' This option governs the placement of the percent sign. This can be either +#' be `right` (the default) or `left`. #' #' @return An object of class `gt_tbl`. #' @@ -1697,22 +1854,42 @@ fmt_percent <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param to_units A keyword that signifies the desired output quantity. This -#' can be any from the following set: `"per-mille"`, `"per-myriad"`, `"pcm"`, -#' `"ppm"`, `"ppb"`, `"ppt"`, or `"ppq"`. -#' @param symbol The symbol/units to use for the quantity. By default, this is -#' set to `"auto"` and **gt** will choose the appropriate symbol based on the +#' +#' @param to_units *Output Quantity* +#' +#' `singl-kw:[per-mille|per-myriad|pcm|ppm|ppb|ppt|ppq]` --- *default:* `"per-mille"` +#' +#' A keyword that signifies the desired output quantity. This can be any from +#' the following set: `"per-mille"`, `"per-myriad"`, `"pcm"`, `"ppm"`, +#' `"ppb"`, `"ppt"`, or `"ppq"`. +#' +#' @param symbol *Symbol or units to use in output display* +#' +#' `scalar` --- *default:* `"auto"` +#' +#' The symbol/units to use for the quantity. By default, this is set to +#' `"auto"` and **gt** will choose the appropriate symbol based on the #' `to_units` keyword and the output context. However, this can be changed by #' supplying a string (e.g, using `symbol = "ppbV"` when `to_units = "ppb"`). -#' @param scale_values Should the values be scaled through multiplication -#' according to the keyword set in `to_units`? By default this is `TRUE` since -#' the expectation is that normally values are proportions. Setting to `FALSE` -#' signifies that the values are already scaled and require only the -#' appropriate symbol/units when formatted. -#' @param incl_space An option for whether to include a space between the value -#' and the symbol/units. The default is `"auto"` which provides spacing -#' dependent on the mark itself. This can be directly controlled by using -#' either `TRUE` or `FALSE`. +#' +#' @param scale_values *Scale input values accordingly* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' Should the values be scaled through multiplication according to the keyword +#' set in `to_units`? By default this is `TRUE` since the expectation is that +#' normally values are proportions. Setting to `FALSE` signifies that the +#' values are already scaled and require only the appropriate symbol/units +#' when formatted. +#' +#' @param incl_space *Include a space between the value and the symbol/units* +#' +#' `scalar|scalar` --- *default:* `"auto"` +#' +#' An option for whether to include a space between the value and the +#' symbol/units. The default is `"auto"` which provides spacing dependent on +#' the mark itself. This can be directly controlled by using either `TRUE` or +#' `FALSE`. #' #' @return An object of class `gt_tbl`. #' @@ -1960,21 +2137,36 @@ fmt_partsper <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param accuracy The type of fractions to generate. This can either be one of -#' the keywords `"low"`, `"med"`, or `"high"` (to generate fractions with -#' denominators of up to 1, 2, or 3 digits, respectively) or an integer value -#' greater than zero to obtain fractions with a fixed denominator (`2` yields -#' halves, `3` is for thirds, `4` is quarters, etc.). For the latter option, -#' using `simplify = TRUE` will simplify fractions where possible (e.g., `2/4` -#' will be simplified as `1/2`). By default, the `"low"` option is used. -#' @param simplify If choosing to provide a numeric value for `accuracy`, the -#' option to simplify the fraction (where possible) can be taken with `TRUE` -#' (the default). With `FALSE`, denominators in fractions will be fixed to the +#' +#' @param accuracy *Accuracy of fractions* +#' +#' `singl-kw:[low|med|high]|scalar(val>=1)` --- *default:* `"low"` +#' +#' The type of fractions to generate. This can either be one of the keywords +#' `"low"`, `"med"`, or `"high"` (to generate fractions with denominators of +#' up to 1, 2, or 3 digits, respectively) or an integer value greater than +#' zero to obtain fractions with a fixed denominator (`2` yields halves, `3` +#' is for thirds, `4` is quarters, etc.). For the latter option, using +#' `simplify = TRUE` will simplify fractions where possible (e.g., `2/4` will +#' be simplified as `1/2`). By default, the `"low"` option is used. +#' +#' @param simplify *Simplify the fraction* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' If choosing to provide a numeric value for `accuracy`, the option to +#' simplify the fraction (where possible) can be taken with `TRUE` (the +#' default). With `FALSE`, denominators in fractions will be fixed to the #' value provided in `accuracy`. -#' @param layout For HTML output, the `"inline"` layout is the default. This -#' layout places the numerals of the fraction on the baseline and uses a -#' standard slash character. The `"diagonal"` layout will generate fractions -#' that are typeset with raised/lowered numerals and a virgule. +#' +#' @param layout *Layout of fractions in HTML output* +#' +#' `singl-kw:[inline|diagonal]` --- *default:* `"inline"` +#' +#' For HTML output, the `"inline"` layout is the default. This layout places +#' the numerals of the fraction on the baseline and uses a standard slash +#' character. The `"diagonal"` layout will generate fractions that are typeset +#' with raised/lowered numerals and a virgule. #' #' @return An object of class `gt_tbl`. #' @@ -2516,7 +2708,12 @@ round_gt <- function(x, digits = 0) { #' the possible inputs to the `currency` argument. #' #' @inheritParams fmt_number -#' @param currency The currency to use for the numeric value. This input can be +#' +#' @param currency *Currency to use* +#' +#' `scalar|obj:` --- *default:* `"USD"` +#' +#' The currency to use for the numeric value. This input can be #' supplied as a 3-letter currency code (e.g., `"USD"` for U.S. Dollars, #' `"EUR"` for the Euro currency). Use [info_currencies()] to get an #' information table with all of the valid currency codes and examples of @@ -2533,14 +2730,28 @@ round_gt <- function(x, digits = 0) { #' the letter "f" in all other output contexts). Please note that `decimals` #' will default to `2` when using the [currency()] helper function. #' -#' If nothing is provided to `currency` then `"USD"` (U.S. dollars) will be -#' used. -#' @param use_subunits An option for whether the subunits portion of a currency -#' value should be displayed. By default, this is `TRUE`. -#' @param placement The placement of the currency symbol. This can be either be -#' `left` (the default) or `right`. -#' @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. +#' @param use_subunits *Show or hide currency subunits* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option for whether the subunits portion of a currency value should be +#' displayed. For example, with an input value of `273.81`, the default +#' formatting will produce `"$273.81"`. Removing the subunits (with +#' `use_subunits = FALSE`) will give us `"$273"`. +#' +#' @param placement *Currency symbol placement* +#' +#' `scalar` --- *default:* `"left"` +#' +#' The placement of the currency symbol. This can be either be `left` (as +#' in `"$450"`) or `right` (which yields `"450$"`). +#' +#' @param incl_space *Include a space between the value and the currency symbol* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' 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 `gt_tbl`. #' @@ -2756,8 +2967,13 @@ fmt_currency <- function( #' numerals, rounding values as necessary. #' #' @inheritParams fmt_number -#' @param case Should Roman numerals should be rendered as uppercase (`"upper"`) -#' or lowercase (`"lower"`) letters? By default, this is set to `"upper"`. +#' +#' @param case *Use uppercase or lowercase letters* +#' +#' `singl-kw:[upper|lower]` --- *default:* `"upper"` +#' +#' Should Roman numerals should be rendered as uppercase (`"upper"`) or +#' lowercase (`"lower"`) letters? By default, this is set to `"upper"`. #' #' @return An object of class `gt_tbl`. #' @@ -2925,14 +3141,23 @@ fmt_roman <- function( #' diacritical marks). #' #' @inheritParams fmt_number -#' @param case Should resulting index characters be rendered as uppercase -#' (`"upper"`) or lowercase (`"lower"`) letters? By default, this is set to -#' `"upper"`. -#' @param index_algo The indexing algorithm for handling the recycling of the -#' index character set. By default, the `"repeat"` option is used where -#' characters are doubled, tripled, and so on, when moving past the character -#' set limit. The alternative is the `"excel"` option, where Excel-based -#' column naming is adapted and used here (e.g., `[..., Y, Z, AA, AB, ...]`). +#' +#' @param case *Use uppercase or lowercase letters* +#' +#' `singl-kw:[upper|lower]` --- *default:* `"upper"` +#' +#' Should the resulting index characters be rendered as uppercase (`"upper"`) +#' or lowercase (`"lower"`) letters? By default, this is set to `"upper"`. +#' +#' @param index_algo *Indexing algorithm* +#' +#' `singl-kw:[repeat|excel]` --- *default:* `"repeat"` +#' +#' The indexing algorithm handles the recycling of the index character set. By +#' default, the `"repeat"` option is used where characters are doubled, +#' tripled, and so on, when moving past the character set limit. The +#' alternative is the `"excel"` option, where Excel-based column naming is +#' adapted and used here (e.g., `[..., Y, Z, AA, AB, ...]`). #' #' @return An object of class `gt_tbl`. #' @@ -3466,15 +3691,39 @@ fmt_spelled_num <- function( #' formatting specific to the chosen locale #' #' @inheritParams fmt_number -#' @param standard The way to express large byte sizes. -#' @param decimals An option to specify the exact number of decimal places to -#' use. The default number of decimal places is `1`. -#' @param incl_space An option for whether to include a space between the value -#' and the units. The default of `TRUE` uses a space character for separation. -#' @param force_sign Should the positive sign be shown for positive numbers -#' (effectively showing a sign for all numbers except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative numbers will -#' display a minus sign. +#' +#' @param standard *Standard used to express byte sizes* +#' +#' `singl-kw:[decimal|binary]` --- *default:* `"decimal"` +#' +#' The form of expressing large byte sizes is divided between: (1) decimal +#' units (powers of 1000; e.g., `"kB"` and `"MB"`), and (2) binary units +#' (powers of 1024; e.g., `"KiB"` and `"MiB"`). +#' +#' @param decimals *Number of decimal places* +#' +#' `scalar(val>=0)` --- *default:* `1` +#' +#' This corresponds to the exact number of decimal places to use. A value +#' such as `2.34` can, for example, be formatted with `0` decimal places and +#' it would result in `"2"`. With `4` decimal places, the formatted value +#' becomes `"2.3400"`. The trailing zeros can be removed with +#' `drop_trailing_zeros = TRUE`. +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive numbers (effectively showing +#' a sign for all numbers except zero)? If so, use `TRUE` for this option. The +#' default is `FALSE`, where only negative numbers will display a minus sign. +#' +#' @param incl_space *Include a space between the value and the units* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option for whether to include a space between the value and the units. +#' The default is to use a space character for separation. #' #' @return An object of class `gt_tbl`. #' @@ -3720,9 +3969,14 @@ fmt_bytes <- function( #' `YYYY-MM-DD`). #' #' @inheritParams fmt_number -#' @param date_style The date style to use. By default this is `"iso"` which -#' corresponds to ISO 8601 date formatting. The other date styles can be -#' viewed using [info_date_style()]. +#' +#' @param date_style *Predefined style for dates* +#' +#' `scalar|scalar(1<=val<=41)` --- *default:* `"iso"` +#' +#' The date style to use. By default this is the short name `"iso"` which +#' corresponds to ISO 8601 date formatting. There are 41 date styles in total +#' and their short names can be viewed using [info_date_style()]. #' #' @return An object of class `gt_tbl`. #' @@ -4009,9 +4263,15 @@ fmt_date <- function( #' always results in the formatting of `00:00:00`). #' #' @inheritParams fmt_number -#' @param time_style The time style to use. By default this is `"iso"` which -#' corresponds to how times are formatted within ISO 8601 datetime values. The -#' other time styles can be viewed using [info_time_style()]. +#' +#' @param time_style *Predefined style for times* +#' +#' `scalar|scalar(1<=val<=25)` --- *default:* `"iso"` +#' +#' The time style to use. By default this is the short name `"iso"` which +#' corresponds to how times are formatted within ISO 8601 datetime values. +#' There are 25 time styles in total and their short names can be viewed using +#' [info_time_style()]. #' #' @return An object of class `gt_tbl`. #' @@ -4291,16 +4551,33 @@ fmt_time <- function( #' in the ISO 8601 form of `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DD`). #' #' @inheritParams fmt_number +#' #' @inheritParams fmt_date +#' #' @inheritParams fmt_time -#' @param sep The separator string to use between the date and time components. -#' By default, this is a single space character (`" "`). Only used when not +#' +#' @param sep *Separator between date and time components* +#' +#' `scalar` --- *default:* `" "` +#' +#' The separator string to use between the date and time components. By +#' default, this is a single space character (`" "`). Only used when not #' specifying a `format` code. -#' @param format An optional formatting string used for generating custom -#' dates/times. If used then the arguments governing preset styles -#' (`date_style` and `time_style`) will be ignored in favor of formatting via -#' the `format` string. -#' @param tz The time zone for printing dates/times (i.e., the output). The +#' +#' @param format *Date/time formatting string* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional formatting string used for generating custom dates/times. If +#' used then the arguments governing preset styles (`date_style` and +#' `time_style`) will be ignored in favor of formatting via the `format` +#' string. +#' +#' @param tz *Time zone* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The time zone for printing dates/times (i.e., the output). The #' default of `NULL` will preserve the time zone of the input data in the #' output. If providing a time zone, it must be one that is recognized by the #' user's operating system (a vector of all valid `tz` values can be produced @@ -5282,45 +5559,74 @@ fmt_datetime <- function( #' which is `c("days", "hours", "minutes", "seconds")` #' #' @inheritParams fmt_number -#' @param input_units If one or more selected columns contains numeric values, a -#' keyword must be provided for `input_units` for **gt** to determine how -#' those values are to be interpreted in terms of duration. The accepted units -#' are: `"seconds"`, `"minutes"`, `"hours"`, `"days"`, and `"weeks"`. -#' @param output_units Controls the output time units. The default, `NULL`, -#' means that **gt** will automatically choose time units based on the input -#' duration value. To control which time units are to be considered for output -#' (before trimming with `trim_zero_units`) we can specify a vector of one or -#' more of the following keywords: `"weeks"`, `"days"`, `"hours"`, -#' `"minutes"`, or `"seconds"`. -#' @param duration_style A choice of four formatting styles for the output -#' duration values. With `"narrow"` (the default style), duration values will -#' be formatted with single letter time-part units (e.g., 1.35 days will be -#' styled as `"1d 8h 24m`). With `"wide"`, this example value will be expanded -#' to `"1 day 8 hours 24 minutes"` after formatting. The `"colon-sep"` style -#' will put days, hours, minutes, and seconds in the `"([D]/)[HH]:[MM]:[SS]"` +#' +#' @param input_units *Declaration of duration units for numerical values* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' If one or more selected columns contains numeric values (not `difftime` +#' values, which contain the duration units), a keyword must be provided for +#' `input_units` for **gt** to determine how those values are to be +#' interpreted in terms of duration. The accepted units are: `"seconds"`, +#' `"minutes"`, `"hours"`, `"days"`, and `"weeks"`. +#' +#' @param output_units *Choice of output units* +#' +#' `mult-kw:[weeks|days|hours|minutes|seconds]` --- *default:* `NULL` (`optional`) +#' +#' Controls the output time units. The default, `NULL`, means that **gt** will +#' automatically choose time units based on the input duration value. To +#' control which time units are to be considered for output (before trimming +#' with `trim_zero_units`) we can specify a vector of one or more of the +#' following keywords: `"weeks"`, `"days"`, `"hours"`, `"minutes"`, or +#' `"seconds"`. +#' +#' @param duration_style *Style for representing duration values* +#' +#' `singl-kw:[narrow|wide|colon-sep|iso]` --- *default:* `"narrow"` +#' +#' A choice of four formatting styles for the output duration values. With +#' `"narrow"` (the default style), duration values will be formatted with +#' single letter time-part units (e.g., 1.35 days will be styled as +#' `"1d 8h 24m"`). With `"wide"`, this example value will be expanded to +#' `"1 day 8 hours 24 minutes"` after formatting. The `"colon-sep"` style will +#' put days, hours, minutes, and seconds in the `"([D]/)[HH]:[MM]:[SS]"` #' format. The `"iso"` style will produce a value that conforms to the ISO #' 8601 rules for duration values (e.g., 1.35 days will become `"P1DT8H24M"`). -#' @param trim_zero_units Provides methods to remove output time units that have -#' zero values. By default this is `TRUE` and duration values that might -#' otherwise be formatted as `"0w 1d 0h 4m 19s"` with -#' `trim_zero_units = FALSE` are instead displayed as `"1d 4m 19s"`. Aside -#' from using `TRUE`/`FALSE` we could provide a vector of keywords for more -#' precise control. These keywords are: (1) `"leading"`, to omit all leading -#' zero-value time units (e.g., `"0w 1d"` -> `"1d"`), (2) `"trailing"`, to -#' omit all trailing zero-value time units (e.g., `"3d 5h 0s"` -> `"3d 5h"`), -#' and `"internal"`, which removes all internal zero-value time units (e.g., -#' `"5d 0h 33m"` -> `"5d 33m"`). -#' @param max_output_units If `output_units` is `NULL`, where the output time -#' units are unspecified and left to **gt** to handle, a numeric value -#' provided for `max_output_units` will be taken as the maximum number of time -#' units to display in all output time duration values. By default, this is -#' `NULL` and all possible time units will be displayed. This option has no -#' effect when `duration_style = "colon-sep"` (only `output_units` can be used -#' to customize that type of duration output). -#' @param force_sign Should the positive sign be shown for positive values -#' (effectively showing a sign for all values except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative value will -#' display a minus sign. +#' +#' @param trim_zero_units *Trimming of zero values* +#' +#' `scalar|mult-kw:[leading|trailing|internal]` --- *default:* `TRUE` +#' +#' Provides methods to remove output time units that have zero values. By +#' default this is `TRUE` and duration values that might otherwise be +#' formatted as `"0w 1d 0h 4m 19s"` with `trim_zero_units = FALSE` are instead +#' displayed as `"1d 4m 19s"`. Aside from using `TRUE`/`FALSE` we could +#' provide a vector of keywords for more precise control. These keywords are: +#' (1) `"leading"`, to omit all leading zero-value time units (e.g., `"0w 1d"` +#' -> `"1d"`), (2) `"trailing"`, to omit all trailing zero-value time units +#' (e.g., `"3d 5h 0s"` -> `"3d 5h"`), and `"internal"`, which removes all +#' internal zero-value time units (e.g., `"5d 0h 33m"` -> `"5d 33m"`). +#' +#' @param max_output_units *Maximum number of time units to display* +#' +#' `scalar(val>=1)` --- *default:* `NULL` (`optional`) +#' +#' If `output_units` is `NULL`, where the output time units are unspecified +#' and left to **gt** to handle, a numeric value provided for +#' `max_output_units` will be taken as the maximum number of time units to +#' display in all output time duration values. By default, this is `NULL` and +#' all possible time units will be displayed. This option has no effect when +#' `duration_style = "colon-sep"` (only `output_units` can be used to +#' customize that type of duration output). +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive values (effectively showing +#' a sign for all values except zero)? If so, use `TRUE` for this option. By +#' default only negative values will display a minus sign. #' #' @return An object of class `gt_tbl`. #' @@ -6093,13 +6399,23 @@ extract_duration_pattern <- function( #' argument, and, the separator can be modified with the `sep` argument. #' #' @inheritParams fmt_number -#' @param sep The separator text that indicates the values are ranged. The -#' default value of `"--"` indicates that an en dash will be used for the -#' range separator. Using `"---"` will be taken to mean that an em dash should -#' be used. Should you want these special symbols to be taken literally, they -#' can be supplied within the base [I()] function. -#' @param fmt Formatting expressions in formula form. The RHS of `~` should -#' contain a formatting call (e.g., +#' +#' @param sep *Separator between values* +#' +#' `scalar` --- *default:* `"--"` +#' +#' The separator text that indicates the values are ranged. The default value +#' of `"--"` indicates that an en dash will be used for the range separator. +#' Using `"---"` will be taken to mean that an em dash should be used. Should +#' you want these special symbols to be taken literally, they can be supplied +#' within the base [I()] function. +#' +#' @param fmt *Formatting expressions* +#' +#' `` --- *default:* `NULL` (`optional`) +#' +#' An optional formatting expression in formula form. If used, the RHS of `~` +#' should contain a formatting call (e.g., #' `~ fmt_number(., decimals = 3, use_seps = FALSE`). #' #' @return An object of class `gt_tbl`. @@ -6371,25 +6687,49 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' text. #' #' @inheritParams fmt_number -#' @param label The visible 'label' to use for the link. If `NULL` (the default) +#' +#' @param label *Link label* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The visible 'label' to use for the link. If `NULL` (the default) #' the URL will serve as the label. There are two non-`NULL` options: (1) a #' static text can be used for the label by providing a string, and (2) a #' function can be provided to fashion a label from every URL. -#' @param as_button An option to style the link as a button. By default, this is +#' +#' @param as_button *Style link as a button* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' An option to style the link as a button. By default, this is #' `FALSE`. If this option is chosen then the `button_fill` argument becomes #' usable. -#' @param color The color used for the resulting link and its underline. This is +#' +#' @param color *Link color* +#' +#' `scalar` --- *default:* `"auto"` +#' +#' The color used for the resulting link and its underline. This is #' `"auto"` by default; this allows **gt** to choose an appropriate color -#' based on various factors (e.g., background `button_fill` when `as_button` -#' is `TRUE`). -#' @param show_underline Should the link be decorated with an underline? By +#' based on various factors (such as the background `button_fill` when +#' `as_button` is `TRUE`). +#' +#' @param show_underline *Show the link underline* +#' +#' `scalar|scalar` --- *default:* `"auto"` +#' +#' Should the link be decorated with an underline? By #' default this is `"auto"` which means that **gt** will choose `TRUE` when #' `as_button = FALSE` and `FALSE` in the other case. The link underline will #' be the same color as that set in the `color` option. -#' @param button_fill,button_width,button_outline Options for styling a -#' link-as-button (and only applies if `as_button = TRUE`). All of these -#' options are by default set to `"auto"`, allowing **gt** to choose -#' appropriate fill, width, and outline values. +#' +#' @param button_fill,button_width,button_outline *Button options* +#' +#' `scalar` --- *default:* `"auto"` +#' +#' Options for styling a link-as-button (and only applies if +#' `as_button = TRUE`). All of these options are by default set to `"auto"`, +#' allowing **gt** to choose appropriate fill, width, and outline values. #' #' @return An object of class `gt_tbl`. #' @@ -6864,16 +7204,42 @@ fmt_url <- function( #' separator to be applied between images. #' #' @inheritParams fmt_number -#' @param height The absolute height of the image in the table cell. By default, -#' this is set to `"1em"`. -#' @param sep In the output of images within a body cell, `sep` provides the -#' separator between each image. -#' @param path An optional path to local image files (this is combined with all +#' +#' @param height *Height of image* +#' +#' `scalar` --- *default:* `"1em"` +#' +#' The absolute height of the image in the table cell. By default, this is set +#' to `"1em"`. +#' +#' @param sep *Separator between images* +#' +#' `scalar` --- *default:* `" "` +#' +#' In the output of images within a body cell, `sep` provides the separator +#' between each image. +#' +#' @param path *Path to image files* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional path to local image files (this is combined with all #' filenames). -#' @param file_pattern The pattern to use for mapping input values in the body -#' cells to the names of the graphics files. -#' @param encode The option to always use Base64 encoding for image paths that -#' are determined to be local. By default, this is `TRUE`. +#' +#' @param file_pattern *File pattern specification* +#' +#' `scalar` --- *default:* `"{x}"` +#' +#' The pattern to use for mapping input values in the body cells to the names +#' of the graphics files. The string supplied should use `"{x}"` in the +#' pattern to map filename fragments to input strings. +#' +#' @param encode *Use Base64 encoding* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' The option to always use Base64 encoding for image paths that are +#' determined to be local. By default, this is `TRUE`. #' #' @return An object of class `gt_tbl`. #' @@ -7141,13 +7507,28 @@ fmt_image <- function( #' icons. #' #' @inheritParams fmt_number -#' @param height The absolute height of the flag icon in the table cell. By -#' default, this is set to `"1em"`. -#' @param sep In the output of flag icons within a body cell, `sep` provides the +#' +#' @param height *Height of flag* +#' +#' `scalar` --- *default:* `"1em"` +#' +#' The absolute height of the flag icon in the table cell. By default, this is +#' set to `"1em"`. +#' +#' @param sep *Separator between flags* +#' +#' `scalar` --- *default:* `" "` +#' +#' In the output of flag icons within a body cell, `sep` provides the #' separator between each icon. By default, this is a single space character #' (`" "`). -#' @param use_title An option to display a tooltip for the country name when -#' hovering over the flag icon. By default this is `TRUE`. +#' +#' @param use_title *Display country name on hover* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option to display a tooltip for the country name (in English) when +#' hovering over the flag icon. #' #' @return An object of class `gt_tbl`. #' @@ -7450,10 +7831,15 @@ fmt_flag <- function( #' appropriate output type during render when using `fmt_markdown()`. #' #' @inheritParams fmt_number -#' @param md_engine The engine preference for Markdown rendering. By default, -#' this is set to `"markdown"` where **gt** will use the **markdown** package -#' for Markdown conversion to HTML and LaTeX. The other option is -#' `"commonmark"` and with that the **commonmark** package will be used. +#' +#' @param md_engine *Choice of Markdown engine* +#' +#' `singl-kw:[markdown|commonmark]` --- *default:* `"markdown"` +#' +#' The engine preference for Markdown rendering. By default, this is set to +#' `"markdown"` where **gt** will use the **markdown** package for Markdown +#' conversion to HTML and LaTeX. The other option is `"commonmark"` and with +#' that the **commonmark** package will be used. #' #' @return An object of class `gt_tbl`. #' @@ -7620,11 +8006,16 @@ fmt_markdown <- function( #' the input data other than to decorate it within a pattern. #' #' @inheritParams fmt_number -#' @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 -#' `TRUE` and setting to `FALSE` would be useful in the case where text is -#' crafted for a specific output format in mind. +#' +#' @param escape *Text escaping* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' 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 `TRUE` but setting +#' as `FALSE` would be useful in the case where text is crafted for a specific +#' output format in mind. #' #' @return An object of class `gt_tbl`. #' @@ -7805,12 +8196,23 @@ fmt_passthrough <- function( #' formatting will be applied. #' #' @inheritParams fmt_number -#' @param scope The scope of automatic formatting. By default this includes -#' `"numbers"`-type values and `"currency"`-type values though the scope can -#' be reduced to a single type of value to format. -#' @param lg_num_pref The preference toward either scientific notation for very -#' small and very large values (`"sci"`, the default option), or, suffixed -#' numbers (`"suf"`, for large values only). +#' +#' @param scope *Scope of automatic formatting* +#' +#' `mult-kw:[numbers|currency]` --- *default:* `c("numbers", "currency")` +#' +#' By default, the function will format both `"numbers"`-type values and +#' `"currency"`-type values though the scope can be reduced to a single type +#' of value to format. +#' +#' @param lg_num_pref *Large-number preference* +#' +#' `singl-kw:[sci|suf]` --- *default:* `"sci"` +#' +#' When large numbers are present, there can be a fixed preference toward how +#' they are formatted. Choices are scientific notation for very small and very +#' large values (`"sci"`), or, the use of suffixed numbers (`"suf"`, for large +#' values only). #' #' @return An object of class `gt_tbl`. #' @@ -8129,9 +8531,19 @@ fmt_auto <- function( #' fallback if all contexts aren't provided. #' #' @inheritParams fmt_number -#' @param fns Either a single formatting function or a named list of functions. -#' @param compat An optional vector that provides the compatible classes for the -#' formatter. By default this is `NULL`. +#' +#' @param compat *Formatting compatibility* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' An optional vector that provides the compatible classes for the formatting. +#' By default this is `NULL`. +#' +#' @param fns *Formatting functions* +#' +#' `function|list of functions` --- **required** +#' +#' Either a single formatting function or a named list of functions. #' #' @return An object of class `gt_tbl`. #' From bfbdb59df1b37f7b37951aec63cffad9d22c8ac5 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:32 -0400 Subject: [PATCH 06/39] Update format_vec.R --- R/format_vec.R | 704 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 500 insertions(+), 204 deletions(-) diff --git a/R/format_vec.R b/R/format_vec.R index 501ec8eaeb..9e338c29e0 100644 --- a/R/format_vec.R +++ b/R/format_vec.R @@ -42,72 +42,159 @@ #' - locale-based formatting: providing a locale ID will result in number #' formatting specific to the chosen locale #' -#' @param x A numeric vector. -#' @param decimals An option to specify the exact number of decimal places to -#' use. The default number of decimal places is `2`. -#' @param n_sigfig A option to format numbers to *n* significant figures. By -#' default, this is `NULL` and thus number values will be formatted according -#' to the number of decimal places set via `decimals`. If opting to format -#' according to the rules of significant figures, `n_sigfig` must be a number -#' greater than or equal to `1`. Any values passed to the `decimals` and -#' `drop_trailing_zeros` arguments will be ignored. -#' @param drop_trailing_zeros A logical value that allows for removal of -#' trailing zeros (those redundant zeros after the decimal mark). -#' @param drop_trailing_dec_mark A logical value that determines whether decimal -#' marks should always appear even if there are no decimal digits to display -#' after formatting (e.g, `23` becomes `23.`). The default for this is `TRUE`, -#' which means that trailing decimal marks are not shown. -#' @param use_seps An option to use digit group separators. The type of digit -#' group separator is set by `sep_mark` and overridden if a locale ID is -#' provided to `locale`. This setting is `TRUE` by default. -#' @param accounting An option to use accounting style for values. With `FALSE` -#' (the default), negative values will be shown with a minus sign. Using -#' `accounting = TRUE` will put negative values in parentheses. -#' @param scale_by A value to scale the input. The default is `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 `suffixing` options (i.e., -#' where `suffixing` is not set to `FALSE`). -#' @param suffixing An option to scale and apply suffixes to larger numbers -#' (e.g., `1924000` can be transformed to `1.92M`). This option can accept a -#' logical value, where `FALSE` (the default) will not perform this -#' transformation and `TRUE` will apply thousands (`K`), millions (`M`), -#' billions (`B`), and trillions (`T`) suffixes after automatic value scaling. -#' We can also specify which symbols to use for each of the value ranges by -#' using a character vector of the preferred symbols to replace the defaults -#' (e.g., `c("k", "Ml", "Bn", "Tr")`). +#' @param x *The input vector* +#' +#' `vector(numeric|integer)` --- **required** +#' +#' This is the input vector that will undergo transformation to a character +#' vector of the same length. Values within the vector will be formatted. +#' +#' @param decimals *Number of decimal places* +#' +#' `scalar(val>=0)` --- *default:* `2` +#' +#' This corresponds to the exact number of decimal places to use. A value +#' such as `2.34` can, for example, be formatted with `0` decimal places and +#' it would result in `"2"`. With `4` decimal places, the formatted value +#' becomes `"2.3400"`. The trailing zeros can be removed with +#' `drop_trailing_zeros = TRUE`. If you always need `decimals = 0`, the +#' [fmt_integer()] function should be considered. +#' +#' @param n_sigfig *Number of significant figures* +#' +#' `scalar(val>=1)` --- *default:* `NULL` (`optional`) +#' +#' A option to format numbers to *n* significant figures. By default, this is +#' `NULL` and thus number values will be formatted according to the number of +#' decimal places set via `decimals`. If opting to format according to the +#' rules of significant figures, `n_sigfig` must be a number greater than or +#' equal to `1`. Any values passed to the `decimals` and `drop_trailing_zeros` +#' arguments will be ignored. +#' +#' @param drop_trailing_zeros *Drop any trailing zeros* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' A logical value that allows for removal of trailing zeros (those redundant +#' zeros after the decimal mark). +#' +#' @param drop_trailing_dec_mark *Drop the trailing decimal mark* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' A logical value that determines whether decimal marks should always appear +#' even if there are no decimal digits to display after formatting (e.g., `23` +#' becomes `23.` if `FALSE`). By default trailing decimal marks are not shown. +#' +#' @param use_seps *Use digit group separators* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option to use digit group separators. The type of digit group separator +#' is set by `sep_mark` and overridden if a locale ID is provided to `locale`. +#' This setting is `TRUE` by default. +#' +#' @param accounting *Use accounting style* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' An option to use accounting style for values. Normally, negative values +#' will be shown with a minus sign but using accounting style will instead put +#' any negative values in parentheses. +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. This value will be +#' ignored if using any of the `suffixing` options (i.e., where `suffixing` is +#' not set to `FALSE`). +#' +#' @param suffixing *Specification for large-number suffixing* +#' +#' `scalar|vector` --- *default:* `FALSE` +#' +#' The `suffixing` option allows us to scale and apply suffixes to larger +#' numbers (e.g., `1924000` can be transformed to `1.92M`). This option can +#' accept a logical value, where `FALSE` (the default) will not perform this +#' transformation and `TRUE` will apply thousands (`"K"`), millions (`"M"`), +#' billions (`"B"`), and trillions (`"T"`) suffixes after automatic value +#' scaling. +#' +#' We can alternatively provide a character vector that serves as a +#' specification for which symbols are to used for each of the value ranges. +#' These preferred symbols will replace the defaults (e.g., +#' `c("k", "Ml", "Bn", "Tr")` replaces `"K"`, `"M"`, `"B"`, and `"T"`). #' #' Including `NA` values in the vector will ensure that the particular range -#' will either not be included in the transformation (e.g, `c(NA, "M", "B", -#' "T")` won't modify numbers in the thousands range) or the range will -#' inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers -#' in the range of millions and billions will be in terms of millions). +#' will either not be included in the transformation (e.g., +#' `c(NA, "M", "B", "T")` won't modify numbers at all in the thousands range) +#' or the range will inherit a previous suffix (e.g., with +#' `c("K", "M", NA, "T")`, all numbers in the range of millions and billions +#' will be in terms of millions). #' #' Any use of `suffixing` (where it is not set expressly as `FALSE`) means #' that any value provided to `scale_by` will be ignored. -#' @param pattern A formatting pattern that allows for decoration of the -#' formatted value. The value itself is represented by `{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 -#' (e.g., using `sep_mark = ","` with `1000` would result in a formatted value -#' of `1,000`). -#' @param dec_mark The character to use as a decimal mark (e.g., using -#' `dec_mark = ","` with `0.152` would result in a formatted value of -#' `0,152`). -#' @param force_sign Should the positive sign be shown for positive values -#' (effectively showing a sign for all values except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative numbers will -#' display a minus sign. This option is disregarded when using accounting -#' notation with `accounting = TRUE`. -#' @param locale An optional locale identifier that can be used for formatting -#' the value according the locale's rules. Examples include `"en"` for English -#' (United States) and `"fr"` for French (France). The use of a locale ID will -#' override any locale-specific values provided. We can use the -#' [info_locales()] function as a useful reference for all of the locales that -#' are supported. -#' @param output The output style of the resulting character vector. This can -#' either be `"auto"` (the default), `"plain"`, `"html"`, `"latex"`, `"rtf"`, -#' or `"word"`. In **knitr** rendering (i.e., Quarto or R Markdown), the -#' `"auto"` option will choose the correct `output` value +#' +#' @param pattern *Specification of the formatting pattern* +#' +#' `scalar` --- *default:* `"{x}"` +#' +#' A formatting pattern that allows for decoration of the formatted value. The +#' formatted value is represented by the `{x}` (which can be used multiple +#' times, if needed) and all other characters will be interpreted as string +#' literals. +#' +#' @param sep_mark *Separator mark for digit grouping* +#' +#' `scalar` --- *default:* `","` +#' +#' The string to use as a separator between groups of digits. For example, +#' using `sep_mark = ","` with a value of `1000` would result in a formatted +#' value of `"1,000"`. This argument is ignored if a `locale` is supplied +#' (i.e., is not `NULL`). +#' +#' @param dec_mark *Decimal mark* +#' +#' `scalar` --- *default:* `"."` +#' +#' The string to be used as the decimal mark. For example, using +#' `dec_mark = ","` with the value `0.152` would result in a formatted value +#' of `"0,152"`). This argument is ignored if a `locale` is supplied (i.e., is +#' not `NULL`). +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive values (effectively showing +#' a sign for all values except zero)? If so, use `TRUE` for this option. The +#' default is `FALSE`, where only negative numbers will display a minus sign. +#' This option is disregarded when using accounting notation with +#' `accounting = TRUE`. +#' +#' @param locale *Locale identifier* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional locale identifier that can be used for formatting values +#' according the locale's rules. Examples include `"en"` for English (United +#' States) and `"fr"` for French (France). We can use the [info_locales()] +#' function as a useful reference for all of the locales that are supported. A +#' locale ID can be also set in the initial [gt()] function call (where it +#' would be used automatically by any function with a `locale` argument) but a +#' `locale` value provided here will override that global locale. +#' +#' @param output *Output format* +#' +#' `singl-kw:[auto|plain|html|latex|rtf|word]` --- *default:* `"auto"` +#' +#' The output style of the resulting character vector. This can either be +#' `"auto"` (the default), `"plain"`, `"html"`, `"latex"`, `"rtf"`, or +#' `"word"`. In **knitr** rendering (i.e., Quarto or R Markdown), the `"auto"` +#' option will choose the correct `output` value #' #' @return A character vector. #' @@ -271,20 +358,28 @@ vec_fmt_number <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param suffixing An option to scale and apply suffixes to larger numbers -#' (e.g., `1924000` can be transformed to `2M`). This option can accept a -#' logical value, where `FALSE` (the default) will not perform this +#' +#' @param suffixing *Specification for large-number suffixing* +#' +#' `scalar|vector` --- *default:* `FALSE` +#' +#' The `suffixing` option allows us to scale and apply suffixes to larger +#' numbers (e.g., `1924000` can be transformed to `2M`). This option can +#' accept a logical value, where `FALSE` (the default) will not perform this #' transformation and `TRUE` will apply thousands (`K`), millions (`M`), #' billions (`B`), and trillions (`T`) suffixes after automatic value scaling. -#' We can also specify which symbols to use for each of the value ranges by -#' using a character vector of the preferred symbols to replace the defaults -#' (e.g., `c("k", "Ml", "Bn", "Tr")`). +#' +#' We can alternatively provide a character vector that serves as a +#' specification for which symbols are to used for each of the value ranges. +#' These preferred symbols will replace the defaults (e.g., +#' `c("k", "Ml", "Bn", "Tr")` replaces `"K"`, `"M"`, `"B"`, and `"T"`). #' #' Including `NA` values in the vector will ensure that the particular range -#' will either not be included in the transformation (e.g, `c(NA, "M", "B", -#' "T")` won't modify numbers in the thousands range) or the range will -#' inherit a previous suffix (e.g., with `c("K", "M", NA, "T")`, all numbers -#' in the range of millions and billions will be in terms of millions). +#' will either not be included in the transformation (e.g., +#' `c(NA, "M", "B", "T")` won't modify numbers at all in the thousands range) +#' or the range will inherit a previous suffix (e.g., with +#' `c("K", "M", NA, "T")`, all numbers in the range of millions and billions +#' will be in terms of millions). #' #' Any use of `suffixing` (where it is not set expressly as `FALSE`) means #' that any value provided to `scale_by` will be ignored. @@ -418,15 +513,31 @@ vec_fmt_integer <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param scale_by A value to scale the input. The default is `1.0`. All numeric -#' values will be multiplied by this value first before undergoing formatting. -#' @param exp_style Style of formatting to use for the scientific notation -#' formatting. By default this is `"x10n"` but other options include using -#' a single letter (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to -#' signal a minimum digit width of one, or `"low-ten"` for using a stylized -#' `"10"` marker. -#' @param force_sign_m,force_sign_n Should the plus sign be shown for positive -#' values of the mantissa (first component) or the exponent? This would +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. +#' +#' @param exp_style *Style declaration for exponent formatting* +#' +#' `scalar` --- *default:* `"x10n"` +#' +#' Style of formatting to use for the scientific notation formatting. By +#' default this is `"x10n"` but other options include using a single letter +#' (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to signal a +#' minimum digit width of one, or `"low-ten"` for using a stylized `"10"` +#' marker. +#' +#' @param force_sign_m,force_sign_n *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the plus sign be shown for positive values of the mantissa (first +#' component, `force_sign_m`) or the exponent (`force_sign_n`)? This would #' effectively show a sign for all values except zero on either of those #' numeric components of the notation. If so, use `TRUE` for either one of #' these options. The default for both is `FALSE`, where only negative numbers @@ -580,15 +691,31 @@ vec_fmt_scientific <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param scale_by A value to scale the input. The default is `1.0`. All numeric -#' values will be multiplied by this value first before undergoing formatting. -#' @param exp_style Style of formatting to use for the engineering notation -#' formatting. By default this is `"x10n"` but other options include using -#' a single letter (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to -#' signal a minimum digit width of one, or `"low-ten"` for using a stylized -#' `"10"` marker. -#' @param force_sign_m,force_sign_n Should the plus sign be shown for positive -#' values of the mantissa (first component) or the exponent? This would +#' +#' @param scale_by *Scale values by a fixed multiplier* +#' +#' `scalar` --- *default:* `1` +#' +#' All numeric values will be multiplied by the `scale_by` value before +#' undergoing formatting. Since the `default` value is `1`, no values will be +#' changed unless a different multiplier value is supplied. +#' +#' @param exp_style *Style declaration for exponent formatting* +#' +#' `scalar` --- *default:* `"x10n"` +#' +#' Style of formatting to use for the scientific notation formatting. By +#' default this is `"x10n"` but other options include using a single letter +#' (e.g., `"e"`, `"E"`, etc.), a letter followed by a `"1"` to signal a +#' minimum digit width of one, or `"low-ten"` for using a stylized `"10"` +#' marker. +#' +#' @param force_sign_m,force_sign_n *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the plus sign be shown for positive values of the mantissa (first +#' component, `force_sign_m`) or the exponent (`force_sign_n`)? This would #' effectively show a sign for all values except zero on either of those #' numeric components of the notation. If so, use `TRUE` for either one of #' these options. The default for both is `FALSE`, where only negative numbers @@ -742,14 +869,29 @@ vec_fmt_engineering <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param scale_values Should the values be scaled through multiplication by -#' 100? By default this is `TRUE` since the expectation is that normally -#' values are proportions. Setting to `FALSE` signifies that the values are +#' +#' @param scale_values *Multiply input values by 100* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' Should the values be scaled through multiplication by 100? By default this +#' scaling is performed since the expectation is that incoming values are +#' usually proportional. Setting to `FALSE` signifies that the values are #' already scaled and require only the percent sign when formatted. -#' @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 -#' `right` (the default) or `left`. +#' +#' @param incl_space *Include a space between the value and the % sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' 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 *Percent sign placement* +#' +#' `scalar` --- *default:* `"right"` +#' +#' This option governs the placement of the percent sign. This can be either +#' be `right` (the default) or `left`. #' #' @return A character vector. #' @@ -929,22 +1071,42 @@ vec_fmt_percent <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param to_units A keyword that signifies the desired output quantity. This -#' can be any from the following set: `"per-mille"`, `"per-myriad"`, `"pcm"`, -#' `"ppm"`, `"ppb"`, `"ppt"`, or `"ppq"`. -#' @param symbol The symbol/units to use for the quantity. By default, this is -#' set to `"auto"` and **gt** will choose the appropriate symbol based on the +#' +#' @param to_units *Output Quantity* +#' +#' `singl-kw:[per-mille|per-myriad|pcm|ppm|ppb|ppt|ppq]` --- *default:* `"per-mille"` +#' +#' A keyword that signifies the desired output quantity. This can be any from +#' the following set: `"per-mille"`, `"per-myriad"`, `"pcm"`, `"ppm"`, +#' `"ppb"`, `"ppt"`, or `"ppq"`. +#' +#' @param symbol *Symbol or units to use in output display* +#' +#' `scalar` --- *default:* `"auto"` +#' +#' The symbol/units to use for the quantity. By default, this is set to +#' `"auto"` and **gt** will choose the appropriate symbol based on the #' `to_units` keyword and the output context. However, this can be changed by #' supplying a string (e.g, using `symbol = "ppbV"` when `to_units = "ppb"`). -#' @param scale_values Should the values be scaled through multiplication -#' according to the keyword set in `to_units`? By default this is `TRUE` since -#' the expectation is that normally values are proportions. Setting to `FALSE` -#' signifies that the values are already scaled and require only the -#' appropriate symbol/units when formatted. -#' @param incl_space An option for whether to include a space between the value -#' and the symbol/units. The default is `"auto"` which provides spacing -#' dependent on the mark itself. This can be directly controlled by using -#' either `TRUE` or `FALSE`. +#' +#' @param scale_values *Scale input values accordingly* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' Should the values be scaled through multiplication according to the keyword +#' set in `to_units`? By default this is `TRUE` since the expectation is that +#' normally values are proportions. Setting to `FALSE` signifies that the +#' values are already scaled and require only the appropriate symbol/units +#' when formatted. +#' +#' @param incl_space *Include a space between the value and the symbol/units* +#' +#' `scalar|scalar` --- *default:* `"auto"` +#' +#' An option for whether to include a space between the value and the +#' symbol/units. The default is `"auto"` which provides spacing dependent on +#' the mark itself. This can be directly controlled by using either `TRUE` or +#' `FALSE`. #' #' @return A character vector. #' @@ -1111,21 +1273,36 @@ vec_fmt_partsper <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param accuracy The type of fractions to generate. This can either be one of -#' the keywords `"low"`, `"med"`, or `"high"` (to generate fractions with -#' denominators of up to 1, 2, or 3 digits, respectively) or an integer value -#' greater than zero to obtain fractions with a fixed denominator (`2` yields -#' halves, `3` is for thirds, `4` is quarters, etc.). For the latter option, -#' using `simplify = TRUE` will simplify fractions where possible (e.g., `2/4` -#' will be simplified as `1/2`). By default, the `"low"` option is used. -#' @param simplify If choosing to provide a numeric value for `accuracy`, the -#' option to simplify the fraction (where possible) can be taken with `TRUE` -#' (the default). With `FALSE`, denominators in fractions will be fixed to the +#' +#' @param accuracy *Accuracy of fractions* +#' +#' `singl-kw:[low|med|high]|scalar(val>=1)` --- *default:* `"low"` +#' +#' The type of fractions to generate. This can either be one of the keywords +#' `"low"`, `"med"`, or `"high"` (to generate fractions with denominators of +#' up to 1, 2, or 3 digits, respectively) or an integer value greater than +#' zero to obtain fractions with a fixed denominator (`2` yields halves, `3` +#' is for thirds, `4` is quarters, etc.). For the latter option, using +#' `simplify = TRUE` will simplify fractions where possible (e.g., `2/4` will +#' be simplified as `1/2`). By default, the `"low"` option is used. +#' +#' @param simplify *Simplify the fraction* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' If choosing to provide a numeric value for `accuracy`, the option to +#' simplify the fraction (where possible) can be taken with `TRUE` (the +#' default). With `FALSE`, denominators in fractions will be fixed to the #' value provided in `accuracy`. -#' @param layout For HTML output, the `"inline"` layout is the default. This -#' layout places the numerals of the fraction on the baseline and uses a -#' standard slash character. The `"diagonal"` layout will generate fractions -#' that are typeset with raised/lowered numerals and a virgule. +#' +#' @param layout *Layout of fractions in HTML output* +#' +#' `singl-kw:[inline|diagonal]` --- *default:* `"inline"` +#' +#' For HTML output, the `"inline"` layout is the default. This layout places +#' the numerals of the fraction on the baseline and uses a standard slash +#' character. The `"diagonal"` layout will generate fractions that are typeset +#' with raised/lowered numerals and a virgule. #' #' @return A character vector. #' @@ -1265,7 +1442,12 @@ vec_fmt_fraction <- function( #' the possible inputs to the `currency` argument. #' #' @inheritParams vec_fmt_number -#' @param currency The currency to use for the numeric value. This input can be +#' +#' @param currency *Currency to use* +#' +#' `scalar|obj:` --- *default:* `"USD"` +#' +#' The currency to use for the numeric value. This input can be #' supplied as a 3-letter currency code (e.g., `"USD"` for U.S. Dollars, #' `"EUR"` for the Euro currency). Use [info_currencies()] to get an #' information table with all of the valid currency codes and examples of @@ -1282,14 +1464,28 @@ vec_fmt_fraction <- function( #' the letter "f" in all other output contexts). Please note that `decimals` #' will default to `2` when using the [currency()] helper function. #' -#' If nothing is provided to `currency` then `"USD"` (U.S. dollars) will be -#' used. -#' @param use_subunits An option for whether the subunits portion of a currency -#' value should be displayed. By default, this is `TRUE`. -#' @param placement The placement of the currency symbol. This can be either be -#' `left` (the default) or `right`. -#' @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. +#' @param use_subunits *Show or hide currency subunits* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option for whether the subunits portion of a currency value should be +#' displayed. For example, with an input value of `273.81`, the default +#' formatting will produce `"$273.81"`. Removing the subunits (with +#' `use_subunits = FALSE`) will give us `"$273"`. +#' +#' @param placement *Currency symbol placement* +#' +#' `scalar` --- *default:* `"left"` +#' +#' The placement of the currency symbol. This can be either be `left` (as +#' in `"$450"`) or `right` (which yields `"450$"`). +#' +#' @param incl_space *Include a space between the value and the currency symbol* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' 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 A character vector. #' @@ -1435,8 +1631,13 @@ vec_fmt_currency <- function( #' rounding values as necessary. #' #' @inheritParams vec_fmt_number -#' @param case Should Roman numerals should be rendered as uppercase (`"upper"`) -#' or lowercase (`"lower"`) letters? By default, this is set to `"upper"`. +#' +#' @param case *Use uppercase or lowercase letters* +#' +#' `singl-kw:[upper|lower]` --- *default:* `"upper"` +#' +#' Should Roman numerals should be rendered as uppercase (`"upper"`) or +#' lowercase (`"lower"`) letters? By default, this is set to `"upper"`. #' #' @return A character vector. #' @@ -1546,14 +1747,23 @@ vec_fmt_roman <- function( #' diacritical marks). #' #' @inheritParams vec_fmt_number -#' @param case Should resulting index characters be rendered as uppercase -#' (`"upper"`) or lowercase (`"lower"`) letters? By default, this is set to -#' `"upper"`. -#' @param index_algo The indexing algorithm for handling the recycling of the -#' index character set. By default, the `"repeat"` option is used where -#' characters are doubled, tripled, and so on, when moving past the character -#' set limit. The alternative is the `"excel"` option, where Excel-based -#' column naming is adapted and used here (e.g., `[..., Y, Z, AA, AB, ...]`). +#' +#' @param case *Use uppercase or lowercase letters* +#' +#' `singl-kw:[upper|lower]` --- *default:* `"upper"` +#' +#' Should the resulting index characters be rendered as uppercase (`"upper"`) +#' or lowercase (`"lower"`) letters? By default, this is set to `"upper"`. +#' +#' @param index_algo *Indexing algorithm* +#' +#' `singl-kw:[repeat|excel]` --- *default:* `"repeat"` +#' +#' The indexing algorithm handles the recycling of the index character set. By +#' default, the `"repeat"` option is used where characters are doubled, +#' tripled, and so on, when moving past the character set limit. The +#' alternative is the `"excel"` option, where Excel-based column naming is +#' adapted and used here (e.g., `[..., Y, Z, AA, AB, ...]`). #' #' @return A character vector. #' @@ -1826,15 +2036,39 @@ vec_fmt_spelled_num <- function( #' formatting specific to the chosen locale #' #' @inheritParams vec_fmt_number -#' @param standard The way to express large byte sizes. -#' @param decimals An option to specify the exact number of decimal places to -#' use. The default number of decimal places is `1`. -#' @param incl_space An option for whether to include a space between the value -#' and the units. The default of `TRUE` uses a space character for separation. -#' @param force_sign Should the positive sign be shown for positive numbers -#' (effectively showing a sign for all numbers except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative numbers will -#' display a minus sign. +#' +#' @param standard *Standard used to express byte sizes* +#' +#' `singl-kw:[decimal|binary]` --- *default:* `"decimal"` +#' +#' The form of expressing large byte sizes is divided between: (1) decimal +#' units (powers of 1000; e.g., `"kB"` and `"MB"`), and (2) binary units +#' (powers of 1024; e.g., `"KiB"` and `"MiB"`). +#' +#' @param decimals *Number of decimal places* +#' +#' `scalar(val>=0)` --- *default:* `1` +#' +#' This corresponds to the exact number of decimal places to use. A value +#' such as `2.34` can, for example, be formatted with `0` decimal places and +#' it would result in `"2"`. With `4` decimal places, the formatted value +#' becomes `"2.3400"`. The trailing zeros can be removed with +#' `drop_trailing_zeros = TRUE`. +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive numbers (effectively showing +#' a sign for all numbers except zero)? If so, use `TRUE` for this option. The +#' default is `FALSE`, where only negative numbers will display a minus sign. +#' +#' @param incl_space *Include a space between the value and the units* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option for whether to include a space between the value and the units. +#' The default is to use a space character for separation. #' #' @return A character vector. #' @@ -1977,9 +2211,14 @@ vec_fmt_bytes <- function( #' `YYYY-MM-DD`). #' #' @inheritParams vec_fmt_number -#' @param date_style The date style to use. By default this is `"iso"` which -#' corresponds to ISO 8601 date formatting. The other date styles can be -#' viewed using [info_date_style()]. +#' +#' @param date_style *Predefined style for dates* +#' +#' `scalar|scalar(1<=val<=41)` --- *default:* `"iso"` +#' +#' The date style to use. By default this is the short name `"iso"` which +#' corresponds to ISO 8601 date formatting. There are 41 date styles in total +#' and their short names can be viewed using [info_date_style()]. #' #' @return A character vector. #' @@ -2158,9 +2397,15 @@ vec_fmt_date <- function( #' always results in the formatting of `00:00:00`). #' #' @inheritParams vec_fmt_number -#' @param time_style The time style to use. By default this is `"iso"` which -#' corresponds to how times are formatted within ISO 8601 datetime values. The -#' other time styles can be viewed using [info_time_style()]. +#' +#' @param time_style *Predefined style for times* +#' +#' `scalar|scalar(1<=val<=25)` --- *default:* `"iso"` +#' +#' The time style to use. By default this is the short name `"iso"` which +#' corresponds to how times are formatted within ISO 8601 datetime values. +#' There are 25 time styles in total and their short names can be viewed using +#' [info_time_style()]. #' #' @return A character vector. #' @@ -2329,16 +2574,33 @@ vec_fmt_time <- function( #' the ISO 8601 form of `YYYY-MM-DD HH:MM:SS` or `YYYY-MM-DD`). #' #' @inheritParams vec_fmt_number +#' #' @inheritParams vec_fmt_date +#' #' @inheritParams vec_fmt_time -#' @param sep The separator string to use between the date and time components. -#' By default, this is a single space character (`" "`). Only used when not +#' +#' @param sep *Separator between date and time components* +#' +#' `scalar` --- *default:* `" "` +#' +#' The separator string to use between the date and time components. By +#' default, this is a single space character (`" "`). Only used when not #' specifying a `format` code. -#' @param format An optional format code used for generating custom dates/times. -#' If used then the arguments governing preset styles (`date_style` and +#' +#' @param format *Date/time formatting string* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional formatting string used for generating custom dates/times. If +#' used then the arguments governing preset styles (`date_style` and #' `time_style`) will be ignored in favor of formatting via the `format` #' string. -#' @param tz The time zone for printing dates/times (i.e., the output). The +#' +#' @param tz *Time zone* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The time zone for printing dates/times (i.e., the output). The #' default of `NULL` will preserve the time zone of the input data in the #' output. If providing a time zone, it must be one that is recognized by the #' user's operating system (a vector of all valid `tz` values can be produced @@ -3183,45 +3445,74 @@ vec_fmt_datetime <- function( #' which is `c("days", "hours", "minutes", "seconds")` #' #' @inheritParams vec_fmt_number -#' @param input_units If one or more selected columns contains numeric values, a -#' keyword must be provided for `input_units` for **gt** to determine how -#' those values are to be interpreted in terms of duration. The accepted units -#' are: `"seconds"`, `"minutes"`, `"hours"`, `"days"`, and `"weeks"`. -#' @param output_units Controls the output time units. The default, `NULL`, -#' means that **gt** will automatically choose time units based on the input -#' duration value. To control which time units are to be considered for output -#' (before trimming with `trim_zero_units`) we can specify a vector of one or -#' more of the following keywords: `"weeks"`, `"days"`, `"hours"`, -#' `"minutes"`, or `"seconds"`. -#' @param duration_style A choice of four formatting styles for the output -#' duration values. With `"narrow"` (the default style), duration values will -#' be formatted with single letter time-part units (e.g., 1.35 days will be -#' styled as `"1d 8h 24m`). With `"wide"`, this example value will be expanded -#' to `"1 day 8 hours 24 minutes"` after formatting. The `"colon-sep"` style -#' will put days, hours, minutes, and seconds in the `"([D]/)[HH]:[MM]:[SS]"` +#' +#' @param input_units *Declaration of duration units for numerical values* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' If one or more selected columns contains numeric values (not `difftime` +#' values, which contain the duration units), a keyword must be provided for +#' `input_units` for **gt** to determine how those values are to be +#' interpreted in terms of duration. The accepted units are: `"seconds"`, +#' `"minutes"`, `"hours"`, `"days"`, and `"weeks"`. +#' +#' @param output_units *Choice of output units* +#' +#' `mult-kw:[weeks|days|hours|minutes|seconds]` --- *default:* `NULL` (`optional`) +#' +#' Controls the output time units. The default, `NULL`, means that **gt** will +#' automatically choose time units based on the input duration value. To +#' control which time units are to be considered for output (before trimming +#' with `trim_zero_units`) we can specify a vector of one or more of the +#' following keywords: `"weeks"`, `"days"`, `"hours"`, `"minutes"`, or +#' `"seconds"`. +#' +#' @param duration_style *Style for representing duration values* +#' +#' `singl-kw:[narrow|wide|colon-sep|iso]` --- *default:* `"narrow"` +#' +#' A choice of four formatting styles for the output duration values. With +#' `"narrow"` (the default style), duration values will be formatted with +#' single letter time-part units (e.g., 1.35 days will be styled as +#' `"1d 8h 24m"`). With `"wide"`, this example value will be expanded to +#' `"1 day 8 hours 24 minutes"` after formatting. The `"colon-sep"` style will +#' put days, hours, minutes, and seconds in the `"([D]/)[HH]:[MM]:[SS]"` #' format. The `"iso"` style will produce a value that conforms to the ISO #' 8601 rules for duration values (e.g., 1.35 days will become `"P1DT8H24M"`). -#' @param trim_zero_units Provides methods to remove output time units that have -#' zero values. By default this is `TRUE` and duration values that might -#' otherwise be formatted as `"0w 1d 0h 4m 19s"` with -#' `trim_zero_units = FALSE` are instead displayed as `"1d 4m 19s"`. Aside -#' from using `TRUE`/`FALSE` we could provide a vector of keywords for more -#' precise control. These keywords are: (1) `"leading"`, to omit all leading -#' zero-value time units (e.g., `"0w 1d"` -> `"1d"`), (2) `"trailing"`, to -#' omit all trailing zero-value time units (e.g., `"3d 5h 0s"` -> `"3d 5h"`), -#' and `"internal"`, which removes all internal zero-value time units (e.g., -#' `"5d 0h 33m"` -> `"5d 33m"`). -#' @param max_output_units If `output_units` is `NULL`, where the output time -#' units are unspecified and left to **gt** to handle, a numeric value -#' provided for `max_output_units` will be taken as the maximum number of time -#' units to display in all output time duration values. By default, this is -#' `NULL` and all possible time units will be displayed. This option has no -#' effect when `duration_style = "colon-sep"` (only `output_units` can be used -#' to customize that type of duration output). -#' @param force_sign Should the positive sign be shown for positive values -#' (effectively showing a sign for all values except zero)? If so, use `TRUE` -#' for this option. The default is `FALSE`, where only negative value will -#' display a minus sign. +#' +#' @param trim_zero_units *Trimming of zero values* +#' +#' `scalar|mult-kw:[leading|trailing|internal]` --- *default:* `TRUE` +#' +#' Provides methods to remove output time units that have zero values. By +#' default this is `TRUE` and duration values that might otherwise be +#' formatted as `"0w 1d 0h 4m 19s"` with `trim_zero_units = FALSE` are instead +#' displayed as `"1d 4m 19s"`. Aside from using `TRUE`/`FALSE` we could +#' provide a vector of keywords for more precise control. These keywords are: +#' (1) `"leading"`, to omit all leading zero-value time units (e.g., `"0w 1d"` +#' -> `"1d"`), (2) `"trailing"`, to omit all trailing zero-value time units +#' (e.g., `"3d 5h 0s"` -> `"3d 5h"`), and `"internal"`, which removes all +#' internal zero-value time units (e.g., `"5d 0h 33m"` -> `"5d 33m"`). +#' +#' @param max_output_units *Maximum number of time units to display* +#' +#' `scalar(val>=1)` --- *default:* `NULL` (`optional`) +#' +#' If `output_units` is `NULL`, where the output time units are unspecified +#' and left to **gt** to handle, a numeric value provided for +#' `max_output_units` will be taken as the maximum number of time units to +#' display in all output time duration values. By default, this is `NULL` and +#' all possible time units will be displayed. This option has no effect when +#' `duration_style = "colon-sep"` (only `output_units` can be used to +#' customize that type of duration output). +#' +#' @param force_sign *Forcing the display of a positive sign* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the positive sign be shown for positive values (effectively showing +#' a sign for all values except zero)? If so, use `TRUE` for this option. By +#' default only negative values will display a minus sign. #' #' @return A character vector. #' @@ -3397,10 +3688,15 @@ vec_fmt_duration <- function( #' appropriate output type. #' #' @inheritParams vec_fmt_number -#' @param md_engine The engine preference for Markdown rendering. By default, -#' this is set to `"markdown"` where **gt** will use the **markdown** package -#' for Markdown conversion to HTML and LaTeX. The other option is -#' `"commonmark"` and with that the **commonmark** package will be used. +#' +#' @param md_engine *Choice of Markdown engine* +#' +#' `singl-kw:[markdown|commonmark]` --- *default:* `"markdown"` +#' +#' The engine preference for Markdown rendering. By default, this is set to +#' `"markdown"` where **gt** will use the **markdown** package for Markdown +#' conversion to HTML and LaTeX. The other option is `"commonmark"` and with +#' that the **commonmark** package will be used. #' #' @return A character vector. #' From e63d10bad0c43597b620afabfdea3c72e7286abc Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:35 -0400 Subject: [PATCH 07/39] Update gt.R --- R/gt.R | 119 +++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 86 insertions(+), 33 deletions(-) diff --git a/R/gt.R b/R/gt.R index 7344448cfb..871a8c01ed 100644 --- a/R/gt.R +++ b/R/gt.R @@ -47,39 +47,92 @@ #' `row_group.sep` argument allows for control in how the row group label will #' appear in the display table. #' -#' @param data A `data.frame` object or a tibble. -#' @param rowname_col The column name in the input `data` table to use as row -#' captions to be placed in the display table stub. If the `rownames_to_stub` -#' option is `TRUE` then any column name provided to `rowname_col` will be -#' ignored. -#' @param groupname_col The column name in the input `data` table to use as -#' group labels for generation of stub row groups. If the input `data` table -#' has the `grouped_df` class (through use of the [dplyr::group_by()] function -#' or associated `group_by*()` functions) then any input here is ignored. -#' @param process_md Should the contents of the `rowname_col` and -#' `groupname_col` be interpreted as Markdown? By default this is `FALSE`. -#' @param caption An optional table caption to use for cross-referencing in R -#' Markdown, Quarto, or **bookdown**. -#' @param rownames_to_stub An option to take rownames from the input `data` -#' table as row captions in the display table stub. -#' @param row_group_as_column An option that alters the display of row group -#' labels. By default this is `FALSE` and row group labels will appear in -#' dedicated rows above their respective groups of rows. If `TRUE`, row group -#' labels will occupy a secondary column in the table stub. -#' @param auto_align Optionally have column data be aligned depending on the -#' content contained in each column of the input `data`. Internally, this -#' calls `cols_align(align = "auto")` for all columns. -#' @param id The table ID. By default, with `NULL`, this will be a random, -#' ten-letter ID as generated by using the [random_id()] function. A custom -#' table ID can be used with any single-length character vector. -#' @param locale An optional locale ID that can be set as the default locale for -#' all functions that take a `locale` argument. Examples of valid locales -#' include `"en"` for English (United States) and `"fr"` for French (France). -#' Refer to the information provided by the [info_locales()] function to -#' determine which locales are supported. -#' @param row_group.sep The separator to use between consecutive group names (a -#' possibility when providing `data` as a `grouped_df` with multiple groups) -#' in the displayed stub row group label. +#' @param data *Input data table* +#' +#' `obj:|obj:` --- **required** +#' +#' A `data.frame` object or a tibble (`tbl_df`). +#' +#' @param rowname_col *Column for row names/labels from `data`* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The column name in the input `data` table to use as row labels to be placed +#' in the table stub. If the `rownames_to_stub` option is `TRUE` then any +#' column name provided to `rowname_col` will be ignored. +#' +#' @param groupname_col *Column for group names/labels from `data`* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The column name in the input `data` table to use as group labels for +#' generation of stub row groups. If the input `data` table has the +#' `grouped_df` class (through use of the [dplyr::group_by()] function or +#' associated `group_by*()` functions) then any input here is ignored. +#' +#' @param process_md *Process Markdown in `rowname_col` and `groupname_col`* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should the contents of the `rowname_col` and `groupname_col` be interpreted +#' as Markdown? By default this won't happen. +#' +#' @param caption *Table caption text* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional table caption to use for cross-referencing in R Markdown, +#' Quarto, or **bookdown**. +#' +#' @param rownames_to_stub *Use data frame row labels in the stub* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' An option to take rownames from the input `data` table (should they be +#' available) as row labels in the display table stub. +#' +#' @param row_group_as_column *Mode for displaying row group labels in the stub* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' An option that alters the display of row group labels. By default this is +#' `FALSE` and row group labels will appear in dedicated rows above their +#' respective groups of rows. If `TRUE` row group labels will occupy a +#' secondary column in the table stub. +#' +#' @param auto_align *Automatic alignment of column values and labels* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' Optionally have column data be aligned depending on the content contained +#' in each column of the input `data`. Internally, this calls +#' `cols_align(align = "auto")` for all columns. +#' +#' @param id *The table ID* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' By default (with `NULL`) this will be a random, ten-letter ID as generated +#' by using the [random_id()] function. A custom table ID can be used be +#' providing a single-length character vector. +#' +#' @param locale *Locale identifier* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional locale identifier that can be set as the default locale for all +#' functions that take a `locale` argument. Examples include `"en"` for +#' English (United States) and `"fr"` for French (France). We can use the +#' [info_locales()] function as a useful reference for all of the locales that +#' are supported. +#' +#' @param row_group.sep *Separator text for multiple row group labels* +#' +#' `scalar` --- *default:* `getOption("gt.row_group.sep", " - ")` +#' +#' The separator to use between consecutive group names (a possibility when +#' providing `data` as a `grouped_df` with multiple groups) in the displayed +#' row group label. #' #' @return An object of class `gt_tbl`. #' From ab96648085dee925bb549cb482b33fd6e403590c Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:36 -0400 Subject: [PATCH 08/39] Update gt_group.R --- R/gt_group.R | 101 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 82 insertions(+), 19 deletions(-) diff --git a/R/gt_group.R b/R/gt_group.R index bc3b6f8708..51e908ae11 100644 --- a/R/gt_group.R +++ b/R/gt_group.R @@ -33,11 +33,25 @@ #' can be printed independently and table separation (usually a page break) #' occurs between each of those. #' -#' @param ... One or more **gt** table (`gt_tbl`) objects, typically generated -#' via the [gt()] function. -#' @param .list Allows for the use of a list as an input alternative to `...`. -#' @param .use_grp_opts Should options specified in the `gt_group` object be -#' applied to all contained **gt** tables? By default this is `FALSE`. +#' @param ... *One or more gt table data objects* +#' +#' `obj:` --- (`optional`) +#' +#' One or more **gt** table (`gt_tbl`) objects, typically generated via the +#' [gt()] function. +#' +#' @param .list *Alternative to `...`* +#' +#' `` --- (or, use `...`) +#' +#' Allows for the use of a list as an input alternative to `...`. +#' +#' @param .use_grp_opts *Apply options to all contained tables?* +#' +#' `scalar` --- *default:* `FALSE` +#' +#' Should options specified in the `gt_group` object be applied to all +#' contained **gt** tables? By default this is `FALSE`. #' #' @return An object of class `gt_group`. #' @@ -96,9 +110,19 @@ gt_group <- function( #' The only thing you need to provide is the index value for the **gt** table #' within the `gt_group` object. #' -#' @param data A `gt_group` container object, typically generated through use of -#' the [gt_group()] function along with one or more `gt_tbl` objects. -#' @param which An index value denoting which `gt_tbl` table should be obtained +#' @param data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is a `gt_group` container object. It is typically generated through +#' use of the [gt_group()] function along with one or more `gt_tbl` objects, +#' or, made by splitting a **gt** table with [gt_split()]. +#' +#' @param which *The table to pull from the group* +#' +#' `scalar` --- **required** +#' +#' A single index value denoting which `gt_tbl` table should be obtained #' from the `gt_group` object. #' #' @return An object of class `gt_tbl`. @@ -143,11 +167,19 @@ grp_pull <- function( #' workflow might be, the `grp_add()` function makes it possible to flexibly #' add one or more new **gt** tables, returning a refreshed `gt_group` object. #' -#' @param .data A `gt_group` container object, typically generated through use -#' of the [gt_group()] function along with one or more `gt_tbl` objects. +#' @param .data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is a `gt_group` container object. It is typically generated through +#' use of the [gt_group()] function along with one or more `gt_tbl` objects, +#' or, made by splitting a **gt** table with [gt_split()]. +#' #' @param ... One or more **gt** table (`gt_tbl`) objects, typically generated #' via the [gt()] function. +#' #' @param .list Allows for the use of a list as an input alternative to `...`. +#' #' @param .before,.after A single index for either `.before` or `.after`, #' specifying where the supplied `gt_tbl` objects should be placed amongst the #' existing collection of **gt** tables. If nothing is provided for either @@ -280,10 +312,17 @@ grp_add <- function( #' function and the placement of the cloned **gt** tables can be controlled with #' either the `before` or `after` arguments. #' -#' @param data A `gt_group` container object, typically generated through use -#' of the [gt_group()] function along with one or more `gt_tbl` objects. +#' @param data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is a `gt_group` container object. It is typically generated through +#' use of the [gt_group()] function along with one or more `gt_tbl` objects, +#' or, made by splitting a **gt** table with [gt_split()]. +#' #' @param which A vector of index values denoting which `gt_tbl` tables should #' be cloned inside of the `gt_group` object. +#' #' @param before,after A single index for either `before` or `after`, #' specifies where the cloned `gt_tbl` objects should be placed amongst the #' existing collection of **gt** tables. If nothing is provided for either @@ -403,11 +442,19 @@ grp_clone <- function( #' tables provided must equal the number of indices for tables present in the #' `gt_group` object. #' -#' @param .data A `gt_group` container object, typically generated through use -#' of the [gt_group()] function along with one or more `gt_tbl` objects. +#' @param .data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is a `gt_group` container object. It is typically generated through +#' use of the [gt_group()] function along with one or more `gt_tbl` objects, +#' or, made by splitting a **gt** table with [gt_split()]. +#' #' @param ... One or more **gt** table (`gt_tbl`) objects, typically generated #' via the [gt()] function. +#' #' @param .list Allows for the use of a list as an input alternative to `...`. +#' #' @param .which Index values denoting which `gt_tbl` tables should be replaced #' in the `gt_group` object. #' @@ -475,9 +522,19 @@ grp_replace <- function( #' specified `gt_tbl` objects gone. The only thing you need to provide is the #' index value for the **gt** table within the `gt_group` object. #' -#' @param data A `gt_group` container object, typically generated through use of -#' the [gt_group()] function along with one or more `gt_tbl` objects. -#' @param which An index value denoting which `gt_tbl` table should be removed +#' @param data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is a `gt_group` container object. It is typically generated through +#' use of the [gt_group()] function along with one or more `gt_tbl` objects, +#' or, made by splitting a **gt** table with [gt_split()]. +#' +#' @param which *The table to remove from the group* +#' +#' `scalar` --- **required** +#' +#' A single index value denoting which `gt_tbl` table should be removed #' from the `gt_group` object. #' #' @return An object of class `gt_group`. @@ -507,8 +564,14 @@ grp_rm <- function( #' element that can adjusted. #' #' @inheritParams tab_options -#' @param data A `gt_group` container object, typically generated through use of -#' the [gt_group()] function along with one or more `gt_tbl` objects. +#' +#' @param data *The gt table group object* +#' +#' `obj:` --- **required** +#' +#' This is `gt_group` container object. It is typically generated through use +#' of the [gt_group()] function along with one or more `gt_tbl` objects, or, +#' made by splitting a **gt** table with [gt_split()]. #' #' @return An object of class `gt_group`. #' From 5de66014db1b85fd59b94104e245b57146ad8b9a Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:38 -0400 Subject: [PATCH 09/39] Update gt_preview.R --- R/gt_preview.R | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/R/gt_preview.R b/R/gt_preview.R index 5bc7a7609d..5cff932b6d 100644 --- a/R/gt_preview.R +++ b/R/gt_preview.R @@ -33,15 +33,33 @@ #' modify the output of `gt_preview()`. Furthermore, you cannot pass a **gt** #' object to `gt_preview()`. #' -#' @param data A `data.frame` object or a tibble. -#' @param top_n This value will be used as the number of rows from the top of -#' the table to display. The default, `5`, will show the first five rows of -#' the table. -#' @param bottom_n The value will be used as the number of rows from the bottom +#' @param data *Input data table* +#' +#' `obj:|obj:` --- **required** +#' +#' A `data.frame` object or a tibble (`tbl_df`). +#' +#' @param top_n *Top n rows to display* +#' +#' `scalar` --- *default:* `5` +#' +#' The `top_n` value will be used as the number of rows from the top of the +#' table to display. The default, `5`, will show the first five rows of the +#' table. +#' +#' @param bottom_n *Bottom n rows to display* +#' +#' `scalar` --- *default:* `1` +#' +#' The `bottom_n` value will be used as the number of rows from the bottom #' of the table to display. The default, `1`, will show the final row of the #' table. -#' @param incl_rownums An option to include the row numbers for `data` in the -#' table stub. By default, this is `TRUE`. +#' +#' @param incl_rownums *Display row numbers* +#' +#' `scalar` --- *default:* `TRUE` +#' +#' An option to include the row numbers for `data` in the table stub. #' #' @return An object of class `gt_tbl`. #' From 391b15ea92c5b02fd5e7f0ff25ea6dde8184b667 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:40 -0400 Subject: [PATCH 10/39] Update gt_split.R --- R/gt_split.R | 40 +++++++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/R/gt_split.R b/R/gt_split.R index a7a33a3515..cd633710e3 100644 --- a/R/gt_split.R +++ b/R/gt_split.R @@ -32,15 +32,37 @@ #' smaller tables across multiple pages (in RTF and Word outputs, primarily via #' [gtsave()]), or, with breaks between them when the output context is HTML. #' -#' @param data A **gt** table object (`gt_tbl`) that is created using the [gt()] -#' function. -#' @param row_every_n A directive to split at every *n* number of rows. This -#' argument expects a single numerical value. -#' @param row_slice_i An argument for splitting at specific row indices. Here, -#' we expect either a vector of index values or a function that evaluates to a -#' numeric vector. -#' @param col_slice_at Any columns where vertical splitting across should occur. -#' The splits occur to the right of the resolved column names. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param row_every_n *Split at every n rows* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' A directive to split at every *n* number of rows. This argument expects a +#' single numerical value. +#' +#' @param row_slice_i *Row-slicing indices* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' An argument for splitting at specific row indices. Here, we expect either a +#' vector of index values or a function that evaluates to a numeric vector. +#' +#' @param col_slice_at *Column-slicing locations* +#' +#' `` --- *default:* `NULL` (`optional`) +#' +#' Any columns where vertical splitting across should occur. The splits occur +#' to the right of the resolved column names. Can either be a series of column +#' names provided in [c()], a vector of column indices, or a select helper +#' function. Examples of select helper functions include [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and +#' [everything()]. #' #' @return An object of class `gt_group`. #' From 91faeb0113a4df487d10315bddad876fbb4cf9bf Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:42 -0400 Subject: [PATCH 11/39] Update helpers.R --- R/helpers.R | 451 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 366 insertions(+), 85 deletions(-) diff --git a/R/helpers.R b/R/helpers.R index 5cf0d624f6..405d42ce90 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -32,10 +32,14 @@ #' in HTML but this function `md()`... it's almost like a two-for-one deal (you #' get to use Markdown plus any HTML fragments *at the same time*). #' -#' @param text The text that is understood to contain Markdown formatting. +#' @param text *Markdown text* +#' +#' `scalar` --- **required** +#' +#' The text that is understood to contain Markdown formatting. #' #' @return A character object of class `from_markdown`. It's tagged as being -#' Markdown text and it will undergo conversion to HTML. +#' Markdown text and it will undergo conversion to the desired output context. #' #' @section Examples: #' @@ -79,8 +83,19 @@ md <- function(text) { #' against escaping, so, your HTML tags will come through as HTML when #' rendered... to HTML. #' -#' @param text,... The text that is understood to be HTML text, which is to be -#' preserved. +#' @param text *HTML text* +#' +#' `scalar` --- **required** +#' +#' The text that is understood to be HTML text, which is to be preserved in +#' the HTML output context. +#' +#' @param ... *Optional parameters for `htmltools::HTML()`* +#' +#' `` --- (`optional`) +#' +#' The `htmltools::HTML()` function contains `...` and anything provided here +#' will be passed to that internal function call. #' #' @return A character object of class `html`. It's tagged as an HTML fragment #' that is not to be sanitized. @@ -143,9 +158,13 @@ is_rtf <- function(x) { #' for an absolute definition of size as opposed to the analogous helper #' function [pct()]. #' -#' @param x the numeric value to format as a string (e.g., `"12px"`) for -#' some [tab_options()] arguments that can take values as units of -#' pixels (e.g., `table.font.size`). +#' @param x *Numeric length in pixels* +#' +#' `scalar` --- **required** +#' +#' The numeric value to format as a string (e.g., `"12px"`) for some +#' [tab_options()] arguments that can take values as units of pixels (e.g., +#' `table.font.size`). #' #' @return A character vector with a single value in pixel units. #' @@ -199,9 +218,12 @@ px <- function(x) { #' [cell_borders()]). Should a more exact definition of size be required, the #' analogous helper function [pct()] will be more useful. #' -#' @param x the numeric value to format as a string percentage for some -#' [tab_options()] arguments that can take percentage values -#' (e.g., `table.width`). +#' @param x *Numeric value in percent* +#' +#' `scalar` --- **required** +#' +#' The numeric value to format as a string percentage for some [tab_options()] +#' arguments that can take percentage values (e.g., `table.width`). #' #' @return A character vector with a single value in percentage units. #' @@ -306,9 +328,12 @@ stub <- function() { #' `locations` argument. The header location where the title and optionally the #' subtitle reside is generated by the [tab_header()] function. #' -#' @param groups We can either specify `"title"`, `"subtitle"`, or both (the -#' default) in a vector to target the title element, the subtitle element, or -#' both elements. +#' @param groups *Specification of groups* +#' +#' `mult-kw:[title|subtitle]` --- *default:* `c("title", "subtitle")` +#' +#' We can either specify `"title"`, `"subtitle"`, or both (the default) in a +#' vector to target the title element, the subtitle element, or both elements. #' #' @return A list object of classes `cells_title` and `location_cells`. #' @@ -517,7 +542,14 @@ cells_stubhead <- function() { #' 'column_spanners' location is generated by one or more uses of the #' [tab_spanner()] function or the [tab_spanner_delim()] function. #' -#' @param spanners The names of the spanners that are to be targeted. +#' @param spanners *Specification of spanner IDs* +#' +#' `` --- *default:* `everything()` +#' +#' The spanners to which targeting operations are constrained. Can either be a +#' series of spanner ID values provided in [c()] or a select helper function. +#' Examples of select helper functions include [starts_with()], [ends_with()], +#' [contains()], [matches()], [one_of()], [num_range()], and [everything()]. #' #' @return A list object with the classes `cells_column_spanners` and #' `location_cells`. @@ -622,7 +654,15 @@ cells_column_spanners <- function(spanners = everything()) { #' functions' `locations` argument. The 'column_labels' location is present by #' default in every **gt** table. #' -#' @param columns The names of the column labels that are to be targeted. +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns to which targeting operations are constrained. Can either +#' be a series of column names provided in [c()], a vector of column indices, +#' or a select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. #' #' @return A list object with the classes `cells_column_labels` and #' `location_cells`. @@ -747,7 +787,15 @@ cells_column_labels <- function(columns = everything()) { #' (by way of [dplyr::group_by()]), or, by specifying groups with the #' [tab_row_group()] function. #' -#' @param groups The names of the row groups that are to be targeted. +#' @param groups *Specification of row group IDs* +#' +#' `` --- *default:* `everything()` +#' +#' The row groups to which targeting operations are constrained. Can either be +#' a series of row group ID values provided in [c()] or a select helper +#' function. Examples of select helper functions include [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and +#' [everything()]. #' #' @return A list object with the classes `cells_row_groups` and #' `location_cells`. @@ -886,7 +934,18 @@ cells_group <- function(groups = everything()) { #' [grand_summary_rows()] with neither of the previous two conditions being #' true. #' -#' @param rows The names of the rows that are to be targeted. +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' The rows to which targeting operations are constrained. The default +#' [everything()] results in all rows in `columns` being formatted. +#' Alternatively, we can supply a vector of row captions within [c()], a +#' vector of row indices, or a select helper function. Examples of select +#' helper functions include [starts_with()], [ends_with()], [contains()], +#' [matches()], [one_of()], [num_range()], and [everything()]. We can also use +#' expressions to filter down to the rows we need (e.g., `[colname_1] > 100 & +#' [colname_2] < 50`). #' #' @return A list object with the classes `cells_stub` and `location_cells`. #' @@ -991,8 +1050,28 @@ cells_stub <- function(rows = everything()) { #' functions' `locations` argument. The 'body' location is present by default in #' every **gt** table. #' -#' @param columns The names of the columns that are to be targeted. -#' @param rows The names of the rows that are to be targeted. +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns to which targeting operations are constrained. Can either +#' be a series of column names provided in [c()], a vector of column indices, +#' or a select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' form a constraint for targeting operations. The default [everything()] +#' results in all rows in `columns` being formatted. Alternatively, we can +#' supply a vector of row captions within [c()], a vector of row indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. We can also use expressions to filter +#' down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`). #' #' @return A list object with the classes `cells_body` and `location_cells`. #' @@ -1130,9 +1209,39 @@ cells_body <- function( #' those functions' `locations` argument. The 'summary' location is generated by #' the [summary_rows()] function. #' -#' @param groups The names of the groups that the summary rows reside in. -#' @param columns The names of the columns that are to be targeted. -#' @param rows The names of the rows that are to be targeted. +#' @param groups *Specification of row group IDs* +#' +#' `` --- *default:* `everything()` +#' +#' The row groups to which targeting operations are constrained. This aids in +#' targeting the summary rows that reside in certain row groups. Can either be +#' a series of row group ID values provided in [c()] or a select helper +#' function. Examples of select helper functions include [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and +#' [everything()]. +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns to which targeting operations are constrained. Can either +#' be a series of column names provided in [c()], a vector of column indices, +#' or a select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' form a constraint for targeting operations. The default [everything()] +#' results in all rows in `columns` being formatted. Alternatively, we can +#' supply a vector of row captions within [c()], a vector of row indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. We can also use expressions to filter +#' down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`). #' #' @return A list object with the classes `cells_summary` and `location_cells`. #' @@ -1302,8 +1411,28 @@ cells_summary <- function( #' each of those functions' `locations` argument. The 'grand_summary' location #' is generated by the [grand_summary_rows()] function. #' -#' @param columns The names of the columns that are to be targeted. -#' @param rows The names of the rows that are to be targeted. +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns to which targeting operations are constrained. Can either +#' be a series of column names provided in [c()], a vector of column indices, +#' or a select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `columns`, we can specify which of their rows should +#' form a constraint for targeting operations. The default [everything()] +#' results in all rows in `columns` being formatted. Alternatively, we can +#' supply a vector of row captions within [c()], a vector of row indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. We can also use expressions to filter +#' down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`). #' #' @return A list object with the classes `cells_grand_summary` and #' `location_cells`. @@ -1448,8 +1577,28 @@ cells_grand_summary <- function( #' each of those functions' `locations` argument. The 'stub_summary' location is #' generated by the [summary_rows()] function. #' -#' @param groups The names of the groups that are to be targeted. -#' @param rows The names of the rows that are to be targeted. +#' @param groups *Specification of row group IDs* +#' +#' `` --- *default:* `everything()` +#' +#' The row groups to which targeting operations are constrained. Can either be +#' a series of row group ID values provided in [c()] or a select helper +#' function. Examples of select helper functions include [starts_with()], +#' [ends_with()], [contains()], [matches()], [one_of()], [num_range()], and +#' [everything()]. +#' +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' In conjunction with `groups`, we can specify which of their rows should +#' form a constraint for targeting operations. The default [everything()] +#' results in all rows in `columns` being formatted. Alternatively, we can +#' supply a vector of row captions within [c()], a vector of row indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. We can also use expressions to filter +#' down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`). #' #' @return A list object with the classes `cells_stub_summary` and #' `location_cells`. @@ -1595,7 +1744,17 @@ cells_stub_summary <- function( #' 'stub_grand_summary' location is generated by the [grand_summary_rows()] #' function. #' -#' @param rows The names of the rows that are to be targeted. +#' @param rows *Rows to target* +#' +#' `` --- *default:* `everything()` +#' +#' We can specify which rows should be targeted. The default [everything()] +#' results in all rows in `columns` being formatted. Alternatively, we can +#' supply a vector of row captions within [c()], a vector of row indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. We can also use expressions to filter +#' down to the rows we need (e.g., `[colname_1] > 100 & [colname_2] < 50`). #' #' @return A list object with the classes `cells_stub_grand_summary` and #' `location_cells`. @@ -1945,9 +2104,18 @@ cells_source_notes <- function() { #' we were to specify currency strings for multiple output contexts, names are #' required each and every context. #' -#' @param ... One or more named arguments using output contexts as the names and +#' @param ... *Currency symbols by output context* +#' +#' `` --- **required** (or, use `.list`) +#' +#' One or more named arguments using output contexts as the names and #' currency symbol text as the values. -#' @param .list Allows for the use of a list as an input alternative to `...`. +#' +#' @param .list *Alternative to `...`* +#' +#' `` --- **required** (or, use `...`) +#' +#' Allows for the use of a list as an input alternative to `...`. #' #' @return A list object of class `gt_currency`. #' @@ -2032,44 +2200,102 @@ currency <- function( #' also define several styles within a single call of `cell_text()` and #' [tab_style()] will reliably apply those styles to the targeted element. #' -#' @param color The text color. -#' @param font The font or collection of fonts (subsequent font names are) used -#' as fallbacks. -#' @param size The size of the font. Can be provided as a number that is assumed -#' to represent `px` values (or could be wrapped in the [px()]) helper -#' function. We can also use one of the following absolute size keywords: -#' `"xx-small"`, `"x-small"`, `"small"`, `"medium"`, `"large"`, `"x-large"`, -#' or `"xx-large"`. -#' @param style The text style. Can be one of either `"normal"`, `"italic"`, or -#' `"oblique"`. -#' @param weight The weight of the font. Can be a text-based keyword such as +#' @param color *Text color* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The text color can be modified through the `color` argument. +#' +#' @param font *Font (or collection of fonts) used for text* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' The font or collection of fonts (subsequent font names are) used as +#' fallbacks. +#' +#' @param size *Text size* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The size of the font. Can be provided as a number that is assumed to +#' represent `px` values (or could be wrapped in the [px()]) helper function. +#' We can also use one of the following absolute size keywords: `"xx-small"`, +#' `"x-small"`, `"small"`, `"medium"`, `"large"`, `"x-large"`, or +#' `"xx-large"`. +#' +#' @param style *Text style* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Can be one of either `"normal"`, `"italic"`, or `"oblique"`. +#' +#' @param weight *Font weight* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The weight of the font can be modified thorough a text-based option such as #' `"normal"`, `"bold"`, `"lighter"`, `"bolder"`, or, a numeric value between #' `1` and `1000`, inclusive. Note that only variable fonts may support the #' numeric mapping of weight. -#' @param align The text alignment. Can be one of either `"center"`, `"left"`, -#' `"right"`, or `"justify"`. -#' @param v_align The vertical alignment of the text in the cell. Options are -#' `"middle"`, `"top"`, or `"bottom"`. -#' @param stretch Allows for text to either be condensed or expanded. We can use -#' one of the following text-based keywords to describe the degree of +#' +#' @param align *Text alignment* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The text in a cell can be aligned though one of the following options: +#' `"center"`, `"left"`, `"right"`, or `"justify"`. +#' +#' @param v_align *Vertical alignment* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The vertical alignment of the text in the cell can be modified through the +#' options `"middle"`, `"top"`, or `"bottom"`. +#' +#' @param stretch *Stretch text* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Allows for text to either be condensed or expanded. We can use one of the +#' following text-based keywords to describe the degree of #' condensation/expansion: `"ultra-condensed"`, `"extra-condensed"`, #' `"condensed"`, `"semi-condensed"`, `"normal"`, `"semi-expanded"`, #' `"expanded"`, `"extra-expanded"`, or `"ultra-expanded"`. Alternatively, we #' can supply percentage values from `0\%` to `200\%`, inclusive. Negative #' percentage values are not allowed. -#' @param decorate Allows for text decoration effect to be applied. Here, we can -#' use `"overline"`, `"line-through"`, or `"underline"`. -#' @param transform Allows for the transformation of text. Options are -#' `"uppercase"`, `"lowercase"`, or `"capitalize"`. -#' @param whitespace A white-space preservation option. By default, runs of -#' white-space will be collapsed into single spaces but several options exist -#' to govern how white-space is collapsed and how lines might wrap at -#' soft-wrap opportunities. The keyword options are `"normal"`, `"nowrap"`, -#' `"pre"`, `"pre-wrap"`, `"pre-line"`, and `"break-spaces"`. -#' @param indent The indentation of the text. Can be provided as a number that -#' is assumed to represent `px` values (or could be wrapped in the [px()]) -#' helper function. Alternatively, this can be given as a percentage (easily -#' constructed with [pct()]). +#' +#' @param decorate *Decorate text* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Allows for text decoration effect to be applied. Here, we can use +#' `"overline"`, `"line-through"`, or `"underline"`. +#' +#' @param transform *Transform text* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Allows for the transformation of text. Options are `"uppercase"`, +#' `"lowercase"`, or `"capitalize"`. +#' +#' @param whitespace *White-space options* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' A white-space preservation option. By default, runs of white-space will be +#' collapsed into single spaces but several options exist to govern how +#' white-space is collapsed and how lines might wrap at soft-wrap +#' opportunities. The options are `"normal"`, `"nowrap"`, `"pre"`, +#' `"pre-wrap"`, `"pre-line"`, and `"break-spaces"`. +#' +#' @param indent *Text indentation* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' The indentation of the text. Can be provided as a number that is assumed to +#' represent `px` values (or could be wrapped in the [px()]) helper function. +#' Alternatively, this can be given as a percentage (easily constructed with +#' [pct()]). #' #' @return A list object of class `cell_styles`. #' @@ -2243,12 +2469,21 @@ cell_style_to_html.cell_text <- function(style) { #' cells. Specifically, the call to `cell_fill()` should be bound to the #' `styles` argument of [tab_style()]. #' -#' @param color The fill color. If nothing is provided, then `"#D3D3D3"` (light -#' gray) will be used as a default. -#' @param alpha An optional alpha transparency value for the `color` as single -#' value in the range of `0` (fully transparent) to `1` (fully opaque). If not -#' provided the fill color will either be fully opaque or use alpha -#' information from the color value if it is supplied in the #RRGGBBAA format. +#' @param color *Cell fill color* +#' +#' `scalar` --- *default:* `"#D3D3D3"` +#' +#' If nothing is provided for `color` then `"#D3D3D3"` (light gray) will be +#' used as a default. +#' +#' @param alpha *Transparency value* +#' +#' `scalar(0>=val>=1)` --- *default:* `NULL` (`optional`) +#' +#' An optional alpha transparency value for the `color` as single value in the +#' range of `0` (fully transparent) to `1` (fully opaque). If not provided the +#' fill color will either be fully opaque or use alpha information from the +#' color value if it is supplied in the `#RRGGBBAA` format. #' #' @return A list object of class `cell_styles`. #' @@ -2336,16 +2571,36 @@ cell_style_to_html.cell_fill <- function(style) { #' With that selection, the `color`, `style`, and `weight` of the selected #' borders can then be modified. #' -#' @param sides The border sides to be modified. Options include `"left"`, +#' @param sides *Border sides* +#' +#' `vector` --- *default:* `"all"` +#' +#' The border sides to be modified. Options include `"left"`, #' `"right"`, `"top"`, and `"bottom"`. For all borders surrounding the #' selected cells, we can use the `"all"` option. -#' @param color,style,weight The border color, style, and weight. The `color` -#' can be defined with a color name or with a hexadecimal color code. The -#' default `color` value is `"#000000"` (black). The `style` can be one of -#' either `"solid"` (the default), `"dashed"`, `"dotted"`, `"hidden"`, or -#' `"double"`. The `weight` of the border lines is to be given in pixel values -#' (the [px()] helper function is useful for this. The default value for -#' `weight` is `"1px"`. Borders for any defined `sides` can be removed by +#' +#' @param color *Border color* +#' +#' `scalar|NULL` --- *default:* `"#000000"` +#' +#' The border `color` can be defined with a color name or with a hexadecimal +#' color code. The default `color` value is `"#000000"` (black). Borders for any +#' defined `sides` can be removed by supplying `NULL` here. +#' +#' @param style *Border line style* +#' +#' `scalar|NULL` --- *default:* `"solid"` +#' +#' The border `style` can be one of either `"solid"` (the default), +#' `"dashed"`, `"dotted"`, `"hidden"`, or `"double"`. Borders for any +#' defined `sides` can be removed by supplying `NULL` here. +#' +#' @param weight *Border weight* +#' +#' `scalar|NULL` --- *default:* `px(1)` +#' +#' The default value for `weight` is `"1px"` and higher values will become +#' more visually prominent. Borders for any defined `sides` can be removed by #' supplying `NULL` to any of `color`, `style`, or `weight`. #' #' @return A list object of class `cell_styles`. @@ -2553,12 +2808,22 @@ cell_style_structure <- function(name, obj, subclass = name) { #' functions from the **scales** package (all of which have a `palette` #' argument). #' -#' @param colors A vector of colors that will undergo an adjustment in -#' luminance. Each color value provided must either be a color name (in the -#' set of colors provided by `grDevices::colors()`) or a hexadecimal string in -#' the form of "#RRGGBB" or "#RRGGBBAA". -#' @param steps A positive or negative factor by which the luminance will be -#' adjusted. Must be a number between `-2.0` and `2.0`. +#' @param colors *Color vector* +#' +#' `vector` --- **required** +#' +#' This is the vector of colors that will undergo an adjustment in luminance. +#' Each color value provided must either be a color name (in the set of colors +#' provided by `grDevices::colors()`) or a hexadecimal string in the form of +#' "#RRGGBB" or "#RRGGBBAA". +#' +#' @param steps *Adjustment level* +#' +#' `scalar(-2>=val>=2)` --- **required** +#' +#' A positive or negative factor by which the luminance of colors in the +#' `colors` vector will be adjusted. Must be a number between `-2.0` and +#' `2.0`. #' #' @return A vector of color values. #' @@ -2669,7 +2934,12 @@ adjust_luminance <- function( #' character-based ID value argument of variable length (the default is 10 #' letters). #' -#' @param n The number of lowercase letters to use for the random ID. +#' @param n *Number of letters* +#' +#' `scalar` --- *default:* `10` +#' +#' The `n` argument defines the number of lowercase letters to use for the +#' random ID. #' #' @return A character vector containing a single, random ID. #' @@ -2707,8 +2977,11 @@ latex_special_chars <- c( #' `escape_latex()` function will transform a character vector so that it is #' safe to use within LaTeX tables. #' -#' @param text A character vector containing the text that is to be -#' LaTeX-escaped. +#' @param text *LaTeX text* +#' +#' `vector` --- **required** +#' +#' A character vector containing the text that is to be LaTeX-escaped. #' #' @return A character vector. #' @@ -2826,7 +3099,11 @@ gt_latex_dependencies <- function() { #' of [cell_text()] (used with [tab_style()]). To get a helpful listing of fonts #' that work well in tables, use the [info_google_fonts()] function. #' -#' @param name The complete name of a font available in *Google Fonts*. +#' @param name *Google Font name* +#' +#' `scalar` --- **required** +#' +#' The complete name of a font available in *Google Fonts*. #' #' @return An object of class `font_css`. #' @@ -2995,8 +3272,12 @@ default_fonts <- function() { #' function). If using [opt_table_font()] we can invoke this function in its #' `stack` argument. #' -#' @param name A keyword from the set of `"system-ui"`, `"transitional"`, -#' `"old-style"`, `"humanist"`, `"geometric-humanist"`, +#' @param name *Name of font stack* +#' +#' `scalar` --- **required** +#' +#' The name of a font stack. Must be drawn from the set of `"system-ui"`, +#' `"transitional"`, `"old-style"`, `"humanist"`, `"geometric-humanist"`, #' `"classical-humanist"`, `"neo-grotesque"`, `"monospace-slab-serif"`, #' `"monospace-code"`, `"industrial"`, `"rounded-sans"`, `"slab-serif"`, #' `"antique"`, `"didone"`, and `"handwritten"`. From 323d3d58510dce48e2631a93acf63aa94bf88031 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:44 -0400 Subject: [PATCH 12/39] Update image.R --- R/image.R | 65 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/R/image.R b/R/image.R index 5bbe55d64b..f31d0f1917 100644 --- a/R/image.R +++ b/R/image.R @@ -45,8 +45,18 @@ #' where a height of `30px` is a default height chosen to work well within the #' heights of most table rows. #' -#' @param url A url that resolves to an image file. -#' @param height The absolute height (px) of the image in the table cell. +#' @param url *An image URL* +#' +#' `scalar` --- **required** +#' +#' A url that resolves to an image file. +#' +#' @param height *Height of image* +#' +#' `scalar` --- *default:* `30` +#' +#' The absolute height of the image in the table cell (in `"px"` units). By +#' default, this is set to `"30px"`. #' #' @return A character object with an HTML fragment that can be placed inside of #' a cell. @@ -169,8 +179,18 @@ web_image <- function( #' where a height of `30px` is a default height chosen to work well within the #' heights of most table rows. #' -#' @param filename A path to an image file. -#' @param height The absolute height (px) of the image in the table cell. +#' @param filename *Path to image file* +#' +#' `scalar` --- **required** +#' +#' A local path to an image file on disk. +#' +#' @param height *Height of image* +#' +#' `scalar` --- *default:* `30` +#' +#' The absolute height of the image in the table cell (in `"px"` units). By +#' default, this is set to `"30px"`. #' #' @return A character object with an HTML fragment that can be placed inside of #' a cell. @@ -257,13 +277,28 @@ local_image <- function( #' the plot (the default `aspect_ratio` is `1.0`) and this is useful for #' elongating any given plot to fit better within the table construct. #' -#' @param plot_object A ggplot plot object. -#' @param height The absolute height (px) of the image in the table cell. -#' @param aspect_ratio The plot's final aspect ratio. Where the height of the -#' plot is fixed using the `height` argument, the `aspect_ratio` -#' will either compress (`aspect_ratio` < `1.0`) or expand -#' (`aspect_ratio` > `1.0`) the plot horizontally. The default value -#' of `1.0` will neither compress nor expand the plot. +#' @param plot_object *A ggplot plot object* +#' +#' `obj:` --- **required** +#' +#' A `ggplot` plot object. +#' +#' @param height *Height of image* +#' +#' `scalar` --- *default:* `100` +#' +#' The absolute height of the output image in the table cell (in `"px"` +#' units). By default, this is set to `"100px"`. +#' +#' @param aspect_ratio *The final aspect ratio of plot* +#' +#' `scalar` --- *default:* `1.0` +#' +#' This is the plot's final aspect ratio. Where the height of the plot is +#' fixed using the `height` argument, the `aspect_ratio` will either compress +#' (`aspect_ratio` < `1.0`) or expand (`aspect_ratio` > `1.0`) the plot +#' horizontally. The default value of `1.0` will neither compress nor expand +#' the plot. #' #' @return A character object with an HTML fragment that can be placed inside of #' a cell. @@ -374,8 +409,12 @@ ggplot_image <- function( #' is an SVG file. This function is most useful when paired with [local_image()] #' since we test various sizes of the test image within that function. #' -#' @param type The type of the image, which can either be `png` (the default) or -#' `svg`. +#' @param type *The image type* +#' +#' `singl-kw:[png|svg]` --- *default:* `"png"` +#' +#' The type of image to produce here can either be `"png"` (the default) or +#' `"svg"`. #' #' @return A character vector with a single path to an image file. #' From fdfa93f8bcf3881c55109a845e2fe5ff64b50e0c Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:46 -0400 Subject: [PATCH 13/39] Update info_tables.R --- R/info_tables.R | 48 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/R/info_tables.R b/R/info_tables.R index 0449def2f9..cc75f62882 100644 --- a/R/info_tables.R +++ b/R/info_tables.R @@ -255,14 +255,23 @@ info_time_style <- function() { #' filter currencies in the info table to just the set beginning with the #' supplied letter. #' -#' @param type The type of currency information provided. Can either be `code` -#' where currency information corresponding to 3-letter currency codes is -#' provided, or `symbol` where currency info for common currency names (e.g., -#' dollar, pound, yen, etc.) is returned. -#' @param begins_with Providing a single letter will filter currencies to only -#' those that begin with that letter in their currency code. The default -#' (`NULL`) will produce a table with all currencies displayed. This option -#' only constrains the information table where `type == "code"`. +#' @param type *Type of currency* +#' +#' `singl-kw:[code|symbol]` --- *default:* `"code"` +#' +#' The type of currency information provided. Can either be `code` where +#' currency information corresponding to 3-letter currency codes is provided, +#' or `symbol` where currency info for common currency names (e.g., dollar, +#' pound, yen, etc.) is returned. +#' +#' @param begins_with *Show currencies beginning with a specific letter* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Providing a single letter will filter currencies to only those that begin +#' with that letter in their currency code. The default (`NULL`) will produce +#' a table with all currencies displayed. This option only constrains the +#' information table where `type == "code"`. #' #' @return An object of class `gt_tbl`. #' @@ -427,9 +436,13 @@ info_currencies <- function( #' locales in the info table to just the set that begins with the supplied #' letter. #' -#' @param begins_with Providing a single letter will filter locales to only -#' those that begin with that letter in their base locale ID. The default -#' (`NULL`) will produce a table with all locales displayed. +#' @param begins_with *Show locales beginning with a specific letter* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' Providing a single letter will filter locales to only those that begin +#' with that letter in their locale ID. The default (`NULL`) will produce +#' a table with all locales displayed #' #' @return An object of class `gt_tbl`. #' @@ -557,6 +570,7 @@ info_locales <- function(begins_with = NULL) { #' color palettes available in **paletteer**. #' #' @details +#' #' The palettes displayed are organized by package and by palette name. These #' values are required when obtaining a palette (as a vector of hexadecimal #' colors), from the the `paletteer::paletteer_d()` function. Once we are @@ -592,10 +606,14 @@ info_locales <- function(begins_with = NULL) { #' \item **yarrr**, 21 palettes #' } #' -#' @param color_pkgs A vector of color packages that determines which sets of -#' palettes should be displayed in the information table. If this is -#' `NULL` (the default) then all of the discrete palettes from all of the -#' color packages represented in **paletteer** will be displayed. +#' @param color_pkgs *Filter to specific color packages* +#' +#' `vector` --- *default:* `NULL` (`optional`) +#' +#' A vector of color packages that determines which sets of palettes should be +#' displayed in the information table. If this is `NULL` (the default) then +#' all of the discrete palettes from all of the color packages represented in +#' **paletteer** will be displayed. #' #' @return An object of class `gt_tbl`. #' From e90a9f15eb821dbf721ce8292cd2a0c6cb2a5ac3 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Wed, 31 May 2023 17:28:48 -0400 Subject: [PATCH 14/39] Update modify_columns.R --- R/modify_columns.R | 547 ++++++++++++++++++++++++++++++++------------- 1 file changed, 396 insertions(+), 151 deletions(-) diff --git a/R/modify_columns.R b/R/modify_columns.R index a8bb4e97db..226d0fec71 100644 --- a/R/modify_columns.R +++ b/R/modify_columns.R @@ -32,15 +32,32 @@ #' allow **gt** to automatically choose the alignment of each column based on #' the data type (with the `auto` option). #' -#' @param data A table object that is created using the [gt()] function. -#' @param align The alignment type. This can be any of `"center"`, `"left"`, or -#' `"right"` for center-, left-, or right-alignment. Alternatively, the -#' `"auto"` option (the default), will automatically align values in columns -#' according to the data type (see the Details section for specifics on which -#' alignments are applied). -#' @param columns The columns for which the alignment should be applied. By -#' default this is set to `everything()` which means that the chosen alignment -#' affects all columns. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param align *Alignment type* +#' +#' `singl-kw:[auto|left|center|right]` --- *default:* `"auto"` +#' +#' This can be any of `"center"`, `"left"`, or `"right"` for center-, left-, +#' or right-alignment. Alternatively, the `"auto"` option (the default), will +#' automatically align values in columns according to the data type (see the +#' Details section for specifics on which alignments are applied). +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns for which the alignment should be applied. Can either be a +#' series of column names provided in [c()], a vector of column indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. By default this is set to [everything()] +#' which means that the chosen alignment affects all columns. #' #' @return An object of class `gt_tbl`. #' @@ -183,21 +200,44 @@ determine_which_character_number <- function( #' number of columns (the function will skip over columns that don't require #' this type of alignment). #' -#' @param data A table object that is created using the [gt()] function. -#' @param columns The columns for which the alignment should be applied. By -#' default this is set to `everything()` which means that the chosen alignment -#' affects all columns. -#' @param dec_mark The character used as a decimal mark in the numeric values to -#' be aligned. If a locale value was used when formatting the numeric values -#' then `locale` is better to use and it will override any value here in -#' `dec_mark`. -#' @param locale An optional locale ID that can be used to obtain the type of -#' decimal mark used in the numeric values to be aligned. Examples include -#' `"en"` for English (United States) and `"fr"` for French (France). The use -#' of a valid locale ID will override any value provided in `dec_mark`. We can -#' use the [info_locales()] function as a useful reference for all of the -#' locales that are supported. Any `locale` value provided here will override -#' any global locale setting performed in [gt()]'s own `locale` argument. +#' @param data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param columns *Columns to target* +#' +#' `` --- *default:* `everything()` +#' +#' The columns for which decimal alignment should be applied. Can either be a +#' series of column names provided in [c()], a vector of column indices, or a +#' select helper function. Examples of select helper functions include +#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], +#' [num_range()], and [everything()]. By default this is set to [everything()] +#' which means that decimal alignment will be attempted on all columns. +#' +#' @param dec_mark *Decimal mark* +#' +#' `scalar` --- *default:* `"."` +#' +#' The character used as a decimal mark in the numeric values to be aligned. +#' If a locale value was used when formatting the numeric values then `locale` +#' is better to use and it will override any value here in `dec_mark`. +#' +#' @param locale *Locale identifier* +#' +#' `scalar` --- *default:* `NULL` (`optional`) +#' +#' An optional locale identifier that can be used to obtain the type of +#' decimal mark used in the numeric values to be aligned (according to the +#' locale's formatting rules). Examples include `"en"` for English (United +#' States) and `"fr"` for French (France). We can use the [info_locales()] +#' function as a useful reference for all of the locales that are supported. A +#' locale ID can be also set in the initial [gt()] function call (where it +#' would be used automatically by any function with a `locale` argument) but a +#' `locale` value provided here will override that global locale. #' #' @return An object of class `gt_tbl`. #' @@ -401,21 +441,35 @@ align_to_char <- function(x, align_at = ".") { #' left-hand side defines the target columns and the right-hand side is a single #' dimension. #' -#' @param .data A table object that is created using the [gt()] function. -#' @param ... Expressions for the assignment of column widths for the table -#' columns in `.data`. Two-sided formulas (e.g, ` ~ `) can be used, -#' where the left-hand side corresponds to selections of columns and the -#' right-hand side evaluates to single-length character values in the form -#' `{##}px` (i.e., pixel dimensions); the [px()] helper function is best used -#' for this purpose. Column names should be enclosed in [c()]. The -#' column-based select helpers [starts_with()], [ends_with()], [contains()], -#' [matches()], [one_of()], and [everything()] can be used in the LHS. -#' Subsequent expressions that operate on the columns assigned previously will -#' result in overwriting column width values (both in the same `cols_width()` -#' call and across separate calls). All other columns can be assigned a -#' default width value by using `everything()` on the left-hand -#' side. -#' @param .list Allows for the use of a list as an input alternative to `...`. +#' @param .data *The gt table data object* +#' +#' `obj:` --- **required** +#' +#' This is the **gt** table object that is commonly created through use of the +#' [gt()] function. +#' +#' @param ... *Column width assignments* +#' +#' `` --- **required** (or, use `.list`) +#' +#' Expressions for the assignment of column widths for the table columns in +#' `.data`. Two-sided formulas (e.g, ` ~ `) can be used, where the +#' left-hand side corresponds to selections of columns and the right-hand side +#' evaluates to single-length character values in the form `{##}px` (i.e., +#' pixel dimensions); the [px()] helper function is best used for this +#' purpose. Column names should be enclosed in [c()]. The column-based select +#' helpers [starts_with()], [ends_with()], [contains()], [matches()], +#' [one_of()], and [everything()] can be used in the LHS. Subsequent +#' expressions that operate on the columns assigned previously will result in +#' overwriting column width values (both in the same `cols_width()` call and +#' across separate calls). All other columns can be assigned a default width +#' value by using `everything()` on the left-hand side. +#' +#' @param .list *Alternative to `...`* +#' +#' `` --- **required** (or, use `...`) +#' +#' Allows for the use of a list as an input alternative to `...`. #' #' @return An object of class `gt_tbl`. #' @@ -570,21 +624,40 @@ cols_width <- function( #' one or more columns and we even have the option to use the [md()] or [html()] #' helper functions for rendering column labels from Markdown or using HTML. #' -#' @param .data A table object that is created using the [gt()] function. -#' @param ... Expressions for the assignment of column labels for the table -#' columns in `.data`. Two-sided formulas (e.g., ` ~ `) can be used, -#' where the left-hand side corresponds to selections of columns and the -#' right-hand side evaluates to single-length values for the label to apply. -#' Column names should be enclosed in [c()]. Select helpers like -#' [starts_with()], [ends_with()], [contains()], [matches()], [one_of()], and -#' [everything()] can be used in the LHS. Named arguments are also valid as -#' input for simple mappings of column name to label text; they should be of -#' the form ` =