Skip to contents

Format a vector as datetime values

Source: R/format_vec.R
vec_fmt_datetime.Rd

Format values in a vector to datetime values using either presets for the date and time components or a formatting directive (this can either use a CLDR datetime pattern or strptime formatting). Input can be in the form of POSIXct (i.e., datetimes), the Date type, or character (must be in the ISO 8601 form of YYYY-MM-DD HH:MM:SS or YYYY-MM-DD).

Usage

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

Arguments

x

The input vector

vector(numeric|integer) // required

This is the input vector that will undergo transformation to a character vector of the same length. Values within the vector will be formatted.

date_style

Predefined style for dates

scalar<character>|scalar<numeric|integer>(1<=val<=41) // default: "iso"

The date style to use. By default this is the short name "iso" which corresponds to ISO 8601 date formatting. There are 41 date styles in total and their short names can be viewed using info_date_style().

time_style

Predefined style for times

scalar<character>|scalar<numeric|integer>(1<=val<=25) // default: "iso"

The time style to use. By default this is the short name "iso" which corresponds to how times are formatted within ISO 8601 datetime values. There are 25 time styles in total and their short names can be viewed using info_time_style().

sep

Separator between date and time components

scalar<character> // default: " "

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

Date/time formatting string

scalar<character> // default: NULL (optional)

An optional formatting string 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

Time zone

scalar<character> // default: NULL (optional)

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

Specification of the formatting pattern

scalar<character> // default: "{x}"

A formatting pattern that allows for decoration of the formatted value. The formatted value is represented by the {x} (which can be used multiple times, if needed) and all other characters will be interpreted as string literals.

locale

Locale identifier

scalar<character> // default: NULL (optional)

An optional locale identifier that can be used for formatting values according to the locale's rules. Examples include "en" for English (United States) and "fr" for French (France). We can call info_locales() for a useful reference for all of the locales that are supported.

output

Output format

singl-kw:[auto|plain|html|latex|rtf|word] // default: "auto"

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

Value

A character vector.

Formatting with the date_style argument

We can supply a preset date style to the date_style argument to separately handle the date portion of the output. The date styles are numerous and can handle localization to any supported locale. A large segment of date styles are termed flexible date formats and this means that their output will adapt to any locale provided. That feature makes the flexible date formats a better option for locales other than "en" (the default locale).

The following table provides a listing of all date styles and their output values (corresponding to an input date of 2000-02-29).

Date StyleOutputNotes
1"iso""2000-02-29"ISO 8601
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"day_m""29 Feb"
11"year""2000"
12"month""February"
13"day""29"
14"year.mn.day""2000/02/29"
15"y.mn.day""00/02/29"
16"year_week""2000-W09"
17"year_quarter""2000-Q1"
18"yMd""2/29/2000"flexible
19"yMEd""Tue, 2/29/2000"flexible
20"yMMM""Feb 2000"flexible
21"yMMMM""February 2000"flexible
22"yMMMd""Feb 29, 2000"flexible
23"yMMMEd""Tue, Feb 29, 2000"flexible
24"GyMd""2/29/2000 A"flexible
25"GyMMMd""Feb 29, 2000 AD"flexible
26"GyMMMEd""Tue, Feb 29, 2000 AD"flexible
27"yM""2/2000"flexible
28"Md""2/29"flexible
29"MEd""Tue, 2/29"flexible
30"MMMd""Feb 29"flexible
31"MMMEd""Tue, Feb 29"flexible
32"MMMMd""February 29"flexible
33"GyMMM""Feb 2000 AD"flexible
34"yQQQ""Q1 2000"flexible
35"yQQQQ""1st quarter 2000"flexible
36"Gy""2000 AD"flexible
37"y""2000"flexible
38"M""2"flexible
39"MMM""Feb"flexible
40"d""29"flexible
41"Ed""29 Tue"flexible

We can call info_date_style() in the console to view a similar table of date styles with example output.

Formatting with the time_style argument

We can supply a preset time style to the time_style argument to separately handle the time portion of the output. 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. Some of the flexible formats (those that begin with "E") include the day of the week. Keep this in mind when pairing such time_style values with a date_style so as to avoid redundant or repeating information.

