lubridate (version 1.7.9)

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

Value

a POSIXct object in the updated time zone

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.

See Also

with_tz(), local_time()

Examples

# NOT RUN {
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"))
# }