gt-vec_fmt_datetime – The gt package

The `vec_fmt_datetime()` function

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 different date_style and time_style options (here, date_style = "yMMMEd" and time_style = "Hm") will result in 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,
  date_style = "yMMMEd",
  time_style = "Hm"
)

[1] "Mon, Jun 13, 2022 18:36" "Fri, Jan 25, 2019 01:08"
[3] NA

#> [1] "Mon, Jun 13, 2022 18:36" "Fri, Jan 25, 2019 01:08" NA

We can choose from any of 41 different date styles and 25 time formatting styles. Many of these styles are flexible, meaning that the structure of the format will adapt to different locales. Let’s use a combination of the "yMMMd" and "hms" date and time styles to demonstrate this (first in the default locale of "en"):

vec_fmt_datetime(
  str_vals,
  date_style = "yMMMd",
  time_style = "hms"
)

[1] "Jun 13, 2022 6:36:00 PM" "Jan 25, 2019 1:08:00 AM"
[3] NA

#> [1] "Jun 13, 2022 6:36:00 PM" "Jan 25, 2019 1:08:00 AM" NA

Let’s perform the same type of formatting in the Italian ("it") locale:

vec_fmt_datetime(
  str_vals,
  date_style = "yMMMd",
  time_style = "hms",
  locale = "it"
)

[1] "13 giu 2022 6:36:00 PM" "25 gen 2019 1:08:00 AM" NA

#> [1] "13 giu 2022 6:36:00 PM" "25 gen 2019 1:08:00 AM" 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_style and time_style options.

It’s possible to supply our own time formatting pattern within the format argument. One way is with a CLDR pattern, which is locale-aware:

vec_fmt_datetime(str_vals, format = "EEEE, MMMM d, y, h:mm a")

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

#> [1] "Monday, June 13, 2022, 06:36 PM"

By using the locale argument, this can be formatted as Dutch datetime values:

vec_fmt_datetime(
  str_vals,
  format = "EEEE, MMMM d, y, h:mm a",
  locale = "nl"
)

[1] "maandag, juni 13, 2022, 6:36 p.m."   
[2] "vrijdag, januari 25, 2019, 1:08 a.m."
[3] NA

#> [1] "maandag, juni 13, 2022, 6:36 p.m."

It’s also possible to use a strptime format code with format (however, any value provided to locale will be ignored).

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

#> [1] "Monday, June 13, 2022 at 06:36 pm"

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,
  sep = " at ",
  pattern = "Date and Time: {x}"
)

[1] "Date and Time: 2022-06-13 at 18:36:00"
[2] "Date and Time: 2019-01-25 at 01:08:00"
[3] NA

#> [1] "Date and Time: 2022-06-13 at 18:36:00"

The vec_fmt_datetime() function

The `vec_fmt_datetime()` function