tinterval: Time Intervals
In tind: A Common Representation of Time Indices of Different Types

tinterval

R Documentation

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 class 'character'
as.tinterval(x, sep, ...)

## S3 method for class 'tinterval'
as.tinterval(x, type = NULL, tz = NULL, ...)

## S3 method for class 'list'
as.tinterval(x, ...)

## S3 method for class 'data.frame'
as.tinterval(x, ...)

## S3 method for class 'tinterval'
as.character(x, ...)

## S3 method for class 'tinterval'
format(x, sep = " -- ", open = "...", aux = TRUE, empty = "-", ...)

## S3 method for class 'tinterval'
as.list(x, ...)

## S3 method for class 'tinterval'
as.data.frame(x, ...)

## S3 method for class 'tinterval'
x[i]

## S3 method for class 'tinterval'
x[[i]]

## S3 replacement method for class 'tinterval'
x[i] <- value

## S3 replacement method for class 'tinterval'
x[[i]] <- value

## S3 method for class 'tinterval'
c(...)

## S3 method for class 'tinterval'
print(x, ...)

## S3 method for class 'tinterval'
summary(object, ...)

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.

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

Examples

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

tind documentation built on Dec. 28, 2025, 1:06 a.m.