Time StyleOutputNotes
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 call info_time_style() in the console to view a similar table of time styles with example output.

Formatting with a CLDR datetime pattern

We can use a CLDR datetime pattern with the format argument to create a highly customized and locale-aware output. This is a character string that consists of two types of elements:

  • Pattern fields, which repeat a specific pattern character one or more times. These fields are replaced with date and time data when formatting. The character sets of A-Z and a-z are reserved for use as pattern characters.

  • Literal text, which is output verbatim when formatting. This can include:

    • Any characters outside the reserved character sets, including spaces and punctuation.

    • Any text between single vertical quotes (e.g., 'text').

    • Two adjacent single vertical quotes (”), which represent a literal single quote, either inside or outside quoted text.

The number of pattern fields is quite sizable so let's first look at how some CLDR datetime patterns work. We'll use the datetime string "2018-07-04T22:05:09.2358(America/Vancouver)" for all of the examples that follow.

  • "mm/dd/y" -> "05/04/2018"

  • "EEEE, MMMM d, y" -> "Wednesday, July 4, 2018"

  • "MMM d E" -> "Jul 4 Wed"

  • "HH:mm" -> "22:05"

  • "h:mm a" -> "10:05 PM"

  • "EEEE, MMMM d, y 'at' h:mm a" -> "Wednesday, July 4, 2018 at 10:05 PM"

Here are the individual pattern fields:

Year

Calendar Year

This yields the calendar year, which is always numeric. In most cases the length of the "y" field specifies the minimum number of digits to display, zero-padded as necessary. More digits will be displayed if needed to show the full year. There is an exception: "yy" gives use just the two low-order digits of the year, zero-padded as necessary. For most use cases, "y" or "yy" should be good enough.

Field PatternsOutput
"y""2018"
"yy""18"
"yyy" to "yyyyyyyyy""2018" to "000002018"

Year in the Week in Year Calendar

This is the year in 'Week of Year' based calendars in which the year transition occurs on a week boundary. This may differ from calendar year "y" near a year transition. This numeric year designation is used in conjunction with pattern character "w" in the ISO year-week calendar as defined by ISO 8601.

Field PatternsOutput
"Y""2018"
"YY""18"
"YYY" to "YYYYYYYYY""2018" to "000002018"

Quarter

Quarter of the Year: formatting and standalone versions

The quarter names are identified numerically, starting at 1 and ending at 4. Quarter names may vary along two axes: the width and the context. The context is either 'formatting' (taken as a default), which the form used within a complete date format string, or, 'standalone', the form for date elements used independently (such as in calendar headers). The standalone form may be used in any other date format that shares the same form of the name. Here, the formatting form for quarters of the year consists of some run of "Q" values whereas the standalone form uses "q".

Field PatternsOutputNotes
"Q"/"q""3"Numeric, one digit
"QQ"/"qq""03"Numeric, two digits (zero padded)
"QQQ"/"qqq""Q3"Abbreviated
"QQQQ"/"qqqq""3rd quarter"Wide
"QQQQQ"/"qqqqq""3"Narrow

Month

Month: formatting and standalone versions

The month names are identified numerically, starting at 1 and ending at 12. Month names may vary along two axes: the width and the context. The context is either 'formatting' (taken as a default), which the form used within a complete date format string, or, 'standalone', the form for date elements used independently (such as in calendar headers). The standalone form may be used in any other date format that shares the same form of the name. Here, the formatting form for months consists of some run of "M" values whereas the standalone form uses "L".

Field PatternsOutputNotes
"M"/"L""7"Numeric, minimum digits
"MM"/"LL""07"Numeric, two digits (zero padded)
"MMM"/"LLL""Jul"Abbreviated
"MMMM"/"LLLL""July"Wide
"MMMMM"/"LLLLL""J"Narrow

Week

Week of Year

Values calculated for the week of year range from 1 to 53. Week 1 for a year is the first week that contains at least the specified minimum number of days from that year. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (if needed).

