tind (version 0.2.4)

seq: Create a Sequence of Time Indices

Description

seq method for objects of tind class allows to easily construct sequences of time indices of all supported types.

Usage

# S3 method for tind
seq(from, to, by = 1, length.out = NULL, along.with = NULL, ...)

Value

An object of tind class.

Arguments

from

an object of tind class or an R object coercible to it.

to

an object of tind class or an R object coercible to it.

by

a numeric value, a tdiff, or a character string determining increment.

length.out

an integer value, the desired length.

along.with

any R object, length of this argument will be taken as the desired length.

...

(ignored) further arguments passed to or from other methods.

Details

seq method requires that exactly two of the three arguments from, to, and length.out are provided. If along.with is not NULL, its length is used as value of length.out.

by can be a number, an object of tdiff class (of length 1), or an object coercible to tdiff like "3w" denoting step by three weeks. by cannot be NA and cannot be 0 when both from and to are provided. Given both from and to, sign of by has to agree with the order of from and to. When by is a number, the underlying unit of time is assumed. For time of day and date-time indices this is always a second.

from and to can be of different types provided that conversion is possible. The result is of higher resolution. This allows to easily construct series like from begging of the month to today, from today till the end of next year, etc. See Examples.

seq.tind slightly differs from seq.Date in terms of interface and requirements with respect to arguments. Firstly, from argument can be missing (provided that to and length.out are given). Secondly, by has the default value of 1.

Both seq method for tind and seq.tind function are exported allowing for conversion to tind as in seq.tind("2025-01", "2025-12").

Examples

# sequences of dates by 1 and 2 months from now
(td <- today())
seq(td, by = "1m", length.out = 12)
seq(td, by = "2m", length.out = 6)
# sequences of dates by 1 and 2 months to now
seq(to = td, by = "1m", length.out = 12)
seq(to = td, by = "2m", length.out = 6)
# sequence of dates from the beginning of the month till today
seq(floor_t(td, "m"), td)
# same
seq(as.month(td), td)
# sequence of dates from today till the end of the next month
seq(td, as.month(td) + 1)
# sequence of date-time from now to midnight by 1 hour
(nw <- now())
seq(nw, ceiling_t(nw, "1d"), by = "1h")
# same
seq(nw, as.date(nw), by = "1h")
# sequence (date-time) from full hour to now by 2 minutes
seq(floor_t(nw, "1h"), nw, by = "2min")
# sequence (time of day) from full hour to now by 2 minutes
seq(floor_t(as.time(nw), "1h"), as.time(nw), by = "2min")
# sequence (date-time) from now down to full hour by 2 minutes
seq(nw, floor_t(nw, "1h"), by = "-2min")
# sequence (time of day) from now down to full hour by 2 minutes
seq(as.time(nw), floor_t(as.time(nw), "1h"), by = "-2min")
# sequence (date-time) of length 10 from now down by 10 seconds
seq(nw, by = -10, length.out = 10)
# sequence (time of day) of length 10 from now down by 10 seconds
seq(as.time(nw), by = -10, length.out = 10)
# explicit call to seq.tind with conversion
seq.tind("2025-01", "2025-12")
## corner cases
# from 2025-12-30 23:00 till end of 2025, note that 2025-12-31 24:00
# (that is 2025-01-01 00:00) is excluded from the result as it is in the next year
seq(as.tind("2025-12-30 23:00", tz = "UTC"), "2025", by = "5h")
# from end of 2025 down to 2025-12-30 23:00, note that 2025-12-31 24:00
# (that is 2025-01-01 00:00) is excluded from the result as it is in the next year
seq(as.tind("2025"), as.tind("2025-12-30 23:00", tz = "UTC"), by = "-5h")