time_add {timechange} | R Documentation |
Add periods to date-time objects. Periods track the change in the "clock time" between two civil times. They are measured in common civil time units: years, months, days, hours, minutes, and seconds.
Arithmetic operations with multiple period units (years, months
etc) are applied in decreasing size order, from year to second. Thus
time_add(x, months = 1, days = 3)
first adds 1 to x
and then 3
days.
Generally period arithmetic is undefined due to the irregular nature of civil time and complexities with DST transitions. 'timechange' allows for a refined control of what happens when an addition of irregular periods (years, months, days) results in "unclear" date.
Let's start with an example. What happens when you add "1 month 3 days" to
"2000-01-31 01:02:03"? 'timechange' operates by applying larger
periods first. First months are added1 + 1 = February
which results in
non-existent time of 2000-02-31 01:02:03
. Here the roll_month
adjustment kicks in:
skip
- no adjustment is done to the simple arithmetic operations (the
gap is skipped as if it's not there. Thus, 2000-01-31 01:02:03 + 1 month + 3 days
is equivalent to 2000-01-01 01:02:03 + 1 month + 31 days + 3 days
resulting in 2000-03-05 01:02:03
.
NA
- if any of the intermediate additions result in non-existent dates
NA
is produced. This is how arithmetic in lubridate
operates.
boundary
- if an intermediate computation falls in a gap, the date is
adjusted to the next valid time. Thus, 2000-01-31 01:02:03 + month = 2000-03-01 00:00:00
.
next
- is like boundary
but preserves the smaller units. Thus,
2000-01-31 01:02:03 + 1 month = 2000-03-01 01:02:03
.
prev
- is like next
but instead of rolling forward to the first day of
the month, it rolls back to the last valid day of the previous month. Thus,
2000-01-31 01:02:03 + 1 month = 2000-02-28 01:02:03
. This is the default.
time_add(time, periods = NULL, years = NULL, months = NULL, weeks = NULL, days = NULL, hours = NULL, minutes = NULL, seconds = NULL, roll_month = "last", roll_dst = "first") time_subtract(time, periods = NULL, years = NULL, months = NULL, weeks = NULL, days = NULL, hours = NULL, minutes = NULL, seconds = NULL, roll_month = "last", roll_dst = "last")
time |
date-time object |
periods |
string of units to add/subtract (not yet implemented) or a
named list of the form |
years, months, weeks, days, hours, minutes, seconds |
Units to be added to
|
roll_month |
controls how addition of months and years behaves when standard arithmetic rules exceed limits of the resulting date's month. See "Details" for the description of possible values. |
roll_dst |
controls how to adjust the updated time if it falls within a DST transition intervals. See the "Details". |
# Addition ## Month gap x <- as.POSIXct("2000-01-31 01:02:03", tz = "America/Chicago") time_add(x, months = 1, roll_month = "first") time_add(x, months = 1, roll_month = "last") time_add(x, months = 1, roll_month = "boundary") time_add(x, months = 1, roll_month = "skip") time_add(x, months = 1, roll_month = "NA") time_add(x, months = 1, days = 3, roll_month = "first") time_add(x, months = 1, days = 3, roll_month = "last") time_add(x, months = 1, days = 3, roll_month = "boundary") time_add(x, months = 1, days = 3, roll_month = "skip") time_add(x, months = 1, days = 3, roll_month = "NA") ## DST gap x <- as.POSIXlt("2010-03-14 01:02:03", tz = "America/Chicago") time_add(x, hours = 1, minutes = 50, roll_dst = "first") time_add(x, hours = 1, minutes = 50, roll_dst = "last") time_add(x, hours = 1, minutes = 50, roll_dst = "boundary") time_add(x, hours = 1, minutes = 50, roll_dst = "skip") time_add(x, hours = 1, minutes = 50, roll_dst = "NA") # SUBTRACTION ## Month gap x <- as.POSIXct("2000-03-31 01:02:03", tz = "America/Chicago") time_subtract(x, months = 1, roll_month = "first") time_subtract(x, months = 1, roll_month = "last") time_subtract(x, months = 1, roll_month = "boundary") time_subtract(x, months = 1, roll_month = "skip") time_subtract(x, months = 1, roll_month = "NA") time_subtract(x, months = 1, days = 3, roll_month = "first") time_subtract(x, months = 1, days = 3, roll_month = "last") time_subtract(x, months = 1, days = 3, roll_month = "boundary") time_subtract(x, months = 1, days = 3, roll_month = "skip") time_subtract(x, months = 1, days = 3, roll_month = "NA") ## DST gap y <- as.POSIXlt("2010-03-15 01:02:03", tz = "America/Chicago") time_subtract(y, hours = 22, minutes = 50, roll_dst = "first") time_subtract(y, hours = 22, minutes = 50, roll_dst = "last") time_subtract(y, hours = 22, minutes = 50, roll_dst = "boundary") time_subtract(y, hours = 22, minutes = 50, roll_dst = "skip") time_subtract(y, hours = 22, minutes = 50, roll_dst = "NA")