R: Info: naive-time

naive_time_info {clock} | R Documentation

## Info: naive-time

### Description

`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`.

### Usage

    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`.

### 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.

### Value

A data frame of low level information.

### 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")

    # 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

    # You can recreate various `nonexistent` strategies with this info
    as_zoned_time(x, zone, nonexistent = "roll-forward")
    as_zoned_time(info$first$end, zone)

    as_zoned_time(x, zone, nonexistent = "roll-backward")
    as_zoned_time(info$first$end - 1, zone)

    as_zoned_time(x, zone, nonexistent = "shift-forward")
    as_zoned_time(as_sys_time(x) - info$first$offset, zone)

    as_zoned_time(x, zone, nonexistent = "shift-backward")
    as_zoned_time(as_sys_time(x) - info$second$offset, zone)

    # ---------------------------------------------------------------------------
    # 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

    # 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

    # 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")
    as_zoned_time(df$sys, "Europe/London")

[Package clock version 0.5.0 Index]