fmt_datetime: Format values as date-times

Description

Format input values to date-time values using one of fourteen presets for the date component and one of five presets for the time component. Input can be in the form of POSIXct (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 preset date and time styles to format the date-time values. The following date styles are available for formatting of the date portion (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

The following time styles are available for formatting of the time portion (all using the input time of 14:35:00 in the example output times):

"hms": 14:35:00
"hm": 14:35
"hms_p": 2:35:00 PM
"hm_p": 2:35 PM
"h_p": 2 PM

We can use the info_date_style() and info_time_style() functions as useful references for all of the possible inputs to date_style and time_style.

Usage

fmt_datetime(
  data,
  columns,
  rows = everything(),
  date_style = 2,
  time_style = 2,
  sep = " ",
  format = NULL,
  tz = NULL,
  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.
time_style: The time style to use. Supply a number (from 1 to 5) that corresponds to the preferred time style, or, provide a named time style ("hms", "hms_p", "h_p", etc.). Use info_time_style() to see the different numbered and named time presets.
sep: The separator string to use between the date and time components. By default, this is a single space character (" "). Only used when not specifying a format code.
format: An optional format code used for generating custom dates/times. If used then the arguments governing preset styles (date_style and time_style) will be ignored in favor of formatting via the format string.
tz: The time zone for printing dates/times (i.e., the output). The default of NULL will preserve the time zone of the input data in the output. If providing a time zone, it must be one that is recognized by the user's operating system (a vector of all valid tz values can be produced with OlsonNames()).
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.

Date and Time Formats

Using format to create custom time formats isn't so hard once we know about all of the different format codes. The formats are all indicated with a leading % and literal characters are any of those without the leading %. We'll use the date and time "2015-06-08 23:05:37.48" for all of the examples here.

First off, let's look at a few format code combinations that work well together as format codes. This will give us an intuition on how these generally work.

"%m/%d/%Y" -> "06/08/2015"
"%A, %B %e, %Y" -> "Monday, June 8, 2015"
"%b %e %a" -> "Jun 8 Mon"
"%H:%M" -> "23:05"
"%I:%M %p" -> "11:05 pm"
"%A, %B %e, %Y at %I:%M %p" -> "Monday, June 8, 2015 at 11:05 pm"

Here are the individual format codes for date components:

"%a" -> "Mon" (abbreviated day of week name)
"%A" -> "Monday" (full day of week name)
"%w" -> "1" (day of week number in 0..6; Sunday is 0)
"%u" -> "1" (day of week number in 1..7; Monday is 1, Sunday 7)
"%y" -> "15" (abbreviated year, using the final two digits)
"%Y" -> "2015" (full year)
"%b" -> "Jun" (abbreviated month name)
"%B" -> "June" (full month name)
"%m" -> "06" (month number)
"%d" -> "08" (day number, zero-padded)
"%e" -> "8" (day number without zero padding)

Here are the individual format codes for time components:

"%H" -> "23" (24h hour)
"%I" -> "11" (12h hour)
"%M" -> "05" (minute)
"%S" -> "37" (second)
"%OS3" -> "37.480" (seconds with decimals; 3 decimal places here)
%p -> "pm" (AM or PM indicator, may not appear in certain locales)

Here are some extra formats that you may find useful:

"%j" -> "159" (day of the year, always zero-padded)
"%W" -> "23" (week number for the year, always zero-padded)
"%V" -> "24" (week number for the year, following ISO 8601 standard)
"%C" -> "20" (the century number)
"%z" -> "+0000" (signed time zone offset, here using UTC)
"%F" -> "2015-06-08" (the date in the ISO 8601 date format)
"%%" -> "%" (the literal "%" character, in case you need it)

Examples

Use exibble to create a gt table. Keep only the datetime column. Format the column to have dates formatted as month_day_year and times to be hms_p.

exibble %>%
  dplyr::select(datetime) %>%
  gt() %>%
  fmt_datetime(
    columns = datetime,
    date_style = 5,
    time_style = 3
  )

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

Function ID

3-12

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.