force_tz

0th

Percentile

Replace time zone to create new date-time

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.

Keywords
manip, chron
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()

Aliases
  • force_tz
  • force_tzs
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"))
# }
Documentation reproduced from package lubridate, version 1.7.4, License: GPL (>= 2)

Community examples

Looks like there are no examples yet.