mt_cyclical_free-arithmetic: Arithmetic for underspecified cyclical time...

mt_cyclical_free-arithmeticR Documentation

Arithmetic for underspecified cyclical time (mt_cyclical_free)

Description

Underspecified cyclical time (see cyclical_time()) is a position within a cycle whose enclosing cycle is unknown, e.g. month_of_year(3) is "March of some year". Only operations that don't depend on the enclosing cycle are defined:

  • Differences: a - b between values of the same cycle is a duration() in their common chronon, the difference between their positions within the cycle (month_of_year(3) - month_of_year(1) is 2 months, and month_of_year(1) - month_of_year(3) is -2 months). This follows the linear ordering of positions within one cycle (see mt_cyclical_free-compare), for cycles of fixed and variable length alike (day_of_month(31) - day_of_month(1) is 30 days).

  • Shifts: x + n and x - n shift by n chronons, where n is a number or a duration() that is a whole number of the value's chronons with a fixed ratio (e.g. month_of_year(1) + months(2) or time_of_day(3600) + hours(2)). Shifts wrap around cycles of a fixed length (month_of_year(12) + 1 is January, day_of_week(1) - 1 is Sunday), so a + (b - a) == b. Cycles of variable length (e.g. day_of_month(), day_of_year() and week_of_year()) can't be shifted, whatever the values: day_of_month(28) + 1 is day 29, or day 1 in a non-leap February.

  • seq() follows the same rules as shifts. The sequence runs linearly within one cycle between from and to (so seq(month_of_year(11), month_of_year(2)) counts down from November to February), while sequences of a given length.out wrap around the cycle.

Everything else is an error: shifting by a duration that isn't a whole number of chronons with a fixed ratio (month_of_year(1) + days(1)), or that spans a whole cycle or more (month_of_year(1) + years(1) would move to another, unknown, year); differences between values of differing cycles, or between an underspecified value and a linear or located time point; subtracting an underspecified value from a number or duration; multiplying or dividing; and summaries that create new values, such as mean() or cumsum(). Comparisons and ordering (sort(), min(), max(), range()) are defined, see mt_cyclical_free-compare.

To do any of these, locate the value in a specific enclosing cycle (e.g. a particular month for a day of month) with time_compose(), giving linear time, e.g. time_compose(yearmonth("2024-02"), day_of_month(28)) + days(1).

Missing values stay missing.

Usage

## S4 method for signature 'mt_cyclical_free'
e1 + e2
## S4 method for signature 'mt_cyclical_free'
e1 - e2

Arguments

e1, e2

Operands, at least one an underspecified (mt_cyclical_free) vector.

Value

For differences, a duration (mt_duration). For shifts, a mt_cyclical_free vector of the same type as the underspecified operand.

See Also

mt_time-arithmetic for arithmetic on linear and located cyclical time points.

Examples

month_of_year(12) + 1L
month_of_year(1) - months(1)
day_of_week(6) + 0:3
month_of_year(3) - month_of_year(1)
day_of_month(31) - day_of_month(1)
seq(day_of_week(6), by = 1, length.out = 4)

# Cycles of variable length can't be shifted until located
try(day_of_month(28) + 1L)
time_compose(yearmonth("2024-02"), day_of_month(28)) + days(1)


mixtime documentation built on Nov. 18, 2026, 5:08 p.m.