lubridate: force_tz – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

force_tz

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

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

lubridate

Make Dealing with Dates a Little Easier

v1.7.10

GPL (>= 2)

Authors

Vitalie Spinu [aut, cre], Garrett Grolemund [aut], Hadley Wickham [aut], Ian Lyttle [ctb], Imanuel Costigan [ctb], Jason Law [ctb], Doug Mitarotonda [ctb], Joseph Larmarange [ctb], Jonathan Boiser [ctb], Chel Hee Lee [ctb], Google Inc. [ctb, cph]

Initial release