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. Iftime
andtzones
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.
Examples
x <- ymd_hms("2009-08-07 00:00:01", tz = "America/New_York")
force_tz(x, "UTC")
#> [1] "2009-08-07 00:00:01 UTC"
force_tz(x, "Europe/Amsterdam")
#> [1] "2009-08-07 00:00:01 CEST"
## DST skip:
y <- ymd_hms("2010-03-14 02:05:05 UTC")
force_tz(y, "America/New_York", roll=FALSE)
#> [1] NA
force_tz(y, "America/New_York", roll=TRUE)
#> [1] "2010-03-14 03:00:00 EDT"
## 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"))
#> [1] "2009-08-07 04:00:01 UTC" "2009-08-06 23:02:03 UTC"
force_tzs(x, tzones = c("America/New_York", "Europe/Amsterdam"), tzone_out = "America/New_York")
#> [1] "2009-08-07 00:00:01 EDT" "2009-08-06 19:02:03 EDT"
x <- ymd_hms("2009-08-07 00:00:01")
force_tzs(x, tzones = c("America/New_York", "Europe/Amsterdam"))
#> [1] "2009-08-07 04:00:01 UTC" "2009-08-06 22:00:01 UTC"