There are two available field lengths. Both will display the week of year value but the "ww" width will always show two digits (where weeks 1 to 9 are zero padded).

Field PatternsOutputNotes
"w""27"Minimum digits
"ww""27"Two digits (zero padded)

Week of Month

The week of a month can range from 1 to 5. The first day of every month always begins at week 1 and with every transition into the beginning of a week, the week of month value is incremented by 1.

Field PatternOutput
"W""1"

Day

Day of Month

The day of month value is always numeric and there are two available field length choices in its formatting. Both will display the day of month value but the "dd" formatting will always show two digits (where days 1 to 9 are zero padded).

Field PatternsOutputNotes
"d""4"Minimum digits
"dd""04"Two digits, zero padded

Day of Year

The day of year value ranges from 1 (January 1) to either 365 or 366 (December 31), where the higher value of the range indicates that the year is a leap year (29 days in February, instead of 28). The field length specifies the minimum number of digits, with zero-padding as necessary.

Field PatternsOutputNotes
"D""185"
"DD""185"Zero padded to minimum width of 2
"DDD""185"Zero padded to minimum width of 3

Day of Week in Month

The day of week in month returns a numerical value indicating the number of times a given weekday had occurred in the month (e.g., '2nd Monday in March'). This conveniently resolves to predicable case structure where ranges of day of the month values return predictable day of week in month values:

  • days 1 - 7 -> 1

  • days 8 - 14 -> 2

  • days 15 - 21 -> 3

  • days 22 - 28 -> 4

  • days 29 - 31 -> 5

Field PatternOutput
"F""1"

Modified Julian Date

The modified version of the Julian date is obtained by subtracting 2,400,000.5 days from the Julian date (the number of days since January 1, 4713 BC). This essentially results in the number of days since midnight November 17, 1858. There is a half day offset (unlike the Julian date, the modified Julian date is referenced to midnight instead of noon).

Field PatternsOutput
"g" to "ggggggggg""58303" -> "000058303"

Weekday

Day of Week Name

The name of the day of week is offered in four different widths.

Field PatternsOutputNotes
"E", "EE", or "EEE""Wed"Abbreviated
"EEEE""Wednesday"Wide
"EEEEE""W"Narrow
"EEEEEE""We"Short

Periods

AM/PM Period of Day

This denotes before noon and after noon time periods. May be upper or lowercase depending on the locale and other options. The wide form may be the same as the short form if the 'real' long form (e.g. 'ante meridiem') is not customarily used. The narrow form must be unique, unlike some other fields.

Field PatternsOutputNotes
"a", "aa", or "aaa""PM"Abbreviated
"aaaa""PM"Wide
"aaaaa""p"Narrow

AM/PM Period of Day Plus Noon and Midnight

Provide AM and PM as well as phrases for exactly noon and midnight. May be upper or lowercase depending on the locale and other options. If the locale doesn't have the notion of a unique 'noon' (i.e., 12:00), then the PM form may be substituted. A similar behavior can occur for 'midnight' (00:00) and the AM form. The narrow form must be unique, unlike some other fields.

(a) input_midnight: "2020-05-05T00:00:00" (b) input_noon: "2020-05-05T12:00:00"

Field PatternsOutputNotes
"b", "bb", or "bbb"(a) "midnight"Abbreviated
(b) "noon"
"bbbb"(a) "midnight"Wide
(b) "noon"
"bbbbb"(a) "mi"Narrow
(b) "n"

Flexible Day Periods

Flexible day periods denotes things like 'in the afternoon', 'in the evening', etc., and the flexibility comes from a locale's language and script. Each locale has an associated rule set that specifies when the day periods start and end for that locale.

(a) input_morning: "2020-05-05T00:08:30" (b) input_afternoon: "2020-05-05T14:00:00"

Field PatternsOutputNotes
"B", "BB", or "BBB"(a) "in the morning"Abbreviated
(b) "in the afternoon"
"BBBB"(a) "in the morning"Wide
(b) "in the afternoon"
"BBBBB"(a) "in the morning"Narrow
(b) "in the afternoon"

Hours, Minutes, and Seconds

