gt (version 0.8.0)

fmt_date: Format values as dates

Description

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

Usage

fmt_date(
  data,
  columns,
  rows = everything(),
  date_style = "iso",
  pattern = "{x}",
  locale = NULL
)

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. By default this is "iso" which corresponds to ISO 8601 date formatting. The other date styles can be viewed using info_date_style().

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.

locale

An optional locale ID that can be used for formatting the value according the locale's rules. Examples include "en" for English (United States) and "fr" for French (France). The use of a valid locale ID will override any values provided in sep_mark and dec_mark. We can use the info_locales() function as a useful reference for all of the locales that are supported. Any locale value provided here will override any global locale setting performed in gt()'s own locale argument.

Targeting the values to be formatted

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.

Formatting with the <code>date_style</code> argument

We need to supply a preset date style to the date_style argument. The date styles are numerous and can handle localization to any supported locale. A large segment of date styles are termed flexible date formats and this means that their output will adapt to any locale provided. That feature makes the flexible date formats a better option for locales other than "en" (the default locale).

The following table provides a listing of all date styles and their output values (corresponding to an input date of 2000-02-29).

	Date Style	Output	Notes
1	"iso"	"2000-02-29"	ISO 8601
2	"wday_month_day_year"	"Tuesday, February 29, 2000"
3	"wd_m_day_year"	"Tue, Feb 29, 2000"
4	"wday_day_month_year"	"Tuesday 29 February 2000"
5	"month_day_year"	"February 29, 2000"
6	"m_day_year"	"Feb 29, 2000"
7	"day_m_year"	"29 Feb 2000"
8	"day_month_year"	"29 February 2000"
9	"day_month"	"29 February"
10	"day_m"	"29 Feb"
11	"year"	"2000"
12	"month"	"February"
13	"day"	"29"
14	"year.mn.day"	"2000/02/29"
15	"y.mn.day"	"00/02/29"
16	"year_week"	"2000-W09"
17	"year_quarter"	"2000-Q1"
18	"yMd"	"2/29/2000"	flexible
19	"yMEd"	"Tue, 2/29/2000"	flexible
20	"yMMM"	"Feb 2000"	flexible
21	"yMMMM"	"February 2000"	flexible
22	"yMMMd"	"Feb 29, 2000"	flexible
23	"yMMMEd"	"Tue, Feb 29, 2000"	flexible
24	"GyMd"	"2/29/2000 A"	flexible
25	"GyMMMd"	"Feb 29, 2000 AD"	flexible
26	"GyMMMEd"	"Tue, Feb 29, 2000 AD"	flexible
27	"yM"	"2/2000"	flexible
28	"Md"	"2/29"	flexible
29	"MEd"	"Tue, 2/29"	flexible
30	"MMMd"	"Feb 29"	flexible
31	"MMMEd"	"Tue, Feb 29"	flexible
32	"MMMMd"	"February 29"	flexible
33	"GyMMM"	"Feb 2000 AD"	flexible
34	"yQQQ"	"Q1 2000"	flexible
35	"yQQQQ"	"1st quarter 2000"	flexible
36	"Gy"	"2000 AD"	flexible
37	"y"	"2000"	flexible
38	"M"	"2"	flexible
39	"MMM"	"Feb"	flexible
40	"d"	"29"	flexible
41	"Ed"	"29 Tue"	flexible

We can use the info_date_style() within the console to view a similar table of date styles with example output.

Examples

Use exibble to create a gt table. Keep only the date and time columns. Format the date column to have dates formatted with the "month_day_year" date style.

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

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"
  )

Use exibble to create another gt table, this time only with the date column. Format the date column to use the "yMMMEd" date style (which is one of the 'flexible' styles). Also, set the locale to "nl" to get the dates in Dutch.

exibble %>%
  dplyr::select(date) %>%
  gt() %>%
  fmt_date(
    columns = date,
    date_style = "yMMMEd",
    locale = "nl"
  )

Function ID

3-11

See Also

Other data formatting functions: data_color(), fmt_bytes(), fmt_currency(), fmt_datetime(), fmt_duration(), fmt_engineering(), fmt_fraction(), fmt_integer(), fmt_markdown(), fmt_number(), fmt_partsper(), fmt_passthrough(), fmt_percent(), fmt_roman(), fmt_scientific(), fmt_time(), fmt(), sub_large_vals(), sub_missing(), sub_small_vals(), sub_values(), sub_zero(), text_transform()