Format vector values to time values using one of 25 preset time styles. Input
can be in the form of POSIXt
(i.e., datetimes), 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
).
vec_fmt_time(
x,
time_style = "iso",
pattern = "{x}",
locale = NULL,
output = c("auto", "plain", "html", "latex", "rtf", "word")
)
A character vector.
A numeric vector.
The time style to use. By default this is "iso"
which
corresponds to how times are formatted within ISO 8601 datetime values. The
other time styles can be viewed using info_time_style()
.
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.
An optional locale ID that can be used for formatting the value
according the locale's rules. Examples include "en"
for English (United
States) and "fr"
for French (France). The use of a valid locale ID will
override any values provided in sep_mark
and dec_mark
. We can use the
info_locales()
function as a useful reference for all of the locales that
are supported.
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
We need to supply a preset time style to the time_style
argument. There are
many time styles and all of them can handle localization to any supported
locale. Many of the time styles are termed flexible time formats and this
means that their output will adapt to any locale
provided. That feature
makes the flexible time formats a better option for locales other than "en"
(the default locale).
The following table provides a listing of all time styles and their output
values (corresponding to an input time of 14:35:00
). It is noted which of
these represent 12- or 24-hour time.
Time Style | Output | Notes | |
1 | "iso" | "14:35:00" | ISO 8601, 24h |
2 | "iso-short" | "14:35" | ISO 8601, 24h |
3 | "h_m_s_p" | "2:35:00 PM" | 12h |
4 | "h_m_p" | "2:35 PM" | 12h |
5 | "h_p" | "2 PM" | 12h |
6 | "Hms" | "14:35:00" | flexible, 24h |
7 | "Hm" | "14:35" | flexible, 24h |
8 | "H" | "14" | flexible, 24h |
9 | "EHm" | "Thu 14:35" | flexible, 24h |
10 | "EHms" | "Thu 14:35:00" | flexible, 24h |
11 | "Hmsv" | "14:35:00 GMT+00:00" | flexible, 24h |
12 | "Hmv" | "14:35 GMT+00:00" | flexible, 24h |
13 | "hms" | "2:35:00 PM" | flexible, 12h |
14 | "hm" | "2:35 PM" | flexible, 12h |
15 | "h" | "2 PM" | flexible, 12h |
16 | "Ehm" | "Thu 2:35 PM" | flexible, 12h |
17 | "Ehms" | "Thu 2:35:00 PM" | flexible, 12h |
18 | "EBhms" | "Thu 2:35:00 in the afternoon" | flexible, 12h |
19 | "Bhms" | "2:35:00 in the afternoon" | flexible, 12h |
20 | "EBhm" | "Thu 2:35 in the afternoon" | flexible, 12h |
21 | "Bhm" | "2:35 in the afternoon" | flexible, 12h |
22 | "Bh" | "2 in the afternoon" | flexible, 12h |
23 | "hmsv" | "2:35:00 PM GMT+00:00" | flexible, 12h |
24 | "hmv" | "2:35 PM GMT+00:00" | flexible, 12h |
25 | "ms" | "35:00" | flexible |
We can use the info_time_style()
within the console to view a similar table
of time styles with example output.
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_time()
(here with the "iso-short"
time style) will result
in a character vector of formatted times. 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_time(str_vals, time_style = "iso-short")
#> [1] "18:36" "01:08" NA
We can choose from any of 25 different time formatting styles. Many of these
styles are flexible, meaning that the structure of the format will adapt
to different locales. Let's use the "Bhms"
time style to demonstrate this
(first in the default locale of "en"
):
vec_fmt_time(str_vals, time_style = "Bhms")
#> [1] "6:36:00 in the evening" "1:08:00 at night" NA
Let's perform the same type of formatting in the German ("de"
) locale:
vec_fmt_time(str_vals, time_style = "Bhms", locale = "de")
#> [1] "6:36:00 abends" "1:08:00 nachts" NA
We can always use info_time_style()
to call up an info table that serves as
a handy reference to all of the time_style
options.
As a last example, one can wrap the time values in a pattern with the
pattern
argument. Note here that NA
values won't have the pattern
applied.
vec_fmt_time(
str_vals,
time_style = "hm",
pattern = "temps: {x}",
locale = "fr_CA"
)
#> [1] "temps: 6:36 PM" "temps: 1:08 AM" NA
14-12
Other vector formatting functions:
vec_fmt_bytes()
,
vec_fmt_currency()
,
vec_fmt_datetime()
,
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_roman()
,
vec_fmt_scientific()