text_case_when: Perform whole text replacements using a...

View source: R/text_transform.R

text_case_whenR Documentation

Perform whole text replacements using a 'case-when'-expression approach


The text_case_when() function provides a useful interface for a case-by-case approach to replacing entire table cells. First off, you have to make sure you're targeting the appropriate cells with the .locations argument. Following that, you supply a sequence of two-sided formulas matching of the general form: ⁠<logical_stmt> ~ <new_text>⁠. In the left hand side (LHS) there should be a predicate statement that evaluates to a logical vector of length one (i.e., either TRUE or FALSE). To refer to the values undergoing transformation, you need to use the x variable.


text_case_when(.data, ..., .default = NULL, .locations = cells_body())



The gt table data object

⁠obj:<gt_tbl>⁠ // required

This is the gt table object that is commonly created through use of the gt() function.


Matching expressions

⁠<multiple expressions>⁠ // required

A sequence of two-sided formulas. The left hand side (LHS) determines which values match this case. The right hand side (RHS) provides the replacement text (it must resolve to a value of the character class). The LHS inputs must evaluate to logical vectors.


Default replacement text

⁠scalar<character>⁠ // default: NULL (optional)

The replacement text to use when cell values aren't matched by any of the LHS inputs. If NULL, the default, no replacement text will be used.


Locations to target

⁠<locations expressions>⁠ // default: cells_body()

The cell or set of cells to be associated with the text transformation. Only the cells_body(), cells_stub(), cells_row_groups(), cells_column_labels(), and cells_column_spanners() helper functions can be used here. We can enclose several of these calls within a list() if we wish to make the transformation happen at different locations.


An object of class gt_tbl.


Use a portion of the metro dataset to create a gt table. We'll use the text_case_when() function to supply pairs of predicate statements and replacement text. For the connect_rer column, we will perform a count of pattern matches with stringr::str_count() and determine which cells have 1, 2, or 3 matched patterns. For each of these cases, descriptive replacement text is provided. Here, we use a .default value to replace the non-matched cases with an empty string (""). Finally, we use cols_label() to modify the labels of the three columns.

metro |>
  dplyr::arrange(desc(passengers)) |>
  dplyr::select(name, lines, connect_rer) |>
  dplyr::slice_head(n = 10) |>
  gt() |>
    stringr::str_count(x, pattern = "[ABCDE]") == 1 ~ "One connection.",
    stringr::str_count(x, pattern = "[ABCDE]") == 2 ~ "Two connections.",
    stringr::str_count(x, pattern = "[ABCDE]") == 3 ~ "Three connections.",
    .default = "", .locations = cells_body(columns = connect_rer)
  ) |>
    name = "Station",
    lines = "Lines Serviced",
    connect_rer = "RER Connections"
This image of a table was generated from the first code example in the `text_case_when()` help file.

Function ID


Function Introduced

v0.9.0 (Mar 31, 2023)

See Also

Other text transforming functions: text_case_match(), text_replace(), text_transform()

gt documentation built on June 22, 2024, 11:11 a.m.