fmt_date: Format values as dates

Description

Format input values to time values using one of fourteen presets. Input can be in the form of POSIXt (i.e., date-times), the Date type, or character (must be in the ISO 8601 form of YYYY-MM-DD HH:MM:SS or YYYY-MM-DD).

Once the appropriate data cells are targeted with columns (and, optionally, rows), we can simply apply a preset date style to format the dates. The following date styles are available for use (all using the input date of 2000-02-29 in the example output dates):

"iso": 2000-02-29
"wday_month_day_year": Tuesday, February 29, 2000
"wd_m_day_year": Tue, Feb 29, 2000
"wday_day_month_year": Tuesday 29 February 2000
"month_day_year": February 29, 2000
"m_day_year": Feb 29, 2000
"day_m_year": 29 Feb 2000
"day_month_year": 29 February 2000
"day_month": 29 February
"year": 2000
"month": February
"day": 29
"year.mn.day": 2000/02/29
"y.mn.day": 00/02/29

We can use the info_date_style() function for a useful reference on all of the possible inputs to date_style.

Usage

fmt_date(data, columns, rows = everything(), date_style = 2, pattern = "{x}")

Value

An object of class gt_tbl.

Arguments

data: A table object that is created using the gt() function.
columns: The columns to format. Can either be a series of column names provided in c(), a vector of column indices, or a helper function focused on selections. The select helper functions are: starts_with(), ends_with(), contains(), matches(), one_of(), num_range(), and everything().
rows: Optional rows to format. Providing everything() (the default) results in all rows in columns being formatted. Alternatively, we can supply a vector of row captions within c(), a vector of row indices, or a helper function focused on selections. The select helper functions are: starts_with(), ends_with(), contains(), matches(), one_of(), num_range(), and everything(). We can also use expressions to filter down to the rows we need (e.g., [colname_1] > 100 & [colname_2] < 50).
date_style: The date style to use. Supply a number (from 1 to 14) that corresponds to the preferred date style, or, provide a named date style ("wday_month_day_year", "m_day_year", "year.mn.day", etc.). Use info_date_style() to see the different numbered and named date presets.
pattern: A formatting pattern that allows for decoration of the formatted value. The value itself is represented by {x} and all other characters are taken to be string literals.

Examples

Use exibble to create a gt table. Keep only the date and time columns. Format the date column to have dates formatted as month_day_year (date style 5).

exibble %>%
  dplyr::select(date, time) %>%
  gt() %>%
  fmt_date(
    columns = date,
    date_style = 5
  )

This image of a table was generated from the first code example in the `fmt_date()` help file.

Use exibble to create a gt table. Keep only the date and time columns. Format the date column to have mixed date formats (dates after April will be different than the others because of the expressions used in the rows argument).

exibble %>%
  dplyr::select(date, time) %>%
  gt() %>%
  fmt_date(
    columns = date,
    rows = as.Date(date) > as.Date("2015-04-01"),
    date_style = "m_day_year"
  ) %>%
  fmt_date(
    columns = date,
    rows = as.Date(date) <= as.Date("2015-04-01"),
    date_style = "day_m_year"
  )

This image of a table was generated from the second code example in the `fmt_date()` help file.

Function ID

3-10

Details

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). Conditional formatting is possible by providing a conditional expression to the rows argument. See the Arguments section for more information on this.