R: Replace time zone to create new date-time

force_tz {lubridate} | R Documentation

## Replace time zone to create new date-time

### Description

`force_tz` returns the date-time that has the same clock time as input time, but in the new time zone. `force_tzs` is the parallel version of `force_tz`, meaning that every element from `time` argument is matched with the corresponding time zone in `tzones` argument.

### Usage

    force_tz(time, tzone = "", roll = FALSE)

    force_tzs(time, tzones, tzone_out = "UTC", roll = FALSE)

### Arguments

`time` | a POSIXct, POSIXlt, Date, chron date-time object, or a data.frame object. When a data.frame all POSIXt elements of a data.frame are processed with `force_tz()` and new data.frame is returned.
`tzone` | a character string containing the time zone to convert to. R must recognize the name contained in the string as a time zone on your system.
`roll` | logical. If TRUE, and `time` falls into the DST-break, assume the next valid civil time, otherwise return NA. See examples.
`tzones` | character vector of timezones to be "enforced" on `time` time stamps. If `time` and `tzones` lengths differ, the smaller one is recycled in accordance with usual R conventions.
`tzone_out` | timezone of the returned date-time vector (for `force_tzs`).

### Details

Although the new date-time has the same clock time (e.g. the same values in the year, month, days, etc. elements) it is a different moment of time than the input date-time.

As R date-time vectors cannot hold elements with non-uniform time zones, `force_tzs` returns a vector with time zone `tzone_out`, UTC by default.

### Value

a POSIXct object in the updated time zone

### See Also

`with_tz()`, `local_time()`

### Examples

    x <- ymd_hms("2009-08-07 00:00:01", tz = "America/New_York")
    force_tz(x, "UTC")
    force_tz(x, "Europe/Amsterdam")

    ## DST skip:

    y <- ymd_hms("2010-03-14 02:05:05 UTC")
    force_tz(y, "America/New_York", roll=FALSE)
    force_tz(y, "America/New_York", roll=TRUE)

    ## Heterogeneous time-zones:

    x <- ymd_hms(c("2009-08-07 00:00:01", "2009-08-07 01:02:03"))
    force_tzs(x, tzones = c("America/New_York", "Europe/Amsterdam"))
    force_tzs(x, tzones = c("America/New_York", "Europe/Amsterdam"), tzone_out = "America/New_York")

    x <- ymd_hms("2009-08-07 00:00:01")
    force_tzs(x, tzones = c("America/New_York", "Europe/Amsterdam"))

[Package lubridate version 1.7.4 Index]