R: Arithmetic: date

Date-arithmetic {clock} | R Documentation

## 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.

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")

[Package clock version 0.4.1 Index]