Date-arithmetic {clock}

Arithmetic: date

Description

These are Date methods for the arithmetic generics.

Calendrical based arithmetic:

These functions convert to a year-month-day calendar, perform the arithmetic, then convert back to a Date.

• add_years()

• add_quarters()

• add_months()

Time point based arithmetic:

These functions convert to a time point, perform the arithmetic, then convert back to a Date.

• add_weeks()

• add_days()

Usage

## S3 method for class 'Date'
add_years(x, n, ..., invalid = NULL)

## S3 method for class 'Date'
add_quarters(x, n, ..., invalid = NULL)

## S3 method for class 'Date'
add_months(x, n, ..., invalid = NULL)

## S3 method for class 'Date'
add_weeks(x, n, ...)

## S3 method for class 'Date'
add_days(x, n, ...)

Arguments

x

⁠[Date]⁠

A Date vector.

n

⁠[integer / clock_duration]⁠

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. n may be negative to subtract units of duration.

...

These dots are for future extensions and must be empty.

invalid

⁠[character(1) / NULL]⁠

One of the following invalid date resolution strategies:

• "previous": The previous valid instant in time.

• "previous-day": The previous valid day in time, keeping the time of day.

• "next": The next valid instant in time.

• "next-day": The next valid day in time, keeping the time of day.

• "overflow": Overflow by the number of days that the input is invalid by. Time of day is dropped.

• "overflow-day": Overflow by the number of days that the input is invalid by. Time of day is kept.

• "NA": Replace invalid dates with NA.

• "error": Error on invalid dates.

Using either "previous" or "next" is generally recommended, as these two strategies maintain the relative ordering between elements of the input.

If NULL, defaults to "error".

If getOption("clock.strict") is TRUE, invalid must be supplied and cannot be NULL. This is a convenient way to make production code robust to invalid dates.

Details

Adding a single quarter with add_quarters() is equivalent to adding 3 months.

x and n are recycled against each other using tidyverse recycling rules.

Only calendrical based arithmetic has the potential to generate invalid dates. Time point based arithmetic, like adding days, will always generate a valid date.

Value

x after performing the arithmetic.

Examples

x <- as.Date("2019-01-01")

add_years(x, 1:5)

y <- as.Date("2019-01-31")

# Adding 1 month to `y` generates an invalid date. Unlike year-month-day
# types, R's native Date type 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 to
# the previous valid date - i.e. the end of the month.
add_months(y, 1:2, invalid = "previous")