diff --git a/R/data_color.R b/R/data_color.R index 4685d469de..0ec753ed5d 100644 --- a/R/data_color.R +++ b/R/data_color.R @@ -26,8 +26,8 @@ #' #' @description #' -#' It's possible to add color to data cells according to their values with the -#' `data_color()` function. There is a multitude of ways to perform data cell +#' It's possible to add color to data cells according to their values with +#' `data_color()` There is a multitude of ways to perform data cell #' colorizing here: #' #' - targeting: we can constrain which columns and rows should receive the @@ -41,9 +41,8 @@ #' argument controls this through keywords and other arguments act as inputs to #' specific methods #' - coloring function: a custom function can be supplied to the `fn` argument -#' for finer control over color evaluation with data; the color mapping -#' `col_*()` functions in the **scales** package can be used here or any -#' function you might want to define +#' for finer control over color evaluation with data; the `scales::col_*()` +#' color mapping functions can be used here or any function you might want to define #' - color palettes: with `palette` we could supply a vector of colors, a #' **virdis** or **RColorBrewer** palette name, or, a palette from the #' **paletteer** package @@ -60,7 +59,7 @@ #' automatically recolor the foreground text to provide the best contrast (can #' be deactivated with `autocolor_text = FALSE`) #' -#' The `data_color()` function won't fail with the default options used, but +#' `data_color()` won't fail with the default options used, but #' that won't typically provide you the type of colorization you really need. #' You can however safely iterate through a collection of different options #' without running into too many errors. @@ -207,10 +206,9 @@ #' #' 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. +#' `scales::col_*()` functions (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 *How to apply color* #' @@ -284,7 +282,7 @@ #' #' @section Color computation methods: #' -#' The `data_color()` function offers four distinct methods for computing color +#' `data_color()` offers four distinct methods for computing color #' based on cell data values. They are set by the `method` argument and the #' options go by the keywords `"numeric"`, `"bin"`, `"quantile"`, and #' `"factor"`. There are other arguments in `data_color()` that variously @@ -295,36 +293,36 @@ #' ### `"numeric"` #' #' The `"numeric"` method provides a simple linear mapping from continuous -#' numeric data to an interpolated `palette`. Internally, this uses the -#' [scales::col_numeric()] function. This method is suited for numeric data cell +#' numeric data to an interpolated `palette`. Internally, this uses +#' [scales::col_numeric()]. This method is suited for numeric data cell #' values and can make use of a supplied `domain` value, in the form of a #' two-element numeric vector describing the range of values, if provided. #' #' ### `"bin"` #' #' The `"bin"` method provides a mapping of continuous numeric data to -#' value-based bins. Internally, this uses the [scales::col_bin()] function -#' which itself uses [base::cut()]. As with the `"numeric"` method, `"bin"` is -#' meant for numeric data cell values. The use of a `domain` value is supported -#' with this method. The `bins` argument in `data_color()` is specific to this -#' method, offering the ability to: (1) specify the number of bins, or (2) -#' provide a vector of cut points. +#' value-based bins. Internally, this uses [scales::col_bin()] which itself +#' uses [base::cut()]. As with the `"numeric"` method, `"bin"` is meant for +#' numeric data cell values. The use of a `domain` value is supported with this +#' method. The `bins` argument in `data_color()` is specific to this method, +#' offering the ability to: (1) specify the number of bins, or (2) provide a +#' vector of cut points. #' #' ### `"quantile"` #' #' The `"quantile"` method provides a mapping of continuous numeric data to -#' quantiles. Internally, this uses the [scales::col_quantile()] function which -#' itself uses [stats::quantile()]. Input data cell values should be numeric, as -#' with the `"numeric"` and `"bin"` methods. A numeric `domain` value is -#' supported with this method. The `quantiles` argument in `data_color()` -#' controls the number of equal-size quantiles to use. +#' quantiles. Internally, this uses [scales::col_quantile()] which itself uses +#' [stats::quantile()]. Input data cell values should be numeric, as with the +#' `"numeric"` and `"bin"` methods. A numeric `domain` value is supported with +#' this method. The `quantiles` argument in `data_color()` controls the number +#' of equal-size quantiles to use. #' #' ### `"factor"` #' #' The `"factor"` method provides a mapping of factors to colors. With discrete #' palettes, color interpolation is used when the number of factors does not -#' match the number of colors in the palette. Internally, this uses the -#' [scales::col_factor()] function. Input data cell values can be of any type +#' match the number of colors in the palette. Internally, this uses +#' [scales::col_factor()]. Input data cell values can be of any type #' (i.e., factor, character, numeric values, and more are supported). The #' optional input to `domain` should take the form of categorical data. The #' `levels` and `ordered` arguments in `data_color()` support this method. @@ -406,7 +404,7 @@ #' #' @section Examples: #' -#' The `data_color()` function can be used without any supplied arguments to +#' `data_color()` can be used without any supplied arguments to #' colorize a **gt** table. Let's do this with the [`exibble`] dataset: #' #' ```r @@ -522,11 +520,11 @@ #' }} #' #' Using your own function in `fn` can be very useful if you want to make use of -#' specialized arguments in the **scales** `col_*()` functions. You could even +#' specialized arguments in the `scales::col_*()` functions. You could even #' supply your own specialized function for performing complex colorizing #' treatments! #' -#' The `data_color()` function has a way to apply colorization indirectly to +#' `data_color()` has a way to apply colorization indirectly to #' other columns. That is, you can apply colors to a column different from the #' one used to generate those specific colors. The trick is to use the #' `target_columns` argument. Let's do this with a more complete @@ -602,7 +600,7 @@ #' #' Now, it's time to use [`pizzaplace`] to create a **gt** table. The color #' palette to be used is the `"ggsci::red_material"` one (it's in the **ggsci** -#' R package but also obtainable from the the **paletteer** package). +#' R package but also obtainable from the **paletteer** package). #' Colorization will be applied to the to the `sold` and `income` columns. We #' don't have to specify those in `columns` because those are the only columns #' in the table. Also, the `domain` is not set here. We'll use the bounds of the @@ -727,15 +725,11 @@ data_color <- function( na_color <- na_color %||% "#808080" # Error early if `palette = NA`, or is a numeric vector. - if (length(palette) > 0 && (is.numeric(palette) || anyNA(palette))) { + if (length(palette) > 0L && (is.numeric(palette) || anyNA(palette))) { cli::cli_abort(c( - "`palette` must {.help [a valid palette](gt::data_color)}, not a numeric vector." + "`palette` must be a {.help [valid palette](gt::data_color)}, not a numeric vector." )) } - # "#FA9DFE" - # if (is.character(palette) && length(palette) > 1) { - # check_named_colors(palette[!grepl("#", palette, fixed = TRUE)]) - # } # Defuse any function supplied to `fn`; if a function is supplied to `colors` # (previous argument for this purpose) then let that take precedent and @@ -948,7 +942,7 @@ data_color <- function( # For the "auto" method, we are getting data values in a piece-wise # fashion and the strategy is to generate a color function (using - # a `col_*()` function from scales) for each piece of data; we can + # a `scales::col_*()` function) for each piece of data; we can # process vectors that are numeric with `scales::col_numeric()` and # vectors that are either character or factor with `scales::col_factor()` @@ -1240,10 +1234,10 @@ screen_palette_for_col_factor <- function(palette, data_vals) { #' Are color values in rgba() format? #' #' The input for this is a character vector that should contain color strings. -#' While users won't directly supply colors in rgba() format, the `html_color()` -#' function can produce these types of color values and this utility function is +#' While users won't directly supply colors in rgba() format, `html_color()` +#' can produce these types of color values and this utility function is #' used in `rgba_to_hex()` to help convert colors *back* to hexadecimal -#' (ultimately for the `ideal_fgnd_color()` function). The output of +#' (ultimately for `ideal_fgnd_color()`). The output of #' `is_rgba_col()` is a vector of logical values (the same length as the input #' `colors` vector). #' @@ -1426,7 +1420,7 @@ html_color <- function(colors, alpha = NULL, call = rlang::caller_env()) { if (any(is_css_excl_named)) { - # The `css_exclusive_colors()` function returns a named vector + # `css_exclusive_colors()` returns a named vector # of the CSS colors not in the X11/R set; the names are the hexadecimal # color values colors[is_css_excl_named] <- diff --git a/R/dt_heading.R b/R/dt_heading.R index 455cadc7f4..1f7395a143 100644 --- a/R/dt_heading.R +++ b/R/dt_heading.R @@ -74,7 +74,7 @@ dt_heading_has_subtitle <- function(data) { heading <- dt_heading_get(data = data) - length(heading) > 0 && is_nonempty_string(heading$subtitle) + length(heading) > 0 && is_nonempty_chr(heading$subtitle) } dt_heading_has_preheader <- function(data) { diff --git a/R/dt_stub_df.R b/R/dt_stub_df.R index a416bb7f3b..b13f1e662a 100644 --- a/R/dt_stub_df.R +++ b/R/dt_stub_df.R @@ -97,7 +97,7 @@ dt_stub_df_init <- function( # # Ensure that the `row_group_ids` values are simplified to reduce # special characters; this requires use of the recoding so that the - # generated IDs map correctly to the the supplied labels + # generated IDs map correctly to the supplied labels # unique_row_group_labels <- unique(row_group_labels) diff --git a/R/export.R b/R/export.R index d316dc3311..32e2d2288b 100644 --- a/R/export.R +++ b/R/export.R @@ -26,7 +26,7 @@ #' #' @description #' -#' The `gtsave()` function makes it easy to save a **gt** table to a file. The +#' `gtsave()` makes it easy to save a **gt** table to a file. The #' function guesses the file type by the extension provided in the output #' filename, producing either an HTML, PDF, PNG, LaTeX, or RTF file. #' @@ -543,13 +543,13 @@ gtsave_filename <- function(path, filename) { #' #' Use a subset of the [`gtcars`] dataset to create a **gt** table. Add a header #' with [tab_header()] and then export the table as HTML code with inlined CSS -#' styles using the `as_raw_html()` function. +#' styles using `as_raw_html()`. #' #' ```r #' tab_html <- #' gtcars |> #' dplyr::select(mfr, model, msrp) |> -#' dplyr::slice(1:5) |> +#' dplyr::slice_head(n = 5) |> #' gt() |> #' tab_header( #' title = md("Data listing from **gtcars**"), @@ -923,8 +923,8 @@ as_rtf <- function( #' @section Examples: #' #' Use a subset of the [`gtcars`] dataset to create a **gt** table. Add a header -#' with [tab_header()] and then export the table as OOXML code for Word using the -#' `as_word()` function. +#' with [tab_header()] and then export the table as OOXML code for Word using +#' `as_word()` #' #' ```r #' tab_rtf <- @@ -1146,8 +1146,8 @@ as_word_tbl_body <- function( #' #' @description #' -#' The `as_gtable()` function performs the transformation of a `gt_tbl` object -#' to a `gtable` object. +#' `as_gtable()` performs the transformation of a `gt_tbl` object to a +#' [`gtable`][gtable::gtable()] object. #' #' @inheritParams gtsave #' @@ -1501,10 +1501,10 @@ grid_layout_widths <- function(layout, data) { #' @description #' #' We can extract the body of a **gt** table, even at various stages of its -#' rendering, from a `gt_tbl` object using the `extract_body()` function. By -#' default, the data frame returned will have gone through all of the build -#' stages but we can intercept the table body after a certain build stage. -#' Here are the eight different build stages and some notes about each: +#' rendering, from a `gt_tbl` object using `extract_body()`. By default, the +#' data frame returned will have gone through all of the build stages but we +#' can intercept the table body after a certain build stage. Here are the eight +#' different build stages and some notes about each: #' #' 1. `"init"`: the body table is initialized here, entirely with `NA` values. #' It's important to note that all columns of the are of the `character` type in @@ -1525,7 +1525,7 @@ grid_layout_widths <- function(layout, data) { #' values now become the string `"NA"`, so, there aren't any true missing values #' in this body table. #' -#' 5. `"cols_merged"`: The result of column-merging operations (though +#' 5. `"cols_merged"`: The result of column-merging operations (through #' [cols_merge()] and related functions) is materialized here. Columns that were #' asked to be hidden will be present here (i.e., hiding columns doesn't remove #' them from the body table). @@ -1658,9 +1658,9 @@ extract_body <- function( #' @description #' #' Get a list of summary row data frames from a `gt_tbl` object where summary -#' rows were added via the [summary_rows()] function. The output data frames -#' contain the `group_id` and `rowname` columns, whereby `rowname` contains -#' descriptive stub labels for the summary rows. +#' rows were added via [summary_rows()]. The output data frames contain the +#' `group_id` and `rowname` columns, whereby `rowname` contains descriptive stub +#' labels for the summary rows. #' #' @inheritParams extract_cells #' diff --git a/R/format_data.R b/R/format_data.R index aa0f7f27f2..343f79e89c 100644 --- a/R/format_data.R +++ b/R/format_data.R @@ -217,20 +217,20 @@ #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for 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`. #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_number()` formatting function is compatible with body cells that are -#' of the `"numeric"` or `"integer"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_number()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -273,10 +273,10 @@ #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_number()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_number()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `decimals` #' - `n_sigfig` @@ -296,11 +296,10 @@ #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -314,13 +313,13 @@ #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' -#' Let's use the [`exibble`] dataset to create a **gt** table. With the -#' `fmt_number()` function, we'll format the `num` column to have three decimal +#' Let's use the [`exibble`] dataset to create a **gt** table. With +#' `fmt_number()`, we'll format the `num` column to have three decimal #' places (with `decimals = 3`) and omit the use of digit separators (with #' `use_seps = FALSE`). #' @@ -405,9 +404,8 @@ #' column of values that specify how many decimal digits to retain. Such a #' column can be added via [cols_add()] or it can be part of the input table for #' [gt()]. With that column available, it can be referenced in the `decimals` -#' argument with the [from_column()] helper function. This approach yields a -#' display of coordinate values that reflects the measurement precision of each -#' value. +#' argument with [from_column()]. This approach yields a display of coordinate +#' values that reflects the measurement precision of each value. #' #' ```r #' towny |> @@ -435,11 +433,11 @@ #' @section Function Introduced: #' `v0.2.0.5` (March 31, 2020) #' -#' @seealso The [fmt_integer()] function might be more useful if you really need -#' to format numeric values to appear as integers (i.e., no decimals will be -#' shown and input values are rounded as necessary). Need to do numeric -#' formatting on a vector? Take a look at the vector-formatting version of -#' this function: [vec_fmt_number()]. +#' @seealso +#' The integer-formatting function (format rounded values (i.e., no decimals shown and +#'input values are rounded as necessary): [fmt_integer()]. +#' +#' The vector-formatting version of this function: [vec_fmt_number()] #' #' @import rlang #' @export @@ -497,7 +495,7 @@ fmt_number <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -711,10 +709,10 @@ fmt_number <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_integer()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_integer()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -757,10 +755,10 @@ fmt_number <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_integer()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_integer()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `use_seps` #' - `accounting` @@ -775,11 +773,10 @@ fmt_number <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -792,14 +789,14 @@ fmt_number <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' #' For this example, we'll use two columns from the [`exibble`] dataset and -#' create a simple **gt** table. With the `fmt_integer()` function, we'll format -#' the `num` column as integer values having no digit separators (with the +#' create a simple **gt** table. With `fmt_integer()`, we'll format the `num` +#' column as integer values having no digit separators (with the #' `use_seps = FALSE` option). #' #' ```r @@ -869,10 +866,10 @@ fmt_number <- function( #' @section Function Introduced: #' `v0.3.1` (August 9, 2021) #' -#' @seealso The [fmt_number()] function might be more of what you need if you'd -#' like decimal values in your outputs. Need to do integer-based formatting on -#' a vector? Take a look at the vector-formatting version of this function: -#' [vec_fmt_integer()]. +#' @seealso +#' Format number with decimal values: [fmt_number()] +#' +#' The vector-formatting version of this function: [vec_fmt_integer()] #' #' @import rlang #' @export @@ -920,7 +917,7 @@ fmt_integer <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -1043,10 +1040,10 @@ fmt_integer <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_scientific()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_scientific()` is compatible with body cells that are of the `"numeric"` +#' or `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -1089,10 +1086,10 @@ fmt_integer <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_scientific()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_scientific()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `decimals` #' - `drop_trailing_zeros` @@ -1109,11 +1106,10 @@ fmt_integer <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -1127,8 +1123,8 @@ fmt_integer <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' @@ -1253,7 +1249,7 @@ fmt_scientific <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -1582,11 +1578,10 @@ fmt_scientific <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_engineering()` formatting function is compatible with body cells -#' that are of the `"numeric"` or `"integer"` types. Any other types of body -#' cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_engineering()` is compatible with body cells that are of the +#' `"numeric"` or `"integer"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -1629,10 +1624,10 @@ fmt_scientific <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_engineering()` to obtain varying parameter values from a specified -#' column within the table. This means that each row could be formatted a little -#' bit differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_engineering()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `decimals` #' - `drop_trailing_zeros` @@ -1649,11 +1644,10 @@ fmt_scientific <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -1667,14 +1661,13 @@ fmt_scientific <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' #' Use the [`exibble`] dataset to create a **gt** table. Format the `num` column -#' to display values in engineering notation using the `fmt_engineering()` -#' function. +#' to display values in engineering notation using `fmt_engineering()`. #' #' ```r #' exibble |> @@ -1746,7 +1739,7 @@ fmt_engineering <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -2153,8 +2146,8 @@ fmt_symbol <- function( #' With numeric values in a **gt** table, we can perform percentage-based #' formatting. It is assumed the input numeric values are proportional values #' and, in this case, the values will be automatically multiplied by `100` -#' before decorating with a percent sign (the other case is accommodated though -#' setting the `scale_values` to `FALSE`). For more control over percentage +#' before decorating with a percent sign (the other case is accommodated through +#' setting `scale_values = FALSE`). For more control over percentage #' formatting, we can use the following options: #' #' - percent sign placement: the percent sign can be placed after or @@ -2201,10 +2194,10 @@ fmt_symbol <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_percent()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_percent()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -2247,10 +2240,10 @@ fmt_symbol <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_percent()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_percent()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `decimals` #' - `drop_trailing_zeros` @@ -2270,11 +2263,10 @@ fmt_symbol <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -2288,14 +2280,14 @@ fmt_symbol <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call[info_locales()] +#' to view an info table. #' #' @section Examples: #' #' Use a summarized version of the [`pizzaplace`] dataset to create a **gt** -#' table. With the `fmt_percent()` function, we can format the `frac_of_quota` -#' column to display values as percentages (to one decimal place). +#' table. With `fmt_percent()`, we can format the `frac_of_quota` column to +#' display values as percentages (to one decimal place). #' #' ```r #' pizzaplace |> @@ -2380,7 +2372,7 @@ fmt_percent <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -2563,10 +2555,10 @@ fmt_percent <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_partsper()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_partsper()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -2609,10 +2601,10 @@ fmt_percent <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_partsper()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_partsper()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `to_units` #' - `symbol` @@ -2632,11 +2624,10 @@ fmt_percent <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -2650,8 +2641,8 @@ fmt_percent <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' @@ -2739,7 +2730,7 @@ fmt_partsper <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -2949,10 +2940,10 @@ fmt_partsper <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_fraction()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_fraction()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -2995,10 +2986,10 @@ fmt_partsper <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_fraction()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_fraction()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit ifferently. These +#' arguments provide support for [from_column()]: #' #' - `accuracy` #' - `simplify` @@ -3012,11 +3003,10 @@ fmt_partsper <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -3030,18 +3020,18 @@ fmt_partsper <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' #' Using a summarized version of the [`pizzaplace`] dataset, let's create a -#' **gt** table. With the `fmt_fraction()` function we can format the `f_sold` -#' and `f_income` columns to display fractions. As for how the fractions are -#' represented, we are electing to use `accuracy = 10`. This gives all fractions -#' as tenths. We won't simplify the fractions (by using `simplify = FALSE`) and -#' this means that a fraction like `5/10` won't become `1/2`. With `layout = -#' "diagonal"`, we get a diagonal display of all fractions. +#' **gt** table. With `fmt_fraction()` we can format the `f_sold` and `f_income` +#' columns to display fractions. As for how the fractions are represented, we +#' are electing to use `accuracy = 10`. This gives all fractions as tenths. +#' We won't simplify the fractions (by using `simplify = FALSE`) and this means +#' that a fraction like `5/10` won't become `1/2`. With `layout ="diagonal"`, +#' we get a diagonal display of all fractions. #' #' ```r #' pizzaplace |> @@ -3159,7 +3149,7 @@ fmt_fraction <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -3534,7 +3524,7 @@ round_gt <- function(x, digits = 0) { #' @description #' #' With numeric values in a **gt** table, we can perform currency-based -#' formatting with the `fmt_currency()` function. The function supports both +#' formatting with `fmt_currency()`. The function supports both #' automatic formatting with either a three-letter or a numeric currency code. #' We can also specify a custom currency that is formatted according to one or #' more output contexts with the [currency()] helper function. We have fine @@ -3562,8 +3552,8 @@ round_gt <- function(x, digits = 0) { #' formatting specific to the chosen locale; it will also retrieve the locale's #' currency if none is explicitly given #' -#' We can use the [info_currencies()] function for a useful reference on all of -#' the possible inputs to the `currency` argument. +#' We can call [info_currencies()] for a useful reference on all of the valid +#' inputs to the `currency` argument. #' #' @inheritParams fmt_number #' @@ -3644,10 +3634,10 @@ round_gt <- function(x, digits = 0) { #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_currency()` formatting function is compatible with body cells that -#' are of the `"numeric"` or `"integer"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_currency()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -3690,10 +3680,10 @@ round_gt <- function(x, digits = 0) { #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_currency()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_currency()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `currency` #' - `use_subunits` @@ -3715,11 +3705,10 @@ round_gt <- function(x, digits = 0) { #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -3735,8 +3724,8 @@ round_gt <- function(x, digits = 0) { #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' @@ -3787,9 +3776,9 @@ round_gt <- function(x, digits = 0) { #' number of `"hawaiian"` pizzas sold (and revenue generated) by month. In the #' **gt** table, we'll format only the `revenue` column. The `currency` value is #' automatically U.S. Dollars when don't supply either a currency code or a -#' locale. We'll also create a grand summary with the [grand_summary_rows()] -#' function. Within that summary row, the total revenue needs to be formatted -#' with `fmt_currency()` and we can do that within the `fmt` argument. +#' locale. We'll also create a grand summary with [grand_summary_rows()]. Within +#' that summary row, the total revenue needs to be formatted with +#' `fmt_currency()` and we can do that within the `fmt` argument. #' #' ```r #' pizzaplace |> @@ -3819,8 +3808,8 @@ round_gt <- function(x, digits = 0) { #' locale's assumed currency and not have to supply a `currency` value (doing so #' would override the locale's default currency). With a column of locale #' values, we can format currency values on a row-by-row basis through the use -#' of the [from_column()] helper function. Here, we'll reference the `locale` -#' column in the argument of the same name. +#' of [from_column()]. Here, we'll reference the `locale` column in the argument +#' of the same name. #' #' ```r #' dplyr::tibble( @@ -3946,7 +3935,7 @@ fmt_currency <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -4086,10 +4075,10 @@ fmt_currency <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_roman()` formatting function is compatible with body cells that are -#' of the `"numeric"` or `"integer"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_roman()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -4132,10 +4121,10 @@ fmt_currency <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_roman()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_roman()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `case` #' - `pattern` @@ -4143,11 +4132,10 @@ fmt_currency <- function( #' Please note that for both of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' @@ -4231,7 +4219,7 @@ fmt_roman <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -4369,10 +4357,10 @@ fmt_roman <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_index()` formatting function is compatible with body cells that are -#' of the `"numeric"` or `"integer"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_index()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -4415,10 +4403,10 @@ fmt_roman <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_index()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_index()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `case` #' - `index_algo` @@ -4428,16 +4416,15 @@ fmt_roman <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' #' Using a summarized version of the [`towny`] dataset, let's create a **gt** -#' table. Here, the `fmt_index()` function is used to transform incremental +#' table. Here, `fmt_index()` is used to transform incremental #' integer values into capitalized letters (in the `ranking` column). With #' [cols_merge()] that formatted column of `"A"` to `"E"` values is merged with #' the `census_div` column to create an indexed listing of census subdivisions, @@ -4451,10 +4438,8 @@ fmt_roman <- function( #' population = sum(population_2021), #' .groups = "drop_last" #' ) |> -#' dplyr::arrange(population) |> -#' dplyr::slice_head(n = 5) |> -#' dplyr::mutate(ranking = dplyr::row_number()) |> -#' dplyr::select(ranking, dplyr::everything()) |> +#' dplyr::slice_min(population, n = 5) |> +#' dplyr::mutate(ranking = dplyr::row_number(), .before = 0) |> #' gt() |> #' fmt_integer() |> #' fmt_index(columns = ranking, pattern = "{x}.") |> @@ -4517,7 +4502,7 @@ fmt_index <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -4695,13 +4680,12 @@ get_letters_from_div <- function(x, set) { #' @description #' #' With numeric values in a **gt** table we can transform those to numbers that -#' are spelled out with the `fmt_spelled_num()` function. Any values from `0` to -#' `100` can be spelled out so, for example, the value `23` will be formatted as -#' `"twenty-three"`. Providing a locale ID will result in the number spelled out -#' in the locale's language rules. For example, should a Swedish locale (`"sv"`) -#' be provided, the input value `23` will yield `"tjugotre"`. In addition to -#' this, we can optionally use the `pattern` argument for decoration of the -#' formatted values. +#' are spelled out with `fmt_spelled_num()`. Any values from `0` to `100` can be +#' spelled out so, for example, the value `23` will be formatted as `"twenty-three"`. +#' Providing a locale ID will result in the number spelled out in the locale's +#' language rules. For example, should a Swedish locale (`"sv"`) be provided, +#' the value `23` will yield `"tjugotre"`. In addition to this, we can +#' optionally use the `pattern` argument for decoration of the formatted values. #' #' @inheritParams fmt_number #' @@ -4709,11 +4693,10 @@ get_letters_from_div <- function(x, set) { #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_spelled_num()` formatting function is compatible with body cells -#' that are of the `"numeric"` or `"integer"` types. Any other types of body -#' cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_spelled_num()` is compatible with body cells that are of the `"numeric"` +#' or `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -4756,10 +4739,10 @@ get_letters_from_div <- function(x, set) { #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_spelled_num()` to obtain varying parameter values from a specified -#' column within the table. This means that each row could be formatted a little -#' bit differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_spelled_num()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `pattern` #' - `locale` @@ -4767,11 +4750,10 @@ get_letters_from_div <- function(x, set) { #' Please note that for both of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Supported locales: #' @@ -4802,17 +4784,14 @@ get_letters_from_div <- function(x, set) { #' @section Examples: #' #' Let's use a summarized version of the [`gtcars`] dataset to create a -#' **gt** table. The `fmt_spelled_num()` function is used to transform +#' **gt** table. `fmt_spelled_num()` is used to transform #' integer values into spelled-out numbering (in the `n` column). That formatted #' column of numbers-as-words is given cell background colors via [data_color()] #' (the underlying numerical values are always available). #' #' ```r #' gtcars |> -#' dplyr::select(mfr, ctry_origin) |> -#' dplyr::group_by(mfr, ctry_origin) |> -#' dplyr::count() |> -#' dplyr::ungroup() |> +#' dplyr::count(mfr, ctry_origin) |> #' dplyr::arrange(ctry_origin) |> #' gt(rowname_col = "mfr", groupname_col = "ctry_origin") |> #' cols_label(n = "No. of Entries") |> @@ -4834,10 +4813,10 @@ get_letters_from_div <- function(x, set) { #' }} #' #' With a considerable amount of **dplyr** and **tidyr** work done to the -#' [`pizzaplace`] dataset, we can create a new **gt** table. The -#' `fmt_spelled_num()` function will be used here to transform the integer -#' values in the `rank` column. We'll do so with a special `pattern` that puts -#' the word 'Number' in front of every spelled-out number. +#' [`pizzaplace`] dataset, we can create a new **gt** table. `fmt_spelled_num()` +#' will be used here to transform the integer values in the `rank` column. +#' We'll do so with a special `pattern` that puts the word 'Number' in front of +#' every spelled-out number. #' #' ```r #' pizzaplace |> @@ -4954,7 +4933,7 @@ fmt_spelled_num <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -5072,7 +5051,7 @@ fmt_spelled_num <- function( #' @description #' #' With numeric values in a **gt** table, we can transform those to values of -#' bytes with human readable units. The `fmt_bytes()` function allows for the +#' bytes with human readable units. `fmt_bytes()` allows for the #' formatting of byte sizes to either of two common representations: (1) with #' decimal units (powers of 1000, examples being `"kB"` and `"MB"`), and (2) #' with binary units (powers of 1024, examples being `"KiB"` and `"MiB"`). @@ -5131,10 +5110,10 @@ fmt_spelled_num <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_bytes()` formatting function is compatible with body cells that are -#' of the `"numeric"` or `"integer"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_bytes()` is compatible with body cells that are of the `"numeric"` or +#' `"integer"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -5177,10 +5156,10 @@ fmt_spelled_num <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_bytes()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_bytes()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `standard` #' - `decimals` @@ -5198,11 +5177,10 @@ fmt_spelled_num <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Adapting output to a specific `locale`: #' @@ -5216,14 +5194,14 @@ fmt_spelled_num <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' #' Use a single column from the [`exibble`] dataset and create a simple **gt** -#' table. We'll format the `num` column to display as byte sizes in the decimal -#' standard through use of the `fmt_bytes()` function. +#' table. We'll use `fmt_bytes()` to format the `num` column to display as byte +#' sizes in the decimal standard. #' #' ```r #' exibble |> @@ -5236,7 +5214,7 @@ fmt_spelled_num <- function( #' `r man_get_image_tag(file = "man_fmt_bytes_1.png")` #' }} #' -#' Let's create an analogous table again by using the `fmt_bytes()` function, +#' Let's create an analogous table again by using `fmt_bytes()`, #' this time showing byte sizes as binary values by using `standard = "binary"`. #' #' ```r @@ -5311,7 +5289,7 @@ fmt_bytes <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -5487,11 +5465,10 @@ fmt_bytes <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_date()` formatting function is compatible with body cells that are -#' of the `"Date"`, `"POSIXt"` or `"character"` types. Any other types of body -#' cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_date()` is compatible with body cells that are of the `"Date"`, +#' `"POSIXt"` or `"character"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -5534,10 +5511,10 @@ fmt_bytes <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_date()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_date()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `date_style` #' - `pattern` @@ -5546,11 +5523,10 @@ fmt_bytes <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Formatting with the `date_style` argument: #' @@ -5608,8 +5584,8 @@ fmt_bytes <- function( #' | 40 | `"d"` | `"29"` | flexible | #' | 41 | `"Ed"` | `"29 Tue"` | flexible | #' -#' We can use the [info_date_style()] function within the console to view a -#' similar table of date styles with example output. +#' We can call [info_date_style()] in the console to view a similar table +#' of date styles with example output. #' #' @section Adapting output to a specific `locale`: #' @@ -5619,14 +5595,14 @@ fmt_bytes <- function( #' global locale setting performed in [gt()]'s own `locale` argument (it is #' settable there as a value received by all other functions that have a #' `locale` argument). As a useful reference on which locales are supported, we -#' can use the [info_locales()] function to view an info table. +#' can call [info_locales()] to view an info table. #' #' @section Examples: #' #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table -#' (keeping only the `date` and `time` columns). With the `fmt_date()` function, -#' we'll format the `date` column to display dates formatted with the -#' `"month_day_year"` date style. +#' (keeping only the `date` and `time` columns). With `fmt_date()`, we'll format +#' the `date` column to display dates formatted with the `"month_day_year"` +#' date style. #' #' ```r #' exibble |> @@ -5732,7 +5708,7 @@ fmt_date <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -5865,11 +5841,10 @@ fmt_date <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_time()` formatting function is compatible with body cells that are -#' of the `"Date"`, `"POSIXt"` or `"character"` types. Any other types of body -#' cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_time()` is compatible with body cells that are of the `"Date"`, +#' `"POSIXt"` or `"character"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -5912,10 +5887,10 @@ fmt_date <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_time()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_time()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `time_style` #' - `pattern` @@ -5924,11 +5899,10 @@ fmt_date <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Formatting with the `time_style` argument: #' @@ -5971,8 +5945,8 @@ fmt_date <- function( #' | 24 | `"hmv"` | `"2:35 PM GMT+00:00"` | flexible, 12h | #' | 25 | `"ms"` | `"35:00"` | flexible | #' -#' We can use the [info_time_style()] function within the console to view a -#' similar table of time styles with example output. +#' We can call [info_time_style()] in the console to view a similar table of +#' time styles with example output. #' #' @section Adapting output to a specific `locale`: #' @@ -5982,14 +5956,13 @@ fmt_date <- function( #' global locale setting performed in [gt()]'s own `locale` argument (it is #' settable there as a value received by all other functions that have a #' `locale` argument). As a useful reference on which locales are supported, we -#' can use the [info_locales()] function to view an info table. +#' can use [info_locales()] to view an info table. #' #' @section Examples: #' #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table #' (keeping only the `date` and `time` columns). Format the `time` column with -#' the `fmt_time()` function to display times formatted with the `"h_m_s_p"` -#' time style. +#' `fmt_time()` to display times formatted with the `"h_m_s_p"` time style. #' #' ```r #' exibble |> @@ -6095,7 +6068,7 @@ fmt_time <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -6258,11 +6231,10 @@ fmt_time <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_datetime()` formatting function is compatible with body cells that -#' are of the `"Date"`, `"POSIXct"` or `"character"` types. Any other types of -#' body cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_datetime()` is compatible with body cells that are of the `"Date"`, +#' `"POSIXct"` or `"character"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -6305,10 +6277,10 @@ fmt_time <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_datetime()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_datetime()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `date_style` #' - `time_style` @@ -6321,11 +6293,10 @@ fmt_time <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Formatting with the `date_style` argument: #' @@ -6383,8 +6354,8 @@ fmt_time <- function( #' | 40 | `"d"` | `"29"` | flexible | #' | 41 | `"Ed"` | `"29 Tue"` | flexible | #' -#' We can use the [info_date_style()] function within the console to view a -#' similar table of date styles with example output. +#' We can call [info_date_style()] in the console to view a similar table of +#' date styles with example output. #' #' @section Formatting with the `time_style` argument: #' @@ -6398,7 +6369,7 @@ fmt_time <- function( #' The following table provides a listing of all time styles and their output #' values (corresponding to an input time of `14:35:00`). It is noted which of #' these represent 12- or 24-hour time. Some of the flexible formats (those -#' that begin with `"E"`) include the the day of the week. Keep this in mind +#' that begin with `"E"`) include the day of the week. Keep this in mind #' when pairing such `time_style` values with a `date_style` so as to avoid #' redundant or repeating information. #' @@ -6430,8 +6401,8 @@ fmt_time <- function( #' | 24 | `"hmv"` | `"2:35 PM GMT+00:00"` | flexible, 12h | #' | 25 | `"ms"` | `"35:00"` | flexible | #' -#' We can use the [info_time_style()] function within the console to view a -#' similar table of time styles with example output. +#' We can call [info_time_style()] in the console to view a similar table of +#' time styles with example output. #' #' @section Formatting with a *CLDR* datetime pattern: #' @@ -6966,7 +6937,7 @@ fmt_time <- function( #' global locale setting performed in [gt()]'s own `locale` argument (it is #' settable there as a value received by all other functions that have a #' `locale` argument). As a useful reference on which locales are supported, we -#' can use the [info_locales()] function to view an info table. +#' can call [info_locales()] to view an info table. #' #' @section Examples: #' @@ -7089,7 +7060,7 @@ fmt_datetime <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -7402,11 +7373,10 @@ fmt_datetime <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_duration()` formatting function is compatible with body cells that -#' are of the `"numeric"`, `"integer"`, or `"difftime"` types. Any other types -#' of body cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_duration()` is compatible with body cells that are of the `"numeric"`, +#' `"integer"`, or `"difftime"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -7459,8 +7429,8 @@ fmt_datetime <- function( #' Note that a `locale` value provided here will override any global locale #' setting performed in [gt()]'s own `locale` argument (it is settable there as #' a value received by all other functions that have a `locale` argument). As a -#' useful reference on which locales are supported, we can use the -#' [info_locales()] function to view an info table. +#' useful reference on which locales are supported, we can call [info_locales()] +#' to view an info table. #' #' @section Examples: #' @@ -7527,8 +7497,8 @@ fmt_duration <- function( # Declare formatting function compatibility compat <- c("numeric", "integer", "difftime") - check_character2(output_units, allow_null = TRUE, allow_0 = FALSE) - check_character2(input_units, allow_null = TRUE, allow_0 = FALSE) + check_chr_has_length(output_units, allow_null = TRUE, allow_0 = FALSE) + check_chr_has_length(input_units, allow_null = TRUE, allow_0 = FALSE) # Stop function if `locale` does not have a valid value; normalize locale # and resolve one that might be set globally validate_locale(locale = locale) @@ -7624,6 +7594,7 @@ fmt_duration <- function( output_units <- rlang::arg_match( output_units, values = c("weeks", "days", "hours", "mins", "minutes", "secs", "seconds"), + # Error message will naturally improve as r-lib/rlang#1682 is fixed multiple = TRUE ) @@ -8079,8 +8050,8 @@ extract_duration_pattern <- function( } #' Format column data containing bin/interval information -#' -#' When using the `cut()` function (or other functions that use it in some way) + +#' When using `cut()` (or other functions that use it in some way) #' you get bins that can look like this: `"(0,10]"`, `"(10,15]"`, `"(15,20]"`, #' `"(20,40]"`. This interval notation expresses the lower and upper limits of #' each range. The square or round brackets define whether each of the endpoints @@ -8100,7 +8071,7 @@ extract_duration_pattern <- function( #' 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. +#' within [base::I()]. #' #' @param fmt *Formatting expressions* #' @@ -8114,10 +8085,10 @@ extract_duration_pattern <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_bins()` formatting function is compatible with body cells that are -#' of the `"character"` or `"factor"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_bins()` is compatible with body cells that are of the `"character"` or +#' `"factor"` types. Any other types of body cells are ignored during formatting. +#' This is to say that cells of incompatible data types may be targeted, but +#' there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -8171,14 +8142,13 @@ extract_duration_pattern <- function( #' @section Examples: #' #' Use the [`countrypops`] dataset to create a **gt** table. Before even getting -#' to the [gt()] call, we use the `cut()` function in conjunction with the -#' [scales::breaks_log()] function to create some highly customized bins. -#' Consequently each country's population in the 2021 year is assigned to a bin. -#' These bins have a characteristic type of formatting that can be used as input -#' to `fmt_bins()`, and using that formatting function allows us to customize -#' the presentation of those ranges. For instance, here we are formatting the -#' left and right values of the ranges with the [fmt_integer()] function (using -#' formula syntax). +#' to the [gt()] call, we use `cut()` in conjunction with [scales::breaks_log()] +#' to create some highly customized bins. Consequently each country's population +#' in the 2021 year is assigned to a bin. These bins have a characteristic type +#' of formatting that can be used as input to `fmt_bins()`, and using that +#' formatting function allows us to customize the presentation of those ranges. +#' For instance, here we are formatting the left and right values of the ranges +#' with [fmt_integer()] (using formula syntax). #' #' ```r #' countrypops |> @@ -8448,11 +8418,10 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_tf()` formatting function is compatible with body cells that are -#' of the `"logical"` (preferred) or `"numeric"` types. Any other types of body -#' cells are ignored during formatting. This is to say that cells of -#' incompatible data types may be targeted, but there will be no attempt to -#' format them. +#' `fmt_tf()` is compatible with body cells that are of the `"logical"` +#' (preferred) or `"numeric"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' There is a special caveat when attempting to format numerical values: the #' values must either be exactly `1` (the analogue for `TRUE`) or exactly `0` @@ -8501,10 +8470,10 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_tf()` to obtain varying parameter values from a specified column within -#' the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_tf()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `tf_style` #' - `pattern` @@ -8516,11 +8485,10 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Formatting with the `tf_style` argument: #' @@ -8556,19 +8524,18 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' global locale setting performed in [gt()]'s own `locale` argument (it is #' settable there as a value received by all other functions that have a #' `locale` argument). As a useful reference on which locales are supported, we -#' can use the [info_locales()] function to view an info table. +#' can call [info_locales()] to view an info table. #' #' @section Examples: #' #' Let's use a subset of the [`sp500`] dataset to create a small **gt** table #' containing opening and closing price data for a week in 2013. We can add -#' a logical column (`dir`) with the [cols_add()] function; the expression used -#' determines whether the `close` value is greater than the `open` value. That -#' new column is inserted between `open` and `close`. Then, we use the -#' `fmt_tf()` function to generate up and down arrows in the `dir` column. We -#' elect to use green upward arrows and red downward arrows (through the -#' `colors` option). With a little numeric formatting and changes to the column -#' labels, the table becomes more presentable. +#' a logical column (`dir`) with [cols_add()]; the expression used determines +#' whether the `close` value is greater than the `open` value. That new column +#' is inserted between `open` and `close`. Then, we use `fmt_tf()` to generate +#' up and down arrows in the `dir` column. We elect to use green upward arrows +#' and red downward arrows (through the `colors` option). With a little numeric +#' formatting and changes to the column labels, the table becomes more presentable. #' #' ```r #' sp500 |> @@ -8694,8 +8661,7 @@ format_bins_by_context <- function(x, sep, fmt, context) { #' columns all receive `TRUE` whereas `no` and `down` will all be `FALSE`. #' With two calls of `fmt_tf()` for each of these pairings, we get the columns' #' namesake words. To have these words translated, the `locale` argument is -#' pointed toward values in the `code` column by using the [from_column()] -#' helper function. +#' pointed toward values in the `code` column by using [from_column()]. #' #' ```r #' dplyr::tibble( @@ -8784,7 +8750,7 @@ fmt_tf <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -9050,8 +9016,8 @@ make_span_with_color <- function(text, color = NULL) { #' #' @description #' -#' The `fmt_units()` function lets you better format measurement units in the -#' table body. These must conform to **gt**'s specialized units notation (e.g., +#' `fmt_units()` lets you better format measurement units in the table body. +#' These must conform to **gt**'s specialized units notation (e.g., #' `"J Hz^-1 mol^-1"` can be used to generate units for the #' *molar Planck constant*) for the best conversion. The notation here provides #' several conveniences for defining units, so as long as the values to be @@ -9113,7 +9079,7 @@ make_span_with_color <- function(text, color = NULL) { #' #' - `"m/s"` and `"m / s"` both render as `"m/s"` #' - `"m s^-1"` will appear with the `"-1"` exponent intact -#' - `"m /s"` gives the the same result, as `"/"` is equivalent to +#' - `"m /s"` gives the same result, as `"/"` is equivalent to #' `"^-1"` #' - `"E_h"` will render an `"E"` with the `"h"` subscript #' - `"t_i^2.5"` provides a `t` with an `"i"` subscript and a `"2.5"` exponent @@ -9275,7 +9241,7 @@ fmt_units <- function( #' #' @description #' -#' The `fmt_chem()` function lets you format chemical formulas or even chemical +#' `fmt_chem()` lets you format chemical formulas or even chemical #' reactions in the table body. Often the input text will be in a common form #' representing single compounds (like `"C2H4O"`, for acetaldehyde) but chemical #' reactions can be used (e.g., `2CH3OH -> CH3OCH3 + H2O"`). So long as the @@ -9404,9 +9370,9 @@ fmt_units <- function( #' Taking just a few rows from the [`photolysis`] dataset, let's create a new #' **gt** table. The `cmpd_formula` and `products` columns both contain text in #' chemistry notation (the first has compounds, and the second column has the -#' products of photolysis reactions). These columns will be formatted by the -#' `fmt_chem()` function. The compound formulas will be merged with the compound -#' names via the [cols_merge()] function. +#' products of photolysis reactions). These columns will be formatted by +#' `fmt_chem()`. The compound formulas will be merged with the compound +#' names with [cols_merge()]. #' #' ```r #' photolysis %>% @@ -9448,7 +9414,7 @@ fmt_units <- function( #' `r man_get_image_tag(file = "man_fmt_chem_2.png")` #' }} #' -#' The `fmt_chem()` function can handle the typesetting of nuclide notation. +#' `fmt_chem()` can handle the typesetting of nuclide notation. #' Let's take a subset of columns and rows from the [`nuclides`] dataset and #' make a new **gt** table. The contents of the `nuclide` column contains #' isotopes of hydrogen and carbon and this is placed in the table stub. Using @@ -9623,7 +9589,7 @@ format_units_by_context <- function( #' #' @description #' -#' Should cells contain URLs, the `fmt_url()` function can be used to make them +#' Should cells contain URLs, `fmt_url()` can be used to make them #' navigable links. This should be expressly used on columns that contain *only* #' URL text (i.e., no URLs as part of a larger block of text). Should you have #' such a column of data, there are options for how the links should be styled. @@ -9695,10 +9661,10 @@ format_units_by_context <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_url()` formatting function is compatible with body cells that are -#' of the `"character"` or `"factor"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_url()` is compatible with body cells that are of the `"character"` or +#' `"factor"` types. Any other types of body cells are ignored during formatting. +#' This is to say that cells of incompatible data types may be targeted, but +#' there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -9741,10 +9707,10 @@ format_units_by_context <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_url()` to obtain varying parameter values from a specified column within -#' the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_url()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `label` #' - `as_button` @@ -9757,18 +9723,17 @@ format_units_by_context <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' #' Using a portion of the [`towny`] dataset, let's create a **gt** table. We can -#' use the `fmt_url()` function on the `website` column to generate navigable -#' links to websites. By default the links are underlined and the color will be -#' chosen for you (it's dark cyan). +#' use `fmt_url()` on the `website` column to generate navigable links to +#' websites. By default the links are underlined and the color will be chosen +#' for you (it's dark cyan). #' #' ```r #' towny |> @@ -9798,7 +9763,7 @@ format_units_by_context <- function( #' the `label` argument (and we'll use the word `"site"` for this). The link #' underline is removable with `show_underline = FALSE`. With this change, it #' seems sensible to merge the link to the `"name"` column and enclose the link -#' text in parentheses (the [cols_merge()] function handles all that). +#' text in parentheses ([cols_merge()] handles all that). #' #' ```r #' towny |> @@ -9831,9 +9796,9 @@ format_units_by_context <- function( #' `r man_get_image_tag(file = "man_fmt_url_2.png")` #' }} #' -#' The `fmt_url()` function allows for the styling of links as 'buttons'. This -#' is as easy as setting `as_button = TRUE`. Doing that unlocks the ability to -#' set a `button_fill` color. This color can automatically selected by **gt** +#' `fmt_url()` allows for the styling of links as 'buttons'. This is as easy as +#' setting `as_button = TRUE`. Doing that unlocks the ability to set a +#' `button_fill` color. This color can automatically selected by **gt** #' (this is the default) but here we're using `"steelblue"`. The `label` #' argument also accepts a function! We can choose to adapt the label text from #' the URLs by eliminating any leading `"https://"` or `"www."` parts. @@ -9877,8 +9842,8 @@ format_units_by_context <- function( #' }} #' #' It's perhaps inevitable that you'll come across missing values in your column -#' of URLs. The `fmt_url()` function will preserve input `NA` values, allowing -#' you to handle them with [sub_missing()]. Here's an example of that. +#' of URLs. `fmt_url()` will preserve input `NA` values, allowing you to handle +#' them with [sub_missing()]. Here's an example of that. #' #' ```r #' towny |> @@ -10001,7 +9966,7 @@ fmt_url <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -10048,6 +10013,7 @@ fmt_url <- function( # called "gt.strict_column_fmt"), stop the function if any of the # resolved columns have data that is incompatible with this formatter if ( + isTRUE(getOption("gt.strict_column_fmt", TRUE)) && !column_classes_are_valid( data = data, columns = {{ columns }}, @@ -10404,15 +10370,14 @@ add_anchor_attr <- function( #' #' @description #' -#' Should cells contain email addresses, the `fmt_email()` function can be used -#' to make email addresses work well with email clients on the user system. -#' This should be expressly used on columns that contain *only* email addresses -#' (i.e., no email addresses as part of a larger block of text). Should you have -#' such a column of data, there are options for how the email addresses should -#' be styled. They can be of the conventional style (with underlines and text -#' coloring that sets it apart from other text), or, they can appear to be -#' button-like (with a surrounding box that can be filled with a color of your -#' choosing). +#' Should cells contain email addresses, `fmt_email()` can be used to make email +#' addresses work well with email clients on the user system. This should be +#' expressly used on columns that contain *only* email addresses (i.e., no email +#' addresses as part of a larger block of text). Should you have such a column of +#' data, there are options for how the email addresses should be styled. They can +#' be of the conventional style (with underlines and text coloring that sets it +#' apart from other text), or, they can appear to be button-like (with a +#' surrounding box that can be filled with a color of your choosing). #' #' Email addresses in data cells are trusted as email addresses. We can also #' provide more readable labels with the `display_name` argument. Supplying a @@ -10479,10 +10444,10 @@ add_anchor_attr <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_email()` formatting function is compatible with body cells that are -#' of the `"character"` or `"factor"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_email()` is compatible with body cells that are of the `"character"` or +#' `"factor"` types. Any other types of body cells are ignored during formatting. +#' This is to say that cells of incompatible data types may be targeted, but +#' there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -10525,10 +10490,10 @@ add_anchor_attr <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_email()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_email()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `display_name` #' - `as_button` @@ -10541,11 +10506,10 @@ add_anchor_attr <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' @@ -10640,10 +10604,10 @@ add_anchor_attr <- function( #' #' Another option is to display the names of the email recipients instead of the #' email addresses, making the display names serve as 'mailto:' links. We can do -#' this by using the [from_column()] function in the `display_name` argument. -#' The display names in this case are the combined given and family names, -#' handled earlier through a `dplyr::mutate()` call. With some space conserved, -#' we take the opportunity here to add in phone information for each person. +#' this by using [from_column()] in the `display_name` argument. The display +#' names in this case are the combined given and family names, handled earlier +#' through a `dplyr::mutate()` call. With some space conserved, we take the +#' opportunity here to add in phone information for each person. #' #' ```r #' peeps |> @@ -10742,7 +10706,7 @@ fmt_email <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -11123,9 +11087,9 @@ generate_email_links <- function(email_address, anchor_attr, label_str) { #' #' @description #' -#' To more easily insert graphics into body cells, we can use the `fmt_image()` -#' function. This allows for one or more images to be placed in the targeted -#' cells. The cells need to contain some reference to an image file, either: (1) +#' To more easily insert graphics into body cells, we can use `fmt_image()`. +#' This allows for one or more images to be placed in the targeted cells. +#' The cells need to contain some reference to an image file, either: (1) #' complete http/https or local paths to the files; (2) the file names, where a #' common path can be provided via `path`; or (3) a fragment of the file name, #' where the `file_pattern` helps to compose the entire file name and `path` @@ -11219,10 +11183,10 @@ generate_email_links <- function(email_address, anchor_attr, label_str) { #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_image()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_image()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `height` #' - `width` @@ -11234,11 +11198,10 @@ generate_email_links <- function(email_address, anchor_attr, label_str) { #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' @@ -11249,11 +11212,11 @@ generate_email_links <- function(email_address, anchor_attr, label_str) { #' graphics for all of these lines within the package (the path for the #' directory containing the images can be accessed via #' `system.file("metro_svg", package = "gt")`), and the filenames roughly -#' correspond to the data in those two columns. The `fmt_image()` function can -#' be used with these inputs since the `path` and `file_pattern` arguments allow -#' us to compose complete and valid file locations. What you get from all of -#' this are sequences of images in the table cells, taken from the referenced -#' graphics files on disk. +#' correspond to the data in those two columns. `fmt_image()` can be used with +#' these inputs since the `path` and `file_pattern` arguments allow us to +#' compose complete and valid file locations. What you get from all of this are +#' sequences of images in the table cells, taken from the referenced graphics +#' files on disk. #' #' ```r #' metro |> @@ -11350,7 +11313,7 @@ fmt_image <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -11739,10 +11702,10 @@ get_image_hw_ratio <- function(filepath) { #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_flag()` formatting function is compatible with body cells that are -#' of the `"character"` or `"factor"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_flag()` is compatible with body cells that are of the `"character"` or +#' `"factor"` types. Any other types of body cells are ignored during +#' formatting. This is to say that cells of incompatible data types may be +#' targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -11785,10 +11748,10 @@ get_image_hw_ratio <- function(filepath) { #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_flag()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_flag()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `height` #' - `sep` @@ -11798,11 +11761,10 @@ get_image_hw_ratio <- function(filepath) { #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Supported regions: #' @@ -11837,7 +11799,7 @@ get_image_hw_ratio <- function(filepath) { #' `"ZA"`, `"ZM"`, and `"ZW"`. #' #' You can view the entire set of supported flag icons as an informative table -#' by using the [info_flags()] function. +#' by calling [info_flags()]. #' #' @section Examples: #' @@ -11898,10 +11860,10 @@ get_image_hw_ratio <- function(filepath) { #' `r man_get_image_tag(file = "man_fmt_flag_2.png")` #' }} #' -#' The `fmt_flag()` function works well even when there are multiple country -#' codes within the same cell. It can operate on comma-separated codes without -#' issue. When rendered to HTML, hovering over each of the flag icons results in -#' tooltip text showing the name of the country. +#' `fmt_flag()` works well even when there are multiple country codes within the +#' same cell. It can operate on comma-separated codes without issue. When +#' rendered to HTML, hovering over each of the flag icons results in tooltip +#' text showing the name of the country. #' #' ```r #' countrypops |> @@ -11978,7 +11940,7 @@ fmt_flag <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -12208,10 +12170,10 @@ fmt_flag <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_country()` formatting function is compatible with body cells that -#' are of the `"character"` or `"factor"` types. Any other types of body cells -#' are ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_country()` function is compatible with body cells that are of the +#' `"character"` or `"factor"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -12254,10 +12216,10 @@ fmt_flag <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_country()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_country()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `pattern` #' - `sep` @@ -12266,11 +12228,10 @@ fmt_flag <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Supported regions: #' @@ -12459,7 +12420,7 @@ fmt_country <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -12729,10 +12690,10 @@ fmt_country <- function( #' #' @section Compatibility of formatting function with data values: #' -#' The `fmt_icon()` formatting function is compatible with body cells that are -#' of the `"character"` or `"factor"` types. Any other types of body cells are -#' ignored during formatting. This is to say that cells of incompatible data -#' types may be targeted, but there will be no attempt to format them. +#' `fmt_icon()` is compatible with body cells that are of the +#' `"character"` or `"factor"` types. Any other types of body cells are ignored +#' during formatting. This is to say that cells of incompatible data types may +#' be targeted, but there will be no attempt to format them. #' #' @section Targeting cells with `columns` and `rows`: #' @@ -12775,10 +12736,10 @@ fmt_country <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_icon()` to obtain varying parameter values from a specified column -#' within the table. This means that each row could be formatted a little bit -#' differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_icon()` to obtain +#' varying parameter values from a specified column within the table. This means +#' that each row could be formatted a little bit differently. These arguments +#' provide support for [from_column()]: #' #' - `height` #' - `sep` @@ -12795,24 +12756,23 @@ fmt_country <- function( #' Please note that for each of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Icons that can be used: #' -#' The `fmt_icon()` function relies on an installation of the **fontawesome** -#' package to operate and every icon within that package can be accessed here -#' with either an icon name or a full name. For example, the *Arrow Down* icon -#' has an icon name of `"arrow-down"` and its corresponding full name is +#' `fmt_icon()` relies on an installation of the **fontawesome** package to +#' operate and every icon within that package can be accessed here with either +#' an icon name or a full name. For example, the *Arrow Down* icon has an icon +#' name of `"arrow-down"` and its corresponding full name is #' `"fas fa-arrow-down"`. In most cases you'll want to use the shorter name, but #' some icons have both a *Solid* (`"fas"`) and a *Regular* (`"far"`) variant so #' only the full name can disambiguate the pairing. In the latest release of #' **fontawesome** (`v0.5.2`), there are 2,025 icons and you can view the entire -#' icon listing by using the [info_icons()] function. What you'll get from that -#' is an information table showing every icon and associated set of identifiers. +#' icon listing by calling [info_icons()]. What you'll get from that is an +#' information table showing every icon and associated set of identifiers. #' #' @section Examples: #' @@ -12882,7 +12842,7 @@ fmt_country <- function( #' can be converged into a single column (`services`) with the `NA` values #' removed. Since the names correspond to icons and they are in the correct #' format (separated by commas), they can be formatted as *Font Awesome* icons -#' with the `fmt_icon()` function. +#' with `fmt_icon()`. #' #' ```r #' metro |> @@ -12923,8 +12883,8 @@ fmt_country <- function( #' `"star-half"` icons. In this case, it is useful to generate the repeating #' sequence of icon names (separated by commas) in the `rating` column before #' introducing the table to [gt()]. We can make use of the numerical rating -#' values in `stars` within the `fmt_icon()` function with a little help from -#' the [from_column()] helper. Using that, we can dynamically adjust the icon's +#' values in `stars` within `fmt_icon()` with a little help from +#' [from_column()]. Using that, we can dynamically adjust the icon's #' `fill_alpha` (i.e., opacity) value and accentuate the films with higher #' scores. #' @@ -12963,11 +12923,10 @@ fmt_country <- function( #' can serve as good visual indicators for this purpose. We can make use of the #' `"up-arrow"` and `"down-arrow"` icons here. The `fmt_icon()` function has to #' find those text values in cells to generate the icons, so, lets generate the -#' text within a new column via the [cols_add()] function (an expression is used -#' therein to generate the correct text given the `close` and `open` values). -#' Following that, `fmt_icon()` is used and its `fill_color` argument is -#' provided with a named vector that indicates which color should be used for -#' each icon. +#' text within a new column with [cols_add()] (an expression is used therein to +#' generate the correct text given the `close` and `open` values). Following +#' that, `fmt_icon()` is used and its `fill_color` argument is provided with a +#' named vector that indicates which color should be used for each icon. #' #' ```r #' sp500 |> @@ -13028,7 +12987,7 @@ fmt_icon <- function( # Determine if the fontawesome package is installed and stop the # function if it is not present - rlang::check_installed("fontawesome", "to insert icons with `fmt_icons()`.") + rlang::check_installed("fontawesome", "to insert icons with `fmt_icon()`.") # # Begin support for `from_column()` objects passed to compatible arguments @@ -13058,7 +13017,7 @@ fmt_icon <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -13299,16 +13258,15 @@ fmt_icon <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with the `md_engine` argument -#' of `fmt_markdown()` to obtain varying parameter values from a specified -#' column within the table. This means that each row could be formatted a little -#' bit differently. +#' [from_column()] can be used with the `md_engine` argument of `fmt_markdown()` +#' to obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. #' #' Please note that for this argument (`md_engine`), a [from_column()] call #' needs to reference a column that has data of the `character` type. Additional -#' columns for parameter values can be generated with the [cols_add()] function -#' (if not already present). Columns that contain parameter data can also be -#' hidden from final display with [cols_hide()]. +#' columns for parameter values can be generated with [cols_add()] (if not +#' already present). Columns that contain parameter data can also be hidden from +#' final display with [cols_hide()]. #' #' @section Examples: #' @@ -13346,8 +13304,8 @@ fmt_icon <- function( #' " #' ``` #' -#' Arrange the text snippets as a tibble using the `dplyr::tribble()` function. -#' then, create a **gt** table and format all columns with `fmt_markdown()`. +#' Arrange the text snippets as a tibble using `dplyr::tribble()`, then, create +#' a **gt** table and format all columns with `fmt_markdown()`. #' #' ```r #' dplyr::tribble( @@ -13364,8 +13322,8 @@ fmt_icon <- function( #' `r man_get_image_tag(file = "man_fmt_markdown_1.png")` #' }} #' -#' The `fmt_markdown()` function can also handle LaTeX math formulas enclosed -#' in `"$..$"` (inline math) and also `"$$..$$"` (display math). The following +#' `fmt_markdown()` can also handle LaTeX math formulas enclosed in +#' `"$..$"` (inline math) and also `"$$..$$"` (display math). The following #' table has body cells that contain mathematical formulas in display mode #' (i.e., the formulas are surrounded by `"$$"`). Further to this, math can be #' used within [md()] wherever there is the possibility to insert text into the @@ -13482,7 +13440,7 @@ fmt_markdown <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -13557,7 +13515,7 @@ fmt_markdown <- function( #' #' @description #' -#' We can format values with the `fmt_passthrough()` function, which does little +#' We can format values with `fmt_passthrough()`, which does little #' more than: (1) coercing to `character` (as all the `fmt_*()` functions do), #' and (2) applying decorator text via the `pattern` argument (the default is to #' apply nothing). This formatting function is useful when don't want to modify @@ -13618,10 +13576,10 @@ fmt_markdown <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with certain arguments of -#' `fmt_passthrough()` to obtain varying parameter values from a specified -#' column within the table. This means that each row could be formatted a little -#' bit differently. These arguments provide support for [from_column()]: +#' [from_column()] can be used with certain arguments of `fmt_passthrough()` to +#' obtain varying parameter values from a specified column within the table. +#' This means that each row could be formatted a little bit differently. These +#' arguments provide support for [from_column()]: #' #' - `escape` #' - `pattern` @@ -13629,11 +13587,10 @@ fmt_markdown <- function( #' Please note that for both of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. Finally, there is no limitation to how many arguments the -#' [from_column()] helper is applied so long as the arguments belong to this -#' closed set. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. +#' Finally, there is no limitation to how many arguments the [from_column()] +#' helper is applied so long as the arguments belong to this closed set. #' #' @section Examples: #' @@ -13698,7 +13655,7 @@ fmt_passthrough <- function( if (args_have_gt_column_obj(arg_vals = arg_vals)) { - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = {{ rows }}, @@ -13816,15 +13773,14 @@ fmt_passthrough <- function( #' #' @description #' -#' The `fmt_auto()` function will automatically apply formatting of various -#' types in a way that best suits the data table provided. The function will -#' attempt to format numbers such that they are condensed to an optimal width, -#' either with scientific notation or large-number suffixing. Currency values -#' are detected by currency codes embedded in the column name and formatted in -#' the correct way. Although the functionality here is comprehensive it's still -#' possible to reduce the scope of automatic formatting with the `scope` -#' argument and also by choosing a subset of columns and rows to which the -#' formatting will be applied. +#' `fmt_auto()` will automatically apply formatting of various types in a way +#' that best suits the data table provided. The function will attempt to format +#' numbers such that they are condensed to an optimal width, either with +#' scientific notation or large-number suffixing. Currency values are detected +#' by currency codes embedded in the column name and formatted in the correct +#' way. Although the functionality here is comprehensive it's still possible to +#' reduce the scope of automatic formatting with the `scope` argument and also +#' by choosing a subset of columns and rows to which the formatting will be applied. #' #' @inheritParams fmt_number #' @@ -14141,9 +14097,8 @@ fmt_auto <- function( #' #' @description #' -#' The `fmt()` function provides a way to execute custom formatting -#' functionality with raw data values in a way that can consider all output -#' contexts. +#' `fmt()` provides a way to execute custom formatting functionality with raw +#' data values in a way that can consider all output contexts. #' #' Along with the `columns` and `rows` arguments that provide some precision in #' targeting data cells, the `fns` argument allows you to define one or more diff --git a/R/format_vec.R b/R/format_vec.R index 44a615fa41..8f5a844313 100644 --- a/R/format_vec.R +++ b/R/format_vec.R @@ -66,8 +66,8 @@ #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -233,8 +233,8 @@ vec_fmt_number <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -370,8 +370,8 @@ vec_fmt_integer <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -527,8 +527,8 @@ vec_fmt_scientific <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -682,8 +682,8 @@ vec_fmt_engineering <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -865,8 +865,8 @@ vec_fmt_percent <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1035,8 +1035,8 @@ vec_fmt_partsper <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1166,8 +1166,8 @@ vec_fmt_fraction <- function( #' formatting specific to the chosen locale; it will also retrieve the locale's #' currency if none is explicitly given #' -#' We can use the [info_currencies()] function for a useful reference on all of -#' the possible inputs to the `currency` argument. +#' We can call [info_currencies()] for a useful reference on all of the possible +#' inputs to the `currency` argument. #' #' @inheritParams fmt_currency #' @@ -1200,8 +1200,8 @@ vec_fmt_fraction <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1451,8 +1451,8 @@ vec_fmt_roman <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for +#' a useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1576,8 +1576,8 @@ vec_fmt_index <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1697,10 +1697,10 @@ vec_fmt_spelled_num <- function( #' @description #' #' With numeric values in a vector, we can transform each into byte values with -#' human readable units. The `vec_fmt_bytes()` function allows for the -#' formatting of byte sizes to either of two common representations: (1) with -#' decimal units (powers of 1000, examples being `"kB"` and `"MB"`), and (2) -#' with binary units (powers of 1024, examples being `"KiB"` and `"MiB"`). +#' human readable units. `vec_fmt_bytes()` allows for the formatting of byte +#' sizes to either of two common representations: (1) with decimal units +#' (powers of 1000, examples being `"kB"` and `"MB"`), and (2) with binary units +#' (powers of 1024, examples being `"KiB"` and `"MiB"`). #' #' It is assumed the input numeric values represent the number of bytes and #' automatic truncation of values will occur. The numeric values will be scaled @@ -1727,8 +1727,8 @@ vec_fmt_spelled_num <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1871,8 +1871,8 @@ vec_fmt_bytes <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -1932,8 +1932,8 @@ vec_fmt_bytes <- function( #' | 40 | `"d"` | `"29"` | flexible | #' | 41 | `"Ed"` | `"29 Tue"` | flexible | #' -#' We can use the [info_date_style()] function within the console to view a -#' similar table of date styles with example output. +#' We can call [info_date_style()] in the console to view a similar table +#' of date styles with example output. #' #' @section Examples: #' @@ -2053,8 +2053,8 @@ vec_fmt_date <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -2099,8 +2099,8 @@ vec_fmt_date <- function( #' | 24 | `"hmv"` | `"2:35 PM GMT+00:00"` | flexible, 12h | #' | 25 | `"ms"` | `"35:00"` | flexible | #' -#' We can use the [info_time_style()] function within the console to view a -#' similar table of time styles with example output. +#' We can call [info_time_style()] in the console to view a similar table of +#' time styles with example output. #' #' @section Examples: #' @@ -2225,8 +2225,8 @@ vec_fmt_time <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' @@ -2286,8 +2286,8 @@ vec_fmt_time <- function( #' | 40 | `"d"` | `"29"` | flexible | #' | 41 | `"Ed"` | `"29 Tue"` | flexible | #' -#' We can use the [info_date_style()] function within the console to view a -#' similar table of date styles with example output. +#' We can call [info_date_style()] in the console to view a similar table of +#' date styles with example output. #' #' @section Formatting with the `time_style` argument: #' @@ -2301,7 +2301,7 @@ vec_fmt_time <- function( #' The following table provides a listing of all time styles and their output #' values (corresponding to an input time of `14:35:00`). It is noted which of #' these represent 12- or 24-hour time. Some of the flexible formats (those -#' that begin with `"E"`) include the the day of the week. Keep this in mind +#' that begin with `"E"`) include the day of the week. Keep this in mind #' when pairing such `time_style` values with a `date_style` so as to avoid #' redundant or repeating information. #' @@ -2333,8 +2333,8 @@ vec_fmt_time <- function( #' | 24 | `"hmv"` | `"2:35 PM GMT+00:00"` | flexible, 12h | #' | 25 | `"ms"` | `"35:00"` | flexible | #' -#' We can use the [info_time_style()] function within the console to view a -#' similar table of time styles with example output. +#' We can call [info_time_style()] in the console to view a similar table of +#' time styles with example output. #' #' @section Formatting with a *CLDR* datetime pattern: #' @@ -3069,8 +3069,8 @@ vec_fmt_datetime <- function( #' #' 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] for a +#' useful reference for all of the locales that are supported. #' #' @return A character vector. #' diff --git a/R/gt.R b/R/gt.R index f0e4b9d3ae..9c58e2a502 100644 --- a/R/gt.R +++ b/R/gt.R @@ -43,7 +43,7 @@ #' within the different row groups). #' #' Row groups can also be created by passing a `grouped_df` to `gt()` by using -#' the [dplyr::group_by()] function on the table data. In this way, two or more +#' [dplyr::group_by()] on the table data. In this way, two or more #' columns of categorical data can be used to make row groups. The #' `row_group.sep` argument allows for control in how the row group labels will #' appear in the display table. @@ -68,8 +68,8 @@ #' #' The column name in the input `data` table to use as group labels for #' generation of 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. +#' class (through use of [dplyr::group_by()] or associated `group_by*()` +#' functions) then any input here is ignored. #' #' @param process_md *Process Markdown in `rowname_col` and `groupname_col`* #' @@ -114,7 +114,7 @@ #' `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 here by +#' by using [random_id()]. A custom table ID can be used here by #' providing a character value. #' #' @param locale *Locale identifier* @@ -123,9 +123,8 @@ #' #' 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. +#' English (United States) and `"fr"` for French (France). We can call +#' [info_locales()] as a useful reference for all of the locales that are supported. #' #' @param row_group.sep *Separator text for multiple row group labels* #' @@ -188,13 +187,13 @@ #' }} #' #' If you'd rather perform the set up of row groups later (i.e., not in the -#' `gt()` call), this is possible with use of the [tab_row_group()] function -#' (and [row_group_order()] can help with the arrangement of row groups). +#' `gt()` call), this is possible with [tab_row_group()] (and [row_group_order()] +#' can help with the arrangement of row groups). #' #' One more thing to consider with row groups is their layout. By default, row #' group labels reside in separate rows the appear above the group. However, -#' we can use the `row_group_as_column = TRUE` option to put the row group -#' labels within a secondary column within the table stub. +#' we can use `row_group_as_column = TRUE` to put the row group labels within a +#' secondary column within the table stub. #' #' ```r #' exibble |> @@ -239,7 +238,7 @@ #' }} #' #' What you'll get from that is center-alignment of all table body values and -#' all column labels. Note that row labels in the the stub are still +#' all column labels. Note that row labels in the stub are still #' left-aligned; and `auto_align` has no effect on alignment within the table #' stub. #' @@ -277,13 +276,12 @@ #' `r man_get_image_tag(file = "man_gt_7.png")` #' }} #' -#' In this example, the [fmt_number()] and [fmt_date()] functions understand -#' that the locale for this table is `"fr"` (French), so the appropriate -#' formatting for that locale is apparent in the `num`, `currency`, and `date` -#' columns. However in the [fmt_datetime()] call, we explicitly use the `"en"` -#' (English) locale. This overrides the `"fr"` default set for this table and -#' the end result is dates formatted with the English locale in the `datetime` -#' column. +#' In this example, [fmt_number()] and [fmt_date()] understand that the locale +#' for this table is `"fr"` (French), so the appropriate formatting for that +#' locale is apparent in the `num`, `currency`, and `date` columns. However in +#' [fmt_datetime()], we explicitly use the `"en"` (English) locale. This +#' overrides the `"fr"` default set for this table and the end result is +#' dates formatted with the English locale in the `datetime` column. #' #' @family table creation functions #' @section Function ID: diff --git a/R/gt_group.R b/R/gt_group.R index d5eb6bcdb8..d7f1323956 100644 --- a/R/gt_group.R +++ b/R/gt_group.R @@ -26,7 +26,7 @@ #' #' @description #' -#' The `gt_group()` function creates a container for storage of multiple **gt** +#' `gt_group()` creates a container for storage of multiple **gt** #' tables. This type of object allows for flexibility in printing multiple #' tables in different output formats. For example, if printing multiple tables #' in a paginated output environment (e.g., RTF, Word, etc.), each **gt** table @@ -104,11 +104,11 @@ gt_group <- function( #' #' @description #' -#' Should you have a `gt_group` object, created through use of the [gt_group()] -#' function, you may have a need to extract a **gt** table from that container. -#' The `grp_pull()` function makes this possible, returning a `gt_tbl` object. -#' The only thing you need to provide is the index value for the **gt** table -#' within the `gt_group` object. +#' Should you have a `gt_group` object, created through use of [gt_group()], +#' you may have a need to extract a **gt** table from that container. +#' `grp_pull()` makes this possible, returning a `gt_tbl` object. The only thing +#' you need to provide is the index value for the **gt** table within the +#' `gt_group` object. #' #' @inheritParams grp_add #' @@ -166,8 +166,8 @@ grp_pull <- function( #' `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()]. +#' use of [gt_group()] along with one or more `gt_tbl` objects, or, made by +#' splitting a **gt** table with [gt_split()]. #' #' @inheritParams gt_group #' @@ -436,12 +436,11 @@ grp_clone <- function( #' #' @description #' -#' The [gt_group()] function can be used to create a container for multiple -#' **gt** tables. In some circumstances, you might want to replace a specific -#' `gt_tbl` object (or multiple) with a different one. This can be done with the -#' `grp_replace()` function. The important thing is that the number of **gt** -#' tables provided must equal the number of indices for tables present in the -#' `gt_group` object. +#' [gt_group()] can be used to create a container for multiple **gt** tables. +#' In some circumstances, you might want to replace a specific `gt_tbl` object +#' (or multiple) with a different one. This can be done with `grp_replace()`. +#' The important thing is that the number of **gt** tables provided must equal +#' the number of indices for tables present in the `gt_group` object. #' #' @inheritParams grp_add #' diff --git a/R/helpers.R b/R/helpers.R index 1a222187c6..7af83b3ed8 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -29,7 +29,7 @@ #' Markdown text can be used in certain places in a **gt** table, and this is #' wherever new text is defined (e.g., footnotes, source notes, the table title, #' etc.). Using Markdown is advantageous for styling text since it will be -#' rendered correctly to the the output format of the **gt** table. There is +#' rendered correctly to the output format of the **gt** table. There is #' also the [html()] helper that allows you use HTML exclusively (for tables #' expressly meant for HTML output) but `md()` allows for both; you get to use #' Markdown plus any HTML fragments at the same time. @@ -46,8 +46,8 @@ #' @section Examples: #' #' Use the [`exibble`] dataset to create a **gt** table. When adding a title -#' through the [tab_header()] function, we'll use the `md()` helper to signify -#' to **gt** that we're using Markdown formatting. +#' through [tab_header()], we'll use the `md()` helper to signify to **gt** that +#' we're using Markdown formatting. #' #' ```r #' exibble |> @@ -105,8 +105,8 @@ md <- function(text) { #' @section Examples: #' #' Use the [`exibble`] dataset to create a **gt** table. When adding a title -#' through the [tab_header()] function, we'll use the `html()` helper to signify -#' to **gt** that we're using HTML formatting. +#' through [tab_header()], we'll use the `html()` helper to signify to **gt** +#' that we're using HTML formatting. #' #' ```r #' exibble |> @@ -325,11 +325,11 @@ pct <- function(x) { #' #' @section Examples: #' -#' The `from_column()` function can be used in a variety of formatting functions -#' so that values for common options don't have to be static, they can change in -#' every row (so long as you have a column of compatible option values). Here's -#' an example where we have a table of repeating numeric values along with a -#' column of currency codes. We can format the numbers to currencies with +#' `from_column()` can be used in a variety of formatting functions so that +#' values for common options don't have to be static, they can change in every +#' row (so long as you have a column of compatible option values). Here's an +#' example where we have a table of repeating numeric values along with a column +#' of currency codes. We can format the numbers to currencies with #' [fmt_currency()] and use `from_column()` to reference the column of currency #' codes, giving us values that are each formatted as having a different #' currency. @@ -358,10 +358,7 @@ pct <- function(x) { #' #' ```r #' gtcars |> -#' dplyr::select(mfr, ctry_origin) |> -#' dplyr::group_by(mfr, ctry_origin) |> -#' dplyr::count() |> -#' dplyr::ungroup() |> +#' dplyr::count(mfr, ctry_origin) |> #' dplyr::arrange(ctry_origin) |> #' gt(groupname_col = "ctry_origin") |> #' tab_style( @@ -1384,8 +1381,7 @@ cells_column_labels <- function(columns = everything()) { #' [tab_style()]. The function is expressly used in each of those functions' #' `locations` argument. The 'row_groups' location can be generated by the #' specifying a `groupname_col` in [gt()], by introducing grouped data to [gt()] -#' (by way of [dplyr::group_by()]), or, by specifying groups with the -#' [tab_row_group()] function. +#' (via [dplyr::group_by()]), or, by specifying groups with [tab_row_group()]. #' #' @param groups *Specification of row group IDs* #' @@ -1409,10 +1405,9 @@ cells_column_labels <- function(columns = everything()) { #' @section Examples: #' #' Let's use a summarized version of the [`pizzaplace`] dataset to create a -#' **gt** table with grouped data. Add a summary with the [summary_rows()] -#' function and then add a footnote to the `"peppr_salami"` row group label with -#' [tab_footnote()]; the targeting is done with `cells_row_groups()` in the -#' `locations` argument. +#' **gt** table with grouped data. Add a summary with [summary_rows()] and then +#' add a footnote to the `"peppr_salami"` row group label with [tab_footnote()]; +#' the targeting is done with `cells_row_groups()` in the `locations` argument. #' #' ```r #' pizzaplace |> @@ -1684,11 +1679,11 @@ cells_body <- function( #' #' @description #' -#' `cells_summary()` is used to target the cells in a group summary -#' and it is useful when applying a footnote with [tab_footnote()] or adding a -#' custom style with [tab_style()]. The function is expressly used in each of -#' those functions' `locations` argument. The 'summary' location is generated by -#' the [summary_rows()] function. +#' `cells_summary()` is used to target the cells in a group summary and it is +#' useful when applying a footnote with [tab_footnote()] or adding a custom +#' style with [tab_style()]. The function is expressly used in each of those +#' functions' `locations` argument. The 'summary' location is generated by +#' [summary_rows()]. #' #' @param groups *Specification of row group IDs* #' @@ -1829,7 +1824,7 @@ cells_summary <- function( #' summary and it is useful when applying a footnote with [tab_footnote()] or #' adding custom styles with [tab_style()]. The function is expressly used in #' each of those functions' `locations` argument. The 'grand_summary' location -#' is generated by the [grand_summary_rows()] function. +#' is generated by [grand_summary_rows()]. #' #' @inheritParams cells_summary #' @@ -1862,7 +1857,7 @@ cells_summary <- function( #' @section Examples: #' #' Use a portion of the [`countrypops`] dataset to create a **gt** table. Add -#' some styling to a grand summary cells with the [tab_style()] function and +#' some styling to a grand summary cells with [tab_style()] and #' `cells_grand_summary()` in the `locations` argument. #' #' ```r @@ -1934,7 +1929,7 @@ cells_grand_summary <- function( #' summary and it is useful when applying a footnote with [tab_footnote()] or #' adding custom styles with [tab_style()]. The function is expressly used in #' each of those functions' `locations` argument. The 'stub_summary' location is -#' generated by the [summary_rows()] function. +#' generated by [summary_rows()]. #' #' @inheritParams cells_row_groups #' @@ -2052,8 +2047,7 @@ cells_stub_summary <- function( #' a grand summary and it is useful when applying a footnote with #' [tab_footnote()] or adding custom styles with [tab_style()]. The function is #' expressly used in each of those functions' `locations` argument. The -#' 'stub_grand_summary' location is generated by the [grand_summary_rows()] -#' function. +#' 'stub_grand_summary' location is generated by [grand_summary_rows()]. #' #' @param rows *Rows to target* #' @@ -2083,8 +2077,8 @@ cells_stub_summary <- function( #' @section Examples: #' #' Use a portion of the [`countrypops`] dataset to create a **gt** table. Add -#' some styling to a grand summary stub cell with the [tab_style()] function and -#' using `cells_stub_grand_summary()` in the `locations` argument. +#' some styling to a grand summary stub cell with [tab_style()] and using +#' `cells_stub_grand_summary()` in the `locations` argument. #' #' ```r #' countrypops |> @@ -2140,10 +2134,10 @@ cells_stub_grand_summary <- function(rows = everything()) { #' `cells_footnotes()` is used to target all footnotes in the #' footer section of the table. This is useful for adding custom styles to the #' footnotes with [tab_style()] (using the `locations` argument). The -#' 'footnotes' location is generated by one or more uses of the [tab_footnote()] -#' function. This location helper function cannot be used for the `locations` -#' argument of [tab_footnote()] and doing so will result in a warning (with no -#' change made to the table). +#' 'footnotes' location is generated by one or more uses of [tab_footnote()]. +#' This location helper function cannot be used for the `locations` argument of +#' `tab_footnote()` and doing so will result in a warning (with no change made +#' to the table). #' #' @return A list object with the classes `cells_footnotes` and #' `location_cells`. @@ -2152,10 +2146,9 @@ cells_stub_grand_summary <- function(rows = everything()) { #' #' Using a subset of the [`sza`] dataset, let's create a **gt** table. We'd like #' to color the `sza` column so that's done with the [data_color()] function. We -#' can add a footnote through the [tab_footnote()] function and we can also -#' style the footnotes section. The styling is done through the use of the -#' [tab_style()] function and to target the footnotes we use `locations = -#' cells_footnotes()`. +#' can add a footnote with [tab_footnote()] and we can also style the +#' footnotes section. The styling is done with [tab_style()] and +#' `locations = cells_footnotes()`. #' #' ```r #' sza |> @@ -2216,10 +2209,7 @@ cells_footnotes <- function() { #' `cells_source_notes()` is used to target all source notes in the #' footer section of the table. This is useful for adding custom styles to the #' source notes with [tab_style()] (using the `locations` argument). The -#' 'source_notes' location is generated by the [tab_source_note()] function. -#' This location helper function cannot be used for the `locations` argument of -#' [tab_footnote()] and doing so will result in a warning (with no change made -#' to the table). +#' 'source_notes' location is generated by [tab_source_note()]. #' #' @return A list object with the classes `cells_source_notes` and #' `location_cells`. @@ -2228,8 +2218,7 @@ cells_footnotes <- function() { #' #' Let's use a subset of the [`gtcars`] dataset to create a **gt** table. Add a #' source note (with [tab_source_note()]) and style the source notes section -#' inside the [tab_style()] call by using the `cells_source_notes()` helper -#' function for the targeting via the `locations` argument. +#' inside [tab_style()] with `locations = cells_source_notes()`. #' #' ```r #' gtcars |> @@ -2274,10 +2263,10 @@ cells_source_notes <- function() { #' #' @description #' -#' This helper function is to be used with the [tab_style()] function, which -#' itself allows for the setting of custom styles to one or more cells. We can -#' also define several styles within a single call of `cell_text()` and -#' [tab_style()] will reliably apply those styles to the targeted element. +#' This helper function can be used with [tab_style()], which itself allows for +#' the setting of custom styles to one or more cells. We can 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 *Text color* #' @@ -2381,10 +2370,10 @@ cells_source_notes <- function() { #' @section Examples: #' #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table -#' (keeping only the `num` and `currency` columns). With the [tab_style()] -#' function (called twice), we'll selectively add style to the values formatted -#' by [fmt_number()]. We do this by using the `cell_text()` helper function in -#' the `style` argument of [tab_style()]. +#' (keeping only the `num` and `currency` columns). With [tab_style()] +#' (called twice), we'll selectively add style to the values formatted with +#' [fmt_number()]. We do this by using `cell_text()` in the `style` argument of +#' `tab_style()`. #' #' ```r #' exibble |> @@ -2558,10 +2547,9 @@ cell_style_to_html.cell_text <- function(style) { #' #' @description #' -#' The `cell_fill()` helper function is to be used with the [tab_style()] -#' function, which itself allows for the setting of custom styles to one or more -#' cells. Specifically, the call to `cell_fill()` should be bound to the -#' `styles` argument of [tab_style()]. +#' `cell_fill()` is to be used with [tab_style()], which itself allows for the +#' setting of custom styles to one or more cells. Specifically, the call to +#' `cell_fill()` should be bound to the `styles` argument of [tab_style()]. #' #' @param color *Cell fill color* #' @@ -2657,13 +2645,12 @@ cell_style_to_html.cell_fill <- function(style) { #' #' @description #' -#' The `cell_borders()` helper function is to be used with the [tab_style()] -#' function, which itself allows for the setting of custom styles to one or more -#' cells. Specifically, the call to `cell_borders()` should be bound to the -#' `styles` argument of [tab_style()]. The `sides` argument is where we define -#' which borders should be modified (e.g., `"left"`, `"right"`, etc.). With that -#' selection, the `color`, `style`, and `weight` of the selected borders can -#' then be modified. +#' `cell_borders()` is to be used with [tab_style()], which itself allows for +#' the setting of custom styles to one or more cells. Specifically, the call to +#' `cell_borders()` should be bound to the `styles` argument of [tab_style()]. +#' The `sides` argument is where we define which borders should be modified +#' (e.g., `"left"`, `"right"`, etc.). With that selection, the `color`, `style`, +#' and `weight` of the selected borders can then be modified. #' #' @param sides *Border sides* #' @@ -2882,9 +2869,8 @@ cell_style_structure <- function(name, obj, subclass = name) { #' #' @description #' -#' The `random_id()` helper function can be used to create a random, -#' character-based ID value argument of variable length (the default is 10 -#' letters). +#' `random_id()` can be used to create a random, character-based ID value +#' argument of variable length (the default is 10 letters). #' #' @param n *Number of letters* #' @@ -2925,9 +2911,9 @@ latex_special_chars <- c( #' #' @description #' -#' Text may contain several characters with special meanings in LaTeX. The -#' `escape_latex()` function will transform a character vector so that it is -#' safe to use within LaTeX tables. +#' Text may contain several characters with special meanings in LaTeX. +#' `escape_latex()` will transform a character vector so that it is safe to use +#' within LaTeX tables. #' #' @param text *LaTeX text* #' @@ -2977,15 +2963,14 @@ escape_latex <- function(text) { #' When working with Rnw (Sweave) files or otherwise writing LaTeX code, #' including a **gt** table can be problematic if we don't have knowledge #' of the LaTeX dependencies. For the most part, these dependencies are the -#' LaTeX packages that are required for rendering a **gt** table. The -#' `gt_latex_dependencies()` function provides an object that can be -#' used to provide the LaTeX in an Rnw file, allowing **gt** tables to work -#' and not yield errors due to missing packages. +#' LaTeX packages that are required for rendering a **gt** table. +#' `gt_latex_dependencies()` provides an object that can be used to provide the +#' LaTeX in an Rnw file, allowing **gt** tables to work and not yield errors +#' due to missing packages. #' #' @details -#' Here is an example Rnw document that shows how the -#' `gt_latex_dependencies()` can be used in conjunction with a **gt** -#' table: +#' Here is an example Rnw document that shows how `gt_latex_dependencies()` +#' can be used in conjunction with a **gt** table: #' #' \preformatted{ #' \%!sweave=knitr @@ -3039,11 +3024,11 @@ gt_latex_dependencies <- function() { #' #' @description #' -#' The `google_font()` helper function can be used wherever a font name should -#' be specified. There are two instances where this helper can be used: the -#' `name` argument in [opt_table_font()] (for setting a table font) and in that -#' 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. +#' `google_font()` can be used wherever a font name should be specified. There +#' are two instances where this helper can be used: the `name` argument in +#' [opt_table_font()] (for setting a table font) and in that of [cell_text()] +#' (used with [tab_style()]). To get a helpful listing of fonts that work well +#' in tables, call [info_google_fonts()]. #' #' @param name *Google Font name* #' @@ -3056,15 +3041,14 @@ gt_latex_dependencies <- function() { #' @section Examples: #' #' Use the [`exibble`] dataset to create a **gt** table of two columns and eight -#' rows. We'll replace missing values with em dashes using the [sub_missing()] -#' function. For text in the `time` column, we will use the font called `"IBM -#' Plex Mono"` which is available in Google Fonts. This is defined in the -#' `google_font()` function call, itself part of a vector that includes fonts -#' returned by the [default_fonts()] function (those fonts will serve as -#' fallbacks just in case the font supplied by Google Fonts is not accessible). -#' In terms of placement, all of this is given to the `font` argument of the -#' [cell_text()] helper function which is itself given to the `style` argument -#' of [tab_style()]. +#' rows. We'll replace missing values with em dashes using [sub_missing()]. +#' For text in the `time` column, we will use the font called `"IBM Plex Mono"` +#' which is available in Google Fonts. This is defined inside the +#' `google_font()` call, itself part of a vector that includes fonts returned by +#' [default_fonts()] (those fonts will serve as fallbacks just in case the font +#' supplied by Google Fonts is not accessible). In terms of placement, all of +#' this is given to the `font` argument of [cell_text()] which is itself given +#' to the `style` argument of [tab_style()]. #' #' ```r #' exibble |> @@ -3156,12 +3140,11 @@ google_font <- function(name) { #' prepending to this vector (i.e., this font stack should be placed after that #' to act as a set of fallbacks). #' -#' This vector of fonts is useful when specifying `font` values in the -#' [cell_text()] function (itself usable in the [tab_style()] and -#' [tab_style_body()] functions). If using [opt_table_font()] (which also has a -#' `font` argument) we probably don't need to specify this vector of fonts since -#' that function prepends font names (this is handled by its `add` option, which -#' is `TRUE` by default). +#' This vector of fonts is useful when specifying `font` values inside +#' [cell_text()] (itself usable in [tab_style()] or [tab_style_body()]). If +#' using [opt_table_font()] (which also has a `font` argument), we probably +#' don't need to specify this vector of fonts since that function prepends font +#' names (this is handled by its `add` option, which is `TRUE` by default). #' #' @return A character vector of font names. #' @@ -3170,10 +3153,9 @@ google_font <- function(name) { #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table #' (keeping only the `char` and `time` columns). Attempting to modify the fonts #' used for the `time` column is much safer if `default_fonts()` is appended to -#' the end of the `font` listing in the `cell_text()` call. What will happen, -#' since the `"Comic Sansa"` and `"Menloa"` fonts shouldn't exist, is that we'll -#' get the first available font from vector of fonts that `default_fonts()` -#' provides. +#' the end of the `font` listing inside `cell_text()`. What will happen, since +#' the `"Comic Sansa"` and `"Menloa"` fonts shouldn't exist, is that we'll get +# the first available font from vector of fonts that `default_fonts()` provides. #' #' ```r #' exibble |> @@ -3214,9 +3196,9 @@ default_fonts <- function() { #' keywords such as `"system-ui"`, `"old-style"`, and `"humanist"` (there are 15 #' in total) representing a themed set of fonts. These sets comprise a font #' family that has been tested to work across a wide range of computer systems. -#' This is useful when specifying `font` values in the [cell_text()] function -#' (itself used in the [tab_style()] function). If using [opt_table_font()] we -#' can invoke this function in its `stack` argument. +#' This is useful when specifying `font` values in [cell_text()] +#' (itself used inside [tab_style()]). If using [opt_table_font()], we can +#' invoke this function in its `stack` argument. #' #' @param name *Name of font stack* #' @@ -3405,9 +3387,9 @@ default_fonts <- function() { #' Use a subset of the [`sp500`] dataset to create a **gt** table with 10 rows. #' For the `date` column and the column labels, let's use a different font stack #' (the `"industrial"` one). The system fonts used in this particular stack are -#' `"Bahnschrift"`, `"DIN Alternate"`, `"Franklin Gothic Medium"`, and `"Nimbus -#' Sans Narrow"` (the generic `"sans-serif-condensed"` and `"sans-serif"` are -#' used if the aforementioned fonts aren't available). +#' `"Bahnschrift"`, `"DIN Alternate"`, `"Franklin Gothic Medium"`, and +#' `"Nimbus Sans Narrow"` (the generic `"sans-serif-condensed"` and `"sans-serif"` +#' are used if the aforementioned fonts aren't available). #' #' ```r #' sp500 |> diff --git a/R/image.R b/R/image.R index cdce64b8fc..4bd4f65af0 100644 --- a/R/image.R +++ b/R/image.R @@ -26,16 +26,15 @@ #' #' @description #' -#' We can flexibly add a web image inside of a table with `web_image()` -#' function. The function provides a convenient way to generate an HTML fragment -#' with an image URL. Because this function is currently HTML-based, it is only -#' useful for HTML table output. To use this function inside of data cells, it -#' is recommended that the [text_transform()] function is used. With that -#' function, we can specify which data cells to target and then include a -#' `web_image()` call within the required user-defined function (for the `fn` -#' argument). If we want to include an image in other places (e.g., in the -#' header, within footnote text, etc.) we need to use `web_image()` within the -#' [html()] helper function. +#' We can flexibly add a web image inside of a table with `web_image()`. +#' The function provides a convenient way to generate an HTML fragment with an +#' image URL. Because this function is currently HTML-based, it is only useful +#' for HTML table output. To use this function inside of data cells, it is +#' recommended to use [text_transform()]. With that function, we can specify +#' which data cells to target and then include a `web_image()` call within the +#' required user-defined function (for the `fn` argument). If we want to include +#' an image in other places (e.g., in the header, within footnote text, etc.) +#' we need to wrap `web_image()` inside [html()]. #' #' By itself, the function creates an HTML image tag, so, the call #' `web_image("http://example.com/image.png")` evaluates to: @@ -70,8 +69,8 @@ #' ``` #' #' Create a tibble that contains heights of an image in pixels (one column as a -#' string, the other as numerical values), then, create a **gt** table. Use the -#' [text_transform()] function to insert the R logo PNG image with the various +#' string, the other as numerical values), then, create a **gt** table. Use +#' [text_transform()] to insert the R logo PNG image with the various #' sizes. #' #' ```r @@ -102,9 +101,9 @@ #' ``` #' #' Create a tibble that contains heights of an image in pixels (one column as a -#' string, the other as numerical values), then, create a **gt** table. Use the -#' [tab_header()] function to insert the **R** logo SVG image once in the title -#' and five times in the subtitle. +#' string, the other as numerical values), then, create a **gt** table. Use +#' [tab_header()] to insert the **R** logo SVG image once in the title and five +#' times in the subtitle. #' #' ```r #' dplyr::tibble( @@ -162,12 +161,12 @@ web_image <- function( #' a table with `local_image()` function. The function provides a convenient way #' to generate an HTML fragment using an on-disk PNG or SVG. Because this #' function is currently HTML-based, it is only useful for HTML table output. To -#' use this function inside of data cells, it is recommended that the -#' [text_transform()] function is used. With that function, we can specify which -#' data cells to target and then include a `local_image()` call within the -#' required user-defined function (for the `fn` argument). If we want to include -#' an image in other places (e.g., in the header, within footnote text, etc.) we -#' need to use `local_image()` within the [html()] helper function. +#' use this function inside of data cells, it is recommended to use +#' [text_transform()] first. With that function, we can specify which data cells +#' to target and then include a `local_image()` call within the required +#' user-defined function (for the `fn` argument). If we want to include an image +#' in other places (e.g., in the header, within footnote text, etc.) we need to +#' use `local_image()` within the [html()] helper function. #' #' By itself, the function creates an HTML image tag with an image URI embedded #' within. We can easily experiment with a local PNG or SVG image that's @@ -193,9 +192,9 @@ web_image <- function( #' @section Examples: #' #' Create a tibble that contains heights of an image in pixels (one column as a -#' string, the other as numerical values), then, create a **gt** table. Use the -#' [text_transform()] function to insert a local test image (PNG) image with the -#' various sizes. +#' string, the other as numerical values), then, create a **gt** table. Use +#' [text_transform()] to insert a local test image (PNG) image with the various +#' sizes. #' #' ```r #' dplyr::tibble( @@ -253,12 +252,12 @@ local_image <- function( #' `ggplot_image()` function. The function provides a convenient way to generate #' an HTML fragment with a `ggplot` object. Because this function is currently #' HTML-based, it is only useful for HTML table output. To use this function -#' inside of data cells, it is recommended that the [text_transform()] function -#' is used. With that function, we can specify which data cells to target and -#' then include a call to `ggplot_image()` within the required user-defined -#' function (for the `fn` argument). If we want to include a plot in other -#' places (e.g., in the header, within footnote text, etc.) we need to use -#' `ggplot_image()` within the [html()] helper function. +#' inside of data cells, it is recommended that [text_transform()] is used. +#' With that function, we can specify which data cells to target and then +#' include a call to `ggplot_image()` within the required user-defined function +#' (for the `fn` argument). If we want to include a plot in other places (e.g., +#' in the header, within footnote text, etc.) we need to use `ggplot_image()` +#' within the [html()] helper function. #' #' By itself, the function creates an HTML image tag with an image URI embedded #' within (a 100 dpi PNG). We can easily experiment with any `ggplot2` plot @@ -352,7 +351,7 @@ ggplot_image <- function( aspect_ratio = 1.0 ) { - rlang::check_installed("ggplot2", "to use the `ggplot_image()` function.") + rlang::check_installed("ggplot2", "to use `ggplot_image()`.") if (is.numeric(height)) { height <- paste0(height, "px") diff --git a/R/info_tables.R b/R/info_tables.R index 0a70b9a6f2..054de61acb 100644 --- a/R/info_tables.R +++ b/R/info_tables.R @@ -26,17 +26,17 @@ #' #' @description #' -#' The [fmt_date()] function lets us format date-based values in a convenient -#' manner using preset styles. The table generated by the `info_date_style()` -#' function provides a quick reference to all styles, with associated format -#' names and example outputs using a fixed date (`2000-02-29`). +#' [fmt_date()] lets us format date-based values in a convenient manner using +#' preset styles. The table generated by `info_date_style()` provides a quick +#' reference to all styles, with associated format names and example outputs +#' using a fixed date (`2000-02-29`). #' #' @return An object of class `gt_tbl`. #' #' @section Examples: #' #' Get a table of info on the different date-formatting styles (which are used -#' by supplying a number code to the [fmt_date()] function). +#' by supplying a number code to [fmt_date()]). #' #' ```r #' info_date_style() @@ -137,17 +137,17 @@ info_date_style <- function() { #' #' @description #' -#' The [fmt_time()] function lets us format time-based values in a convenient -#' manner using preset styles. The table generated by the `info_time_style()` -#' function provides a quick reference to all styles, with associated format -#' names and example outputs using a fixed time (`14:35`). +#' [fmt_time()] lets us format time-based values in a convenient manner using +#' preset styles. The table generated by `info_time_style()` provides a quick +#' reference to all styles, with associated format names and example outputs +#' using a fixed time (`14:35`). #' #' @return An object of class `gt_tbl`. #' #' @section Examples: #' #' Get a table of info on the different time-formatting styles (which are used -#' by supplying a number code to the [fmt_time()] function). +#' by supplying a number code to `fmt_time()`). #' #' ```r #' info_time_style() @@ -240,10 +240,10 @@ info_time_style <- function() { #' #' @description #' -#' The [fmt_currency()] function lets us format numeric values as currencies. -#' The table generated by the [info_currencies()] function provides a quick -#' reference to all the available currencies. The currency identifiers are -#' provided (name, 3-letter currency code, and 3-digit currency code) along with +#' [fmt_currency()] lets us format numeric values as currencies. The table +#' generated by `info_currencies()` provides a quick reference to all the +#' available currencies. The currency identifiers are provided +#' (name, 3-letter currency code, and 3-digit currency code) along with #' the each currency's exponent value (number of digits of the currency #' subunits). A formatted example is provided (based on the value of `49.95`) to #' demonstrate the default formatting of each currency. @@ -568,24 +568,22 @@ info_locales <- function(begins_with = NULL) { #' #' @description #' -#' While the [data_color()] function allows us to flexibly color data cells in -#' our **gt** table, the harder part of this process is discovering and -#' choosing color palettes that are suitable for the table output. We can make -#' this process much easier in two ways: (1) by using the **paletteer** -#' package, which makes a wide range of palettes from various R packages readily -#' available, and (2) calling the `info_paletteer()` function to give us an -#' information table that serves as a quick reference for all of the discrete -#' color palettes available in **paletteer**. +#' While [data_color()] allows us to flexibly color data cells in our **gt** +#' table, the harder part of this process is discovering and choosing color +#' palettes that are suitable for the table output. We can make this process +#' much easier in two ways: (1) by using the **paletteer** package, which makes +#' a wide range of palettes from various R packages readily available, and (2) +#' calling `info_paletteer()` to give us an information table that serves as a +#' quick reference for all of the discrete 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 -#' familiar with the names of the color palette packages (e.g., -#' **RColorBrewer**, **ggthemes**, **wesanderson**), we can narrow down -#' the content of this information table by supplying a vector of such package -#' names to `color_pkgs`. +#' colors), from `paletteer::paletteer_d()`. Once we are familiar with the names +#' of the color palette packages (e.g., **RColorBrewer**, **ggthemes**, +#' **wesanderson**), we can narrow down the content of this information table by +#' supplying a vector of such package names to `color_pkgs`. #' #' Colors from the following color packages (all supported by **paletteer**) #' are shown by default with `info_paletteer()`: @@ -756,10 +754,10 @@ info_google_fonts <- function() { #' #' @description #' -#' The [fmt_flag()] function can be used to render flag icons within -#' body cells that have 2-letter country codes. There are a lot of countries, -#' so, the `info_flags()` function can be helpful in showing all of the valid -#' and supported country codes along with their flag icons. +#' [fmt_flag()] can be used to render flag icons within body cells that have +#' 2-letter country codes. There are a lot of countries, so, calling +#' `info_flags()` can be helpful in showing all of the valid and supported +#' country codes along with their flag icons. #' #' @return An object of class `gt_tbl`. #' @@ -791,7 +789,7 @@ info_flags <- function() { #' #' @description #' -#' The [fmt_icon()] function can be used to render *Font Awesome* icons within +#' [fmt_icon()] can be used to render *Font Awesome* icons within #' body cells that reference the icon names. Further to this, the text #' transformation functions (e.g., [text_case_match()]) allow for the insertion #' of these icons as replacement text (so long as you use the `fa()` function diff --git a/R/modify_columns.R b/R/modify_columns.R index 08d08eedbc..70beeeef2d 100644 --- a/R/modify_columns.R +++ b/R/modify_columns.R @@ -229,10 +229,10 @@ determine_which_character_number <- function( #' 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 +#' States) and `"fr"` for French (France). We can call [info_locales()] for 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`. @@ -611,9 +611,9 @@ cols_width <- function( #' using [gt()], column names effectively become the column labels. While this #' serves as a good first approximation, column names as label defaults aren't #' often as appealing in a **gt** table as the option for custom column labels. -#' The `cols_label()` function provides the flexibility to relabel 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. +#' `cols_label()` provides the flexibility to relabel one or more columns and +#' we even have the option to use [md()] or [html()] for rendering column labels +#' from Markdown or using HTML. #' #' @inheritParams cols_width #' @@ -691,7 +691,7 @@ cols_width <- function( #' #' - `"m/s"` and `"m / s"` both render as `"m/s"` #' - `"m s^-1"` will appear with the `"-1"` exponent intact -#' - `"m /s"` gives the the same result, as `"/"` is equivalent to +#' - `"m /s"` gives the same result, as `"/"` is equivalent to #' `"^-1"` #' - `"E_h"` will render an `"E"` with the `"h"` subscript #' - `"t_i^2.5"` provides a `t` with an `"i"` subscript and a `"2.5"` exponent @@ -770,8 +770,7 @@ cols_width <- function( #' ```r #' metro |> #' dplyr::select(name, lines, passengers, connect_other) |> -#' dplyr::arrange(desc(passengers)) |> -#' dplyr::slice_head(n = 10) |> +#' dplyr::slice_max(passengers, n = 10) |> #' gt() |> #' cols_hide(columns = passengers) |> #' cols_label( @@ -1330,7 +1329,7 @@ cols_label_with <- function( #' #' - `"m/s"` and `"m / s"` both render as `"m/s"` #' - `"m s^-1"` will appear with the `"-1"` exponent intact -#' - `"m /s"` gives the the same result, as `"/"` is equivalent to +#' - `"m /s"` gives the same result, as `"/"` is equivalent to #' `"^-1"` #' - `"E_h"` will render an `"E"` with the `"h"` subscript #' - `"t_i^2.5"` provides a `t` with an `"i"` subscript and a `"2.5"` exponent @@ -1450,8 +1449,7 @@ cols_label_with <- function( #' name, land_area_km2, #' ends_with("2016"), ends_with("2021") #' ) |> -#' dplyr::arrange(desc(population_2021)) |> -#' dplyr::slice_head(n = 10) |> +#' dplyr::slice_max(population_2021, n = 10) |> #' gt(rowname_col = "name") |> #' tab_stubhead(label = "City") |> #' fmt_integer() |> @@ -1728,8 +1726,7 @@ cols_units <- function( #' towny |> #' dplyr::select(name, population_2021, land_area_km2) |> #' dplyr::filter(population_2021 > 100000) |> -#' dplyr::arrange(desc(population_2021)) |> -#' dplyr::slice_head(n = 10) |> +#' dplyr::slice_max(population_2021, n = 10) |> #' gt() |> #' cols_add( #' land_area = land_area_km2 / 2.58998811, @@ -3237,17 +3234,15 @@ cols_move <- function( #' @details #' #' The columns supplied in `columns` must all exist in the table. If you need to -#' place one or columns at the end of the column series, the -#' [cols_move_to_end()] function should be used. More control is offered with -#' the [cols_move()] function, where columns could be placed after a specific -#' column. +#' place one or columns at the end of the column series, [cols_move_to_end()] +#' should be used. More control is offered with [cols_move()], where columns +#' could be placed after a specific column. #' #' @section Examples: #' #' For this example, we'll use a portion of the [`countrypops`] dataset to #' create a simple **gt** table. Let's move the `year` column, which is the -#' middle column, to the start of the column series with the -#' `cols_move_to_start()` function. +#' middle column, to the start of the column series with `cols_move_to_start()`. #' #' ```r #' countrypops |> @@ -3362,17 +3357,15 @@ cols_move_to_start <- function( #' @details #' #' The columns supplied in `columns` must all exist in the table. If you need to -#' place one or columns at the start of the column series, the -#' [cols_move_to_start()] function should be used. More control is offered with -#' the [cols_move()] function, where columns could be placed after a specific -#' column. +#' place one or columns at the start of the column series, [cols_move_to_start()] +#' should be used. More control is offered with [cols_move()], where columns +#' could be placed after a specific column. #' #' @section Examples: #' #' For this example, we'll use a portion of the [`countrypops`] dataset to #' create a simple **gt** table. Let's move the `year` column, which is the -#' middle column, to the end of the column series with the -#' `cols_move_to_end()` function. +#' middle column, to the end of the column series with `cols_move_to_end()`. #' #' ```r #' countrypops |> @@ -3462,12 +3455,12 @@ cols_move_to_end <- function( #' #' @description #' -#' The `cols_hide()` function allows us to hide one or more columns from +#' `cols_hide()` allows us to hide one or more columns from #' appearing in the final output table. While it's possible and often desirable -#' to omit columns from the input table data before introduction to the [gt()] -#' function, there can be cases where the data in certain columns is useful (as -#' a column reference during formatting of other columns) but the final display -#' of those columns is not necessary. +#' to omit columns from the input table data before introduction to [gt()], +#' there can be cases where the data in certain columns is useful (as a column +#' reference during formatting of other columns) but the final display of those +#' columns is not necessary. #' #' @inheritParams cols_align #' @@ -3488,13 +3481,13 @@ cols_move_to_end <- function( #' #' The hiding of columns is internally a rendering directive, so, all columns #' that are 'hidden' are still accessible and useful in any expression provided -#' to a `rows` argument. Furthermore, the `cols_hide()` function (as with many -#' **gt** functions) can be placed anywhere in a pipeline of **gt** function -#' calls (acting as a promise to hide columns when the timing is right). However +#' to a `rows` argument. Furthermore, `cols_hide()` (as with many **gt** +#' functions) can be placed anywhere in a pipeline of **gt** function calls +#' (acting as a promise to hide columns when the timing is right). However, #' there's perhaps greater readability when placing this call closer to the end -#' of such a pipeline. The `cols_hide()` function quietly changes the visible -#' state of a column (much like the [cols_unhide()] function) and doesn't yield -#' warnings or messages when changing the state of already-invisible columns. +#' of such a pipeline. `cols_hide()` quietly changes the visible state of a +#' column (much like [cols_unhide()]) and doesn't yield warnings or messages +#' when changing the state of already-invisible columns. #' #' @section Examples: #' @@ -3517,8 +3510,8 @@ cols_move_to_end <- function( #' Using another [`countrypops`]-based **gt** table, we can use the `population` #' column to provide the conditional placement of footnotes. Then, we'll hide #' that column along with the `country_code_3` column. Note that the order of -#' the `cols_hide()` and [tab_footnote()] statements has no effect on the final -#' display of the table. +#' `cols_hide()` and [tab_footnote()] has no effect on the final display of the +#' table. #' #' ```r #' countrypops |> @@ -3589,11 +3582,10 @@ cols_hide <- function( #' #' @description #' -#' The `cols_unhide()` function allows us to take one or more hidden columns -#' (usually made so via the [cols_hide()] function) and make them visible -#' in the final output table. This may be important in cases where the user -#' obtains a `gt_tbl` object with hidden columns and there is motivation to -#' reveal one or more of those. +#' `cols_unhide()` allows us to take one or more hidden columns (usually done +#' via [cols_hide()]) and make them visible in the final output table. This may +#' be important in cases where the user obtains a `gt_tbl` object with hidden +#' columns and there is motivation to reveal one or more of those. #' #' @inheritParams cols_align #' @@ -3621,8 +3613,8 @@ cols_hide <- function( #' @section Examples: #' #' Let's use a small portion of the [`countrypops`] dataset to create a **gt** -#' table. We'll hide the `country_code_2` and `country_code_3` columns with the -#' [cols_hide()] function. +#' table. We'll hide the `country_code_2` and `country_code_3` columns with +#' [cols_hide()]. #' #' ```r #' tab_1 <- @@ -3641,7 +3633,7 @@ cols_hide <- function( #' #' If the `tab_1` object is provided without the code or source data to #' regenerate it, and, the user wants to reveal otherwise hidden columns then -#' the `cols_unhide()` function becomes useful. +#' `cols_unhide()` becomes useful. #' #' ```r #' tab_1 |> cols_unhide(columns = country_code_2) @@ -3959,13 +3951,13 @@ cols_merge <- function( #' #' @description #' -#' The `cols_merge_uncert()` function is a specialized variant of the -#' [cols_merge()] function. It takes as input a base value column (`col_val`) -#' and either: (1) a single uncertainty column, or (2) two columns representing -#' lower and upper uncertainty bounds. These columns will be essentially merged -#' in a single column (that of `col_val`). What results is a column with values -#' and associated uncertainties (e.g., `12.0 ± 0.1`), and any columns specified -#' in `col_uncert` are hidden from appearing the output table. +#' `cols_merge_uncert()` is a specialized variant of [cols_merge()]. It takes as +#' input a base value column (`col_val`) and either: (1) a single uncertainty +#' column, or (2) two columns representing lower and upper uncertainty bounds. +#' These columns will be essentially merged in a single column (that of +#' `col_val`). What results is a column with values and associated uncertainties +#' (e.g., `12.0 ± 0.1`), and any columns specified in `col_uncert` are hidden +#' from appearing the output table. #' #' @inheritParams cols_align #' @@ -4039,7 +4031,7 @@ cols_merge <- function( #' merged column (e.g., `NA` + `NA` = `NA`) #' #' Any resulting `NA` values in the `col_val` column following the merge -#' operation can be easily formatted using the [sub_missing()] function. +#' operation can be easily formatted using [sub_missing()]. #' #' This function is part of a set of four column-merging functions. The other #' three are the general [cols_merge()] function and the specialized @@ -4148,12 +4140,11 @@ cols_merge_uncert <- function( #' #' @description #' -#' The `cols_merge_range()` function is a specialized variant of the -#' [cols_merge()] function. It operates by taking a two columns that constitute -#' a range of values (`col_begin` and `col_end`) and merges them into a single -#' column. What results is a column containing both values separated by a long -#' dash (e.g., `12.0 — 20.0`). The column specified in `col_end` is dropped from -#' the output table. +#' `cols_merge_range()` is a specialized variant of [cols_merge()]. It operates +#' by taking a two columns that constitute a range of values (`col_begin` and +#' `col_end`) and merges them into a single column. What results is a column +#' containing both values separated by a long dash (e.g., `12.0 — 20.0`). The +#' column specified in `col_end` is dropped from the output table. #' #' @inheritParams cols_align #' @@ -4214,11 +4205,11 @@ cols_merge_uncert <- function( #' #' An optional locale identifier that can be used for applying a `sep` pattern #' specific to a 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. +#' States) and `"fr"` for French (France). We can call [info_locales()] 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`. #' @@ -4237,9 +4228,9 @@ cols_merge_uncert <- function( #' the merged column #' #' Any resulting `NA` values in the `col_begin` column following the merge -#' operation can be easily formatted using the [sub_missing()] function. -#' Separate calls of [sub_missing()] can be used for the `col_begin` and -#' `col_end` columns for finer control of the replacement values. +#' operation can be easily formatted using [sub_missing()]. Separate calls of +#' [sub_missing()] can be used for the `col_begin` and `col_end` columns for +#' finer control of the replacement values. #' #' This function is part of a set of four column-merging functions. The other #' three are the general [cols_merge()] function and the specialized @@ -4391,12 +4382,12 @@ cols_merge_resolver <- function( #' #' @description #' -#' The `cols_merge_n_pct()` function is a specialized variant of the -#' [cols_merge()] function. It operates by taking two columns that constitute -#' both a count (`col_n`) and a fraction of the total population (`col_pct`) and -#' merges them into a single column. What results is a column containing both -#' counts and their associated percentages (e.g., `12 (23.2%)`). The column -#' specified in `col_pct` is dropped from the output table. +#' `cols_merge_n_pct()` is a specialized variant of [cols_merge()], +#' It operates by taking two columns that constitute both a count (`col_n`) and +#' a fraction of the total population (`col_pct`) and merges them into a single +#' column. What results is a column containing both counts and their associated +#' percentages (e.g., `12 (23.2%)`). The column specified in `col_pct` is +#' dropped from the output table. #' #' @inheritParams cols_align #' @@ -4459,7 +4450,7 @@ cols_merge_resolver <- function( #' `"0"` (i.e., no percentage will be shown) #' #' Any resulting `NA` values in the `col_n` column following the merge -#' operation can be easily formatted using the [sub_missing()] function. +#' operation can be easily formatted using [sub_missing()]. #' Separate calls of [sub_missing()] can be used for the `col_n` and #' `col_pct` columns for finer control of the replacement values. It is the #' responsibility of the user to ensure that values are correct in both the diff --git a/R/modify_rows.R b/R/modify_rows.R index c43d4311f0..d126830c1b 100644 --- a/R/modify_rows.R +++ b/R/modify_rows.R @@ -26,13 +26,12 @@ #' #' @description #' -#' We can modify the display order of any row groups in a **gt** object with the -#' `row_group_order()` function. The `groups` argument takes a vector of row -#' group ID values. After this function is invoked, the row groups will adhere -#' to this revised ordering. It isn't necessary to provide all row ID values in -#' `groups`, rather, what is provided will assume the specified ordering at the -#' top of the table and the remaining row groups will follow in their original -#' ordering. +#' We can modify the display order of any row groups in a **gt** object with +#' `row_group_order()`. The `groups` argument takes a vector of row group ID values. +#' After this function is invoked, the row groups will adhere to this revised +#' ordering. It isn't necessary to provide all row ID values in `groups`, rather, +#' what is provided will assume the specified ordering at the top of the table +#' and the remaining row groups will follow in their original ordering. #' #' @inheritParams cols_align #' diff --git a/R/opts.R b/R/opts.R index b63d2c5363..9101a66ac5 100644 --- a/R/opts.R +++ b/R/opts.R @@ -64,8 +64,8 @@ #' @section Examples: #' #' Use `exibble` to create a **gt** table with a number of table parts added. -#' Then, use the `opt_stylize()` function to give the table some additional -#' style (using the `"cyan"` color variation and style number `6`). +#' Then, use `opt_stylize()` to give the table some additional style +#' (using the `"cyan"` color variation and style number `6`). #' #' ```r #' exibble |> @@ -703,7 +703,7 @@ opt_footnote_spec <- function( #' Use the [`exibble`] dataset to create a **gt** table with a number of table #' parts added (using functions like [summary_rows()], [grand_summary_rows()], #' and more). Following that, we'll add row striping to every second row with -#' the `opt_row_striping()` function. +#' `opt_row_striping()`. #' #' ```r #' exibble |> @@ -871,7 +871,7 @@ opt_align_table_header <- function( #' parts added (using functions like [summary_rows()], [grand_summary_rows()], #' and more). Following that, we'll lessen the amount of vertical padding across #' the entire table with `opt_vertical_padding()`. Using a `scale` value of -#' `0.25` (down from the default of `1`) means the the vertical space will be +#' `0.25` (down from the default of `1`) means the vertical space will be #' greatly reduced, resulting in a more compact table. #' #' @@ -963,7 +963,7 @@ opt_vertical_padding <- function( #' parts added (using functions like [summary_rows()], [grand_summary_rows()], #' and more). Following that, we'll increase the amount of horizontal padding #' across the entire table with `opt_horizontal_padding()`. Using a `scale` -#' value of `3` (up from the default of `1`) means the the horizontal space will +#' value of `3` (up from the default of `1`) means the horizontal space will #' be greatly increased, resulting in a more spacious table. #' #' ```r @@ -1182,8 +1182,8 @@ opt_all_caps <- function( #' #' @description #' -#' The `opt_table_lines()` function sets table lines in one of three possible -#' ways: (1) all possible table lines drawn (`"all"`), (2) no table lines at all +#' `opt_table_lines()` sets table lines in one of three possible ways: +#' (1) all possible table lines drawn (`"all"`), (2) no table lines at all #' (`"none"`), and (3) resetting to the default line styles (`"default"`). This #' is great if you want to start off with lots of lines and subtract just a few #' of them with [tab_options()] or [tab_style()]. Or, use it to start with a @@ -1412,8 +1412,8 @@ opt_table_outline <- function( #' #' @description #' -#' The `opt_table_font()` function makes it possible to define fonts used for an -#' entire **gt** table. Any font names supplied in `font` will (by default, with +#' `opt_table_font()` makes it possible to define fonts used for an entire +#' **gt** table. Any font names supplied in `font` will (by default, with #' `add = TRUE`) be placed before the names present in the existing font stack #' (i.e., they will take precedence). You can choose to base the font stack on #' those provided by [system_fonts()] by providing a valid keyword for a themed @@ -1421,7 +1421,7 @@ opt_table_outline <- function( #' #' Take note that you could still have entirely different fonts in specific #' locations of the table. For that you would need to use [tab_style()] or -#' [tab_style_body()] in conjunction with the [cell_text()] helper function. +#' [tab_style_body()] in conjunction with [cell_text()]. #' #' @inheritParams fmt_number #' @@ -1473,9 +1473,9 @@ opt_table_outline <- function( #' #' We have the option to supply one or more font names for the `font` argument. #' They can be enclosed in `c()` or a `list()`. You can generate this list or -#' vector with a combination of font names, and you can freely use the -#' [google_font()], [default_fonts()], and [system_fonts()] functions to help -#' compose your font family. +#' vector with a combination of font names, and you can freely use +#' [google_font()], [default_fonts()], and [system_fonts()] to help compose +#' your font family. #' #' @section Possibilities for the `stack` argument: #' @@ -1483,7 +1483,7 @@ opt_table_outline <- function( #' helper function. That function can be used to generate all or a segment of a #' vector supplied to the `font` argument. However, using the `stack` argument #' with one of the 15 keywords for the font stacks available in -#' [system_fonts()], we could be sure that the typeface class will work across +#' `system_fonts()`, we could be sure that the typeface class will work across #' multiple computer systems. Any of the following keywords can be used: #' #' - `"system-ui"` @@ -1505,10 +1505,10 @@ opt_table_outline <- function( #' @section Examples: #' #' Use a subset of the [`sp500`] dataset to create a small **gt** table. We'll -#' use the [fmt_currency()] function to display a dollar sign for the first row -#' of monetary values. Then, set a larger font size for the table and use the -#' `"Merriweather"` font (from *Google Fonts*, via [google_font()]) with two -#' system font fallbacks (`"Cochin"` and the generic `"serif"`). +#' use [fmt_currency()] to display a dollar sign for the first row of monetary +#' values. Then, set a larger font size for the table and use the `"Merriweather"` +#' font (from *Google Fonts*, via [google_font()]) with two system font +#' fallbacks (`"Cochin"` and the generic `"serif"`). #' #' ```r #' sp500 |> @@ -1650,10 +1650,10 @@ opt_table_font <- function( #' #' @description #' -#' The `opt_css()` function makes it possible to add CSS to a **gt** table. This -#' CSS will be added after the compiled CSS that **gt** generates automatically -#' when the object is transformed to an HTML output table. You can supply `css` -#' as a vector of lines or as a single string. +#' `opt_css()` makes it possible to add CSS to a **gt** table. This CSS will be +#' added after the compiled CSS that **gt** generates automatically when the +#' object is transformed to an HTML output table. You can supply `css` as a +#' vector of lines or as a single string. #' #' @inheritParams fmt_number #' @@ -1687,7 +1687,7 @@ opt_table_font <- function( #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table #' (keeping only the `num` and `currency` columns). Through use of the #' `opt_css()` function, we can insert CSS rulesets as as string. We need to -#' ensure that the the table ID is set explicitly (we've done so here with the +#' ensure that the table ID is set explicitly (we've done so here with the #' ID value of `"one"`, setting it in the [gt()] function). #' #' ```r diff --git a/R/rows_add.R b/R/rows_add.R index f02279224a..ae7b7ccc1c 100644 --- a/R/rows_add.R +++ b/R/rows_add.R @@ -205,10 +205,10 @@ #' }} #' #' All missing values were substituted with an empty string (`""`), and that was -#' done by using the [sub_missing()] function. We removed the top border of the +#' done by using [sub_missing()]. We removed the top border of the #' new rows with a call to [tab_style()], targeting those rows where the row #' labels end with `"end"`. Finally, we get rid of the row labels with the use -#' of the [text_case_when()] function, using a similar strategy of targeting the +#' of [text_case_when()], using a similar strategy of targeting the #' name of the row label. #' #' Another application is starting from nothing (really just the definition of diff --git a/R/shiny.R b/R/shiny.R index 3eea0dc979..585a05de83 100644 --- a/R/shiny.R +++ b/R/shiny.R @@ -30,16 +30,12 @@ #' #' With `render_gt()` we can create a reactive **gt** table that works #' wonderfully once assigned to an output slot (with [gt_output()]). This -#' function is to be used within Shiny's `server()` component. We have some -#' options for controlling the size of the container holding the **gt** table. -#' The `width` and `height` arguments allow for sizing the container, and the -#' `align` argument allows us to align the table within the container (some -#' other fine-grained options for positioning are available in the -#' [tab_options()] function). -#' -#' We need to ensure that we have the **shiny** package installed first. This -#' is easily by using `install.packages("shiny")`. More information on creating -#' Shiny apps can be found on the \href{https://shiny.posit.co}{Shiny website}. +#' function is to be used within [Shiny](https://shiny.posit.co)'s `server()` +#' component. We have some options for controlling the size of the container +#' holding the **gt** table. The `width` and `height` arguments allow for sizing +#' the container, and the `align` argument allows us to align the table within +#' the container (some other fine-grained options for positioning are available +#' in [tab_options()]). #' #' @param expr *Expression* #' @@ -202,18 +198,14 @@ render_gt <- function( #' @description #' #' Using `gt_output()` we can render a reactive **gt** table, a process -#' initiated by using the [render_gt()] function in the `server` component of a -#' Shiny app. The `gt_output()` call is to be used in the Shiny `ui` component, -#' the position and context wherein this call is made determines the where the -#' **gt** table is rendered on the app page. It's important to note that the -#' ID given during the [render_gt()] call is needed as the `outputId` in +#' initiated by using [render_gt()] in the `server` component of a +#' Shiny app. `gt_output()` is to be used in the [Shiny](https://shiny.posit.co) +#' `ui` component, the position and context wherein this call is made determines +#' the where the **gt** table is rendered on the app page. It's important to note +#' that the ID given during [render_gt()] is needed as the `outputId` in #' `gt_output()` (e.g., **server**: `output$ <- render_gt(...)`; **ui**: #' `gt_output(outputId = ""`). #' -#' We need to ensure that we have the **shiny** package installed first. This -#' is easily by using `install.packages("shiny")`. More information on creating -#' Shiny apps can be found on the \href{https://shiny.posit.co}{Shiny website}. -#' #' @param outputId *Shiny output ID* #' #' `scalar` // **required** diff --git a/R/substitution.R b/R/substitution.R index a5aed0f0da..7b3f8ed10a 100644 --- a/R/substitution.R +++ b/R/substitution.R @@ -27,9 +27,9 @@ #' @description #' #' Wherever there is missing data (i.e., `NA` values) customizable content may -#' present better than the standard `NA` text that would otherwise appear. The -#' `sub_missing()` function allows for this replacement through its -#' `missing_text` argument (where an em dash serves as the default). +#' present better than the standard `NA` text that would otherwise appear. +#' `sub_missing()` allows for this replacement through its `missing_text` +#' argument (where an em dash serves as the default). #' #' @inheritParams fmt_number #' @@ -61,8 +61,8 @@ #' `scalar` // *default:* `"---"` #' #' The text to be used in place of `NA` values in the rendered table. We can -#' optionally use the [md()] and [html()] functions to style the text as -#' Markdown or to retain HTML elements in the text. +#' optionally use [md()] or [html()] to style the text as Markdown or to +#' retain HTML elements in the text. #' #' @return An object of class `gt_tbl`. #' @@ -212,9 +212,9 @@ fmt_missing <- function( ) { cli::cli_warn(c( - "Since gt v0.6.0 the `fmt_missing()` function is deprecated and will + "Since gt v0.6.0 {.fn fmt_missing} is deprecated and will soon be removed.", - "*" = "Use the `sub_missing()` function instead." + "i" = "Use {.fn sub_missing} instead." ), .frequency = "regularly", .frequency_id = "fmt_missing_fn_deprecation" @@ -233,8 +233,8 @@ fmt_missing <- function( #' @description #' #' Wherever there is numerical data that are zero in value, replacement text may -#' be better for explanatory purposes. The `sub_zero()` function allows for this -#' replacement through its `zero_text` argument. +#' be better for explanatory purposes. `sub_zero()` allows for this replacement +#' through its `zero_text` argument. #' #' @inheritParams fmt_number #' @@ -266,7 +266,7 @@ fmt_missing <- function( #' `scalar` // *default:* `"nil"` #' #' The text to be used in place of zero values in the rendered table. We can -#' optionally use the [md()] and [html()] functions to style the text as +#' optionally use [md()] or [html()] to style the text as #' Markdown or to retain HTML elements in the text. #' #' @return An object of class `gt_tbl`. @@ -387,14 +387,13 @@ sub_zero <- function( #' @description #' #' Wherever there is numerical data that are very small in value, replacement -#' text may be better for explanatory purposes. The `sub_small_vals()` function -#' allows for this replacement through specification of a `threshold`, a -#' `small_pattern`, and the sign of the values to be considered. The -#' substitution will occur for those values found to be between `0` and the -#' threshold value. This is possible for small positive and small negative -#' values (this can be explicitly set by the `sign` option). Note that the -#' interval does not include the `0` or the `threshold` value. Should you need -#' to include zero values, use the [sub_zero()] function. +#' text may be better for explanatory purposes. `sub_small_vals()` allows for +#' this replacement through specification of a `threshold`, a `small_pattern`, +#' and the sign of the values to be considered. The substitution will occur for +#' those values found to be between `0` and the threshold value. This is +#' possible for small positive and small negative values (this can be explicitly +#' set by the `sign` option). Note that the interval does not include the `0` or +#' the `threshold` value. Should you need to include zero values, use [sub_zero()]. #' #' @inheritParams fmt_number #' @@ -667,10 +666,9 @@ sub_small_vals <- function( #' @description #' #' Wherever there are numerical data that are very large in value, replacement -#' text may be better for explanatory purposes. The `sub_large_vals()` function -#' allows for this replacement through specification of a `threshold`, a -#' `large_pattern`, and the sign (positive or negative) of the values to be -#' considered. +#' text may be better for explanatory purposes. `sub_large_vals()` allows for +#' this replacement through specification of a `threshold`, a `large_pattern`, +#' and the sign (positive or negative) of the values to be considered. #' #' @inheritParams fmt_number #' @@ -954,9 +952,9 @@ check_sub_fn_sign <- function(sign, call = rlang::caller_env()) { #' #' @description #' -#' Should you need to replace specific cell values with custom text, the -#' `sub_values()` function can be good choice. We can target cells for -#' replacement though value, regex, and custom matching rules. +#' Should you need to replace specific cell values with custom text, +#' `sub_values()` can be good choice. We can target cells for replacement +#' through value, regex, and custom matching rules. #' #' @inheritParams fmt_number #' diff --git a/R/summary_rows.R b/R/summary_rows.R index 03234ea37a..a6ef60a621 100644 --- a/R/summary_rows.R +++ b/R/summary_rows.R @@ -272,16 +272,16 @@ #' #' @section Extraction of summary rows: #' -#' Should we need to obtain the summary data for external purposes, the -#' [extract_summary()] function can be used with a `gt_tbl` object where summary -#' rows were added via `summary_rows()` or [grand_summary_rows()]. +#' Should we need to obtain the summary data for external purposes, +#' [extract_summary()] can be used with a `gt_tbl` object where summary rows +#' were added via `summary_rows()` or [grand_summary_rows()]. #' #' @section Examples: #' #' Use a modified version of [`sp500`] dataset to create a **gt** table with row #' groups and row labels. Create the summary rows labeled `min`, `max`, and -#' `avg` by row group (where each each row group is a week number) with the -#' `summary_rows()` function. +#' `avg` by row group (where each each row group is a week number) with +#' `summary_rows()`. #' #' ```r #' sp500 |> @@ -452,9 +452,10 @@ summary_rows <- function( !!rowname_col_private := rep("", nrow(data$`_data`)) ) data$`_data` <- - dplyr::select( + dplyr::relocate( data$`_data`, - dplyr::everything(), dplyr::all_of(rowname_col_private) + dplyr::all_of(rowname_col_private), + .after = dplyr::last_col() ) # Get the `stub_df` object from `data` @@ -688,15 +689,15 @@ summary_rows <- function( #' #' @section Extraction of summary rows: #' -#' Should we need to obtain the summary data for external purposes, the -#' [extract_summary()] function can be used with a `gt_tbl` object where summary -#' rows were added via `grand_summary_rows()` or [summary_rows()]. +#' Should we need to obtain the summary data for external purposes, +#' [extract_summary()] can be used with a `gt_tbl` object where summary rows +#' were added via `grand_summary_rows()` or [summary_rows()]. #' #' @section Examples: #' #' Use a modified version of the [`sp500`] dataset to create a **gt** table with #' row groups and row labels. Create the grand summary rows `min`, `max`, and -#' `avg` for the table with the `grand_summary_rows()` function. +#' `avg` for the table with `grand_summary_rows()`. #' #' ```r #' sp500 |> diff --git a/R/tab_create_modify.R b/R/tab_create_modify.R index 6450aeca82..d1396ce6ec 100644 --- a/R/tab_create_modify.R +++ b/R/tab_create_modify.R @@ -27,7 +27,7 @@ #' @description #' #' We can add a table header to the **gt** table with a title and even a -#' subtitle using the `tab_header()` function. A table header is an optional +#' subtitle using `tab_header()`. A table header is an optional #' table part that is positioned just above the column labels table part. We #' have the flexibility to use Markdown or HTML formatting for the header's #' title and subtitle with the [md()] and [html()] helper functions. @@ -46,8 +46,8 @@ #' #' `scalar` // *default:* `NULL` (`optional`) #' -#' Text to be used in the table subtitle. We can elect to use the [md()] and -#' [html()] helper functions to style the text as Markdown or to retain HTML +#' Text to be used in the table subtitle. We can elect to use [md()] or +#' [html()] helper functions to style the text as Markdown or to retain HTML #' elements in the text. #' #' @param preheader *RTF preheader text* @@ -63,9 +63,8 @@ #' #' Let's use a small portion of the [`gtcars`] dataset to create a **gt** table. #' A header part can be added to the table with the `tab_header()` function. -#' We'll add a title and the optional subtitle as well. With the [md()] helper -#' function, we can make sure the Markdown formatting is interpreted and -#' transformed. +#' We'll add a title and the optional subtitle as well. With [md()], we can +#' make sure the Markdown formatting is interpreted and transformed. #' #' ```r #' gtcars |> @@ -112,8 +111,8 @@ #' `r man_get_image_tag(file = "man_tab_header_2.png")` #' }} #' -#' If using HTML but doing something far simpler, we can use the [html()] helper -#' function to declare that the text provided is HTML. +#' If using HTML but doing something far simpler, we can wrap our title or +#' subtitle inside [html()] to declare that the text provided is HTML. #' #' ```r #' gtcars |> @@ -132,9 +131,9 @@ #' #' Sometimes, aligning the heading elements to the left can improve the #' presentation of a table. Here, we use the [`nuclides`] dataset to generate a -#' display of natural abundance values for several stable isotopes. The -#' [opt_align_table_header()] function is used with `align = "left"` to make it -#' so the title and subtitle are left aligned in the header area. +#' display of natural abundance values for several stable isotopes. +#' [opt_align_table_header()] is used with `align = "left"` to make it so the +#' title and subtitle are left aligned in the header area. #' #' ```r #' nuclides |> @@ -216,18 +215,17 @@ tab_header <- function( #' #' @description #' -#' With the `tab_spanner()` function, you can insert a spanner in the column -#' labels part of a **gt** table. This part of the table contains, at a minimum, -#' column labels and, optionally, an unlimited number of levels for spanners. A -#' spanner will occupy space over any number of contiguous column labels and it -#' will have an associated label and ID value. This function allows for mapping -#' to be defined by column names, existing spanner ID values, or a mixture of -#' both. The spanners are placed in the order of calling `tab_spanner()` so if a -#' later call uses the same columns in its definition (or even a subset) as the -#' first invocation, the second spanner will be overlaid atop the first. Options -#' exist for forcibly inserting a spanner underneath other (with `level` as -#' space permits) and with `replace`, which allows for full or partial spanner -#' replacement. +#' With `tab_spanner()`, you can insert a spanner in the column labels part of a +#' **gt** table. This part of the table contains, at a minimum, column labels +#' and, optionally, an unlimited number of levels for spanners. A spanner will +#' occupy space over any number of contiguous column labels and it will have an +#' associated label and ID value. This function allows for mapping to be defined +#' by column names, existing spanner ID values, or a mixture of both. The +#' spanners are placed in the order of calling `tab_spanner()` so if a later call +#' uses the same columns in its definition (or even a subset) as the first +#' invocation, the second spanner will be overlaid atop the first. Options exist +#' for forcibly inserting a spanner underneath other (with `level` as space +#' permits) and with `replace`, which allows for full or partial spanner replacement. #' #' @inheritParams fmt_number #' @@ -235,8 +233,8 @@ tab_header <- function( #' #' `scalar` // **required** #' -#' The text to use for the spanner label. We can optionally use the [md()] and -#' [html()] functions to style the text as Markdown or to retain HTML elements +#' The text to use for the spanner label. We can optionally use [md()] or +#' [html()] to style the text as Markdown or to retain HTML elements #' in the text. #' #' @param columns *Columns to target* @@ -607,11 +605,10 @@ tab_header <- function( #' ```r #' towny |> #' dplyr::select( -#' name, ends_with("2001"), ends_with("2006"), matches("2001_2006") +#' name, ends_with(c("2001", "2006)), matches("2001_2006") #' ) |> #' dplyr::filter(population_2001 > 100000) |> -#' dplyr::arrange(desc(pop_change_2001_2006_pct)) |> -#' dplyr::slice_head(n = 10) |> +#' dplyr::slice_max(pop_change_2001_2006_pct, n = 10) |> #' gt() |> #' fmt_integer() |> #' fmt_percent(columns = matches("change"), decimals = 1) |> @@ -852,18 +849,17 @@ resolve_spanned_column_names <- function( #' #' @description #' -#' The `tab_spanner_delim()` function can take specially-crafted column names -#' and generate one or more spanners (and revise column labels at the same -#' time). This is done by splitting the column name by the specified delimiter -#' text (`delim`) and placing the fragments from top to bottom (i.e., -#' higher-level spanners to the column labels) or vice versa. Furthermore, -#' neighboring text fragments on different spanner levels that have the same -#' text will be coalesced together. For instance, having the three side-by-side -#' column names `rating_1`, `rating_2`, and `rating_3` will (in the default case -#' at least) result in a spanner with the label `"rating"` above columns with -#' the labels `"1"`, `"2"`, and `"3"`. There are many options in -#' `cols_spanner_delim()` to slice and dice delimited column names in different -#' ways: +#' `tab_spanner_delim()` can take specially-crafted column names and generate +#' one or more spanners (and revise column labels at the same time). This is +#' done by splitting the column name by the specified delimiter text (`delim`) +#' and placing the fragments from top to bottom (i.e., higher-level spanners to +#' the column labels) or vice versa. Furthermore, neighboring text fragments on +#' different spanner levels that have the same text will be coalesced together. +#' For instance, having the three side-by-side column names `rating_1`, +#' `rating_2`, and `rating_3` will (in the default case at least) result in a +#' spanner with the label `"rating"` above columns with the labels `"1"`, `"2"`, +#' and `"3"`. There are many options in `cols_spanner_delim()` to slice and dice +#' delimited column names in different ways: #' #' - delimiter text: choose the delimiter text to use for the fragmentation of #' column names into spanners with the `delim` argument @@ -970,13 +966,13 @@ resolve_spanned_column_names <- function( #' @section Examples: #' #' With a subset of the [`towny`] dataset, we can create a **gt** table and then -#' use the `tab_spanner_delim()` function to automatically generate column -#' spanner labels. In this case we have some column names in the form -#' `population_`. The underscore character is the delimiter that separates -#' a common word `"population"` and a year value. In this default way of -#' splitting, fragments to the right are lowest (really they become new column -#' labels) and moving left we get spanners. Let's have a look at how -#' `tab_spanner_delim()` handles these column names: +#' use `tab_spanner_delim()` to automatically generate column spanner labels. +#' In this case we have some column names in the form `population_`. +#' The underscore character is the delimiter that separates a common word +#' `"population"` and a year value. In this default way of splitting, fragments +#' to the right are lowest (really they become new column labels) and moving +#' left we get spanners. Let's have a look at how `tab_spanner_delim()` handles +#' these column names: #' #' ```r #' towny_subset_gt <- @@ -1034,8 +1030,7 @@ resolve_spanned_column_names <- function( #' #' ```r #' towny |> -#' dplyr::arrange(desc(population_2021)) |> -#' dplyr::slice_head(n = 5) |> +#' dplyr::slice_max(population_2021, n = 5) |> #' dplyr::select(name, ends_with("pct")) |> #' dplyr::rename_with( #' .fn = function(x) { @@ -1441,11 +1436,11 @@ str_split_across <- function( #' #' @description #' -#' We can create a row group from a collection of rows with the -#' `tab_row_group()` function. This requires specification of the rows to be -#' included, either by supplying row labels, row indices, or through use of a -#' select helper function like [starts_with()]. To modify the order of row -#' groups, we can use the [row_group_order()] function. +#' We can create a row group from a collection of rows with `tab_row_group()`. +#' This requires specification of the rows to be included, either by supplying +#' row labels, row indices, or through use of a select helper function like +#' [starts_with()]. To modify the order of row groups, we can use +#' [row_group_order()]. #' #' To set a default row group label for any rows not formally placed in a row #' group, we can use a separate call to `tab_options(row_group.default_label = @@ -1459,9 +1454,8 @@ str_split_across <- function( #' #' `scalar` // **required** #' -#' The text to use for the row group label. We can optionally use the [md()] -#' and [html()] functions to style the text as Markdown or to retain HTML -#' elements in the text. +#' The text to use for the row group label. We can optionally use [md()] or +#' [html()] to style the text as Markdown or to retain HTML elements in the text. #' #' @param rows *Rows to target* #' @@ -1507,9 +1501,9 @@ str_split_across <- function( #' #' Using a subset of the [`gtcars`] dataset, let's create a simple **gt** table #' with row labels (from the `model` column) inside of a stub. This eight-row -#' table begins with no row groups at all but with a single use of the -#' `tab_row_group()` function, we can specify a row group that will contain any -#' rows where the car model begins with a number. +#' table begins with no row groups at all but with a single use of +#' `tab_row_group()`, we can specify a row group that will contain any rows +#' where the car model begins with a number. #' #' ```r #' gtcars |> @@ -1531,8 +1525,7 @@ str_split_across <- function( #' doesn't display a label at all. Rather, it is set off from the other group #' with a double line. This may be a preferable way to display the arrangement #' of one distinct group and an 'others' or default group. If that's the case -#' but you'd like the order reversed, the [row_group_order()] function can be -#' used for that. +#' but you'd like the order reversed, you can use [row_group_order()]. #' #' ```r #' gtcars |> @@ -1717,7 +1710,7 @@ tab_row_group <- function( # Get the `stub_df` data frame from `data` stub_df <- dt_stub_df_get(data = data) - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = !!row_expr, @@ -1756,14 +1749,13 @@ tab_row_group <- function( #' #' @description #' -#' We can add a label to the stubhead of a **gt** table with the -#' `tab_stubhead()` function. The stubhead is the lone part of the table that is -#' positioned left of the column labels, and above the stub. If a stub does not -#' exist, then there is no stubhead (so no visible change will be made when -#' using this function in that case). We have the flexibility to use Markdown -#' formatting for the stubhead label via the [md()] helper function. -#' Furthermore, if the table is intended for HTML output, we can use HTML inside -#' of [html()] for the stubhead label. +#' We can add a label to the stubhead of a **gt** table with `tab_stubhead()`. +#' The stubhead is the lone part of the table that is positioned left of the +#' column labels, and above the stub. If a stub does not exist, then there is no +#' stubhead (so no visible change will be made when using this function in that +#' case). We have the flexibility to use Markdown formatting for the stubhead +#' label via the [md()] helper function. Furthermore, if the table is intended +#' for HTML output, we can use HTML inside of [html()] for the stubhead label. #' #' @inheritParams fmt_number #' @@ -1771,9 +1763,8 @@ tab_row_group <- function( #' #' `scalar` // **required** #' -#' The text to be used as the stubhead label. We can optionally use the [md()] -#' and [html()] functions to style the text as Markdown or to retain HTML -#' elements in the text. +#' The text to be used as the stubhead label. We can optionally use [md()] or +#' [html()] to style the text as Markdown or to retain HTML elements in the text. #' #' @return An object of class `gt_tbl`. #' @@ -1782,7 +1773,7 @@ tab_row_group <- function( #' Using a small subset of the [`gtcars`] dataset, we can create a **gt** table #' with row labels. Since we have row labels in the stub (via use of #' `rowname_col = "model"` in the [gt()] function call) we have a stubhead, so, -#' let's add a stubhead label (`"car"`) with the `tab_stubhead()` function to +#' let's add a stubhead label (`"car"`) with `tab_stubhead()` to #' describe what's in the stub. #' #' ```r @@ -1843,10 +1834,10 @@ tab_row_group <- function( #' `r man_get_image_tag(file = "man_tab_stubhead_3.png")` #' }} #' -#' The stubhead cell and its text can be styled using [tab_style()] along with -#' the [cells_stubhead()] function. In this example, using the [`reactions`] -#' dataset, we style the stubhead label so that it is vertically centered with -#' text that is highly emboldened. +#' The stubhead cell and its text can be styled using [tab_style()] with +#' [cells_stubhead()]. In this example, using the [`reactions`] dataset, we +#' style the stubhead label so that it is vertically centered with text that is +#' highly emboldened. #' #' ```r #' reactions |> @@ -1897,7 +1888,7 @@ tab_stubhead <- function( #' @description #' #' Indentation of row labels is an effective way for establishing structure in a -#' table stub. The `tab_stub_indent()` function allows for fine control over +#' table stub. `tab_stub_indent()` allows for fine control over #' row label indentation in the stub. We can use an explicit definition of an #' indentation level (with a number between `0` and `5`), or, employ an #' indentation directive using keywords (`"increase"`/`"decrease"`). @@ -1930,16 +1921,15 @@ tab_stubhead <- function( #' #' @section Compatibility of arguments with the `from_column()` helper function: #' -#' The [from_column()] helper function can be used with the `indent` argument -#' of `tab_stub_indent()` to obtain varying parameter values from a specified -#' column within the table. This means that each row label could be indented a -#' little bit differently. +#' [from_column()] can be used with the `indent` argument of `tab_stub_indent()` +#' to obtain varying parameter values from a specified column within the table. +#' This means that each row label could be indented a little bit differently. #' #' Please note that for this argument (`indent`), a [from_column()] call needs #' to reference a column that has data of the `numeric` or `integer` type. -#' Additional columns for parameter values can be generated with the -#' [cols_add()] function (if not already present). Columns that contain -#' parameter data can also be hidden from final display with [cols_hide()]. +#' Additional columns for parameter values can be generated with [cols_add()] +#' (if not already present). Columns that contain parameter data can also be +#' hidden from final display with [cols_hide()]. #' #' @section Examples: #' @@ -1968,10 +1958,9 @@ tab_stubhead <- function( #' }} #' #' Let's use a summarized version of the [`pizzaplace`] dataset to create a -#' another **gt** table with row groups and row labels. With the -#' [summary_rows()] function, we'll generate summary rows at the top of each row -#' group. Using `tab_stub_indent()` we can add indentation to the row labels in -#' the stub. +#' another **gt** table with row groups and row labels. With [summary_rows()], +#' we'll generate summary rows at the top of each row group. Using +#' `tab_stub_indent()` we can add indentation to the row labels in the stub. #' #' ```r #' pizzaplace |> @@ -2013,9 +2002,9 @@ tab_stubhead <- function( #' variations of a row label are mutated to eliminate the common leading text #' (replacing it with `"..."`). At the same time, the indentation for those rows #' is set to `4` in the `indent` column (value is `0` otherwise). The -#' `tab_stub_indent()` statement uses the [from_column()] helper function, which -#' passes values from the `indent` column to the namesake argument. We hide the -#' `indent` column from view by use of the [cols_hide()] function. +#' `tab_stub_indent()` statement uses [from_column()], which passes values from +#' the `indent` column to the namesake argument. We hide the `indent` column +#' from view by use of [cols_hide()]. #' #' ```r #' constants |> @@ -2085,7 +2074,7 @@ tab_stub_indent <- function( # Get the `stub_df` data frame from `data` stub_df <- dt_stub_df_get(data = data) - # Resolve the row numbers using the `resolve_vars` function + # Resolve the row numbers using `resolve_vars()` resolved_rows_idx <- resolve_rows_i( expr = !!row_expr, @@ -2201,8 +2190,8 @@ tab_stub_indent <- function( #' #' @description #' -#' The `tab_footnote()` function can make it a painless process to add a -#' footnote to a **gt** table. There are commonly two components to a footnote: +#' `tab_footnote()` can make it a painless process to add a footnote to a +#' **gt** table. There are commonly two components to a footnote: #' (1) a footnote mark that is attached to the targeted cell content, and (2) #' the footnote text itself that is placed in the table's footer area. Each unit #' of footnote text in the footer is linked to an element of text or otherwise @@ -2236,9 +2225,8 @@ tab_stub_indent <- function( #' #' `scalar` // **required** #' -#' The text to be used in the footnote. We can optionally use the [md()] and -#' [html()] functions to style the text as Markdown or to retain HTML elements -#' in the footnote text. +#' The text to be used in the footnote. We can optionally use [md()] or [html()] +#' to style the text as Markdown or to retain HTML elements in the footnote text. #' #' @param locations *Locations to target* #' @@ -2271,8 +2259,8 @@ tab_stub_indent <- function( #' #' There are several options for controlling the formatting of the footnotes, #' their marks, and related typesetting in the footer. All of these options are -#' available within the [tab_options()] function and a subset of these are -#' exposed in their own `opt_*()` functions. +#' available within [tab_options()] and a subset of these are exposed in their +#' own `opt_*()` functions. #' #' ## Choosing the footnote marks #' @@ -2341,9 +2329,9 @@ tab_stub_indent <- function( #' #' Using a subset of the [`sza`] dataset, let's create a new **gt** table. The #' body cells in the `sza` column will receive background color fills according -#' to their data values (with the [data_color()] function). After that, the use -#' of `tab_footnote()` lets us add a footnote to the `sza` column label -#' (explaining what the color gradient signifies). +#' to their data values (with [data_color()]). After that, the use of +#' `tab_footnote()` lets us add a footnote to the `sza` column label (explaining +#' what the color gradient signifies). #' #' ```r #' sza |> @@ -2913,8 +2901,8 @@ set_footnote.cells_footnotes <- function( #' #' `scalar` // **required** #' -#' Text to be used in the source note. We can optionally use the [md()] and -#' [html()] functions to style the text as Markdown or to retain HTML elements +#' Text to be used in the source note. We can optionally use [md()] and +#' [html()] to style the text as Markdown or to retain HTML elements #' in the text. #' #' @return An object of class `gt_tbl`. @@ -2922,7 +2910,7 @@ set_footnote.cells_footnotes <- function( #' @section Examples: #' #' With three columns from the [`gtcars`] dataset, let's create a **gt** table. -#' We can use the `tab_source_note()` function to add a source note to the table +#' We can use `tab_source_note()` to add a source note to the table #' footer. Here we are citing the data source but this function can be used for #' any text you'd prefer to display in the footer section. #' @@ -2984,8 +2972,8 @@ tab_source_note <- function( #' @section Examples: #' #' With three columns from the [`gtcars`] dataset, let's create a **gt** table. -#' First, we'll add a header part with the [tab_header()] function. After that, -#' a caption is added through use of `tab_caption()`. +#' First, we'll add a header part with [tab_header()]. After that, a caption is +#' added with `tab_caption()`. #' #' ```r #' gtcars |> @@ -3030,7 +3018,7 @@ tab_caption <- function( #' #' @description #' -#' With the `tab_style()` function we can [target specific cells][location-helper] +#' With `tab_style()` we can [target specific cells][location-helper] #' and apply styles to them. This is best done in conjunction with the helper #' functions [cell_text()], [cell_fill()], and [cell_borders()]. Currently, this #' function is focused on the application of styles for HTML output only @@ -3081,13 +3069,12 @@ tab_caption <- function( #' #' @section Using `from_column()` with `cell_*()` styling functions: #' -#' The [from_column()] helper function can be used with certain arguments of -#' [cell_fill()] and [cell_text()]; this allows you to get parameter values from -#' a specified column within the table. This means that body cells targeted for -#' styling could be formatted a little bit differently, using options taken from -#' a column. For [cell_fill()], we can use [from_column()] for its `color` -#' argument. The [cell_text()] function allows the use of [from_column()] in the -#' following arguments: +#' [from_column()] can be used with certain arguments of [cell_fill()] and +#' [cell_text()]; this allows you to get parameter values from a specified +#' column within the table. This means that body cells targeted for styling +#' could be formatted a little bit differently, using options taken from a +#' column. For [cell_fill()], we can use [from_column()] for its `color` +#' argument. [cell_text()] allows the use of [from_column()] in the following arguments: #' #' - `color` #' - `size` @@ -3104,11 +3091,10 @@ tab_caption <- function( #' Please note that for all of the aforementioned arguments, a [from_column()] #' call needs to reference a column that has data of the correct type (this is #' different for each argument). Additional columns for parameter values can be -#' generated with the [cols_add()] function (if not already present). Columns -#' that contain parameter data can also be hidden from final display with -#' [cols_hide()]. +#' generated with [cols_add()] (if not already present). Columns that contain +#' parameter data can also be hidden from final display with [cols_hide()]. #' -#' Importantly, a call of `tab_style()` with any use of [from_column()] within +#' Importantly, a `tab_style()` call with any use of [from_column()] within #' styling expressions must only use [cells_body()] within `locations`. This is #' because we cannot map multiple options taken from a column onto other #' locations. @@ -3116,13 +3102,13 @@ tab_caption <- function( #' @section Examples: #' #' Let's use the [`exibble`] dataset to create a simple, two-column **gt** table -#' (keeping only the `num` and `currency` columns). With the [tab_style()] -#' function (called twice), we'll selectively add style to the values formatted -#' by [fmt_number()]. In the `style` argument of each `tab_style()` call, we -#' can define multiple types of styling with the [cell_fill()] and [cell_text()] -#' helper functions (enclosed in a list). The cells to be targeted for styling -#' require the use of helper functions like [cells_body()], which is used here -#' with different columns and rows being targeted. +#' (keeping only the `num` and `currency` columns). With [tab_style()] +#' (called twice), we'll selectively add style to the values formatted by +#' [fmt_number()]. In the `style` argument of each `tab_style()` call, we can +#' define multiple types of styling with [cell_fill()] and [cell_text()] +#' (enclosed in a list). The cells to be targeted for styling require the use of +#' helpers like [cells_body()], which is used here with different columns and +#' rows being targeted. #' #' ```r #' exibble |> @@ -3186,8 +3172,8 @@ tab_caption <- function( #' }} #' #' With another two-column table based on the [`exibble`] dataset, let's create -#' a **gt** table. First, we'll replace missing values with the [sub_missing()] -#' function. Next, we'll add styling to the `char` column. This styling will be +#' a **gt** table. First, we'll replace missing values with [sub_missing()]. +#' Next, we'll add styling to the `char` column. This styling will be #' HTML-specific and it will involve (all within a list): (1) a [cell_fill()] #' call (to set a `"lightcyan"` background), and (2) a string containing a CSS #' style declaration (`"font-variant: small-caps;"`). @@ -3306,13 +3292,13 @@ tab_caption <- function( #' `r man_get_image_tag(file = "man_tab_style_4.png")` #' }} #' -#' The [from_column()] helper function can be used to get values from a column. -#' We'll use it in the next example, which begins with a table having a color -#' name column and a column with the associated hexadecimal color code. To show -#' the color in a separate column, we first create one with [cols_add()] ( -#' ensuring that missing values are replaced with `""` via [sub_missing()]). -#' Then, `tab_style()` is used to style that column, calling [from_column()] in -#' the `color` argument of the [cell_fill()] function. +#' [from_column()] can be used to get values from a column. We'll use it in the +#' next example, which begins with a table having a color name column and a +#' column with the associated hexadecimal color code. To show the color in a +#' separate column, we first create one with [cols_add()] (ensuring that missing +#' values are replaced with `""` via [sub_missing()]). Then, `tab_style()` is +#' used to style that column, using [color = from_column()][from_column()] +#' within [cell_fill()]. #' #' ```r #' dplyr::tibble( @@ -3345,16 +3331,16 @@ tab_caption <- function( #' `r man_get_image_tag(file = "man_tab_style_5.png")` #' }} #' -#' The [cell_text()] function also allows the use of [from_column()] for many of -#' its arguments. Let's take a small portion of data from [`sp500`] and add an -#' up or down arrow based on the values in the `open` and `close` columns. -#' Within [cols_add()] we can create a new column (`dir`) with an expression to -#' get either `"red"` or `"green"` text from a comparison of the `open` and -#' `close` values. These values are transformed to up or down arrows with the -#' [text_case_match()] function, using **fontawesome** icons in the end. -#' However, the text values are still present and can be used by [cell_text()] -#' within `tab_style()`. The [from_column()] helper function makes it possible -#' to use the text in the cells of the `dir` column as `color` input values. +#' [cell_text()] also allows the use of [from_column()] for many ofits arguments. +#' Let's take a small portion of data from [`sp500`] and add an up or down arrow +#' based on the values in the `open` and `close` columns. Within [cols_add()] we +#' can create a new column (`dir`) with an expression to get either `"red"` or +#' `"green"` text from a comparison of the `open` and `close` values. These +#' values are transformed to up or down arrows with [text_case_match()], using +#' **fontawesome** icons in the end. However, the text values are still present +#' and can be used by [cell_text()] within `tab_style()`. [from_column()] makes +#' it possible to use the text in the cells of the `dir` column as `color` input +#' values. #' #' ```r #' sp500 |> @@ -3404,8 +3390,6 @@ tab_style <- function( # Resolve into a list of locations locations <- as_locations(locations) - # Keep original value for future error message. - style0 <- style # Upgrade `style` to be within a list if not provided as such if (inherits(style, "cell_styles")) { style <- list(style) @@ -4213,7 +4197,7 @@ set_style.cells_source_notes <- function(loc, data, style) { #' @param footnotes.marks *Sequence of footnote marks* #' #' The set of sequential marks used to reference and identify each of the -#' footnotes (same input as the [opt_footnote_marks()] function). We can +#' footnotes (same input as [opt_footnote_marks()]). We can #' supply a vector that represents the series of footnote marks. This vector #' is recycled when its usage goes beyond the length of the set. At each #' cycle, the marks are simply combined (e.g., `*` -> `**` -> `***`). The @@ -4228,7 +4212,7 @@ set_style.cells_source_notes <- function(loc, data, style) { #' #' Optional specifications for formatting of footnote references #' (`footnotes.spec_ref`) and their associated marks the footer section -#' (`footnotes.spec_ftr`) (same input as the [opt_footnote_spec()] function). +#' (`footnotes.spec_ftr`) (same input as [opt_footnote_spec()]). #' This is a string containing specification control characters. The default #' is the spec string `"^i"`, which is superscript text set in italics. Other #' control characters that can be used are: (1) `"b"` for bold text, and (2) @@ -4439,8 +4423,7 @@ set_style.cells_source_notes <- function(loc, data, style) { #' Use select columns from the [`exibble`] dataset to create a **gt** table with #' a number of table parts added (using functions like [summary_rows()], #' [grand_summary_rows()], and more). We can use this **gt** object going -#' forward to demo some of the features available in the `tab_options()` -#' function. +#' forward to demo some of `tab_options()` features. #' #' ```r #' tab_1 <- diff --git a/R/tab_info.R b/R/tab_info.R index 43346c745a..c0ed378f0e 100644 --- a/R/tab_info.R +++ b/R/tab_info.R @@ -24,11 +24,10 @@ #' @section Examples: #' #' Let's use a portion of the [`gtcars`] dataset to create a **gt** table. We'll -#' use the [tab_spanner()] function to group two columns together under a -#' spanner column with the ID and label `"performance"`. Finally, we can use the -#' `tab_info()` function in a separate, interactive statement so that we can -#' inspect a table that summarizes the ID values any associated label text for -#' all parts of the table. +#' use [tab_spanner()] to group two columns together under a spanner column with +#' the ID and label `"performance"`. Finally, we can use`tab_info()` in a +#' separate, interactive statement so that we can inspect a table that +#' summarizes the ID values any associated label text for all parts of the table. #' #' ```r #' gt_tbl <- diff --git a/R/tab_remove.R b/R/tab_remove.R index 9959ab5050..06cdc296b8 100644 --- a/R/tab_remove.R +++ b/R/tab_remove.R @@ -4,7 +4,7 @@ #' #' We can remove the table header from a **gt** table quite easily with #' `rm_header()`. The table header is an optional table part (positioned above -#' the column labels) that can be added through the [tab_header()]. +#' the column labels) that can be added through [tab_header()]. #' #' This function for removal is useful if you have received a **gt** table #' (perhaps through an API that returns **gt** objects) but would prefer that @@ -23,7 +23,7 @@ #' @section Examples: #' #' Let's use a subset of the [`gtcars`] dataset to create a **gt** table. A -#' header part can be added with the [tab_header()] function; with that, we get +#' header part can be added with [tab_header()]; with that, we get #' a title and a subtitle for the table. #' #' ```r @@ -45,7 +45,7 @@ #' }} #' #' If you decide that you don't want the header in the `gt_tbl` object, it can -#' be removed with the `rm_header()` function. +#' be removed with `rm_header()`. #' #' ```r #' rm_header(data = gt_tbl) @@ -78,7 +78,7 @@ rm_header <- function(data) { #' #' We can easily remove the stubhead label from a **gt** table with #' `rm_stubhead()`. The stubhead location only exists if there is a table stub -#' and the text in that cell is added through the [tab_stubhead()] function. +#' and the text in that cell is added with [tab_stubhead()]. #' #' This function for removal is useful if you have received a **gt** table #' (perhaps through an API that returns **gt** objects) but would prefer that @@ -91,9 +91,9 @@ rm_header <- function(data) { #' #' @section Examples: #' -#' Using the [`gtcars`] datset, we'll create a **gt** table. With the -#' [tab_stubhead()] function, it's possible to add a stubhead label. This -#' appears in the top-left and can be used to describe what is in the stub. +#' Using the [`gtcars`] dataset, we'll create a **gt** table. With +#' [tab_stubhead()], it's possible to add a stubhead label. This appears in the +#' top-left and can be used to describe what is in the stub. #' #' ```r #' gt_tbl <- @@ -111,7 +111,7 @@ rm_header <- function(data) { #' }} #' #' If you decide that you don't want the stubhead label in the `gt_tbl` object, -#' it can be removed with the `rm_stubhead()` function. +#' it can be removed with `rm_stubhead()`. #' #' ```r #' rm_stubhead(data = gt_tbl) @@ -144,7 +144,7 @@ rm_stubhead <- function(data) { #' #' If you would like to remove column spanner labels then the `rm_spanners()` #' function can make this possible. Column spanner labels appear above the -#' column labels and can occupy several levels via stacking either though +#' column labels and can occupy several levels via stacking either through #' [tab_spanner()] or [tab_spanner_delim()]. Spanner column labels are #' distinguishable and accessible by their ID values. #' @@ -180,10 +180,10 @@ rm_stubhead <- function(data) { #' #' @section Examples: #' -#' Use a portion of the [`gtcars`] dataset to create a **gt** table. With the -#' [tab_spanner()] function, we can group several related columns together under -#' a spanner column. In this example, that is done with several calls of -#' [tab_spanner()] in order to create two levels of spanner column labels. +#' Use a portion of the [`gtcars`] dataset to create a **gt** table. With +#' [tab_spanner()], we can group several related columns together under a +#' spanner column. In this example, that is done with several [tab_spanner()] +#' calls in order to create two levels of spanner column labels. #' #' ```r #' gt_tbl <- @@ -213,7 +213,7 @@ rm_stubhead <- function(data) { #' }} #' #' If you decide that you don't want any of the spanners in the `gt_tbl` object, -#' they can all be removed with the `rm_spanners()` function. +#' they can all be removed with `rm_spanners()`. #' #' ```r #' rm_spanners(data = gt_tbl) @@ -351,10 +351,10 @@ rm_spanners <- function( #' #' @description #' -#' If you have one or more footnotes that ought to be removed, the -#' `rm_footnotes()` function allows for such a selective removal. The table -#' footer is an optional table part that is positioned below the table body, -#' containing areas for both the footnotes and source notes. +#' If you have one or more footnotes that ought to be removed, `rm_footnotes()` +#' allows for such a selective removal. The table footer is an optional table +#' part that is positioned below the table body, containing areas for both the +#' footnotes and source notes. #' #' This function for removal is useful if you have received a **gt** table #' (perhaps through an API that returns **gt** objects) but would prefer that @@ -380,7 +380,7 @@ rm_spanners <- function( #' @section Examples: #' #' Use a subset of the [`sza`] dataset to create a **gt** table. Color the `sza` -#' column using the [data_color()] function, then, use [tab_footnote()] twice to +#' column using [data_color()], then, use [tab_footnote()] twice to #' add two footnotes (each one targeting a different column label). #' #' ```r @@ -424,7 +424,7 @@ rm_spanners <- function( #' }} #' #' If you decide that you don't want the footnotes in the `gt_tbl` object, -#' they can be removed with the `rm_footnotes()` function. +#' they can be removed with `rm_footnotes()`. #' #' ```r #' rm_footnotes(data = gt_tbl) @@ -519,10 +519,10 @@ rm_footnotes <- function( #' #' @description #' -#' If you have one or more source notes that ought to be removed, the -#' `rm_source_notes()` function allows for such a selective removal. The table -#' footer is an optional table part that is positioned below the table body, -#' containing areas for both the source notes and footnotes. +#' If you have one or more source notes that ought to be removed, +#' `rm_source_notes()` allows for such a selective removal. The table footer is +#' an optional table part that is positioned below the table body, containing +#' areas for both the source notes and footnotes. #' #' This function for removal is useful if you have received a **gt** table #' (perhaps through an API that returns **gt** objects) but would prefer that @@ -547,10 +547,10 @@ rm_footnotes <- function( #' #' @section Examples: #' -#' Use a subset of the [`gtcars`] dataset to create a **gt** table. The -#' [tab_source_note()] function is used to add a source note to the table footer -#' that cites the data source (or, it could just be arbitrary text). We'll use -#' the function twice, in effect adding two source notes to the footer. +#' Use a subset of the [`gtcars`] dataset to create a **gt** table. +#' [tab_source_note()] is used to add a source note to the table footer that +#' cites the data source (or, it could just be arbitrary text). We'll use the +#' function twice, in effect adding two source notes to the footer. #' #' ```r #' gt_tbl <- @@ -570,7 +570,7 @@ rm_footnotes <- function( #' }} #' #' If you decide that you don't want the source notes in the `gt_tbl` object, -#' they can be removed with the `rm_source_notes()` function. +#' they can be removed with `rm_source_notes()`. #' #' ```r #' rm_source_notes(data = gt_tbl) @@ -682,8 +682,8 @@ rm_source_notes <- function( #' @section Examples: #' #' Use a portion of the [`gtcars`] dataset to create a **gt** table. We'll add a -#' header part with the [tab_header()] function, and, a caption will also be -#' added via the [tab_caption()] function. +#' header part with [tab_header()], and, a caption will also be added via +#' [tab_caption()]. #' #' ```r #' gt_tbl <- @@ -704,8 +704,8 @@ rm_source_notes <- function( #' `r man_get_image_tag(file = "man_rm_caption_1.png")` #' }} #' -#' If you decide that you don't want the caption in the `gt_tbl` object, -#' it can be removed with the `rm_caption()` function. +#' If you decide that you don't want the caption in the `gt_tbl` object, it can +#' be removed with `rm_caption()`. #' #' ```r #' rm_caption(data = gt_tbl) diff --git a/R/tab_style_body.R b/R/tab_style_body.R index a1c5837284..333d9ae83b 100644 --- a/R/tab_style_body.R +++ b/R/tab_style_body.R @@ -2,11 +2,11 @@ #' #' @description #' -#' With the `tab_style_body()` function we can target cells though value, regex, -#' and custom matching rules and apply styles to them and their surrounding -#' context (i.e., styling an entire row or column wherein the match is found). -#' Just as with the general [tab_style()] function, this function is focused on -#' the application of styles for HTML output only (as such, other output formats +#' With `tab_style_body()` we can target cells through value, regex, and +#' custom matching rules and apply styles to them and their surrounding context +#' (i.e., styling an entire row or column wherein the match is found). Just as +#' with the general [tab_style()] function, this function is focused on the +#' application of styles for HTML output only (as such, other output formats #' will ignore all `tab_style()` calls). #' #' With the collection of `cell_*()` helper functions available in **gt**, we @@ -29,12 +29,11 @@ #' #' `