Learn R Programming
gt (version 0.7.0)

vec_fmt_datetime: Format a vector as date-time values

Description

Format vector 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

vec_fmt_datetime(
  x,
  date_style = 2,
  time_style = 2,
  sep = " ",
  format = NULL,
  tz = NULL,
  pattern = "{x}",
  output = c("auto", "plain", "html", "latex", "rtf", "word")
)

Value

A character vector.

Arguments

x

A numeric vector.

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.

output

The output style of the resulting character vector. This can either be "auto" (the default), "plain", "html", "latex", "rtf", or "word". In knitr rendering (i.e., Quarto or R Markdown), the "auto" option will choose the correct output value

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

Let's create a character vector of datetime values in the ISO-8601 format for the next few examples:

str_vals <- c("2022-06-13 18:36", "2019-01-25 01:08", NA)

Using vec_fmt_datetime() with the default options will create a character vector of formatted datetime values. Any NA values remain as NA values. The rendering context will be autodetected unless specified in the output argument (here, it is of the "plain" output type).

vec_fmt_datetime(str_vals)


#> [1] "Monday, June 13, 2022 18:36"
#> [2] "Friday, January 25, 2019 01:08"
#> [3] NA

We can change the formatting style of the date and time portions separately with the date_style (values 1-14) and time_style (values 1-5) arguments. The sep option allows for a customized separator string between the date and time.

vec_fmt_datetime(
  str_vals,
  date_style = 2,
  time_style = 4,
  sep = " at "
)


#> [1] "Monday, June 13, 2022 at 6:36 PM"
#> [2] "Friday, January 25, 2019 at 1:08 AM"
#> [3] NA

We can always use info_date_style() or info_time_style() to call up info tables that serve as handy references to all of the date and time styles.

It's possible to supply our own time formatting pattern and have greater control over the final formatting (even including string literals as please):

vec_fmt_datetime(str_vals, format = "%A, %B %e, %Y at %I:%M %p")


#> [1] "Monday, June 13, 2022 at 06:36 PM"
#> [2] "Friday, January 25, 2019 at 01:08 AM"
#> [3] NA

As a last example, one can wrap the datetime values in a pattern with the pattern argument. Note here that NA values won't have the pattern applied.

vec_fmt_datetime(
  str_vals,
  date_style = 6,
  time_style = 4,
  sep = " at ",
  pattern = "Date and Time: {x}"
)


#> [1] "Date and Time: Jun 13, 2022 at 6:36 PM"
#> [2] "Date and Time: Jan 25, 2019 at 1:08 AM"
#> [3] NA

Function ID

14-12

See Also

Other vector formatting functions: vec_fmt_bytes(), vec_fmt_currency(), vec_fmt_date(), vec_fmt_duration(), vec_fmt_engineering(), vec_fmt_fraction(), vec_fmt_integer(), vec_fmt_markdown(), vec_fmt_number(), vec_fmt_partsper(), vec_fmt_percent(), vec_fmt_scientific(), vec_fmt_time()