Hour 0-23

Hours from 0 to 23 are for a standard 24-hour clock cycle (midnight plus 1 minute is 00:01) when using "HH" (which is the more common width that indicates zero-padding to 2 digits).

Using "2015-08-01T08:35:09":

Field PatternsOutputNotes
"H""8"Numeric, minimum digits
"HH""08"Numeric, 2 digits (zero padded)

Hour 1-12

Hours from 1 to 12 are for a standard 12-hour clock cycle (midnight plus 1 minute is 12:01) when using "hh" (which is the more common width that indicates zero-padding to 2 digits).

Using "2015-08-01T08:35:09":

Field PatternsOutputNotes
"h""8"Numeric, minimum digits
"hh""08"Numeric, 2 digits (zero padded)

Hour 1-24

Using hours from 1 to 24 is a less common way to express a 24-hour clock cycle (midnight plus 1 minute is 24:01) when using "kk" (which is the more common width that indicates zero-padding to 2 digits).

Using "2015-08-01T08:35:09":

Field PatternsOutputNotes
"k""9"Numeric, minimum digits
"kk""09"Numeric, 2 digits (zero padded)

Hour 0-11

Using hours from 0 to 11 is a less common way to express a 12-hour clock cycle (midnight plus 1 minute is 00:01) when using "KK" (which is the more common width that indicates zero-padding to 2 digits).

Using "2015-08-01T08:35:09":

Field PatternsOutputNotes
"K""7"Numeric, minimum digits
"KK""07"Numeric, 2 digits (zero padded)

Minute

The minute of the hour which can be any number from 0 to 59. Use "m" to show the minimum number of digits, or "mm" to always show two digits (zero-padding, if necessary).

Field PatternsOutputNotes
"m""5"Numeric, minimum digits
"mm""06"Numeric, 2 digits (zero padded)

Seconds

The second of the minute which can be any number from 0 to 59. Use "s" to show the minimum number of digits, or "ss" to always show two digits (zero-padding, if necessary).

Field PatternsOutputNotes
"s""9"Numeric, minimum digits
"ss""09"Numeric, 2 digits (zero padded)

Fractional Second

The fractional second truncates (like other time fields) to the width requested (i.e., count of letters). So using pattern "SSSS" will display four digits past the decimal (which, incidentally, needs to be added manually to the pattern).

Field PatternsOutput
"S" to "SSSSSSSSS""2" -> "235000000"

Milliseconds Elapsed in Day

There are 86,400,000 milliseconds in a day and the "A" pattern will provide the whole number. The width can go up to nine digits with "AAAAAAAAA" and these higher field widths will result in zero padding if necessary.

Using "2011-07-27T00:07:19.7223":

Field PatternsOutput
"A" to "AAAAAAAAA""439722" -> "000439722"

Era

The Era Designator

This provides the era name for the given date. The Gregorian calendar has two eras: AD and BC. In the AD year numbering system, AD 1 is immediately preceded by 1 BC, with nothing in between them (there was no year zero).

Field PatternsOutputNotes
"G", "GG", or "GGG""AD"Abbreviated
"GGGG""Anno Domini"Wide
"GGGGG""A"Narrow

Time Zones

TZ // Short and Long Specific non-Location Format

The short and long specific non-location formats for time zones are suggested for displaying a time with a user friendly time zone name. Where the short specific format is unavailable, it will fall back to the short localized GMT format ("O"). Where the long specific format is unavailable, it will fall back to the long localized GMT format ("OOOO").

Field PatternsOutputNotes
"z", "zz", or "zzz""PDT"Short Specific
"zzzz""Pacific Daylight Time"Long Specific

TZ // Common UTC Offset Formats

The ISO8601 basic format with hours, minutes and optional seconds fields is represented by "Z", "ZZ", or "ZZZ". The format is equivalent to RFC 822 zone format (when the optional seconds field is absent). This is equivalent to the "xxxx" specifier. The field pattern "ZZZZ" represents the long localized GMT format. This is equivalent to the "OOOO" specifier. Finally, "ZZZZZ" pattern yields the ISO8601 extended format with hours, minutes and optional seconds fields. The ISO8601 UTC indicator Z is used when local time offset is 0. This is equivalent to the "XXXXX" specifier.

