posixt-arithmetic {clock} | R Documentation |
These are POSIXct/POSIXlt methods for the arithmetic generics.
Calendrical based arithmetic:
These functions convert to a naive-time, then to a year-month-day, perform the arithmetic, then convert back to a date-time.
add_years()
add_quarters()
add_months()
Naive-time based arithmetic:
These functions convert to a naive-time, perform the arithmetic, then convert back to a date-time.
add_weeks()
add_days()
Sys-time based arithmetic:
These functions convert to a sys-time, perform the arithmetic, then convert back to a date-time.
add_hours()
add_minutes()
add_seconds()
## S3 method for class 'POSIXt'
add_years(x, n, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
add_quarters(x, n, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
add_months(x, n, ..., invalid = NULL, nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
add_weeks(x, n, ..., nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
add_days(x, n, ..., nonexistent = NULL, ambiguous = x)
## S3 method for class 'POSIXt'
add_hours(x, n, ...)
## S3 method for class 'POSIXt'
add_minutes(x, n, ...)
## S3 method for class 'POSIXt'
add_seconds(x, n, ...)
x |
A date-time vector. |
n |
An integer vector to be converted to a duration, or a duration
corresponding to the arithmetic function being used. This corresponds
to the number of duration units to add. |
... |
These dots are for future extensions and must be empty. |
invalid |
One of the following invalid date resolution strategies:
Using either If If |
nonexistent |
One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input:
Using either If If |
ambiguous |
One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input:
Alternatively, Finally, If If |
Adding a single quarter with add_quarters()
is equivalent to adding
3 months.
x
and n
are recycled against each other.
Calendrical based arithmetic has the potential to generate invalid dates (like the 31st of February), nonexistent times (due to daylight saving time gaps), and ambiguous times (due to daylight saving time fallbacks).
Naive-time based arithmetic will never generate an invalid date, but may generate a nonexistent or ambiguous time (i.e. you added 1 day and landed in a daylight saving time gap).
Sys-time based arithmetic operates in the UTC time zone, which means that it will never generate any invalid dates or nonexistent / ambiguous times.
The conversion from POSIXct/POSIXlt to the corresponding clock type uses
a "best guess" about whether you want to do the arithmetic using a naive-time
or a sys-time. For example, when adding months, you probably want to
retain the printed time when converting to a year-month-day to perform
the arithmetic, so the conversion goes through naive-time. However,
when adding smaller units like seconds, you probably want
"2020-03-08 01:59:59" + 1 second
in the America/New_York time zone to
return "2020-03-08 03:00:00"
, taking into account the fact that there
was a daylight saving time gap. This requires doing the arithmetic in
sys-time, so that is what clock converts to. If you disagree with this
heuristic for any reason, you can take control and perform the conversions
yourself. For example, you could convert the previous example to a
naive-time instead of a sys-time manually with as_naive_time()
, add
1 second giving "2020-03-08 02:00:00"
, then convert back to a
POSIXct/POSIXlt, dealing with the nonexistent time that gets created by
using the nonexistent
argument of as.POSIXct()
.
x
after performing the arithmetic.
x <- as.POSIXct("2019-01-01", tz = "America/New_York")
add_years(x, 1:5)
y <- as.POSIXct("2019-01-31 00:30:00", tz = "America/New_York")
# Adding 1 month to `y` generates an invalid date. Unlike year-month-day
# types, R's native date-time types cannot handle invalid dates, so you must
# resolve them immediately. If you don't you get an error:
try(add_months(y, 1:2))
add_months(as_year_month_day(y), 1:2)
# Resolve invalid dates by specifying an invalid date resolution strategy
# with the `invalid` argument. Using `"previous"` here sets the date-time to
# the previous valid moment in time - i.e. the end of the month. The
# time is set to the last moment in the day to retain the relative ordering
# within your input. If you are okay with potentially losing this, and
# want to retain your time of day, you can use `"previous-day"` to set the
# date-time to the previous valid day, while keeping the time of day.
add_months(y, 1:2, invalid = "previous")
add_months(y, 1:2, invalid = "previous-day")