timechange (version 0.0.2)

time-zones: Time-zone manipulation

Description

time_at_tz returns a date-time as it would appear in a different time zone. The actual moment of time measured does not change, just the time zone it is measured in. time_at_tz defaults to the Universal Coordinated time zone (UTC) when an unrecognized time zone is supplied.

time_force_tz returns the date-time that has the same clock time as input time, but in the new time zone. Although the new date-time has the same clock time (e.g. the same values in the seconds, minutes, hours, etc.) it is a different moment of time than the input date-time. Computation is vectorized over both time and tz arguments.

time_clock_at_tz retrieves day clock time in specified time zones. Computation is vectorized over both dt and tz arguments, tz defaults to the timezone of time.

Usage

time_at_tz(time, tz = "UTC")
time_force_tz(time, tz = "UTC", tzout = tz[[1]], roll_dst = "boundary")
time_clock_at_tz(time, tz = NULL, units = "secs")

Value

a POSIXct object with the updated time zone

Arguments

time

a date-time object (POSIXct, POSIXlt, Date) or a list of date-time objects. When a list, all contained elements are updated the new list is returned.

tz

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. For time_force_tz and time_clock_at_tzs, tz can be a vector of heterogeneous time-zones, in which case time and tz arguments are paired. If time and tz lengths differ, the smaller one is recycled according with usual R conventions.

tzout

timezone of the output date-time vector. Meaningful only when tz argument is a vector of heterogenuous time-zones. This argument is necessary because R date-time vectors cannot hold elements with different time-zones.

roll_dst

same as in time_add which see.

units

passed directly to as.difftime().

Examples

x <- as.POSIXct("2009-08-07 00:00:00", tz = "America/New_York")
time_at_tz(x, "UTC")
time_force_tz(x, "UTC")
time_force_tz(x, "Europe/Amsterdam")

## DST skip:

y <- as.POSIXct("2010-03-14 02:05:05", tz = "UTC")
time_force_tz(y, "America/New_York", roll = "boundary")
time_force_tz(y, "America/New_York", roll = "first")
time_force_tz(y, "America/New_York", roll = "last")
time_force_tz(y, "America/New_York", roll = "NA")

## Heterogeneous time-zones:

x <- as.POSIXct(c("2009-08-07 00:00:01", "2009-08-07 01:02:03"), tz = "UTC")
time_force_tz(x, tz = c("America/New_York", "Europe/Amsterdam"))
time_force_tz(x, tz = c("America/New_York", "Europe/Amsterdam"), tzout = "America/New_York")

x <- as.POSIXct("2009-08-07 00:00:01", tz = "UTC")
time_force_tz(x, tz = c("America/New_York", "Europe/Amsterdam"))

## Local clock:

x <- as.POSIXct(c("2009-08-07 01:02:03", "2009-08-07 10:20:30"), tz = "UTC")
time_clock_at_tz(x, units = "secs")
time_clock_at_tz(x, units = "hours")
time_clock_at_tz(x, "Europe/Amsterdam")

x <- as.POSIXct("2009-08-07 01:02:03", tz = "UTC")
time_clock_at_tz(x, tz = c("America/New_York", "Europe/Amsterdam", "Asia/Shanghai"), unit = "hours")