stri_datetime_format {stringi}R Documentation

Date and Time Formatting and Parsing

Description

These functions convert a given date/time object to a character vector, or vice versa.

Usage

stri_datetime_format(
  time,
  format = "uuuu-MM-dd HH:mm:ss",
  tz = NULL,
  locale = NULL
)

stri_datetime_parse(
  str,
  format = "uuuu-MM-dd HH:mm:ss",
  lenient = FALSE,
  tz = NULL,
  locale = NULL
)

Arguments

time

an object of class POSIXct with date-time data to be formatted (as.POSIXct will be called on character vectors and objects of class POSIXlt, Date, and factor)

format

character vector, see Details; see also stri_datetime_fstr

tz

NULL or '' for the default time zone or a single string with a timezone identifier, see stri_timezone_get and stri_timezone_list

locale

NULL or '' for the default locale, or a single string with locale identifier; a non-Gregorian calendar may be specified by setting the @calendar=name keyword

str

character vector with strings to be parsed

lenient

single logical value; should date/time parsing be lenient?

Details

Vectorized over format and time or str.

When parsing strings, unspecified date-time fields (e.g., seconds where only hours and minutes are given) are based on today's midnight in the local time zone (for compatibility with strptime).

By default, stri_datetime_format (for compatibility with the strftime function) formats a date/time object using the current default time zone.

format may be one of DT_STYLE or DT_relative_STYLE, where DT is equal to date, time, or datetime, and STYLE is equal to full, long, medium, or short. This gives a locale-dependent date and/or time format. Note that currently ICU does not support relative time formats, thus this flag is currently ignored in such a context.

Otherwise, format is a pattern: a string where specific sequences of characters are replaced with date/time data from a calendar when formatting or used to generate data for a calendar when parsing. For example, y stands for 'year'. Characters may be used multiple times: yy might produce 99, whereas yyyy yields 1999. For most numerical fields, the number of characters specifies the field width. For example, if h is the hour, h might produce 5, but hh yields 05. For some characters, the count specifies whether an abbreviated or full form should be used.

Two single quotes represent a literal single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way (except for two adjacent single quotes). Otherwise, all ASCII letters from a to z and A to Z are reserved as syntax characters, and require quoting if they are to represent literal characters. In addition, certain ASCII punctuation characters may become available in the future (e.g., : being interpreted as the time separator and / as a date separator, and replaced by respective locale-sensitive characters in display).

