R: Sequences: date

date-sequence {clock} | R Documentation

## Sequences: date

### Description

This is a Date method for the `date_seq()` generic.

`date_seq()` generates a date (Date) sequence.

When calling `date_seq()`, exactly two of the following must be specified:

- `to`

- `by`

- `total_size`

### Usage

    ## S3 method for class 'Date'
    date_seq(from, ..., to = NULL, by = NULL, total_size = NULL, invalid = NULL)

### Arguments

`from` | `[Date(1)]` A date to start the sequence from. `from` is always included in the result.
`...` | These dots are for future extensions and must be empty.
`to` | `[Date(1) / NULL]` A date to stop the sequence at. `to` is only included in the result if the resulting sequence divides the distance between `from` and `to` exactly. If `to` is supplied along with `by`, all components of `to` more precise than the precision of `by` must match `from` exactly. For example, if `by = duration_months(1)`, the day component of `to` must match the day component of `from`. This ensures that the generated sequence is, at a minimum, a weakly monotonic sequence of dates.
`by` | `[integer(1) / clock_duration(1) / NULL]` The unit to increment the sequence by. If `to < from`, then `by` must be positive. If `to > from`, then `by` must be negative. If `by` is an integer, it is equivalent to `duration_days(by)`. If `by` is a duration, it is allowed to have a precision of: year quarter month week day
`total_size` | `[positive integer(1) / NULL]` The size of the resulting sequence. If specified alongside `to`, this must generate a non-fractional sequence between `from` and `to`.
`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.

### Value

A date vector.

### Examples

    from <- date_build(2019, 1)
    to <- date_build(2019, 4)

    # Defaults to daily sequence
    date_seq(from, to = to, by = 7)

    # Use durations to change to monthly or yearly sequences
    date_seq(from, to = to, by = duration_months(1))
    date_seq(from, by = duration_years(-2), total_size = 3)

    # Note that components of `to` more precise than the precision of `by`
    # must match `from` exactly. For example, this is not well defined:
    from <- date_build(2019, 5, 2)
    to <- date_build(2025, 7, 5)
    try(date_seq(from, to = to, by = duration_years(1)))

    # The month and day components of `to` must match `from`
    to <- date_build(2025, 5, 2)
    date_seq(from, to = to, by = duration_years(1))

    # ---------------------------------------------------------------------------

    # Invalid dates must be resolved with the `invalid` argument
    from <- date_build(2019, 1, 31)
    to <- date_build(2019, 12, 31)

    try(date_seq(from, to = to, by = duration_months(1)))
    date_seq(from, to = to, by = duration_months(1), invalid = "previous")

    # Compare this to the base R result, which is often a source of confusion
    seq(from, to = to, by = "1 month")

    # This is equivalent to the overflow invalid resolution strategy
    date_seq(from, to = to, by = duration_months(1), invalid = "overflow")

    # ---------------------------------------------------------------------------

    # Usage of `to` and `total_size` must generate a non-fractional sequence
    # between `from` and `to`
    from <- date_build(2019, 1, 1)
    to <- date_build(2019, 1, 4)

    # These are fine
    date_seq(from, to = to, total_size = 2)
    date_seq(from, to = to, total_size = 4)

    # But this is not!
    try(date_seq(from, to = to, total_size = 3))

[Package clock version 0.4.1 Index]