stri_datetime_format: 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 (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

lenient

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

Details

Vectorized over format and time or str.

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

Unspecified fields (e.g., seconds where only hours and minutes are given) are filled with the ones based on current date and time.

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')
## [1] "2015-02-28 10:41:57 AEDT" NA
stri_datetime_parse(x, 'yyyy-MM-dd', lenient=TRUE)
## [1] "2015-02-28 10:41:57 AEDT" "2015-03-01 10:41:57 AEDT"
stri_datetime_parse(x %s+% " 00:00:00", "yyyy-MM-dd HH:mm:ss")
## [1] "2015-02-28 00:00:00 AEDT" NA
stri_datetime_parse('19 lipca 2015', 'date_long', locale='pl_PL')
## [1] "2015-07-19 10:41:57 AEST"
stri_datetime_format(stri_datetime_now(), 'datetime_relative_medium')
## [1] "today, 10:41:57 am"