Nothing
#' Comparison operators for linear time (`mt_linear`)
#'
#' @description
#' Discrete linear time values represent a *closed interval* spanning their
#' chronon (e.g. `year(2020)` spans every instant from the start of 2020 to
#' the end of 2020), while continuous linear time values represent a single
#' instant. Comparing two `mt_linear` vectors therefore compares the
#' start/end instants of the (possibly zero-width) interval each value
#' represents:
#'
#' - `a == b` iff `start(a) == start(b)` and `end(a) == end(b)`
#' - `a < b` iff `end(a) <= start(b)` (i.e. before with or without a gap)
#' - `a > b` iff `start(a) >= end(b)` (i.e. after with or without a gap)
#' - `a <= b` iff `end(a) <= end(b)` (right-bound comparison)
#' - `a >= b` iff `start(a) >= start(b)` (left-bound comparison)
#'
#' This is not a total order for comparisons between time points at different
#' granularities: `<=`/`>=` are **not** shorthand for `(< or ==)`/`(> or ==)`.
#' For example, `yearquarter("2020 Q3") <= year("2020")` is TRUE despite
#' `yearquarter("2020 Q3") < year("2020")` and
#' `yearquarter("2020 Q3") == year("2020")` being FALSE.
#'
#' The inequality operators `<`/`>` and `<=`/`>=` are useful conjugations of
#' Allen's interval algebra for common data manipulation needs. The complete set
#' of Allen's 13 base relations are documented in [allen-interval-algebra].
#'
#' @param e1,e2 `mt_linear` vectors (or values castable to one, such as
#' plain numeric vectors in the other operand's chronon, read from its epoch
#' as [mixtime()] reads them, so `year(x) == 2026L` compares with 2026).
#'
#' @return A logical vector.
#'
#' @usage
#' \S4method{==}{mt_linear}(e1, e2)
#' \S4method{!=}{mt_linear}(e1, e2)
#' \S4method{<}{mt_linear}(e1, e2)
#' \S4method{<=}{mt_linear}(e1, e2)
#' \S4method{>}{mt_linear}(e1, e2)
#' \S4method{>=}{mt_linear}(e1, e2)
#'
#' @aliases ==,mt_linear-method !=,mt_linear-method <,mt_linear-method <=,mt_linear-method >,mt_linear-method >=,mt_linear-method
#' @name mt_linear-compare
NULL
# Express both operands as half-open intervals ([start, end)) of real chronon
# instants in their common (finest shared) chronon, then defer to
# `interval_relation()`. A discrete value spans a whole common-chronon unit
# ([v, v+1)); a continuous value is a zero-width instant ([v, v)).
linear_compare <- function(op, e1, e2) {
x_time <- S7_inherits(e1, mt_linear)
y_time <- S7_inherits(e2, mt_linear)
if (!x_time) e1 <- vec_cast(e1, e2)
if (!y_time) e2 <- vec_cast(e2, e1)
x_chronon <- e1@chronon
y_chronon <- e2@chronon
xv <- S7_data(e1)
yv <- S7_data(e2)
x_discrete <- is.integer(xv)
y_discrete <- is.integer(yv)
if (x_discrete != y_discrete) {
warn_span_instant(
op,
if (x_discrete) yv else xv,
side = if (x_discrete) 2L else 1L,
is_time = if (x_discrete) y_time else x_time,
rewrap = "linear_time"
)
}
if (identical(x_chronon, y_chronon)) {
# No conversion needed: a shared chronon unit is always exactly 1 wide
x_start <- as.double(xv)
y_start <- as.double(yv)
x_end <- if (x_discrete) x_start + 1 else x_start
y_end <- if (y_discrete) y_start + 1 else y_start
} else {
# Convert to the common chronon before measuring each operand's width in it
common <- chronon_glb_impl(list(x_chronon, y_chronon))
x_start <- as.double(chronon_convert_impl(xv, x_chronon, common, discrete = x_discrete))
y_start <- as.double(chronon_convert_impl(yv, y_chronon, common, discrete = y_discrete))
x_end <- x_start
if (x_discrete) x_end <- x_start + chronon_cardinality(common, x_chronon, at = xv)
y_end <- y_start
if (y_discrete) y_end <- y_start + chronon_cardinality(common, y_chronon, at = yv)
}
interval_relation(op, list(x_start, x_end), list(y_start, y_end))
}
# A span (discrete) is never equal to an instant (continuous), and ordering
# that measures against an instant's (zero-width) end differs from measuring
# against the end of the span it starts (`year(2016L) > year(2016)` is TRUE).
# When every instant sits exactly on the start of its chronon (e.g.
# `year(2016)`), the instant was most likely meant as the span it starts, so
# hint at the fix, rewritten from the code used for the instant's operand where
# possible. Measures against the instant's start are unaffected, as that is
# where the span starts too.
warn_span_instant <- function(op, instant, side, is_time, rewrap = NULL) {
# `a <= b` compares both ends, `a > b` uses the end of `b` and `a < b` the end
# of `a`, while `a >= b` only compares starts (see `mt_linear-compare`).
ambiguous <- c("==", "!=", "<=", if (side == 2L) ">" else "<")
if (!op %in% ambiguous) return(invisible())
instant <- instant[!is.na(instant)]
if (!length(instant) || any(instant != floor(instant))) return(invisible())
# Warn once per comparison, rather than once per granularity group that
# vecvec compares separately within a mixed vector.
dispatch <- compare_dispatch_frame()
if (!is.null(dispatch)) {
if (isTRUE(get0(".mixtime_span_instant_warned", envir = dispatch$env, inherits = FALSE))) {
return(invisible())
}
assign(".mixtime_span_instant_warned", TRUE, envir = dispatch$env)
}
expr <- if (!is.null(dispatch)) compare_operand_expr(dispatch, side)
fix <- if (!is.null(expr)) span_operand_fix(expr, is_time, rewrap)
hint <- if (is.null(fix)) {
"To compare spans, create both from integers (e.g. {.code year(2015L)} rather than {.code year(2015)})."
} else {
"To compare spans, use {.code {deparse1(fix)}} instead of {.code {deparse1(expr)}}."
}
cli::cli_warn(
c(
if (op %in% c("==", "!=")) {
"Comparing time spans with instants, which are never equal."
} else {
"{.code {op}} between time spans and instants compares with the instant, not the span it starts."
},
"i" = "Discrete (integer) times span their chronon, while continuous (double) times are instants.",
"i" = hint
),
class = "mixtime_warning_span_instant",
call = NULL
)
}
# The outermost S3 `Ops` dispatch frame (vecvec or S7) of the comparison call
# that was written, as `list(env, call)`; its call still holds the unevaluated
# operands.
compare_dispatch_frame <- function() {
frames <- sys.frames()
for (i in seq_along(frames)) {
generic <- get0(".Generic", envir = frames[[i]], inherits = FALSE)
if (is.character(generic) && generic %in% c("==", "!=", "<", "<=", ">", ">=")) {
return(list(env = frames[[i]], call = sys.call(i)))
}
}
NULL
}
# The code for operand `side` (1 or 2) of the comparison in `dispatch`. `NULL`
# (for the general hint) unless it is code the user wrote: comparisons made
# inside a package's code would show names local to that code, and calls built
# by `do.call()` or `!!` hold already-evaluated objects rather than code.
compare_operand_expr <- function(dispatch, side) {
call <- dispatch$call
if (length(call) != 3L) return(NULL)
# S3 dispatch records the environment the comparison was evaluated in
# (e.g. a data mask), which belongs to a package when its code made it
caller <- get0(".GenericCallEnv", envir = dispatch$env, inherits = FALSE)
if (is.null(caller) || isNamespace(topenv(caller))) return(NULL)
expr <- call[[side + 1L]]
if (is_plain_code(expr)) expr
}
# Whether `expr` is code (symbols, calls and bare scalar constants) rather than
# an evaluated object injected into a call.
is_plain_code <- function(expr) {
if (is.symbol(expr)) return(TRUE)
if (is.call(expr)) {
args <- as.list(expr)
args <- args[!vapply(args, identical, logical(1L), quote(expr = ))]
return(all(vapply(args, is_plain_code, logical(1L))))
}
is.atomic(expr) && length(expr) <= 1L && is.null(attributes(expr))
}
# Rewrite an instant's code into code for the span it starts:
# * a numeric literal becomes an integer literal (`2026` -> `2026L`)
# * a call with a numeric literal first argument has it made integer
# (`year(2015)` -> `year(2015L)`)
# * a call setting `discrete` gets the general hint, as an integer first
# argument needn't make it discrete
# * a plain numeric operand is truncated (`myvar` -> `as.integer(myvar)`)
# * any other time is made discrete with `rewrap` (`linear_time(myvar)`)
span_operand_fix <- function(expr, is_time, rewrap) {
if (is_double_literal(expr)) return(as_integer_literal(expr))
if (is.call(expr) && "discrete" %in% names(expr)) return(NULL)
if (is.call(expr) && length(expr) >= 2L && is_double_literal(expr[[2L]])) {
expr[[2L]] <- as_integer_literal(expr[[2L]])
return(expr)
}
if (!is_time) return(call("as.integer", expr))
if (!is.null(rewrap)) return(call(rewrap, expr))
NULL
}
is_double_literal <- function(expr) {
if (is.call(expr) && identical(expr[[1L]], quote(`-`)) && length(expr) == 2L) {
expr <- expr[[2L]]
}
is.double(expr) && length(expr) == 1L && is.finite(expr) && expr == floor(expr)
}
as_integer_literal <- function(expr) {
if (is.call(expr)) {
expr[[2L]] <- as.integer(expr[[2L]])
return(expr)
}
as.integer(expr)
}
method(`==`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("==", e1, e2)
method(`==`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("==", e1, e2)
method(`!=`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("!=", e1, e2)
method(`!=`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("!=", e1, e2)
method(`<`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("<", e1, e2)
method(`<`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("<", e1, e2)
method(`<=`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("<=", e1, e2)
method(`<=`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("<=", e1, e2)
method(`>`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare(">", e1, e2)
method(`>`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare(">", e1, e2)
method(`>=`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare(">=", e1, e2)
method(`>=`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare(">=", e1, e2)
#' Comparison operators for durations (`mt_duration`)
#'
#' @description
#' A duration is a scalar magnitude of time measured in a given chronon (e.g.
#' `days(3)`), with no reference to a point in time. Comparing two durations is
#' therefore a plain magnitude comparison, once both operands have been
#' expressed in a common chronon:
#'
#' - `a == b` iff the two magnitudes are equal in their common chronon
#' - `a < b`, `a <= b`, `a > b`, `a >= b` compare the magnitudes directly
#'
#' Unlike `mt_linear` comparison there is no interval/span to consider, so this
#' *is* a total order. When both operands already share a chronon the magnitudes
#' are compared as-is; otherwise both are scaled to their finest common chronon
#' (the same scaling used when combining durations arithmetically, see
#' `duration_combine()`).
#'
#' @param e1,e2 `mt_duration` vectors (or values castable to one, such as plain
#' numeric vectors interpreted in the other operand's chronon).
#'
#' @return A logical vector.
#'
#' @usage
#' \S4method{==}{mt_duration}(e1, e2)
#' \S4method{!=}{mt_duration}(e1, e2)
#' \S4method{<}{mt_duration}(e1, e2)
#' \S4method{<=}{mt_duration}(e1, e2)
#' \S4method{>}{mt_duration}(e1, e2)
#' \S4method{>=}{mt_duration}(e1, e2)
#'
#' @aliases ==,mt_duration-method !=,mt_duration-method <,mt_duration-method <=,mt_duration-method >,mt_duration-method >=,mt_duration-method
#' @name mt_duration-compare
NULL
duration_compare <- function(op, e1, e2) {
if (!S7_inherits(e1, mt_duration)) e1 <- vec_cast(e1, e2)
if (!S7_inherits(e2, mt_duration)) e2 <- vec_cast(e2, e1)
x_chronon <- e1@chronon
y_chronon <- e2@chronon
xd <- S7_data(e1)
yd <- S7_data(e2)
if (!identical(x_chronon, y_chronon)) {
# Scale both magnitudes to their finest common chronon (mirrors `duration_combine()`)
tu <- chronon_glb_impl(list(x_chronon, y_chronon))
xd <- xd * chronon_cardinality(tu, x_chronon)
yd <- yd * chronon_cardinality(tu, y_chronon)
}
switch(
op,
"==" = xd == yd,
"!=" = xd != yd,
"<" = xd < yd,
">" = xd > yd,
"<=" = xd <= yd,
">=" = xd >= yd
)
}
method(`==`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare("==", e1, e2)
method(`==`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare("==", e1, e2)
method(`!=`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare("!=", e1, e2)
method(`!=`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare("!=", e1, e2)
method(`<`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare("<", e1, e2)
method(`<`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare("<", e1, e2)
method(`<=`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare("<=", e1, e2)
method(`<=`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare("<=", e1, e2)
method(`>`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare(">", e1, e2)
method(`>`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare(">", e1, e2)
method(`>=`, list(mt_duration, class_any)) <- function(e1, e2) duration_compare(">=", e1, e2)
method(`>=`, list(class_any, mt_duration)) <- function(e1, e2) duration_compare(">=", e1, e2)
#' Comparison operators for underspecified cyclical time (`mt_cyclical_free`)
#'
#' @description
#' Underspecified cyclical time (see [cyclical_time()]) is a magnitude within
#' a cycle whose enclosing cycle is unknown (e.g. `day_of_year(60)`, "day
#' 60 of the year", with no year known) - modelled on [mt_duration], not
#' [mt_cyclical]. Comparing two free values is therefore
#' [mt_duration-compare]'s plain magnitude comparison, not
#' [mt_cyclical-compare]'s interval/position reduction:
#'
#' - `a == b` iff the two magnitudes are equal in their common chronon
#' - `a < b`, `a <= b`, `a > b`, `a >= b` compare the magnitudes directly
#'
#' Both operands must share a `cycle` (a type-compatibility tag, not a unit -
#' see [mt_cyclical-compare]): comparing (say) a day-of-week-free against a
#' day-of-year-free is an error. Differing chronons within a shared cycle are
#' reconciled by scaling both magnitudes to their finest common chronon via
#' [chronon_cardinality()] - never [chronon_divmod()], which would assert
#' that the stored number's position is measured relative to some specific
#' enclosing cycle, a claim that is false by construction for data
#' defined to carry no knowledge of which cycle it falls in.
#'
#' Underspecified cyclical time can also be compared against located
#' [mt_cyclical]: the located side reduces to its position within the cycle via its own
#' existing, unchanged machinery (the same reduction [format()] and
#' [mt_cyclical-compare] use), and both sides are then compared as
#' magnitudes.
#'
#' Positions are ordered linearly within one cycle (January < ... <
#' December, with no wrapping), which [sort()], [order()], [min()], [max()]
#' and [range()] follow. Subtraction follows the same order: `a - b` between
#' free values of the same cycle is the duration between their positions,
#' so `month_of_year(3) - month_of_year(1)` is 2 months and
#' `month_of_year(1) - month_of_year(3)` is -2 months (see
#' [mt_cyclical_free-arithmetic] for the arithmetic rules).
#'
#' Unlike `mt_cyclical`, this is a total order (there is no interval to
#' compare - see [mt_duration-compare]), so Allen's interval algebra
#' (`%p%`, `%m%`, ...) is not supported, matching `mt_duration`'s own
#' documented exclusion.
#'
#' @param e1,e2 `mt_cyclical_free` vectors sharing a cycle (or values castable
#' to one, such as plain numeric vectors sharing the other operand's
#' chronon), or one `mt_cyclical_free` and one located `mt_cyclical`
#' sharing a cycle.
#'
#' @return A logical vector.
#'
#' @usage
#' \S4method{==}{mt_cyclical_free}(e1, e2)
#' \S4method{!=}{mt_cyclical_free}(e1, e2)
#' \S4method{<}{mt_cyclical_free}(e1, e2)
#' \S4method{<=}{mt_cyclical_free}(e1, e2)
#' \S4method{>}{mt_cyclical_free}(e1, e2)
#' \S4method{>=}{mt_cyclical_free}(e1, e2)
#'
#' @aliases ==,mt_cyclical_free-method !=,mt_cyclical_free-method <,mt_cyclical_free-method <=,mt_cyclical_free-method >,mt_cyclical_free-method >=,mt_cyclical_free-method
#' @name mt_cyclical_free-compare
NULL
free_compare <- function(op, e1, e2) {
if (!S7_inherits(e1, mt_cyclical_free)) e1 <- vec_cast(e1, e2)
if (!S7_inherits(e2, mt_cyclical_free)) e2 <- vec_cast(e2, e1)
# A cycle is a modulus, not a unit, so differing cycles have no common cycle
cycle <- cycle_common(e1@cycle, e2@cycle)
if (is.null(cycle)) {
vctrs::stop_incompatible_op(op, e1, e2, details = cycle_incompatible_details)
}
x_chronon <- e1@chronon
y_chronon <- e2@chronon
xd <- S7_data(e1)
yd <- S7_data(e2)
if (!identical(x_chronon, y_chronon)) {
# Scale both magnitudes to their finest common chronon - never chronon_divmod().
tu <- chronon_glb_impl(list(x_chronon, y_chronon))
xd <- xd * chronon_cardinality(tu, x_chronon)
yd <- yd * chronon_cardinality(tu, y_chronon)
}
switch(
op,
"==" = xd == yd,
"!=" = xd != yd,
"<" = xd < yd,
">" = xd > yd,
"<=" = xd <= yd,
">=" = xd >= yd
)
}
# Reduce the located side via cyclical_position(); compare both as magnitudes.
free_cyclical_compare <- function(op, e1, e2) {
e1_free <- S7_inherits(e1, mt_cyclical_free)
e2_free <- S7_inherits(e2, mt_cyclical_free)
if (!e1_free && !S7_inherits(e1, mt_cyclical)) e1 <- vec_cast(e1, e2)
if (!e2_free && !S7_inherits(e2, mt_cyclical)) e2 <- vec_cast(e2, e1)
cycle <- cycle_common(attr(e1, "cycle"), attr(e2, "cycle"))
if (is.null(cycle)) {
vctrs::stop_incompatible_op(op, e1, e2, details = cycle_incompatible_details)
}
common <- chronon_glb_impl(list(attr(e1, "chronon"), attr(e2, "chronon")))
free_magnitude <- function(x) as.numeric(S7_data(x)) * chronon_cardinality(common, attr(x, "chronon"))
located_position <- function(x) {
xv <- chronon_convert_impl(
S7_data(x), attr(x, "chronon"), common, discrete = is.integer(S7_data(x))
)
cyclical_position(xv, common, cycle)
}
xd <- if (e1_free) free_magnitude(e1) else located_position(e1)
yd <- if (e2_free) free_magnitude(e2) else located_position(e2)
switch(
op,
"==" = xd == yd,
"!=" = xd != yd,
"<" = xd < yd,
">" = xd > yd,
"<=" = xd <= yd,
">=" = xd >= yd
)
}
method(`==`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare("==", e1, e2)
method(`==`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare("==", e1, e2)
method(`!=`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare("!=", e1, e2)
method(`!=`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare("!=", e1, e2)
method(`<`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare("<", e1, e2)
method(`<`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare("<", e1, e2)
method(`<=`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare("<=", e1, e2)
method(`<=`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare("<=", e1, e2)
method(`>`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare(">", e1, e2)
method(`>`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare(">", e1, e2)
method(`>=`, list(mt_cyclical_free, class_any)) <- function(e1, e2) free_compare(">=", e1, e2)
method(`>=`, list(class_any, mt_cyclical_free)) <- function(e1, e2) free_compare(">=", e1, e2)
# More specific than the class_any pairs above.
method(`==`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare("==", e1, e2)
method(`==`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare("==", e1, e2)
method(`!=`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare("!=", e1, e2)
method(`!=`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare("!=", e1, e2)
method(`<`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare("<", e1, e2)
method(`<`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare("<", e1, e2)
method(`<=`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare("<=", e1, e2)
method(`<=`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare("<=", e1, e2)
method(`>`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare(">", e1, e2)
method(`>`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare(">", e1, e2)
method(`>=`, list(mt_cyclical_free, mt_cyclical)) <- function(e1, e2) free_cyclical_compare(">=", e1, e2)
method(`>=`, list(mt_cyclical, mt_cyclical_free)) <- function(e1, e2) free_cyclical_compare(">=", e1, e2)
#' Comparison operators for cyclical time (`mt_cyclical`)
#'
#' @description
#' A cyclical time value stores an absolute chronon count but *means* a position
#' within its cycle (e.g. `day_of_week()` means a weekday, not a particular
#' Wednesday). Comparison therefore reduces both operands to their position
#' within the cycle - the same reduction [format()] displays - and compares
#' those:
#'
#' - `day_of_week(date("2020-01-15")) == day_of_week(date("2020-01-22"))` is
#' `TRUE`, since both are a Wednesday.
#' - `day_of_year(date("2020-01-15")) == day_of_year(date("2021-01-15"))` is
#' `TRUE`, since both are the 15th day of their year.
#'
#' Both operands must share a `cycle`: a cycle is a modulus rather than a unit,
#' so there is no meaningful common cycle between (say) a weekday and a
#' day-of-year, and comparing them is an error. Differing *chronons* within a
#' shared cycle are reconciled as they are for [mt_linear][mt_linear-compare]:
#' both positions are expressed in the finest common chronon, and a discrete
#' value spans the closed interval of its chronon, so
#'
#' - `a == b` iff `start(a) == start(b)` and `end(a) == end(b)`
#' - `a < b`/`a > b` iff `a`/`b` ends at or before the other begins (a gap, or
#' just adjacency - see [mt_linear-compare] for why this includes adjacency)
#' - `a <= b` iff `end(a) <= end(b)`, `a >= b` iff `start(a) >= start(b)`
#'
#' As for `mt_linear`, this is not a total order when chronons differ. Ordering
#' follows the position within the cycle (so `Mon < Wed`); the cycle's wrap-around
#' is not treated as circular.
#'
#' @param e1,e2 `mt_cyclical` vectors sharing a cycle (or values castable to one,
#' such as plain numeric vectors in the other operand's chronon, read from
#' its epoch as [mixtime()] reads them).
#'
#' @return A logical vector.
#'
#' @usage
#' \S4method{==}{mt_cyclical}(e1, e2)
#' \S4method{!=}{mt_cyclical}(e1, e2)
#' \S4method{<}{mt_cyclical}(e1, e2)
#' \S4method{<=}{mt_cyclical}(e1, e2)
#' \S4method{>}{mt_cyclical}(e1, e2)
#' \S4method{>=}{mt_cyclical}(e1, e2)
#'
#' @aliases ==,mt_cyclical-method !=,mt_cyclical-method <,mt_cyclical-method <=,mt_cyclical-method >,mt_cyclical-method >=,mt_cyclical-method
#' @name mt_cyclical-compare
NULL
# Reduce an absolute chronon count to its position within `cycle`, as format()
# displays: the integer position from chronon_parts(), plus the fraction a
# continuous (double) time model carries but chronon_parts() floors away.
cyclical_position <- function(x, chronon, cycle) {
x <- mt_cyclical(x, chronon = chronon, cycle = cycle)
pos <- chronon_parts(x, cyclical = list(list(chronon, cycle)))$cyclical[[1L]]
xd <- S7_data(x)
if (is.double(xd)) {
xd <- round_ulp(xd)
pos <- pos + (xd - floor(xd))
}
pos
}
# As `linear_compare()`, but positions are first reduced to their place
# within the shared cycle before forming half-open interval endpoints.
cyclical_compare <- function(op, e1, e2) {
x_time <- S7_inherits(e1, mt_cyclical)
y_time <- S7_inherits(e2, mt_cyclical)
if (!x_time) e1 <- vec_cast(e1, e2)
if (!y_time) e2 <- vec_cast(e2, e1)
# A cycle is a modulus, not a unit, so differing cycles have no common cycle
cycle <- cycle_common(e1@cycle, e2@cycle)
if (is.null(cycle)) {
vctrs::stop_incompatible_op(op, e1, e2, details = cycle_incompatible_details)
}
x_chronon <- e1@chronon
y_chronon <- e2@chronon
xv <- S7_data(e1)
yv <- S7_data(e2)
x_discrete <- is.integer(xv)
y_discrete <- is.integer(yv)
if (x_discrete != y_discrete) {
warn_span_instant(
op,
if (x_discrete) yv else xv,
side = if (x_discrete) 2L else 1L,
is_time = if (x_discrete) y_time else x_time
)
}
if (identical(x_chronon, y_chronon)) {
# No conversion needed: a shared chronon unit is always exactly 1 wide
x_start <- cyclical_position(xv, x_chronon, cycle)
y_start <- cyclical_position(yv, y_chronon, cycle)
x_end <- if (x_discrete) x_start + 1 else x_start
y_end <- if (y_discrete) y_start + 1 else y_start
} else {
# Convert to the common chronon before reducing to a cycle position and
# measuring each operand's width in it, mirroring `linear_compare()`
common <- chronon_glb_impl(list(x_chronon, y_chronon))
x_start <- cyclical_position(
chronon_convert_impl(xv, x_chronon, common, discrete = x_discrete),
common, cycle
)
y_start <- cyclical_position(
chronon_convert_impl(yv, y_chronon, common, discrete = y_discrete),
common, cycle
)
x_end <- x_start
if (x_discrete) x_end <- x_start + chronon_cardinality(common, x_chronon, at = xv)
y_end <- y_start
if (y_discrete) y_end <- y_start + chronon_cardinality(common, y_chronon, at = yv)
}
interval_relation(op, list(x_start, x_end), list(y_start, y_end))
}
method(`==`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("==", e1, e2)
method(`==`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("==", e1, e2)
method(`!=`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("!=", e1, e2)
method(`!=`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("!=", e1, e2)
method(`<`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("<", e1, e2)
method(`<`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("<", e1, e2)
method(`<=`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("<=", e1, e2)
method(`<=`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("<=", e1, e2)
method(`>`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare(">", e1, e2)
method(`>`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare(">", e1, e2)
method(`>=`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare(">=", e1, e2)
method(`>=`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare(">=", e1, e2)
interval_relation <- function(op, e1, e2) {
switch(
op,
"==" = e1[[1L]] == e2[[1L]] & e1[[2L]] == e2[[2L]],
"!=" = !(e1[[1L]] == e2[[1L]] & e1[[2L]] == e2[[2L]]),
"<" = e1[[2L]] <= e2[[1L]],
">" = e1[[1L]] >= e2[[2L]],
"<=" = e1[[2L]] <= e2[[2L]],
">=" = e1[[1L]] >= e2[[1L]],
"%p%" = e1[[2L]] < e2[[1L]],
"%pi%" = e2[[2L]] < e1[[1L]],
"%m%" = e1[[2L]] == e2[[1L]],
"%mi%" = e2[[2L]] == e1[[1L]],
"%o%" = e1[[1L]] < e2[[1L]] & e2[[1L]] < e1[[2L]] & e1[[2L]] < e2[[2L]],
"%oi%" = e2[[1L]] < e1[[1L]] & e1[[1L]] < e2[[2L]] & e2[[2L]] < e1[[2L]],
"%s%" = e1[[1L]] == e2[[1L]] & e1[[2L]] < e2[[2L]],
"%si%" = e1[[1L]] == e2[[1L]] & e1[[2L]] > e2[[2L]],
"%d%" = e1[[1L]] > e2[[1L]] & e1[[2L]] < e2[[2L]],
"%di%" = e1[[1L]] < e2[[1L]] & e1[[2L]] > e2[[2L]],
"%f%" = e1[[2L]] == e2[[2L]] & e1[[1L]] > e2[[1L]],
"%fi%" = e1[[2L]] == e2[[2L]] & e1[[1L]] < e2[[1L]]
)
}
#' Allen's interval algebra for time vectors
#'
#' @description
#' Allen's interval algebra has thirteen base relations for time intervals.
#' `==` is defined in [mt_linear-compare]/[mt_cyclical-compare]; the twelve
#' operators below define the rest, computed from the same interval endpoints
#' (`start`/`end`) that comparison derives. Together, they cover all thirteen
#' relations:
#'
#' | Operator | Relation | `e1 %op% e2` holds iff |
#' | -------- | ------------- | ---------------------------------------------------------- |
#' | `%p%` | precedes | `e1` ends before `e2` begins (a gap) |
#' | `%m%` | meets | `e1` ends exactly where `e2` begins (no gap, no overlap) |
#' | `%o%` | overlaps | `e1` begins before `e2`, `e1` ends between the start and end of `e2` |
#' | `%s%` | starts | `e1` and `e2` begin together, and `e1` ends first |
#' | `%d%` | during | `e1` is strictly within `e2`'s span |
#' | `%f%` | finishes | `e1` and `e2` end together, and `e1` begins later |
#' | `==` | equals | `e1` and `e2` share both endpoints |
#' | `%pi%` | preceded by | `e2 %p% e1` |
#' | `%mi%` | met by | `e2 %m% e1` |
#' | `%oi%` | overlapped by | `e2 %o% e1` |
#' | `%si%` | started by | `e2 %s% e1` |
#' | `%di%` | contains | `e2 %d% e1` |
#' | `%fi%` | finished by | `e2 %f% e1` |
#'
#' [mt_linear-compare]/[mt_cyclical-compare]'s `<`/`>` are a deliberate
#' deviations from their use as 'precedes' in Allen's interval algebra
#' (`%p%`/`%pi%` operators). The important difference is that `<`/`>` include
#' 'meets' relations, while `%p%`/`%pi%` requires gaps, so in the examples
#' below `jan < feb` is TRUE in mixtime but the equivalent symbol in Allen's
#' interval algebra (`jan %p% feb`) is FALSE because there is no gap.
#'
#' The implementation here also extends to continuous time instants, which are
#' treated as degenerate zero-width intervals. This allows testing how a
#' specific time instant relates to time spans, for example does January 2020
#' contain 30% through the day 2020-01-24 is
#' `yearmonth("2020-01") %di% date(datetime("2020-01-24 07:12:00"), discrete = FALSE)`.
#' This is a technical deviation from Allen's interval algebra, which assumes
#' that intervals are non-degenerate (i.e. end > start, not end >= start).
#'
#' @param e1,e2 `mt_linear` or `mt_cyclical` vectors sharing a mode of time
#' (and, for `mt_cyclical`, a cycle) - or values castable to one, such as
#' plain numeric vectors in the other operand's chronon, read from its epoch
#' as [mixtime()] reads them. `mt_duration`
#' has no interval to compare and so is not supported.
#'
#' @return A logical vector.
#'
#' @seealso [mt_linear-compare] and [mt_cyclical-compare] for `==`, `<`, `>`,
#' `<=`, `>=` - the three of Allen's relations that also form the package's
#' ordering (`<`/`>` in a looser, adjacency-inclusive form than `%p%`/`%pi%`).
#'
#' @references
#' Allen, J. F. (1983). Maintaining knowledge about temporal intervals.
#' *Communications of the ACM*, 26(11), 832-843.
#'
#' @examples
#' jan <- yearmonth("2020 Jan")
#' feb <- yearmonth("2020 Feb")
#' mar <- yearmonth("2020 Mar")
#' q1 <- yearquarter("2020 Q1")
#'
#' jan == jan # January equals itself
#'
#' jan %p% mar # January precedes March: February leaves a genuine gap
#' mar %pi% jan # ... equivalently, March is preceded by January
#'
#' jan %m% feb # January meets February: adjacent, no gap
#' feb %mi% jan # ... equivalently, February is met by January
#' jan < feb # `<` also holds for adjacent pairs, unlike `%p%`
#' jan %p% feb # FALSE: no gap between them, so they don't (strictly) precede
#'
#' jan %s% q1 # January and Q1 start together, but January finishes first
#' q1 %si% jan # ... equivalently, Q1 is started by January
#'
#' feb %d% q1 # February is strictly within Q1
#' q1 %di% feb # ... equivalently, Q1 contains February
#'
#' mar %f% q1 # March and Q1 finish together, but March starts later
#' q1 %fi% mar # ... equivalently, Q1 is finished by March
#'
#' @name allen-interval-algebra
NULL
#' @rdname allen-interval-algebra
#' @export
`%p%` <- S7::new_generic("%p%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%pi%` <- S7::new_generic("%pi%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%m%` <- S7::new_generic("%m%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%mi%` <- S7::new_generic("%mi%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%o%` <- S7::new_generic("%o%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%oi%` <- S7::new_generic("%oi%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%s%` <- S7::new_generic("%s%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%si%` <- S7::new_generic("%si%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%d%` <- S7::new_generic("%d%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%di%` <- S7::new_generic("%di%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%f%` <- S7::new_generic("%f%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
#' @rdname allen-interval-algebra
#' @export
`%fi%` <- S7::new_generic("%fi%", c("e1", "e2"), fun = function(e1, e2) S7::S7_dispatch())
# Custom infix operators aren't aware of vecvec's slot dispatch
# This function factory defines the mixtime dispatch for these new operators
mixtime_compare <- function(.generic) {
function(e1, e2) vecvec::vecvec_mapply(list(e1, e2), .generic, ptype = logical())
}
method(`%p%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%p%", e1, e2)
method(`%p%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%p%", e1, e2)
method(`%p%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%p%", e1, e2)
method(`%p%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%p%", e1, e2)
method(`%p%`, list(class_mixtime, class_any)) <- mixtime_compare(`%p%`)
method(`%p%`, list(class_any, class_mixtime)) <- mixtime_compare(`%p%`)
method(`%pi%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%pi%", e1, e2)
method(`%pi%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%pi%", e1, e2)
method(`%pi%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%pi%", e1, e2)
method(`%pi%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%pi%", e1, e2)
method(`%pi%`, list(class_mixtime, class_any)) <- mixtime_compare(`%pi%`)
method(`%pi%`, list(class_any, class_mixtime)) <- mixtime_compare(`%pi%`)
method(`%m%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%m%", e1, e2)
method(`%m%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%m%", e1, e2)
method(`%m%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%m%", e1, e2)
method(`%m%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%m%", e1, e2)
method(`%m%`, list(class_mixtime, class_any)) <- mixtime_compare(`%m%`)
method(`%m%`, list(class_any, class_mixtime)) <- mixtime_compare(`%m%`)
method(`%mi%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%mi%", e1, e2)
method(`%mi%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%mi%", e1, e2)
method(`%mi%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%mi%", e1, e2)
method(`%mi%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%mi%", e1, e2)
method(`%mi%`, list(class_mixtime, class_any)) <- mixtime_compare(`%mi%`)
method(`%mi%`, list(class_any, class_mixtime)) <- mixtime_compare(`%mi%`)
method(`%o%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%o%", e1, e2)
method(`%o%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%o%", e1, e2)
method(`%o%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%o%", e1, e2)
method(`%o%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%o%", e1, e2)
method(`%o%`, list(class_mixtime, class_any)) <- mixtime_compare(`%o%`)
method(`%o%`, list(class_any, class_mixtime)) <- mixtime_compare(`%o%`)
# `%o%` overrides base's outer-product operator (both are named `%o%`); when neither
# operand is a mixtime type, fall back to that base behaviour instead of erroring, so
# attaching mixtime doesn't break existing `%o%` usage.
method(`%o%`, list(class_any, class_any)) <- function(e1, e2) outer(e1, e2)
method(`%oi%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%oi%", e1, e2)
method(`%oi%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%oi%", e1, e2)
method(`%oi%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%oi%", e1, e2)
method(`%oi%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%oi%", e1, e2)
method(`%oi%`, list(class_mixtime, class_any)) <- mixtime_compare(`%oi%`)
method(`%oi%`, list(class_any, class_mixtime)) <- mixtime_compare(`%oi%`)
method(`%s%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%s%", e1, e2)
method(`%s%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%s%", e1, e2)
method(`%s%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%s%", e1, e2)
method(`%s%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%s%", e1, e2)
method(`%s%`, list(class_mixtime, class_any)) <- mixtime_compare(`%s%`)
method(`%s%`, list(class_any, class_mixtime)) <- mixtime_compare(`%s%`)
method(`%si%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%si%", e1, e2)
method(`%si%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%si%", e1, e2)
method(`%si%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%si%", e1, e2)
method(`%si%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%si%", e1, e2)
method(`%si%`, list(class_mixtime, class_any)) <- mixtime_compare(`%si%`)
method(`%si%`, list(class_any, class_mixtime)) <- mixtime_compare(`%si%`)
method(`%d%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%d%", e1, e2)
method(`%d%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%d%", e1, e2)
method(`%d%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%d%", e1, e2)
method(`%d%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%d%", e1, e2)
method(`%d%`, list(class_mixtime, class_any)) <- mixtime_compare(`%d%`)
method(`%d%`, list(class_any, class_mixtime)) <- mixtime_compare(`%d%`)
method(`%di%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%di%", e1, e2)
method(`%di%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%di%", e1, e2)
method(`%di%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%di%", e1, e2)
method(`%di%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%di%", e1, e2)
method(`%di%`, list(class_mixtime, class_any)) <- mixtime_compare(`%di%`)
method(`%di%`, list(class_any, class_mixtime)) <- mixtime_compare(`%di%`)
method(`%f%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%f%", e1, e2)
method(`%f%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%f%", e1, e2)
method(`%f%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%f%", e1, e2)
method(`%f%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%f%", e1, e2)
method(`%f%`, list(class_mixtime, class_any)) <- mixtime_compare(`%f%`)
method(`%f%`, list(class_any, class_mixtime)) <- mixtime_compare(`%f%`)
method(`%fi%`, list(mt_linear, class_any)) <- function(e1, e2) linear_compare("%fi%", e1, e2)
method(`%fi%`, list(class_any, mt_linear)) <- function(e1, e2) linear_compare("%fi%", e1, e2)
method(`%fi%`, list(mt_cyclical, class_any)) <- function(e1, e2) cyclical_compare("%fi%", e1, e2)
method(`%fi%`, list(class_any, mt_cyclical)) <- function(e1, e2) cyclical_compare("%fi%", e1, e2)
method(`%fi%`, list(class_mixtime, class_any)) <- mixtime_compare(`%fi%`)
method(`%fi%`, list(class_any, class_mixtime)) <- mixtime_compare(`%fi%`)
#' Ordering of mixtime vectors
#'
#' @description
#' `sort()` and `xtfrm()` (which powers `order()` and `rank()`) order a mixtime
#' vector chronologically. A discrete time (e.g. `yearmonth("2020 Jan")`) is a
#' span rather than an instant, so ordering it against time of another
#' chronon first picks an instant within the span.
#'
#' `align_discrete` sets that instant: `0` for the start of the span, `1` for
#' its end, and `0.5` (the default) for its midpoint. It only changes the order
#' of time with different chronons; time sharing a chronon keeps its order.
#'
#' `xtfrm()` takes no other arguments, so `order()`, `rank()` and vctrs
#' ordering always use the midpoint. Use `sort()` to choose another instant.
#'
#' @param x,decreasing,na.last,... See [sort()].
#' @param align_discrete The position within a discrete time span used to
#' order it against time of another chronon, from `0` (start) to `1` (end).
#'
#' @return
#' `sort()` returns a mixtime vector; `xtfrm()` returns a numeric vector
#' suitable for ranking.
#'
#' @examples
#' x <- c(yearmonth("2020 Jan"), date("2020-01-20"), yearmonth("2020 Feb"))
#' sort(x)
#' # January ends after the 20th
#' sort(x, align_discrete = 1)
#' sort(x, decreasing = TRUE)
#'
#' @name mixtime-order
#' @aliases xtfrm.mixtime sort.mixtime
NULL
# Ordering and de-duplication of mixtime vectors
#' Ordering proxy for mixtime vectors
#'
#' Builds the ordering key underlying [xtfrm()] and [sort()] on mixtime
#' vectors (see `mixtime-order`).
#'
#' @param x A mixtime vector.
#' @param align_discrete The fractional position (0 = start, 1 = end) within
#' a discrete time span's chronon to use as its ordering instant.
#'
#' @noRd
mixtime_order_proxy <- function(x, align_discrete = 0.5) {
mode <- check_common_time_mode(x)
if (!length(x@x)) return(vec_proxy_order(vecvec::unvecvec(x)))
# The granules each part is reduced to, read before converting the parts below
# replaces them with bare chronon counts carrying neither granule.
chronon <- chronon_glb_impl(lapply(x@x, function(v) attr(v, "chronon")))
cycle <- if (identical(mode, "cyclical")) check_common_cycle(x)
# Convert all time values to a common chronon, which a single part already is
if (length(x@x) > 1L) {
x@x <- lapply(x@x, function(v) {
if (is.integer(v)) v <- v + align_discrete
chronon_convert(v, chronon)
})
}
if (!is.null(cycle)) {
# Cyclical values order by their position within the cycle, matching `==`
# and `<` on `mt_cyclical` (see `mt_cyclical-compare`) rather than the
# absolute chronon count stored underneath.
x@x <- lapply(x@x, function(v) cyclical_position(vec_data(v), chronon, cycle))
}
vec_proxy_order(vecvec::unvecvec(x))
}
#' @rdname mixtime-order
#' @export
method(xtfrm, class_mixtime) <- function(x) {
xtfrm(mixtime_order_proxy(x))
}
#' @rdname mixtime-order
#' @export
method(sort, class_mixtime) <- function(x, decreasing = FALSE, na.last = NA, ..., align_discrete = 0.5) {
key <- xtfrm(mixtime_order_proxy(x, align_discrete = align_discrete))
x[order(key, na.last = na.last, decreasing = decreasing)]
}
method(unique, class_mixtime) <- function(x, incomparables = FALSE, ...) {
vctrs::vec_unique(x)
}
method(duplicated, class_mixtime) <- function(x, incomparables = FALSE, ...) {
vctrs::vec_duplicate_id(x) != seq_along(x)
}
method(anyDuplicated, class_mixtime) <- function(x, incomparables = FALSE, ...) {
match(TRUE, duplicated(x), nomatch = 0L)
}
#' Tolerant comparison of mixtime time values
#'
#' @description
#' [vecvec::class_vecvec]'s `all.equal()` method (which `mixtime` inherits,
#' since a mixtime vector is a `vecvec`) handles length/`NA` mismatches and
#' groups elements by their underlying storage slot, then compares each
#' group's *raw* values with `all.equal()`. That raw comparison has no notion
#' of chronon: two elements that are `==` (e.g. `days(1)` and `hours(24)`, or
#' a `yearmonth` and an equivalent-instant `yearweek`) can end up stored with
#' different chronons or magnitudes, and so are wrongly reported as unequal.
#'
#' This method fixes that at the per-slot level: elements already `==` (which
#' is chronon-aware, see [mt_linear-compare]/[mt_duration-compare]) count as
#' equal outright; for the rest, the discrepancy is measured as the duration
#' between them in their common chronon. A time point has no "typical
#' magnitude" to scale a *relative* tolerance against the way a plain number
#' does, so - unlike [base::all.equal.numeric()] - `tolerance` is always
#' absolute, in (possibly fractional) chronon units.
#'
#' @param target,current `mt_time` vectors of the same length to compare (as
#' passed down by [vecvec::class_vecvec]'s `all.equal()`).
#' @param tolerance Numeric tolerance, as an absolute number of `target`'s
#' chronon units. Defaults to `sqrt(.Machine$double.eps)`, as for
#' [base::all.equal()].
#' @param ... Ignored.
#'
#' @return `TRUE` if `target` and `current` are equal within `tolerance`,
#' otherwise a string describing the discrepancy.
#'
#' @examples
#' all.equal(yearmonth(0), yearmonth(0))
#' all.equal(yearmonth(0), yearmonth(1))
#' all.equal(days(1), hours(24))
#'
#' @keywords internal
#' @method all.equal mixtime::mt_time
#' @export
`all.equal.mixtime::mt_time` <- function(
target, current, tolerance = sqrt(.Machine$double.eps), ...
) {
# `class_vecvec`'s all.equal() only filters *sparse* missingness (an NA
# vecvec index); an NA stored inline within a slot's own data (as here)
# still reaches us and needs handling directly - mirroring the NA check in
# `all.equal.numeric()`.
na_t <- is.na(target)
na_c <- tryCatch(is.na(current), error = function(e) NULL)
if (is.null(na_c)) {
return(sprintf(
"target is %s, current is %s",
class(target)[[1L]], class(current)[[1L]]
))
}
if (!identical(na_t, na_c)) {
return(sprintf(
"'is.NA' value mismatch: %d in current, %d in target",
sum(na_c), sum(na_t)
))
}
keep <- !na_t
eq <- tryCatch(target[keep] == current[keep], error = function(e) NULL)
if (is.null(eq)) {
return(sprintf(
"target is %s, current is %s",
class(target)[[1L]], class(current)[[1L]]
))
}
if (all(eq)) return(TRUE)
d <- target[keep][!eq] - current[keep][!eq]
xy <- mean(abs(as.double(vec_data(d))))
if (xy > tolerance) {
sprintf("Mean absolute difference: %s", format(xy))
} else {
TRUE
}
}
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.