naive_time_info() retrieves a set of low-level information generally not required for most date-time manipulations. It is used implicitly by as_zoned_time() when converting from a naive-time.

It returns a data frame with the following columns:

  • type: A character vector containing one of:

    • "unique": The naive-time maps uniquely to a zoned-time that can be created with zone.

    • "nonexistent": The naive-time does not exist as a zoned-time that can be created with zone.

    • "ambiguous": The naive-time exists twice as a zoned-time that can be created with zone.

  • first: A sys_time_info() data frame.

  • second: A sys_time_info() data frame.

type == "unique"

  • first will be filled out with sys-info representing daylight saving time information for that time point in zone.

  • second will contain only NA values, as there is no ambiguity to represent information for.

type == "nonexistent"

  • first will be filled out with the sys-info that ends just prior to x.

  • second will be filled out with the sys-info that begins just after x.

type == "ambiguous"

  • first will be filled out with the sys-info that ends just after x.

  • second will be filled out with the sys-info that starts just before x.

naive_time_info(x, zone)

Arguments

x

[clock_naive_time]

A naive-time.

zone

[character]

A valid time zone name.

Unlike most functions in clock, in naive_time_info() zone is vectorized and is recycled against x.

Value

A data frame of low level information.

Details

If the tibble package is installed, it is recommended to convert the output to a tibble with as_tibble(), as that will print the df-cols much nicer.

Examples

library(vctrs) x <- year_month_day(1970, 04, 26, 02, 30, 00) x <- as_naive_time(x) # Maps uniquely to a time in London naive_time_info(x, "Europe/London")
#> type first.begin first.end first.offset first.dst #> 1 unique 1968-10-26 23:00:00 1971-10-31 02:00:00 3600 FALSE #> first.abbreviation second.begin second.end second.offset second.dst #> 1 BST <NA> <NA> <NA> NA #> second.abbreviation #> 1 <NA>
# This naive-time never existed in New York! # A DST gap jumped the time from 01:59:59 -> 03:00:00, # skipping the 2 o'clock hour zone <- "America/New_York" info <- naive_time_info(x, zone) info
#> type first.begin first.end first.offset first.dst #> 1 nonexistent 1969-10-26 06:00:00 1970-04-26 07:00:00 -18000 FALSE #> first.abbreviation second.begin second.end second.offset #> 1 EST 1970-04-26 07:00:00 1970-10-25 06:00:00 -14400 #> second.dst second.abbreviation #> 1 TRUE EDT
# You can recreate various `nonexistent` strategies with this info as_zoned_time(x, zone, nonexistent = "roll-forward")
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 03:00:00-04:00"
as_zoned_time(info$first$end, zone)
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 03:00:00-04:00"
as_zoned_time(x, zone, nonexistent = "roll-backward")
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 01:59:59-05:00"
as_zoned_time(info$first$end - 1, zone)
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 01:59:59-05:00"
as_zoned_time(x, zone, nonexistent = "shift-forward")
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 03:30:00-04:00"
as_zoned_time(as_sys_time(x) - info$first$offset, zone)
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 03:30:00-04:00"
as_zoned_time(x, zone, nonexistent = "shift-backward")
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 01:30:00-05:00"
as_zoned_time(as_sys_time(x) - info$second$offset, zone)
#> <zoned_time<second><America/New_York>[1]> #> [1] "1970-04-26 01:30:00-05:00"
# --------------------------------------------------------------------------- # Normalizing to UTC # Imagine you had the following printed times, and knowledge that they # are to be interpreted as in the corresponding time zones df <- data_frame( x = c("2020-01-05 02:30:00", "2020-06-03 12:20:05"), zone = c("America/Los_Angeles", "Europe/London") ) # The times are assumed to be naive-times, i.e. if you lived in the `zone` # at the moment the time was recorded, then you would have seen that time # printed on the clock. Currently, these are strings. To convert them to # a time based type, you'll have to acknowledge that R only lets you have # 1 time zone in a vector of date-times at a time. So you'll need to # normalize these naive-times. The easiest thing to normalize them to # is UTC. df$naive <- naive_time_parse(df$x) # Get info about the naive times using a vector of zones info <- naive_time_info(df$naive, df$zone) info
#> type first.begin first.end first.offset first.dst #> 1 unique 2019-11-03 09:00:00 2020-03-08 10:00:00 -28800 FALSE #> 2 unique 2020-03-29 01:00:00 2020-10-25 01:00:00 3600 TRUE #> first.abbreviation second.begin second.end second.offset second.dst #> 1 PST <NA> <NA> <NA> NA #> 2 BST <NA> <NA> <NA> NA #> second.abbreviation #> 1 <NA> #> 2 <NA>
# We'll assume that some system generated these naive-times with no # chance of them ever being nonexistent or ambiguous. So now all we have # to do is use the offset to convert the naive-time to a sys-time. The # relationship used is: # offset = naive_time - sys_time df$sys <- as_sys_time(df$naive) - info$first$offset df
#> x zone naive #> 1 2020-01-05 02:30:00 America/Los_Angeles 2020-01-05 02:30:00 #> 2 2020-06-03 12:20:05 Europe/London 2020-06-03 12:20:05 #> sys #> 1 2020-01-05 10:30:00 #> 2 2020-06-03 11:20:05
# At this point, both times are in UTC. From here, you can convert them # both to either America/Los_Angeles or Europe/London as required. as_zoned_time(df$sys, "America/Los_Angeles")
#> <zoned_time<second><America/Los_Angeles>[2]> #> [1] "2020-01-05 02:30:00-08:00" "2020-06-03 04:20:05-07:00"
as_zoned_time(df$sys, "Europe/London")
#> <zoned_time<second><Europe/London>[2]> #> [1] "2020-01-05 10:30:00+00:00" "2020-06-03 12:20:05+01:00"