zoned-parsing {clock} R Documentation

## Parsing: zoned-time

### Description

There are two parsers into a zoned-time, zoned_time_parse_complete() and zoned_time_parse_abbrev().

#### zoned_time_parse_complete()

zoned_time_parse_complete() is a parser for complete date-time strings, like "2019-01-01T00:00:00-05:00[America/New_York]". A complete date-time string has both the time zone offset and full time zone name in the string, which is the only way for the string itself to contain all of the information required to construct a zoned-time. Because of this, zoned_time_parse_complete() requires both the ⁠%z⁠ and ⁠%Z⁠ commands to be supplied in the format string.

The default options assume that x should be parsed at second precision, using a format string of "%Y-%m-%dT%H:%M:%S%Ez[%Z]". This matches the default result from calling format() on a zoned-time. Additionally, this format matches the de-facto standard extension to RFC 3339 for creating completely unambiguous date-times.

#### zoned_time_parse_abbrev()

zoned_time_parse_abbrev() is a parser for date-time strings containing only a time zone abbreviation, like "2019-01-01 00:00:00 EST". The time zone abbreviation is not enough to identify the full time zone name that the date-time belongs to, so the full time zone name must be supplied as the zone argument. However, the time zone abbreviation can help with resolving ambiguity around daylight saving time fallbacks.

For zoned_time_parse_abbrev(), ⁠%Z⁠ must be supplied and is interpreted as the time zone abbreviation rather than the full time zone name.

If used, the ⁠%z⁠ command must parse correctly, but its value will be completely ignored.

The default options assume that x should be parsed at second precision, using a format string of "%Y-%m-%d %H:%M:%S %Z". This matches the default result from calling print() or format(usetz = TRUE) on a POSIXct date-time.

### Usage

zoned_time_parse_complete(
x,
...,
format = NULL,
precision = "second",
locale = clock_locale()
)

zoned_time_parse_abbrev(
x,
zone,
...,
format = NULL,
precision = "second",
locale = clock_locale()
)

### Details

If zoned_time_parse_complete() is given input that is length zero, all NAs, or completely fails to parse, then no time zone will be able to be determined. In that case, the result will use "UTC".

If your date-time strings contain time zone offsets (like -04:00), but not the full time zone name, you might need sys_time_parse().

If your date-time strings don't contain time zone offsets or the full time zone name, you might need to use naive_time_parse(). From there, if you know the time zone that the date-times are supposed to be in, you can convert to a zoned-time with as_zoned_time().

A zoned-time.

### Full Precision Parsing

It is highly recommended to parse all of the information in the date-time string into a type at least as precise as the string. For example, if your string has fractional seconds, but you only require seconds, specify a sub-second precision, then round to seconds manually using whatever convention is appropriate for your use case. Parsing such a string directly into a second precision result is ambiguous and undefined, and is unlikely to work as you might expect.

### Examples

library(magrittr)

zoned_time_parse_complete("2019-01-01T01:02:03-05:00[America/New_York]")

zoned_time_parse_complete(
"January 21, 2019 -0500 America/New_York",
format = "%B %d, %Y %z %Z"
)

# Nanosecond precision
x <- "2019/12/31 01:05:05.123456700-05:00[America/New_York]"
zoned_time_parse_complete(
x,
format = "%Y/%m/%d %H:%M:%S%Ez[%Z]",
precision = "nanosecond"
)

# The %z offset must correspond to the true offset that would be used
# if the input was parsed as a naive-time and then converted to a zoned-time
# with as_zoned_time(). For example, the time that was parsed above used an
# offset of -05:00. We can confirm that this is correct with:
year_month_day(2019, 1, 1, 1, 2, 3) %>%
as_naive_time() %>%
as_zoned_time("America/New_York")

# So the following would not parse correctly
zoned_time_parse_complete("2019-01-01T01:02:03-04:00[America/New_York]")

# %z is useful for breaking ties in otherwise ambiguous times. For example,
# these two times are on either side of a daylight saving time fallback.
# Without the %z offset, you wouldn't be able to tell them apart!
x <- c(
"1970-10-25T01:30:00-04:00[America/New_York]",
"1970-10-25T01:30:00-05:00[America/New_York]"
)

zoned_time_parse_complete(x)

# If you have date-time strings with time zone abbreviations,
# zoned_time_parse_abbrev() should be able to help. The zone must be
# provided, because multiple countries may use the same time zone
# abbreviation. For example:
x <- "1970-01-01 02:30:30 IST"

# IST = India Standard Time
zoned_time_parse_abbrev(x, "Asia/Kolkata")

# IST = Israel Standard Time
zoned_time_parse_abbrev(x, "Asia/Jerusalem")

# The time zone abbreviation is mainly useful for resolving ambiguity
# around daylight saving time fallbacks. Without the abbreviation, these
# date-times would be ambiguous.
x <- c(
"1970-10-25 01:30:00 EDT",
"1970-10-25 01:30:00 EST"
)
zoned_time_parse_abbrev(x, "America/New_York")

[Package clock version 0.6.1 Index]