gt (version 0.5.0)

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

1. "iso": 2000-02-29

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. "year": 2000

11. "month": February

12. "day": 29

13. "year.mn.day": 2000/02/29

14. "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):

1. "hms": 14:35:00

2. "hm": 14:35

3. "hms_p": 2:35:00 PM

4. "hm_p": 2:35 PM

5. "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}"
)

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.

Value

An object of class gt_tbl.

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)

Figures

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.

See Also

Other Format Data: data_color(), fmt_bytes(), fmt_currency(), fmt_date(), fmt_engineering(), fmt_fraction(), fmt_integer(), fmt_markdown(), fmt_missing(), fmt_number(), fmt_passthrough(), fmt_percent(), fmt_scientific(), fmt_time(), fmt(), text_transform()

Examples

# NOT RUN {
# 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`
tab_1 <-
  exibble %>%
  dplyr::select(datetime) %>%
  gt() %>%
  fmt_datetime(
    columns = datetime,
    date_style = 5,
    time_style = 3
  )

# }