Field PatternsOutputNotes
"Z", "ZZ", or "ZZZ""-0700"ISO 8601 basic format
"ZZZZ""GMT-7:00"Long localized GMT format
"ZZZZZ""-07:00"ISO 8601 extended format

TZ // Short and Long Localized GMT Formats

The localized GMT formats come in two widths "O" (which removes the minutes field if it's 0) and "OOOO" (which always contains the minutes field). The use of the GMT indicator changes according to the locale.

Field PatternsOutputNotes
"O""GMT-7"Short localized GMT format
"OOOO""GMT-07:00"Long localized GMT format

TZ // Short and Long Generic non-Location Formats

The generic non-location formats are useful for displaying a recurring wall time (e.g., events, meetings) or anywhere people do not want to be overly specific. Where either of these is unavailable, there is a fallback to the generic location format ("VVVV"), then the short localized GMT format as the final fallback.

Field PatternsOutputNotes
"v""PT"Short generic non-location format
"vvvv""Pacific Time"Long generic non-location format

TZ // Short Time Zone IDs and Exemplar City Formats

These formats provide variations of the time zone ID and often include the exemplar city. The widest of these formats, "VVVV", is useful for populating a choice list for time zones, because it supports 1-to-1 name/zone ID mapping and is more uniform than other text formats.

Field PatternsOutputNotes
"V""cavan"Short time zone ID
"VV""America/Vancouver"Long time zone ID
"VVV""Vancouver"The tz exemplar city
"VVVV""Vancouver Time"Generic location format

TZ // ISO 8601 Formats with Z for +0000

The "X"-"XXX" field patterns represent valid ISO 8601 patterns for time zone offsets in datetimes. The final two widths, "XXXX" and "XXXXX" allow for optional seconds fields. The seconds field is not supported by the ISO 8601 specification. For all of these, the ISO 8601 UTC indicator Z is used when the local time offset is 0.

Field PatternsOutputNotes
"X""-07"ISO 8601 basic format (h, optional m)
"XX""-0700"ISO 8601 basic format (h & m)
"XXX""-07:00"ISO 8601 extended format (h & m)
"XXXX""-0700"ISO 8601 basic format (h & m, optional s)
"XXXXX""-07:00"ISO 8601 extended format (h & m, optional s)

TZ // ISO 8601 Formats (no use of Z for +0000)

The "x"-"xxxxx" field patterns represent valid ISO 8601 patterns for time zone offsets in datetimes. They are similar to the "X"-"XXXXX" field patterns except that the ISO 8601 UTC indicator Z will not be used when the local time offset is 0.

Field PatternsOutputNotes
"x""-07"ISO 8601 basic format (h, optional m)
"xx""-0700"ISO 8601 basic format (h & m)
"xxx""-07:00"ISO 8601 extended format (h & m)
"xxxx""-0700"ISO 8601 basic format (h & m, optional s)
"xxxxx""-07:00"ISO 8601 extended format (h & m, optional s)

Formatting with a strptime format code

Performing custom date/time formatting with the format argument can also occur with a strptime format code. This works by constructing a string of individual format codes representing formatted date and time elements. These are all indicated with a leading %, literal characters are interpreted as any characters not starting with a % character.

First off, let's look at a few format code combinations that work well together as a strptime format. This will give us an intuition on how these generally work. We'll use the datetime "2015-06-08 23:05:37.48" for all of the examples that follow.

  • "%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 the 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)

  • "%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 the ISO 8601 standard)

  • "%C" -> "20" (the century number)

Here are the individual format codes for the 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)

Here are some extra formats that you may find useful:

  • "%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 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" 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" 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

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, 06:36 PM"
#> [2] "Friday, January 25, 2019, 01:08 AM"
#> [3] NA

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

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

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

Function ID

15-15

Function Introduced

v0.7.0 (Aug 25, 2022)

See also

The variant function intended for formatting gt table data: fmt_datetime().

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