fmt_time: Format values as times

Description

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

Once the appropriate data cells are targeted with columns (and, optionally, rows), we can simply apply a preset time style to format the times. The following time styles are available for use (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_time_style() function for a useful reference on all of the possible inputs to time_style.

Usage

fmt_time(data, columns, rows = everything(), time_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).
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.
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 time column to have times formatted as hms_p (time style 3).

exibble %>%
  dplyr::select(date, time) %>%
  gt() %>%
  fmt_time(
    columns = time,
    time_style = 3
  )

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

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

exibble %>%
  dplyr::select(date, time) %>%
  gt() %>%
  fmt_time(
    columns = time,
    rows = time > "16:00",
    time_style = 3
  ) %>%
  fmt_time(
    columns = time,
    rows = time <= "16:00",
    time_style = 4
  )

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

Function ID

3-11

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.