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 = "", ...)
# S3 method for default
force_tz(time, tzone = "", roll_dst = c("NA", "post"), roll = NULL, ...)
force_tzs(
  time,
  tzones,
  tzone_out = "UTC",
  roll_dst = c("NA", "post"),
  roll = NULL
)

Value

a POSIXct object in the updated time zone

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.

...

Parameters passed to other methods.

roll_dst

is a string vector of length one or two. When two values are supplied they specify how to roll date-times when they fall into "skipped" and "repeated" DST transitions respectively. Singleton strings is replicated to the length of two. Possible values are:

* `pre` - Use the time before the transition boundary.
* `boundary` - Use the time exactly at the boundary transition.
* `post` - Use the time after the boundary transition.
* `NA` - Produce NAs when the resulting time falls inside the problematic interval.

For example `roll_dst = c("pre", "NA") indicates that for repeated intervals return the time in the earlier interval and for skipped intervals return NA.

roll

deprecated, same as roll_dst parameter.

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.

Examples

Run this code

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_dst = "NA")
force_tz(y, "America/New_York", roll_dst = "pre")
force_tz(y, "America/New_York", roll_dst = "boundary")
force_tz(y, "America/New_York", roll_dst = "post")

## DST repeat
y <- ymd_hms("2014-11-02 01:35:00", tz = "UTC")
force_tz(y, "America/New_York", roll_dst = "NA")
force_tz(y, "America/New_York", roll_dst = "pre")
force_tz(y, "America/New_York", roll_dst = "boundary")
force_tz(y, "America/New_York", roll_dst = "post")

## DST skipped and repeated
y <- ymd_hms("2010-03-14 02:05:05 UTC", "2014-11-02 01:35:00", tz = "UTC")
force_tz(y, "America/New_York", roll_dst = c("NA", "pre"))
force_tz(y, "America/New_York", roll_dst = c("boundary", "post"))

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