R/compare.R

Defines functions `all.equal.mixtime::mt_time` mixtime_order_proxy mixtime_compare interval_relation cyclical_compare cyclical_position free_cyclical_compare free_compare duration_compare as_integer_literal is_double_literal span_operand_fix is_plain_code compare_operand_expr compare_dispatch_frame warn_span_instant linear_compare

#' 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
  }
}

Try the mixtime package in your browser

Any scripts or data that you put into this service are public.

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