Nothing
#' Base S7 class for calendars
#'
#' `mt_calendar` is the parent class of every calendar. A calendar is a named
#' list of time unit classes, and each calendar created with [new_calendar()]
#' is the single instance of its own subclass of `mt_calendar` (e.g.
#' `cal_isoweek` is an instance of class `cal_isoweek`). This allows methods to
#' dispatch on the calendar, such as formatting a shared unit differently in
#' each calendar that contains it.
#'
#' Time units record their calendar by its identifier (`"<package>::<name>"`),
#' which is resolved back to the calendar object when the unit's `@calendar`
#' is accessed. This keeps time objects small when serialised, and their
#' calendar is restored from the current definition when read back in.
#'
#' @param .data A named list of time unit classes.
#'
#' @return An S7 class object, or a calendar when called as a constructor.
#' End users should use [new_calendar()] to create calendars.
#'
#' @seealso [new_calendar()] for creating calendars, [time_calendar()] for
#' obtaining the calendar of a time object.
#'
#' @export
mt_calendar <- S7::new_class(
"mt_calendar",
parent = S7::class_list,
validator = function(self) {
units <- S7::S7_data(self)
if (length(units) > 0L && (is.null(names(units)) || any(names(units) == ""))) {
return("must contain named time units")
}
if (!all(vapply(units, is_unit_class, logical(1L)))) {
return("must contain only time unit classes")
}
}
)
# Is `x` a time unit class (an S7 class inheriting from mt_unit)?
is_unit_class <- function(x) {
while (inherits(x, "S7_class")) {
if (identical(x@name, "mt_unit") && identical(x@package, "mixtime")) {
return(TRUE)
}
x <- x@parent
}
FALSE
}
#' Base S7 class for creating new time units
#'
#' This class is the primitive class for time units, and should
#' be extended from when creating new time units. A new class
#' is typically created with [new_time_unit()] using:
#' `new_time_unit("tu_***", parent = mt_tz_unit)`
#'
#' Time units are the building blocks of calendars in mixtime. Each unit
#' represents a specific temporal component (e.g., day, month, year) and
#' can be combined using [new_calendar()] to create a calendar system.
#'
#' When creating custom calendars, define time unit classes that inherit
#' from either `mt_unit` (for standard units) or `mt_tz_unit` (for
#' timezone-aware units), then pass them as named arguments to
#' [new_calendar()]. The calendar will use these names to create
#' constructor functions accessible via `$` notation (e.g., `calendar$day(1L)`).
#'
#' @section Calendar Algebra Methods:
#'
#' Time units enable calendar arithmetic through key generic methods
#' that should be implemented for custom time units:
#'
#' * `chronon_cardinality_fixed(x, y)` - Returns the number of unit `x`
#' granules that fit within one unit `y` granule, for relationships that are
#' a constant, context-independent number (e.g., 7 days per week, 24 hours
#' per day). Prefer this over `chronon_cardinality()` whenever the
#' relationship does not depend on `at`, since it is also used to determine
#' which relationships are safe to use for [chronon_divmod()]'s graph
#' traversal.
#'
#' * `chronon_cardinality(x, y, at)` - Returns the number of `x` granule
#' that fit within one `y` granule. This is variable based on `at` (e.g.,
#' 28-31 days per month). Only implement this directly (rather than
#' `chronon_cardinality_fixed()`) when the relationship genuinely depends on
#' `at`, and pair it with a direct `chronon_divmod()` method so that the
#' relationship remains reachable during graph traversal.
#'
#' * `chronon_divmod(x, from, to)` - Converts time point `x` from granules of
#' `from` to granules of `to`, returning a list with `div` (the quotient)
#' and `mod`. This enables conversions between granules that have
#' variable cardinality (e.g., the date 2020-03-23 to the month 2020-03).
#' All conversions should be based on chronons since epoch (1970-01-01),
#' in the UTC time zone.
#'
#' These methods work together to enable mixtime to perform calendar-aware
#' arithmetic, understanding that months have variable lengths and handling
#' timezone-aware conversions.
#'
#' @param n The step size of time granule. For example, `n = 2L` is 2 time
#' units, and `cal_isoweek$week(2L)` would represent 2 weeks (a fortnight).
#' @param calendar The calendar containing the unit. Calendar constructors
#' supply this automatically.
#'
#' @return A time granule object of class `mt_unit`
#'
#' @seealso [new_calendar()] for creating calendars from time units
#'
#' @examples
#' # Create a timezone-aware unit class
#'
#' # Use these units to create a calendar
#' my_calendar <- new_calendar(
#' day = new_time_unit("tu_my_day", parent = mt_unit),
#' month = new_time_unit("tu_my_month", parent = mt_tz_unit),
#' name = "my_calendar"
#' )
#'
#' # Access unit constructors from the calendar
#' my_calendar$day(1L)
#' my_calendar$month(3L, tz = "America/New_York")
#'
#' @export
#' @rdname mt_unit
mt_unit <- S7::new_class(
"mt_unit",
properties = list(
n = S7::new_property(
class = S7::class_numeric,
default = 1L,
# Store whole-number sizes as integers, so equal granules are
# `identical()` regardless of whether `n` was computed as a double
# (e.g. `unit@n * as.numeric(duration)`).
setter = function(self, value) {
self@n <- granule_n_normalise(value)
self
}
),
calendar = S7::new_property(
# The S3 form of mt_calendar avoids embedding its class definition in
# every time unit class (the setter validates the calendar).
class = NULL | S7::new_S3_class("mixtime::mt_calendar"),
# The calendar is stored by its identifier, and resolved on access.
getter = function(self) {
calendar_resolve(attr(self, "calendar", exact = TRUE))
},
setter = function(self, value) {
attr(self, "calendar") <- calendar_id(value)
self
},
default = quote(attr(sys.function(), "cal"))
)
),
# validator = function(self) {
# if (length(self@n) != 1L) {
# paste0("@n must be length 1 <numeric> value, not length ", length(self@n), ".")
# }
# }
)
#' Time vector classes
#'
#' @description
#' The `mt_time` family are the S7 vector classes that store time points as a
#' numeric count of chronons. `mt_time` is the (internal) base class carrying
#' the `chronon` property; the common modes of time are:
#'
#' * `mt_linear` - linear time points, typically produced with [linear_time()].
#' * `mt_cyclical` - located cyclical time: positions within a `cycle` granule
#' that know their enclosing cycle, typically produced with
#' [cyclical_time()] from time points.
#' * `mt_duration` - time durations, typically produced with [duration()].
#' * `mt_cyclical_free` - underspecified cyclical time: positions within a
#' cycle whose enclosing cycle is unknown (e.g. "day 60 of the year" with no
#' year known), produced by [cyclical_time()] with bare numeric input, or
#' by [time_compose()]/[time_parse()] with no [lin()] component.
#'
#' The underlying data can be either **integer** (discrete time) or **double**
#' (continuous time). The `chronon` (and, for `mt_cyclical`, the `cycle`) are
#' time granules, the result from a [mt_unit] object.
#'
#' @param ... Passed to the parent constructor, typically `.data`: a numeric
#' vector of chronon counts (integer or double).
#' @param chronon,cycle Time granules ([mt_unit] objects) giving the unit of the
#' chronon counts and, for `mt_cyclical`, the length of the cycle.
#'
#' @return An S7 class object (used for method dispatch), or a time vector when
#' called as a constructor.
#'
#' @seealso [mt_linear()], [mt_duration()], and [mt_cyclical()] to construct
#' time vectors, and [mt_unit] for the granule type stored in `chronon`/`cycle`.
#'
#' @name mt_time-class
NULL
# Lightweight S3 carrier for the mode of time (integer or double). It exists
# *only* so S7 accepts either an integer or double inputs (an S7 base-type
# class fixes a single base type).
mt_data <- S7::new_S3_class(
"mt_time_data",
constructor = function(.data = integer()) {
structure(.data, class = "mt_time_data")
},
validator = function(self) {
if (!is.numeric(self)) {
cli::cli_abort("{.var self} must be an integer or double vector.", call. = FALSE)
}
}
)
granule_len1 <- function(value) {
if (length(value@n) != 1L) {
"must wrap a single time granule (its `@n` must be length 1)"
}
}
#' @rdname mt_time-class
#' @usage NULL
#' @export
mt_time <- S7::new_class(
"mt_time",
parent = mt_data,
properties = list(
chronon = S7::new_property(
class = mt_unit,
default = quote(mt_unit(1L)),
validator = granule_len1
)
)
)
#' @rdname mt_time-class
#' @usage NULL
#' @export
mt_linear <- S7::new_class("mt_linear", parent = mt_time)
#' @rdname mt_time-class
#' @usage NULL
#' @export
mt_duration <- S7::new_class("mt_duration", parent = mt_time)
#' @rdname mt_time-class
#' @usage NULL
#' @export
mt_cyclical <- S7::new_class(
"mt_cyclical",
parent = mt_time,
properties = list(
cycle = S7::new_property(
class = mt_unit,
default = quote(mt_unit(1L)),
validator = granule_len1
)
)
)
#' @rdname mt_time-class
#' @usage mt_cyclical_free(..., chronon = mt_unit(1L), cycle = mt_unit(1L))
#' @export
mt_cyclical_free <- S7::new_class(
"mt_cyclical_free",
parent = mt_time,
properties = list(
cycle = S7::new_property(
class = mt_unit,
default = quote(mt_unit(1L)),
validator = granule_len1
)
),
# A free value has no instant to localise, so its granules never carry a tz.
constructor = function(..., chronon = mt_unit(1L), cycle = mt_unit(1L)) {
S7::new_object(
mt_time(..., chronon = granule_drop_tz(chronon)),
cycle = granule_drop_tz(cycle)
)
}
)
# Make a granule time-zone-naive (a no-op for granules without a tz).
granule_drop_tz <- function(x) {
if (S7_inherits(x, mt_tz_unit)) {
x@tz <- naive_tz
}
x
}
#' Base S7 class for mixtime vector objects
#'
#' `class_mixtime` is the base S7 class for all mixtime vector objects,
#' inheriting from [vecvec::class_vecvec]. While not intended to be used
#' directly, this S7 class is suitable to use when defining S7 methods for
#' mixtime vectors. S3 methods can be defined using the `mixtime::mixtime`
#' class.
#'
#' When called as a constructor, its arguments are passed to the
#' [vecvec::class_vecvec()] constructor:
#' * `x`: A list of `"mt_time"` vectors, see [mt_linear()] for details.
#' * `i`: A vector of integers specifying the location of each element in
#' `x` as if they were combined in order. Defaults to a sequence from 1 to
#' the total number of elements across all vectors in `x`.
#'
#' @return When used as a class definition (e.g., in `S7::method(generic,
#' class_mixtime)`), an S7 class object representing the `mixtime` class,
#' inheriting from [vecvec::class_vecvec]. When called as a constructor
#' (`class_mixtime(list(...))`), a mixtime vector of S7 class `mixtime`
#' (also inheriting the S3 class `"mixtime"`), containing the supplied list
#' of time vectors as a [vecvec::class_vecvec] structure. End users should
#' prefer [mixtime()] or [new_mixtime()] for construction.
#'
#' @seealso [mixtime()] for creating mixtime vectors, and [new_mixtime()] for
#' the low-level constructor function of this S7 class.
#'
#' @importFrom vecvec class_vecvec
#' @usage NULL
#' @export
class_mixtime <- S7::new_class(
"mixtime",
parent = class_vecvec
)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.