Symbol Meaning Example(s) Output
G era designator G, GG, or GGG AD
GGGG Anno Domini
GGGGG A
y year yy 96
y or yyyy 1996
u extended year u 4601
U cyclic year name, as in Chinese lunar calendar U
r related Gregorian year r 1996
Q quarter Q or QQ 02
QQQ Q2
QQQQ 2nd quarter
QQQQQ 2
q Stand Alone quarter q or qq 02
qqq Q2
qqqq 2nd quarter
qqqqq 2
M month in year M or MM 09
MMM Sep
MMMM September
MMMMM S
L Stand Alone month in year L or LL 09
LLL Sep
LLLL September
LLLLL S
w week of year w or ww 27
W week of month W 2
d day in month d 2
dd 02
D day of year D 189
F day of week in month F 2 (2nd Wed in July)
g modified Julian day g 2451334
E day of week E, EE, or EEE Tue
EEEE Tuesday
EEEEE T
EEEEEE Tu
e local day of week e or ee 2
example: if Monday is 1st day, Tuesday is 2nd ) eee Tue
eeee Tuesday
eeeee T
eeeeee Tu
c Stand Alone local day of week c or cc 2
ccc Tue
cccc Tuesday
ccccc T
cccccc Tu
a am/pm marker a pm
h hour in am/pm (1~12) h 7
hh 07
H hour in day (0~23) H 0
HH 00
k hour in day (1~24) k 24
kk 24
K hour in am/pm (0~11) K 0
KK 00
m minute in hour m 4
mm 04
s second in minute s 5
ss 05
S fractional second - truncates (like other time fields) S 2
to the count of letters when formatting. Appends SS 23
zeros if more than 3 letters specified. Truncates at SSS 235
three significant digits when parsing. SSSS 2350
A milliseconds in day A 61201235
z Time Zone: specific non-location z, zz, or zzz PDT
zzzz Pacific Daylight Time
Z Time Zone: ISO8601 basic hms? / RFC 822 Z, ZZ, or ZZZ -0800
Time Zone: long localized GMT (=OOOO) ZZZZ GMT-08:00
Time Zone: ISO8601 extended hms? (=XXXXX) ZZZZZ -08:00, -07:52:58, Z
O Time Zone: short localized GMT O GMT-8
Time Zone: long localized GMT (=ZZZZ) OOOO GMT-08:00
v Time Zone: generic non-location v PT
(falls back first to VVVV) vvvv Pacific Time or Los Angeles Time
V Time Zone: short time zone ID V uslax
Time Zone: long time zone ID VV America/Los_Angeles
Time Zone: time zone exemplar city VVV Los Angeles
Time Zone: generic location (falls back to OOOO) VVVV Los Angeles Time
X Time Zone: ISO8601 basic hm?, with Z for 0 X -08, +0530, Z
Time Zone: ISO8601 basic hm, with Z XX -0800, Z
Time Zone: ISO8601 extended hm, with Z XXX -08:00, Z
Time Zone: ISO8601 basic hms?, with Z XXXX -0800, -075258, Z
Time Zone: ISO8601 extended hms?, with Z XXXXX -08:00, -07:52:58, Z
x Time Zone: ISO8601 basic hm?, without Z for 0 x -08, +0530
Time Zone: ISO8601 basic hm, without Z xx -0800
Time Zone: ISO8601 extended hm, without Z xxx -08:00
Time Zone: ISO8601 basic hms?, without Z xxxx -0800, -075258
Time Zone: ISO8601 extended hms?, without Z xxxxx -08:00, -07:52:58
' escape for text ' (nothing)
' ' two single quotes produce one ' ' '

Note that any characters in the pattern that are not in the ranges of [a-z] and [A-Z] will be treated as quoted text. For instance, characters like :, ., (a space), # and @ will appear in the resulting time text even if they are not enclosed within single quotes. The single quote is used to “escape” the letters. Two single quotes in a row, inside or outside a quoted sequence, represent a “real” single quote.

A few examples:

Example Pattern Result
yyyy.MM.dd 'at' HH:mm:ss zzz 2015.12.31 at 23:59:59 GMT+1
EEE, MMM d, ''yy czw., gru 31, '15
h:mm a 11:59 PM
hh 'o''clock' a, zzzz 11 o'clock PM, GMT+01:00
K:mm a, z 11:59 PM, GMT+1
yyyyy.MMMM.dd GGG hh:mm aaa 2015.grudnia.31 n.e. 11:59 PM
uuuu-MM-dd'T'HH:mm:ssZ 2015-12-31T23:59:59+0100 (the ISO 8601 guideline)

Value

stri_datetime_format returns a character vector.

stri_datetime_parse returns an object of class POSIXct.

Author(s)

Marek Gagolewski and other contributors

References

Formatting Dates and Times – ICU User Guide, https://unicode-org.github.io/icu/userguide/format_parse/datetime/

See Also

The official online manual of stringi at https://stringi.gagolewski.com/

Gagolewski M., stringi: Fast and portable character string processing in R, Journal of Statistical Software 103(2), 2022, 1-59, doi:10.18637/jss.v103.i02

Other datetime: stri_datetime_add(), stri_datetime_create(), stri_datetime_fields(), stri_datetime_fstr(), stri_datetime_now(), stri_datetime_symbols(), stri_timezone_get(), stri_timezone_info(), stri_timezone_list()

Examples

x <- c('2015-02-28', '2015-02-29')
stri_datetime_parse(x, 'yyyy-MM-dd')
stri_datetime_parse(x, 'yyyy-MM-dd', lenient=TRUE)
stri_datetime_parse(x %s+% " 17:13", "yyyy-MM-dd HH:mm")
stri_datetime_parse('19 lipca 2015', 'date_long', locale='pl_PL')
stri_datetime_format(stri_datetime_now(), 'datetime_relative_medium')
[Package stringi version 1.8.4 Index]