tinterval: Time Intervals

Description

Objects of auxiliary tinterval class represent time intervals as pairs of time indices (start and end). Time intervals can be constructed via a call to tinterval function or using convenience %--% operator. Open-ended intervals are supported. The main applications of this class are set operations (see set-ops) and checking if a particular time index belongs to (one of) given interval(s) (see match_t).

Usage

tinterval(start = NULL, end = NULL, ...)
start %--% end
is.tinterval(x)
as.tinterval(x, ...)
# S3 method for character
as.tinterval(x, sep, ...)
# S3 method for tinterval
as.tinterval(x, type = NULL, tz = NULL, ...)
# S3 method for list
as.tinterval(x, ...)
# S3 method for data.frame
as.tinterval(x, ...)
# S3 method for tinterval
as.character(x, ...)
# S3 method for tinterval
format(x, sep = " -- ", open = "...", aux = TRUE, empty = "-", ...)
# S3 method for tinterval
as.list(x, ...)
# S3 method for tinterval
as.data.frame(x, ...)
# S3 method for tinterval
[(x, i)
# S3 method for tinterval
[[(x, i)
# S3 method for tinterval
[(x, i) <- value
# S3 method for tinterval
[[(x, i) <- value
# S3 method for tinterval
c(...)
# S3 method for tinterval
print(x, ...)
# S3 method for tinterval
summary(object, ...)

Value

tinterval, %--%, and as.tinterval return objects of tinterval class.

is.tinterval returns a logical value.

In general, methods for tinterval return objects of tinterval class.

as.character and format return character vectors.

as.list and as.data.frame return a two-element list and a two-column data frame, respectively. Names are set to c("start", "end").

print returns its argument invisibly and is used for its side effect.

summary returns an object of class c("summaryDefault", "table").

Arguments

start: an object of tind class or an R object coercible to it, beginning of the interval(s).
end: an object of tind class or an R object coercible to it, end of the interval(s).
...: objects of tinterval class to be concatenated by c or additional arguments passed to or from methods.
x: an object of tinterval class or an R object passed to as.tinterval.
sep: a character string used as separator between start and end of an interval (" -- " by default).
type: a character determining time index type or NULL.
tz: (optional) a character value determining the time zone (the default NULL is interpreted as the system time zone). See tzone documentation for information on time zones.
open: a character string used to print open interval ends ("..." by default).
aux: a logical value, if TRUE (the default), auxiliary information (time spans of intervals) is added to the output.
empty: a character string used to mark empty intervals ("-" by default).
i: an integer vector of indices or a logical vector indicating selection.
value: replacement value, should be coercible to tinterval.
object: an object of tinterval class.

Details

tinterval constructor takes two arguments: beginnings and ends of intervals. Additional arguments (passed via ...) are forwarded to as.tind method. x %--% y is equivalent to tinterval(x, y).

as.tinterval can be used to construct time intervals from character strings, two-element lists, or two-column data frames. Additionally, as.tinterval allows to convert time intervals represented using one type of time indices to time intervals represented by time indices of higher resolution (for example months to dates).

Internally, time intervals are represented by lists of two vectors. However, in operations they behave like vectors with standard indexing and replacement operators implemented.

Interval limits can be accessed via $ operator: x$start returns vector of beginnings of intervals in x and x$end vector of ends.

For discrete time indices (represented as integers, i.e. years, quarters, months, weeks, dates, arbitrary integer indices) time interval a %--% b represents all indices falling in a or after and in b or before, i.e. the set: $\{x: a \le x \wedge x \le b\} = \{a, a + 1, \dots, b - 1, b\}$. For continuous time indices (representing point in time, i.e. date-time, time of day, arbitrary numeric indices) time interval a %--% b represents all indices starting with a and before b, i.e. the set: $[a, b)$. The difference in interpretations between discrete and continuous time indices assures consistency during conversions. Consider time interval "2025-08-02" %--% "2025-08-03". This represents all date-time indices falling on one of those two days, so exactly 2025-08-02 00:00 or after but before 2025-08-04 00:00.

Examples

Run this code

td <- today()
# from today till the day after tomorrow
td %--% (td + 2)
# from today till the end of next year
td %--% (as.year(td) + 1)
# from the beginning of the year till today
as.year(td) %--% td
# 9 to 5
as.time("9am") %--% as.time("5pm")
# 7 to 9 and 4 to 6 via constructor...
tinterval(as.time(c("7am", "4pm")), as.time(c("9am", "6pm")))
# ... or more naturally via concatenation
c(as.time("7am") %--% as.time("9am"), as.time("4pm") %--% as.time("6pm"))
# automatic parsing
as.tinterval(c("2023-01 -- 2024-06", "2024-12 -- 2025-03"))
# empty time interval
as.tinterval(c("2024-01 -- 2023-06"))
# open time interval
"2024-01" %--% NULL
"2024-01" %--% as.month(NA)
as.tinterval(c("2024-01 -- ..."))
# +/- operators
(x <- tinterval(td, td + 2))
x + c(0, 7, 14)
x %+w% 0:2
# indexing
(x <- "2023-01" %--% "2024-06")
(x <- x %+y% c(0, 2, 4))
x[2:3]
x[-1]
# beginnings and ends of intervals
x$start
x$end
# conversion from interval represented by months to dates
(x <- "2025-07" %--% "2025-08")
as.tinterval(x, "d")
# conversion from interval represented by dates to date-time (see Details)
(x <- "2025-08-02" %--% "2025-08-03")
as.tinterval(x, "t")