carray 3.0.2 → 3.0.4

data/lib/carray/time.rb

@@ -11,7 +11,9 @@
 #   - Same pattern for CATimedelta
 #
 # Base epoch fixed to 1970-01-01 (Unix epoch).
-# NetCDF CF convention (= reference time epoch) is delegated to external gems (timesteps etc.).
+# Counts from another reference time (a NetCDF CF units attribute) convert in
+# core through CATime::Grid; only non-standard calendars are left to external
+# gems.
 
 # Internal: unit-conversion algebra shared by CATime / CATimedelta
 # (used by to_comparable to align a search query to the reference unit).
@@ -25,6 +27,11 @@
 # Civil-date arithmetic on int64 CArrays: the calendar kernel every time
 # grid is built on (Howard Hinnant's days<->civil algorithms, vectorized).
 # Internal to the time surface: nothing here is part of the public API.
+# Loaded with the file, not inside the methods: a require is a lock that
+# Ractors running these methods at the same time can deadlock on.
+require 'date'
+require 'time'
+
 module CATimeCivil
   module_function
 
@@ -93,6 +100,53 @@ module CATimeUnitAlgebra
 
   module_function
 
+  # An operand of a time or duration operator, taken through its to_ca when
+  # it exports MemoryView and defines one (an Apache Arrow duration array, given
+  # a bridge that adds to_ca), as the core binary operators take it; other
+  # objects are returned as they are, for the operator to accept or refuse.
+  def operand(other)
+    if !other.is_a?(CArray) && other.respond_to?(:to_ca) &&
+       CArray.memory_view_available?(other)
+      other.to_ca
+    else
+      other
+    end
+  end
+
+  # A single value an operator meets an array with, as a one-cell array
+  # marked scalar (a CScalar) of its kind, or nil when it is not one: a
+  # duration -- a CATimedelta::Element, or a String that reads as one
+  # ("3 days") -- or an instant -- a CATime::Element, a Time, a Date, or any
+  # other String.  An instant that lands on the +unit+ grid is given in that
+  # unit, so a day array minus "2024-01-02" answers in days.
+  def scalar_operand(x, unit)
+    case x
+    when CATimedelta::Element
+      CATimedelta.wrap(CScalar.int64 { x.value }, unit: x.unit)
+    when String
+      res = begin
+              CATime::Resolution.parse(x)
+            rescue ArgumentError
+              nil
+            end
+      return CATimedelta.wrap(CScalar.int64 { res.count }, unit: res.base) if res
+      scalar_instant(CATimeLiteral.exact_instant(x), unit)
+    when CATime::Element
+      CATime.wrap(CScalar.int64 { x.value }, unit: x.unit)
+    when Time, Date
+      scalar_instant(CATimeLiteral.exact_instant(x), unit)
+    end
+  end
+
+  def scalar_instant(t, unit)
+    v = begin
+          convert_instant!(t.parent, t.unit, unit)[0]
+        rescue ArgumentError
+          return CATime.wrap(CScalar.int64 { t.parent[0] }, unit: t.unit)
+        end
+    CATime.wrap(CScalar.int64 { v }, unit: unit)
+  end
+
   # seconds- (fixed) or months- (calendar) per base tick.
   def base_ratio(base)
     FIXED[base] || CALENDAR[base]
@@ -208,7 +262,7 @@ module CATimeUnitAlgebra
   # fine->coarse divides only when every value is exact; cross-group ALWAYS
   # raises -- a :M / :Y duration has no fixed ratio to days (a month is
   # calendar-variable), so it genuinely cannot scale to seconds.
-  def convert_scale!(storage, from, to)
+  def convert_scale!(storage, from, to, instant: false)
     a = res(from); b = res(to)
     return storage if a == b
     r = ratio(a, b)
@@ -221,6 +275,11 @@ module CATimeUnitAlgebra
     scaled = widen(storage, r.numerator)    # coarse -> fine: lossless multiply
     return scaled if r.denominator == 1
     unless (scaled % r.denominator).eq(0).all
+      if instant
+        raise ArgumentError,
+              "cannot convert times in #{a} to #{b} without loss: " \
+              "some are not on the #{b} grid (they would be moved to it)"
+      end
       raise ArgumentError,
             "cannot scale duration #{a} to #{b} without loss: " \
             "some values are not a whole multiple of #{b} " \
@@ -236,7 +295,8 @@ module CATimeUnitAlgebra
   # CATimedelta#to_unit and by dt +/- td, where the result keeps the time's
   # unit and a finer duration is truncated to it (a :D time + a 5 h duration
   # is + 0 days; + 30 h is + 1 day).  Cross-group still raises (a calendar
-  # duration has no fixed ratio to a fixed unit).
+  # duration has no fixed ratio to a fixed unit; dt +/- a month moves the date
+  # through shift_months instead).
   def convert_scale_trunc(storage, from, to)
     a = res(from); b = res(to)
     return storage if a == b
@@ -251,6 +311,67 @@ module CATimeUnitAlgebra
     r.denominator == 1 ? scaled : trunc_divide(scaled, r.denominator)
   end
 
+  # A duration brought onto a time's grid for dt +/- td.  A duration finer
+  # than the grid is truncated toward zero (a :D time + 5 h is + 0 days), but
+  # one whose tick is coarser and not a whole number of grid ticks ("1 day"
+  # on a "7 hours" grid, "15 minutes" on a "10 minutes" grid) must land on
+  # the grid exactly: cutting it would move the time by part of its own
+  # tick, which no rounding of the time asked for.
+  def duration_on_grid(storage, from, to)
+    r = ratio(res(from), res(to))
+    return convert_scale_trunc(storage, from, to) if r.nil? || r <= 1 || r.denominator == 1
+    scaled = widen(storage, r.numerator)
+    unless (scaled % r.denominator).eq(0).all
+      raise ArgumentError,
+            "a duration in #{res(from)} does not land on the #{res(to)} grid " \
+            "(it is not a whole number of #{res(to)} ticks); convert the time " \
+            "to a grid both share first"
+    end
+    scaled / r.denominator
+  end
+
+  # a + b and a - b on int64 storage (b a CArray or an Integer), raising
+  # instead of wrapping around when a result leaves int64.  An overflow is a
+  # result whose sign differs from both terms of the sum (a and b for +, a
+  # and -b for -).
+  def checked_add(a, b)
+    check_term(b, "+")
+    r = a + b
+    overflow_raise("+") if ((a ^ r) & (b ^ r)).lt(0).any
+    r
+  end
+
+  def checked_sub(a, b)
+    check_term(b, "-")
+    r = a - b
+    overflow_raise("-") if ((a ^ b) & (a ^ r)).lt(0).any
+    r
+  end
+
+  def checked_mul(a, k)
+    check_term(k, "*")
+    lo = a.min
+    unless lo == UNDEF
+      [lo, a.max].each do |x|
+        overflow_raise("*") unless (INT64_MIN..INT64_MAX).cover?(Integer(x) * k)
+      end
+    end
+    a * k
+  end
+
+  def check_term(b, op)
+    overflow_raise(op) if b.is_a?(Integer) && !(INT64_MIN..INT64_MAX).cover?(b)
+  end
+
+  def overflow_raise(op)
+    raise RangeError,
+          "time arithmetic overflows int64 (#{op}): the result is outside " \
+          "the range of the storage unit; use a coarser unit"
+  end
+
+  INT64_MIN = -2**63
+  INT64_MAX = 2**63 - 1
+
   # Truncating integer division of an int64 CArray (toward zero).  CArray
   # `/` floors toward the past, which is what an instant wants; a duration
   # is a magnitude and shrinks toward zero instead.
@@ -271,7 +392,7 @@ module CATimeUnitAlgebra
   def convert_instant!(storage, from, to)
     a = res(from); b = res(to)
     return storage if a == b
-    return convert_scale!(storage, a, b) if ratio(a, b)   # same group
+    return convert_scale!(storage, a, b, instant: true) if ratio(a, b)   # same group
     if CALENDAR.key?(a.base)
       convert_instant_calendar_to_fixed(storage, a, b)   # widen
     else
@@ -279,6 +400,40 @@ module CATimeUnitAlgebra
     end
   end
 
+  # A time on a fixed grid moved by whole months, as Ruby's Date#>> moves a
+  # date: the year and the month move, the day stays unless the new month is
+  # shorter (then it is that month's last day), and the time of day stays.
+  # The grid has to tile a day, so the result lands on it; on any other grid
+  # (:W, "3 days", "7 hours") a month moves a time off its grid, and that
+  # raises.  +months+ is an Integer or an int64 CArray of the time's shape.
+  def shift_months(storage, from, months)
+    rd = ratio(CATime::Resolution.new(1, :D), from)   # ticks of `from` per day
+    unless rd && rd.denominator == 1
+      raise ArgumentError,
+            "cannot move a time on the #{from} grid by months: a day is not a " \
+            "whole number of its ticks, so the result would be off the grid"
+    end
+    n    = rd.numerator
+    days = storage / n                                 # floors toward the past
+    rest = storage - days * n                          # the time of day, in ticks
+    y, m, d = CATimeCivil.civil_from_days(days)
+    ord  = y * 12 + (m - 1) + months                   # month ordinal after the move
+    ny   = ord / 12
+    nm   = ord - ny * 12 + 1
+    ones = CArray.int64(*storage.shape) { 1 }
+    head = CATimeCivil.days_from_civil(ny, nm, ones)
+    ord1 = ord + 1
+    ny1  = ord1 / 12
+    last = CATimeCivil.days_from_civil(ny1, ord1 - ny1 * 12 + 1, ones) - head
+    widen(head + d.pmin(last) - 1, n) + rest
+  end
+
+  # Whole months in a calendar duration of +res+: its count of months or of
+  # years.
+  def months_per_tick(res)
+    (res.count * CALENDAR.fetch(res.base)).to_i
+  end
+
   # calendar time (Resolution `from`) -> days since the epoch (int64
   # CArray).  Folds the resolution count (value = count-Y/M buckets).
   def calendar_days_since_epoch(storage, from)
@@ -307,25 +462,29 @@ module CATimeUnitAlgebra
     widen(calendar_days_since_epoch(storage, from), r.numerator)
   end
 
+  # Whole days since the epoch (floored) of fixed-length ticks, and the
+  # remainder that says whether each instant sits on a day boundary.  A tick
+  # need not divide a day, nor be a whole number of days ("7 hours",
+  # "36 hours", "7 seconds"): the count is scaled to a grid both share.
+  def fixed_storage_days(storage, from)
+    rd     = ratio(CATime::Resolution.new(1, :D), from)  # `from` ticks per day
+    scaled = widen(storage, rd.denominator)
+    n      = rd.numerator
+    { days: scaled / n, rest: scaled % n }
+  end
+
   # fixed-length grid -> calendar time: the coarsening half of
   # convert_instant!, exact-or-raise.  Every instant must land on a day
   # boundary and then on the calendar boundary itself (the 1st, and
   # January too for :Y), since a mid-month instant has no :M value.
   def convert_instant_fixed_to_calendar(storage, from, to)
-    rd = ratio(CATime::Resolution.new(1, :D), from)  # `from` ticks per day
-    days =
-      if rd.denominator == 1
-        n = rd.numerator
-        unless (storage % n).eq(0).all
-          raise ArgumentError,
-                "cannot convert time #{from} to #{to} without loss " \
-                "(instant is not on a day boundary)"
-        end
-        storage / n
-      else                                             # coarser than a day (:W)
-        storage * (from.tick_ratio / 86400r).to_i
-      end
-    y, m, d = CATimeCivil.civil_from_days(days)
+    days = fixed_storage_days(storage, from)
+    unless (days[:rest]).eq(0).all
+      raise ArgumentError,
+            "cannot convert time #{from} to #{to} without loss " \
+            "(instant is not on a day boundary)"
+    end
+    y, m, d = CATimeCivil.civil_from_days(days[:days])
     on_boundary = d.eq(1)
     on_boundary &= m.eq(1) if to.base == :Y
     unless on_boundary.all
@@ -372,20 +531,110 @@ module CATimeUnitAlgebra
   # month, whatever day and time it carries.  The flooring counterpart of
   # convert_instant_fixed_to_calendar.
   def convert_instant_fixed_to_calendar_floor(storage, from, to)
-    rd   = ratio(CATime::Resolution.new(1, :D), from)   # `from` ticks per day
-    days =
-      if rd.denominator == 1
-        storage / rd.numerator
-      else                                             # coarser than a day (:W)
-        storage * (from.tick_ratio / 86400r).to_i
-      end
-    y, m, = CATimeCivil.civil_from_days(days)
+    y, m, = CATimeCivil.civil_from_days(fixed_storage_days(storage, from)[:days])
     ord = to.base == :M ? (y * 12 + (m - 1) - 1970 * 12) : (y - 1970)
     to.count > 1 ? ord / to.count : ord
   end
 end
 
+# A reduction of a time Face takes `fill_value:` as a value of the Face (an
+# Element, or what an assignment to the Face accepts), the same as
+# `strip_mask` and `[]=` read it.  The reduction runs on the storage, so the
+# fill goes in after the result is a Face again: a whole reduction keeps its
+# axes for that, so the fill lands in a typed cell, and is then taken out.
+module CATimeSurfaceFill
+
+  private
+
+  def with_surface_fill (opts)
+    fill = opts[:fill_value]
+    return yield(opts) if fill.nil? || fill.equal?(UNDEF)
+    o = opts.reject { |k, _| k == :fill_value }
+    o[:keep_axis] = true
+    r = yield(o)
+    kept = nil
+    unless opts[:keep_axis]
+      axes = opts[:axis].nil? ? (0...ndim).to_a :
+               Array(opts[:axis]).map { |a| a < 0 ? a + ndim : a }
+      kept = shape.each_with_index.reject { |_, i| axes.include?(i) }.map(&:first)
+    end
+    surface_fill(r, fill, kept)
+  end
+
+  # `kept` is the shape to return to, or nil to keep the reduced axes.
+  def surface_fill (r, fill, kept)
+    case r
+    when Array then r.map { |x| surface_fill(x, fill, kept) }
+    when CArray
+      r = r.strip_mask(fill) if r.has_mask?
+      if kept.nil?      then r
+      elsif kept.empty? then r[*Array.new(r.ndim, 0)]
+      else                   r.reshape(*kept)
+      end
+    else r
+    end
+  end
+
+end
+
+# The part of to_comparable the two time Faces share: values written one by
+# one (a Ruby Array) and an array that is not of this kind (an object column,
+# a string column) are each read as a value of this Face by to_comparable, an
+# UNDEF or a masked cell kept masked.  Nil for any other operand, which the Face's own
+# to_comparable decides.
+module CATimeOperandValues
+
+  # The reference and the operand of a comparison (eq, <, count, search,
+  # linear_section, pmax ...) brought to one unit: the operand read in its
+  # own unit, then the reference's unit when the operand sits on its grid
+  # (the reference is not converted), else the finer unit the two share, as
+  # is_in and the set operations meet.  A value that is not of this kind is
+  # refused as to_comparable refuses it.  An assignment, which has to land on
+  # the reference's grid, reconciles with to_comparable instead.
+  # @api private
+  def comparable_pair (operand)
+    lifted = lift_operand(operand)
+    return [self, lifted] if lifted.unit == unit
+    narrowed = lifted.to_unit(unit)
+    if narrowed.to_unit(lifted.unit).parent.eq(lifted.parent).all
+      return [self, narrowed]
+    end
+    in_common_unit_with(lifted)
+  end
+
+  private
+
+  # The operand as an array of this kind in its own unit: one value read as
+  # it is written, an Array or an array of another kind read value by value
+  # in the unit they share, an UNDEF or a masked cell kept masked.
+  def lift_operand (operand)
+    return operand if operand.is_a?(self.class)
+    case operand
+    when Array
+      # A nested Array keeps its shape; reading it row by row would land
+      # each row as one value.
+      return lift_operand(CA_OBJECT(operand)) if operand.any?(Array)
+      lifted = operand.map { |v| UNDEF.equal?(v) ? nil : lift_operand(v) }
+      units  = lifted.compact.map(&:unit)
+      u = units.empty? ? unit : units.reduce { |a, b| common_unit(a, b) }
+      self.class.wrap(CA_INT64(lifted.map { |x| x ? x.to_unit(u).parent[0] : UNDEF }),
+                      unit: u)
+    when CArray
+      lift_operand(operand.to_a.flatten).reshape(*operand.shape)
+    else
+      lift_value(operand) || to_comparable(operand)
+    end
+  end
+
+  def reconcile_values (operand)
+    to_comparable(lift_operand(operand))
+  end
+
+end
+
 class CATime
+  include CATimeSurfaceFill
+  include CATimeOperandValues
   # @overload new(*shape, unit: :ns)
   #   Allocates a new int64 storage CArray of the given `shape` and
   #   wraps it as a CATime Face with the given `unit`. The
@@ -406,7 +655,7 @@ class CATime
   #   @param unit [Resolution, Symbol, String] tick resolution.
   #   @return [CATime]
   def self.wrap(raw, unit: :ns)
-    __wrap__(raw, unit)
+    wrap_storage(raw, unit)
   end
 
   # Element-return class: a single time element carries both its
@@ -438,8 +687,6 @@ class CATime
     # @return [Time] the instant this scalar denotes (UTC).  For a calendar
     #   unit this is the first instant (midnight of day 1) of the granule.
     def to_time
-      require 'time'
-      require 'date'
       case unit.base
       when :Y then d = epoch_date.next_year(value * unit.count);  Time.utc(d.year, d.month, d.day)
       when :M then d = epoch_date.next_month(value * unit.count); Time.utc(d.year, d.month, d.day)
@@ -451,7 +698,6 @@ class CATime
     # @return [Date] the date this scalar denotes (UTC).  A sub-day unit is
     #   floored to its day.
     def to_date
-      require 'date'
       case unit.base
       when :Y then epoch_date.next_year(value * unit.count)
       when :M then epoch_date.next_month(value * unit.count)
@@ -472,7 +718,7 @@ class CATime
     # @return [String]
     def to_s
       case unit.base
-      when :Y      then format("%04d", to_date.year)
+      when :Y      then to_date.strftime("%Y")
       when :M      then to_date.strftime("%Y-%m")
       when :W, :D  then to_date.strftime("%Y-%m-%d")
       else              to_time.iso8601(fractional_second_digits)  # :h .. :as (time shown)
@@ -500,6 +746,10 @@ class CATime
         to_time <=> other.getutc
       when (defined?(DateTime) ? DateTime : nil)
         to_time <=> other.to_time.getutc
+      when (defined?(Date) ? Date : nil)
+        # a Date names the midnight (UTC) that begins it, as it does when an
+        # array is compared with it
+        to_time.to_r <=> CATimeLiteral.epoch_seconds(other)
       end
     rescue ArgumentError
       nil
@@ -517,18 +767,27 @@ class CATime
       [value, unit].hash
     end
 
+    # Marshal carries the tick and its resolution.
+    def marshal_dump = [value, unit.count, unit.base]
+
+    def marshal_load(data)
+      v, count, base = data
+      initialize(v, CATime::Resolution.new(count, base))
+    end
+
     # @overload +(td)
     #   Returns this instant advanced by a {CATimedelta::Element}.  The time
     #   is the anchor: the result keeps `self`'s unit and the duration is
     #   converted into it, truncated toward zero when finer (a :D time + a
     #   5 h duration is + 0 days; + 30 h is + 1 day) -- the same rule as the
-    #   array {CATime#+}.  Only a duration in the SAME group (both calendar
-    #   or both fixed) is accepted -- a cross-group step (a :s time + a :M
-    #   duration) is calendar arithmetic; use `to_date` +
-    #   `Date#next_month` / `#next_year` for that.
+    #   array {CATime#+}.  A month or year duration on a fixed grid moves
+    #   the date as Ruby's `Date#>>` does (the day stays unless the month is
+    #   shorter, the time of day stays); a fixed duration on a month or year
+    #   grid raises, as does a month on a grid a day does not divide.
     #   @param td [CATimedelta::Element]
     #   @return [CATime::Element]
-    #   @raise [TypeError, ArgumentError] on a non-timedelta / cross-group operand.
+    #   @raise [TypeError, ArgumentError] on a non-timedelta operand, or a
+    #     pair that has no answer on self's grid.
     def +(td)
       shifted_by_duration(td, 1)
     end
@@ -544,9 +803,13 @@ class CATime
       case other
       when Element
         u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
-        CATimedelta::Element.new(instant_in(u) - other.instant_in(u), u)
-      when CATimedelta::Element
+        v = instant_in(u) - other.instant_in(u)
+        CATimeUnitAlgebra.check_term(v, "-")
+        CATimedelta::Element.new(v, u)
+      when CATimedelta::Element, CATimedelta
         shifted_by_duration(other, -1)
+      when CATime
+        -(other - self)
       else
         raise TypeError, "CATime::Element - #{other.class} is not allowed"
       end
@@ -565,22 +828,33 @@ class CATime
 
     # s +/- td: the time is the anchor, so the result keeps self's unit and
     # the duration is converted into it (truncated toward zero when finer; a
-    # cross-group calendar duration raises).  Mirrors the array CATime +/-.
+    # month or year duration on a fixed grid moves the date by months).
+    # Mirrors the array CATime +/-.
     def shifted_by_duration(td, sign)
+      # An array of durations gives an array of instants, anchored here.
+      return sign > 0 ? td + self : (-td) + self if td.is_a?(CATimedelta)
       unless td.is_a?(CATimedelta::Element)
         raise TypeError,
               "CATime::Element #{sign > 0 ? '+' : '-'} #{td.class} is not " \
               "allowed (add / subtract a CATimedelta)"
       end
-      tv = CATimeUnitAlgebra.convert_scale_trunc(CA_INT64([td.value]), td.unit, unit)[0]
-      Element.new(value + sign * tv, unit)
+      if CATimeUnitAlgebra::CALENDAR.key?(td.unit.base) &&
+         !CATimeUnitAlgebra::CALENDAR.key?(unit.base)
+        # months on a fixed grid move the date as Date#>> does, as the
+        # array does
+        months = sign * td.value * CATimeUnitAlgebra.months_per_tick(td.unit)
+        return Element.new(CATimeUnitAlgebra.shift_months(CA_INT64([value]), unit, months)[0], unit)
+      end
+      tv = CATimeUnitAlgebra.duration_on_grid(CA_INT64([td.value]), td.unit, unit)[0]
+      v = value + sign * tv
+      CATimeUnitAlgebra.check_term(v, sign > 0 ? "+" : "-")
+      Element.new(v, unit)
     end
 
     # Base epoch as a Date.  next_month / next_year clamp end-of-month
     # (Jan 31 -> Feb 28), but the base is day 1, so no clamping ever occurs --
     # do not move the base off the first of the month without revisiting.
     def epoch_date
-      require 'date'
       Date.new(1970, 1, 1, Date::GREGORIAN)  # proleptic Gregorian, matching to_time
     end
 
@@ -602,6 +876,8 @@ class CATime
 end
 
 class CATimedelta
+  include CATimeSurfaceFill
+  include CATimeOperandValues
   # @overload new(*shape, unit: :ns)
   #   Allocates a new int64 storage CArray of the given `shape` and
   #   wraps it as a CATimedelta Face with the given `unit`.
@@ -619,7 +895,7 @@ class CATimedelta
   #   @param unit [CATime::Resolution, Symbol, String] tick resolution.
   #   @return [CATimedelta]
   def self.wrap(raw, unit: :ns)
-    __wrap__(raw, unit)
+    wrap_storage(raw, unit)
   end
 
   # A single duration: an integer tick count plus the resolution those ticks
@@ -686,6 +962,14 @@ class CATimedelta
       [value, unit].hash
     end
 
+    # Marshal carries the tick and its resolution.
+    def marshal_dump = [value, unit.count, unit.base]
+
+    def marshal_load(data)
+      v, count, base = data
+      initialize(v, CATime::Resolution.new(count, base))
+    end
+
     # @overload +(other)
     #   Returns the sum of two durations, promoting to the finer unit.  A
     #   cross-group operand (a :M + a :s duration) has no fixed relation and
@@ -706,7 +990,9 @@ class CATimedelta
     #   @return [CATimedelta::Element]
     def *(n)
       raise TypeError, "CATimedelta::Element * #{n.class} is not allowed (Integer only)" unless n.is_a?(Integer)
-      Element.new(value * n, unit)
+      v = value * n
+      CATimeUnitAlgebra.check_term(v, "*")
+      Element.new(v, unit)
     end
 
     # @overload /(other)
@@ -741,12 +1027,21 @@ class CATimedelta
     private
 
     def combined_with_duration(other, sign)
+      # An array gives an array: durations by durations, and instants for a
+      # duration added to times (subtracting times from a duration is not
+      # defined).
+      case other
+      when CATimedelta then return sign > 0 ? other + self : -(other - self)
+      when CATime      then return other + self if sign > 0
+      end
       unless other.is_a?(Element)
         raise TypeError,
               "CATimedelta::Element #{sign > 0 ? '+' : '-'} #{other.class} is not allowed"
       end
       u = CATimeUnitAlgebra.finer(unit, other.unit)
-      Element.new(duration_in(u) + sign * other.duration_in(u), u)
+      v = duration_in(u) + sign * other.duration_in(u)
+      CATimeUnitAlgebra.check_term(v, sign > 0 ? "+" : "-")
+      Element.new(v, u)
     end
   end
 end
@@ -813,19 +1108,36 @@ class CATime
   #   Returns `self + other` for a {CATimedelta}: the time is the
   #   anchor, so the result keeps `self`'s unit and the duration is converted
   #   into it (a duration finer than `self`'s unit is truncated to it; a
-  #   cross-group calendar duration raises).  Adding two datetimes is
-  #   ill-defined.
-  #   @param other [CATimedelta]
+  #   coarser one that is not a whole number of `self`'s ticks raises).  A
+  #   month or year duration on a fixed grid moves each date as Ruby's
+  #   `Date#>>` does: the day stays unless the new month is shorter (then it
+  #   is that month's last day), and the time of day stays, so
+  #   `2024-01-31 + 1 month` is `2024-02-29`.  The grid has to divide a day
+  #   into whole ticks; on any other (`:W`, `"3 days"`) a month raises, as a
+  #   fixed duration on a month or year grid does.  Adding two datetimes is
+  #   ill-defined.  A single duration -- a {CATimedelta::Element} or a String
+  #   such as `"3 days"` -- is added to every cell.
+  #   @param other [CATimedelta, CATimedelta::Element, String]
+  #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
+  #     duration array)
   #   @return [CATime]
   #   @raise [TypeError] on a non-timedelta operand.
+  #   @raise [ArgumentError] when the duration does not land on `self`'s grid.
+  #   @raise [RangeError] when a result leaves the range of int64 ticks.
   def +(other)
+    given, other = other, CATimeUnitAlgebra.operand(other)
+    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
-      (parent + CATimeUnitAlgebra.convert_scale_trunc(other.parent, other.unit, unit)).time(unit: unit)
+      return shifted_by_months(other, 1) if moved_by_months?(other)
+      d = CATimeUnitAlgebra.duration_on_grid(other.parent, other.unit, unit)
+      d = d[0] if other.scalar?
+      CATimeUnitAlgebra.checked_add(parent, d).time(unit: unit)
     when CATime
       raise TypeError, "CATime + CATime is ill-defined"
     else
-      raise TypeError, "CATime + #{other.class} is not allowed (use CATimedelta)"
+      raise TypeError, "CATime + #{given.class} is not allowed: add a duration " \
+                       "(a CATimedelta, a CATimedelta::Element or a String such as \"3 days\")"
     end
   end
 
@@ -833,24 +1145,91 @@ class CATime
   #   Subtracting a {CATimedelta} yields a {CATime} at `self`'s unit (the
   #   duration is converted into it, truncated when finer); subtracting
   #   another {CATime} yields a {CATimedelta} at the finer of the two
-  #   units (cross-group falls to the fixed unit).
-  #   @param other [CATimedelta, CATime]
+  #   units (cross-group falls to the fixed unit).  A single duration (a
+  #   {CATimedelta::Element}, `"3 days"`) or time (a {CATime::Element}, a
+  #   `Time`, a `Date`, `"2024-01-02"`) is subtracted from every cell.
+  #   @param other [CATimedelta, CATime, CATimedelta::Element, CATime::Element, Time, Date, String]
+  #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
+  #     duration or timestamp array)
   #   @return [CATime, CATimedelta]
   #   @raise [TypeError] on an unsupported operand.
   def -(other)
+    given, other = other, CATimeUnitAlgebra.operand(other)
+    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
-      (parent - CATimeUnitAlgebra.convert_scale_trunc(other.parent, other.unit, unit)).time(unit: unit)
+      return shifted_by_months(other, -1) if moved_by_months?(other)
+      d = CATimeUnitAlgebra.duration_on_grid(other.parent, other.unit, unit)
+      d = d[0] if other.scalar?
+      CATimeUnitAlgebra.checked_sub(parent, d).time(unit: unit)
     when CATime
       u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
       a = CATimeUnitAlgebra.convert_instant!(parent, unit, u)
       b = CATimeUnitAlgebra.convert_instant!(other.parent, other.unit, u)
-      (a - b).timedelta(unit: u)
+      b = b[0] if other.scalar?
+      CATimeUnitAlgebra.checked_sub(a, b).timedelta(unit: u)
     else
-      raise TypeError, "CATime - #{other.class} is not allowed"
+      raise TypeError, "CATime - #{given.class} is not allowed: subtract a duration " \
+                       "(a CATimedelta, a CATimedelta::Element or a String such as \"3 days\") " \
+                       "or a time (a CATime, a CATime::Element, a Time, a Date or a String)"
     end
   end
 
+  # Whether a duration moves this time by calendar months: a month or year
+  # duration on a time whose grid is fixed-length.  A time on a month or year
+  # grid adds it as months already, and a fixed duration on a calendar grid
+  # is refused by the scale conversion.
+  private def moved_by_months? (td)
+    CATimeUnitAlgebra::CALENDAR.key?(td.unit.base) &&
+      !CATimeUnitAlgebra::CALENDAR.key?(unit.base)
+  end
+
+  # self moved by the months of +td+ (+sign+ 1 to add, -1 to subtract), as
+  # Ruby's Date#>> moves a date: the day is kept unless the month is shorter.
+  private def shifted_by_months (td, sign)
+    months = td.parent.int64 * (sign * CATimeUnitAlgebra.months_per_tick(td.unit))
+    months = months[0] if td.scalar?
+    CATimeUnitAlgebra.shift_months(parent, unit, months).time(unit: unit)
+  end
+
+  # @overload pmax(other)
+  #   The later of each cell and `other`, cell by cell: `other` is a time
+  #   array of the same shape, or one time (a {CATime::Element}, a `Time`, a
+  #   `Date`, `"2024-01-02"`) for every cell.  The two meet as a comparison
+  #   does, so the result is in `self`'s unit when `other` sits on its grid
+  #   and in the finer unit the two share otherwise.  A masked cell on either
+  #   side gives a masked cell.
+  #   @param other [CATime, CATime::Element, Time, Date, String]
+  #   @return [CATime]
+  #   @raise [TypeError] when `other` is not a time.
+  def pmax (other)
+    pick_by_order(other) { |a, b| a < b }
+  end
+
+  # @overload pmin(other)
+  #   The earlier of each cell and `other`; see {#pmax}.
+  #   @param other [CATime, CATime::Element, Time, Date, String]
+  #   @return [CATime]
+  #   @raise [TypeError] when `other` is not a time.
+  def pmin (other)
+    pick_by_order(other) { |a, b| a > b }
+  end
+
+  # A time has no NaN, so maximum / minimum (which let a NaN win) are pmax /
+  # pmin, and fmax / fmin are their other names.
+  alias_method :maximum, :pmax
+  alias_method :minimum, :pmin
+  alias_method :fmax, :pmax
+  alias_method :fmin, :pmin
+
+  # `other` where the block says self's cell loses to it, else self's cell.
+  private def pick_by_order (other)
+    return copy.tap { |out| out[] = UNDEF } if UNDEF.equal?(other)
+    a, b = comparable_pair(other)
+    b = b[0] unless other.is_a?(CArray) || other.is_a?(Array)
+    yield(a, b).then_else(b, a)
+  end
+
   # Element-wise comparison (< <= > >= <=>) rides the core comparison Face
   # gate (ca_face_reconcile_comparison in ext/ca_obj_face.c): the inherited
   # CArray operators descend to storage and reconcile a CATime RHS in a
@@ -858,38 +1237,19 @@ class CATime
   # base CArray#<=> composed from the (gated) > and <.
 
   # Element decode convention via the C-layer macro
-  # `CA_FACE_STORAGE_TO_SCALAR_IF_FACE`: no Ruby `[]` override is needed, a
+  # `CA_FACE_STORAGE_TO_ELEMENT_IF_FACE`: no Ruby `[]` override is needed, a
   # scalar auto-decodes on all scalar-return paths such as `ca[i,j,k]` /
-  # `ca[k]`.  storage_to_scalar itself lives in C (ext/ca_obj_datetime.c)
+  # `ca[k]`.  storage_to_element itself lives in C (ext/ca_obj_datetime.c)
   # so the hot path stays off Ruby method dispatch.  Its write counterpart
-  # is scalar_to_storage (below, surface -> storage on store).
+  # is element_to_storage (below, surface -> storage on store).
 
   # @!group Reductions
 
-  # min / max are order-structure reductions: they ride the core reduce
-  # Face gate (ORDERABLE storage descent + output re-lift, see
-  # ext/mkkernel.rb face_gate: :relift), so no Ruby override is needed --
-  # the inherited CArray#min / #max handle the Element / CATime return
-  # shapes directly.  minmax is the paired form; it has no core gate, so
-  # re-lift both extremes here.  They are actual elements, so they keep the
-  # storage unit (no rounding, unlike mean).
-
-  # @overload minmax(*axes, **opts)
-  #   Returns the earliest and latest time as a `[min, max]` pair (§8).
-  #   @return [Array(Element, Element), Array(CATime, CATime)]
-  def minmax(*args, **opts)
-    lo, hi = parent.minmax(*args, **opts)
-    [relift_extremum(lo), relift_extremum(hi)]
-  end
-
-  def relift_extremum(r)
-    case r
-    when Integer then Element.new(r, unit)
-    when CArray  then r.time(unit: unit)
-    else r
-    end
-  end
-  private :relift_extremum
+  # min / max / minmax are order-structure reductions: they ride the core
+  # reduce Face gate (ORDERABLE storage descent + output re-lift, see
+  # ext/mkkernel.rb face_gate: :relift), so the inherited methods return the
+  # Element / CATime shapes directly.  The extremes are actual elements, so
+  # they keep the storage unit (no rounding, unlike mean).
 
   # The centroid / spread / order reductions report on the array's own grid:
   # they run on the storage ticks and round the result back to the nearest
@@ -953,22 +1313,43 @@ class CATime
 
   # @overload sum(*)
   #   Not supported; use {#mean} for a centroid.
-  #   @raise [TypeError] always.
+  #   @raise [CArray::DataTypeError] always.
   def sum(*)
-    raise TypeError, "CATime#sum is ill-defined; use mean for centroid"
+    raise CArray::DataTypeError, "CATime#sum is ill-defined; use mean for centroid"
   end
 
+  # @overload accumulate(*)
+  #   Not supported, for the same reason as {#sum}.
+  #   @raise [CArray::DataTypeError] always.
+  def accumulate(*); raise CArray::DataTypeError, "CATime#accumulate is ill-defined (a sum of instants)"; end
+
+  # @overload cumsum(*)
+  #   Not supported, for the same reason as {#sum}.  The running position
+  #   relative to the first instant is `(t - t[0])` cumulated as durations.
+  #   @raise [CArray::DataTypeError] always.
+  def cumsum(*); raise CArray::DataTypeError, "CATime#cumsum is ill-defined (a sum of instants)"; end
+
+  # @overload prod(*)
+  #   Not supported: a product of instants has no meaning.
+  #   @raise [CArray::DataTypeError] always.
+  def prod(*); raise CArray::DataTypeError, "CATime#prod is ill-defined (a product of instants)"; end
+
+  # @overload cumprod(*)
+  #   Not supported, for the same reason as {#prod}.
+  #   @raise [CArray::DataTypeError] always.
+  def cumprod(*); raise CArray::DataTypeError, "CATime#cumprod is ill-defined (a product of instants)"; end
+
   # @overload variance(*)
   #   Not supported: the variance of instants has squared-time units, which
   #   no type represents (ill-defined, like {#sum}).  Use {#stddev} for the
   #   spread as a duration.
-  #   @raise [TypeError] always.
-  def variance(*); raise TypeError, "CATime#variance is ill-defined (squared-time units); use stddev"; end
+  #   @raise [CArray::DataTypeError] always.
+  def variance(*); raise CArray::DataTypeError, "CATime#variance is ill-defined (squared-time units); use stddev"; end
 
   # @overload variancep(*)
   #   Not supported, for the same reason as {#variance}.  Use {#stddevp}.
-  #   @raise [TypeError] always.
-  def variancep(*); raise TypeError, "CATime#variancep is ill-defined (squared-time units); use stddevp"; end
+  #   @raise [CArray::DataTypeError] always.
+  def variancep(*); raise CArray::DataTypeError, "CATime#variancep is ill-defined (squared-time units); use stddevp"; end
   # @!endgroup
 
   # sort / partition ride the core sort Face gate (ORDERABLE storage
@@ -986,11 +1367,15 @@ class CATime
   #   different unit or shape), so the gate routes the operand through here.
   #
   #   Accepted operands: another {CATime} (unit-rescaled to self),
-  #   a {Element} (lifted to a length-1 CATime), a Ruby `Time`, and a
-  #   Ruby `DateTime` (both absolute instants converted to self's unit,
-  #   Unix epoch, UTC).  A `String` is out of scope (parsing is a separate,
-  #   opposite-direction mechanism).  A bare Integer / other type raises;
-  #   descend to `ca.parent` to compare the hidden storage directly.
+  #   a {Element} (lifted to a length-1 CATime), and an instant written
+  #   outside CArray -- a Ruby `Time`, `Date`, `DateTime`, or a `String` in
+  #   the grammar {CArray.time} reads (UTC unless it carries an offset).
+  #   Those are read at the precision they carry, not at self's unit, and
+  #   then go through the same conversion as a CATime: "2024-01-02 09:00"
+  #   against a day-unit array raises rather than matching 2024-01-02.  A
+  #   bare Integer / other type raises; descend to `ca.parent` to compare
+  #   the hidden storage directly.  An Array of any of these is a 1-D set
+  #   of instants (the value set of {#is_in}).
   #
   #   The rescale is an INSTANT conversion (convert_instant!), lossless: a
   #   coarser->finer unit always converts; a finer->coarser unit converts only
@@ -1000,9 +1385,36 @@ class CATime
   #   :D and finer, and a fixed operand coarsens to :M/:Y only when it sits on
   #   the calendar boundary (:W is the one exception -- month/year starts are
   #   not week-aligned, so :Y/:M <-> :W raises).
-  #   @param operand [CATime, CATime::Element, Time, DateTime]
+  #   @param operand [CATime, CATime::Element, Time, Date, DateTime, String, Array]
   #   @return [CATime] in self's unit.
   #   @raise [TypeError, ArgumentError] on an unreconcilable operand / unit.
+  # Returns `[self, other]` in one unit that holds every value of both
+  # exactly: the finer grid of two same-group units, or the fixed-length one
+  # of a calendar / fixed pair (a month begins on a day).  A lookup between
+  # two arrays of different units (is_in, the set operations, locate_addr and
+  # the joins on them) meets there, so it does not depend on which array is
+  # the receiver.
+  # @api private
+  def in_common_unit_with (other)
+    return [self, other] if other.unit == unit
+    u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
+    [to_unit(u), other.to_unit(u)]
+  end
+
+  private def common_unit (a, b)
+    CATimeUnitAlgebra.diff_unit(a, b)
+  end
+
+  # One instant as a length-1 time array in its own unit, or nil.
+  private def lift_value (operand)
+    case operand
+    when CATime::Element
+      CATime.wrap(CA_INT64([operand.value]), unit: operand.unit)
+    when Time, String, Date
+      CATimeLiteral.exact_instant(operand)
+    end
+  end
+
   def to_comparable (operand)
     case operand
     when CATime
@@ -1012,36 +1424,36 @@ class CATime
     when CATime::Element
       lifted = CATime.wrap(CA_INT64([operand.value]), unit: operand.unit)
       to_comparable(lifted)
-    when Time
-      # Reuse the single-literal builder; it yields a length-1 CATime
-      # in the requested (= self's) resolution.
-      CArray.time(operand, unit: unit)
-    when defined?(DateTime) && DateTime
-      to_comparable(operand.to_time.utc)
+    when Time, String, Date
+      to_comparable(CATimeLiteral.exact_instant(operand))
+    when Array, CArray
+      # A set of instants written one by one (is_in(["2024-01-02", ...])),
+      # or an array that is not a time array (an object column of Time
+      # values, a string column), read value by value.
+      reconcile_values(operand)
     else
       raise TypeError,
             "CATime cannot reconcile #{operand.class} " \
-            "(use ca.parent to compare the raw int64 storage directly)"
+            "(compare #ticks for the raw int64 storage)"
     end
   end
 
-  # @overload scalar_to_storage(surface)
-  #   Write-direction counterpart of storage_to_scalar (the store hook fired
+  # @overload element_to_storage(surface)
+  #   Write-direction counterpart of storage_to_element (the store hook fired
   #   from rb_ca_obj2ptr): brings a surface value object into this Face's
   #   int64 storage (count in self's unit since the Unix epoch) so a scalar
-  #   store round-trips with a fetch.  A {Element} / `Time` / `DateTime` is
-  #   reconciled to self's unit via {#to_comparable} (same lossless
-  #   discipline: a cross-group unit or a non-exact finer->coarser cast
-  #   raises).  A bare Integer (the documented `.parent` raw-storage escape)
-  #   and a String (parsing is a separate, opposite-direction mechanism)
-  #   pass through unchanged to the storage cast.
-  #   @param surface [Element, Time, DateTime, Integer, String]
+  #   store round-trips with a fetch.  A {Element} / `Time` / `Date` /
+  #   `DateTime` / `String` is reconciled to self's unit via {#to_comparable}
+  #   (same lossless discipline: a cross-group unit or a non-exact
+  #   finer->coarser cast raises).  A bare Integer (the documented `.parent`
+  #   raw-storage escape) passes through unchanged to the storage cast.
+  #   @param surface [Element, Time, Date, DateTime, Integer, String]
   #   @return [Integer, Object] the storage-domain value, or `surface`
   #     unchanged for a pass-through type.
   #   @raise [TypeError, ArgumentError] on an unreconcilable surface / unit.
-  def scalar_to_storage (surface)
+  def element_to_storage (surface)
     case surface
-    when Integer, String
+    when Integer
       surface
     else
       to_comparable(surface).parent[0]
@@ -1109,7 +1521,6 @@ class CATime
   #   CArray.  Array-level counterpart to {Element#to_time}.
   #   @return [CArray]
   def to_time
-    require 'time'
     if CATimeUnitAlgebra::FIXED.key?(unit.base)
       f = unit.tick_ratio                        # exact seconds / tick (Rational)
       parent.convert(:object) {|v| Time.at(v * f, in: 'UTC')}
@@ -1124,7 +1535,6 @@ class CATime
   #   {Element#to_date}.
   #   @return [CArray]
   def to_date
-    require 'date'
     # 2440588 = JD of 1970-01-01; proleptic Gregorian to match to_time and the field accessors.
     days_since_epoch.convert(:object) {|d| Date.jd(2440588 + d, Date::GREGORIAN)}
   end
@@ -1134,7 +1544,6 @@ class CATime
   #   as an object CArray.
   #   @return [CArray]
   def to_datetime
-    require 'date'
     to_time.convert(:object) {|t| t.to_datetime}
   end
 
@@ -1187,6 +1596,54 @@ class CATime
   # @return [CArray] integer.
   def second; clock_field(:s); end
 
+  # Quarter of the year, 1..4 (January to March is 1).  For a fiscal year,
+  # count quarters with `timesteps(unit: "3 months", origin:)`.
+  # @return [CArray] integer.
+  def quarter
+    (month - 1) / 3 + 1
+  end
+
+  # ISO 8601 week number, 1..53.  A week runs Monday to Sunday and belongs
+  # to the year its Thursday is in, so the first days of January can be in
+  # the last week of the year before, and the last days of December in
+  # week 1 of the next; {#iso_year} is that year.
+  # @return [CArray] integer.
+  def iso_week
+    thursday, year = iso_thursday
+    ones = CArray.int64(*shape) { 1 }
+    (thursday - CATimeCivil.days_from_civil(year, ones, ones)) / 7 + 1
+  end
+
+  # The ISO 8601 year of each time's week (see {#iso_week}): the calendar
+  # year except in the few days around New Year whose week is counted in the
+  # neighbouring year.
+  # @return [CArray] integer.
+  def iso_year
+    iso_thursday[1]
+  end
+
+  # The Thursday of each time's ISO week, in days since the epoch, and the
+  # year it falls in.
+  private def iso_thursday
+    days = days_since_epoch
+    iso_weekday = (days + 3) % 7 + 1          # Monday 1 .. Sunday 7; 1970-01-01 is a Thursday
+    thursday = days - iso_weekday + 4
+    [thursday, CATimeCivil.civil_from_days(thursday)[0]]
+  end
+
+  # Number of days in the month, 28..31 (January's for `:Y` storage, which
+  # does not resolve months).  `t.day.eq(t.days_in_month)` is the last day of
+  # the month.
+  # @return [CArray] integer.
+  def days_in_month
+    y, m, = CATimeCivil.civil_from_days(days_since_epoch)
+    ones = CArray.int64(*shape) { 1 }
+    ord  = y * 12 + m                     # the next month's ordinal (m is 1..12)
+    ny   = ord / 12
+    CATimeCivil.days_from_civil(ny, ord - ny * 12 + 1, ones) -
+      CATimeCivil.days_from_civil(y, m, ones)
+  end
+
   # Day of the week, Sunday = 0 .. Saturday = 6.
   # @return [CArray] integer.
   def weekday
@@ -1209,7 +1666,6 @@ class CATime
   #   Returns the Julian Day Number for each element.
   #   @return [CArray]
   def jd
-    require 'date'
     to_time.convert(:int) {|t| t.to_date.jd}
   end
 
@@ -1218,7 +1674,6 @@ class CATime
   #   day) for each element.
   #   @return [CArray]
   def ajd
-    require 'date'
     to_time.convert(:double) {|t| t.to_datetime.ajd.to_f}
   end
 
@@ -1248,7 +1703,9 @@ class CATime
   # the centroid of month numbers (a caller wanting the day-space answer
   # writes to_unit(:D) first) -- and the result is rounded back to a tick.
   def reduce_on_own_grid(op, kind, args, opts)
-    round_and_relift(parent.public_send(op, *args, **opts), kind)
+    with_surface_fill(opts) do |o|
+      round_and_relift(parent.public_send(op, *args, **o), kind)
+    end
   end
 
   # Round-to-nearest onto the storage grid, then wear the Face again.  An
@@ -1273,6 +1730,41 @@ class CATime
     end
   end
 
+  # inspect's name for the array: the class and the tick, which the storage
+  # type name (fixlen[8]) does not tell.
+  private def inspect_label
+    "#{self.class}[#{unit}]"
+  end
+
+  # inspect's cell: the instant as Element#to_s writes it, but with the
+  # digits of a second that some cell of the array needs, the same in every
+  # cell so that the cells line up; the unit is in the label.
+  private def inspect_cell_formatter
+    digits = inspect_second_digits
+    lambda do |e|
+      case e.unit.base
+      when :Y, :M, :W, :D then e.to_s
+      else                     e.to_time.iso8601(digits)
+      end
+    end
+  end
+
+  # The digits of a second inspect writes: 0, 3, 6 or 9, the fewest that
+  # show every present cell exactly (9 at most, as Time holds).
+  private def inspect_second_digits
+    base_digits = { ms: 3, us: 6, ns: 9, ps: 12, fs: 15, as: 18 }[unit.base]
+    return 0 unless base_digits
+    count = unit.count
+    [0, 3, 6, 9].each do |d|
+      break if d >= base_digits
+      m = 10**(base_digits - d)
+      # ticks * count is a multiple of m when ticks is one of m / gcd(m, count),
+      # which does not multiply out of int64.
+      return d if (ticks % (m / m.gcd(count))).eq(0).all
+    end
+    [base_digits, 9].min
+  end
+
 end
 
 # ============================================================================
@@ -1319,19 +1811,26 @@ class CATimedelta
   #   {CATimedelta}; a {CATime} operand delegates to
   #   {CATime#+} (commutative).
   #   @param other [CATimedelta, CATime]
+  #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
+  #     duration or timestamp array)
   #   @return [CATimedelta, CATime]
   #   @raise [TypeError] on incompatible operands.
   def +(other)
+    given, other = other, CATimeUnitAlgebra.operand(other)
+    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
       u = common_duration_unit(other.unit)
       a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
-      (a + b).timedelta(unit: u)
+      b = b[0] if other.scalar?
+      CATimeUnitAlgebra.checked_add(a, b).timedelta(unit: u)
     when CATime
-      other + self  # commutative -> time's unit
+      return other + self unless other.scalar?   # commutative -> time's unit
+      d = CATimeUnitAlgebra.duration_on_grid(parent, unit, other.unit)
+      CATimeUnitAlgebra.checked_add(d, other.parent[0]).time(unit: other.unit)
     else
-      raise TypeError, "CATimedelta + #{other.class} is not allowed"
+      raise TypeError, "CATimedelta + #{given.class} is not allowed"
     end
   end
 
@@ -1339,17 +1838,22 @@ class CATimedelta
   #   Returns the difference of two {CATimedelta} at the finer of the two
   #   units (a cross-group pair raises).
   #   @param other [CATimedelta]
+  #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
+  #     duration array)
   #   @return [CATimedelta]
   #   @raise [TypeError] on a non-timedelta operand.
   def -(other)
+    given, other = other, CATimeUnitAlgebra.operand(other)
+    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
       u = common_duration_unit(other.unit)
       a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
-      (a - b).timedelta(unit: u)
+      b = b[0] if other.scalar?
+      CATimeUnitAlgebra.checked_sub(a, b).timedelta(unit: u)
     else
-      raise TypeError, "CATimedelta - #{other.class} is not allowed"
+      raise TypeError, "CATimedelta - #{given.class} is not allowed"
     end
   end
 
@@ -1375,28 +1879,34 @@ class CATimedelta
   #   @raise [TypeError] when `other` is not an Integer.
   def *(other)
     case other
-    when Integer then (parent * other).timedelta(unit: unit)
+    when Integer then CATimeUnitAlgebra.checked_mul(parent, other).timedelta(unit: unit)
     else raise TypeError, "CATimedelta * #{other.class} is not allowed (Integer only)"
     end
   end
 
   # @overload /(other)
   #   Returns element-wise division: by Integer yields a
-  #   {CATimedelta}, by another {CATimedelta} with matching `unit`
-  #   yields a dimensionless CArray.
+  #   {CATimedelta} (truncated toward zero to the unit), by another
+  #   {CATimedelta} their ratio as a float64 CArray (90 s / 60 s is 1.5),
+  #   the two brought to a common unit first.
   #   @param other [Integer, CATimedelta]
+  #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
+  #     duration array)
   #   @return [CATimedelta, CArray]
   #   @raise [TypeError] on incompatible operands.
   def /(other)
+    given, other = other, CATimeUnitAlgebra.operand(other)
     case other
     when Integer
       CATimeUnitAlgebra.trunc_divide(parent, other).timedelta(unit: unit)
     when CATimedelta
+      # A ratio of durations is a number, not a count of whole ticks: 90 s /
+      # 60 s is 1.5.  Both are brought to one unit first, so the ratio does
+      # not depend on the units they are held in.
       u = common_duration_unit(other.unit)
-      CATimeUnitAlgebra.trunc_divide(
-        CATimeUnitAlgebra.convert_scale!(parent, unit, u),
-        CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u))
-    else raise TypeError, "CATimedelta / #{other.class} is not allowed"
+      CATimeUnitAlgebra.convert_scale!(parent, unit, u).to_type(:float64) /
+        CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
+    else raise TypeError, "CATimedelta / #{given.class} is not allowed"
     end
   end
 
@@ -1409,17 +1919,73 @@ class CATimedelta
 
   # @overload sum(*args, **opts)
   #   Returns the sum of durations as a {Element} for full reduction
-  #   or as a {CATimedelta} view for per-axis reduction.
+  #   or as a {CATimedelta} view for per-axis reduction.  The sum is exact:
+  #   the unit counts are added in int64, not in float64.
   #   @return [Element, CATimedelta]
+  #   @raise [RangeError] if a sum does not fit int64 (for a per-axis
+  #     reduction, if any of its cells does not).
   def sum(*args, **opts)
-    round_and_relift(parent.sum(*args, **opts))
+    with_surface_fill(opts) { |o|
+      exact_sum_relift(parent.accumulate(*args, **o), parent.sum(*args, **o))
+    }
+  end
+
+  # int64 addition is exact modulo 2**64, so the int64 sum is the true sum
+  # whenever the true sum fits int64, whatever order the cells were added
+  # in.  Whether it fits is read from the float64 sum, whose error is far
+  # inside the factor of 2 between 2**62 and 2**63.
+  def exact_sum_relift (exact, approx)
+    past = case approx
+           when Numeric then approx.abs > 2.0**62
+           when CArray  then (approx.abs > 2.0**62).any
+           else false
+           end
+    raise RangeError, "sum of durations does not fit int64 (in #{unit})" if past
+    case exact
+    when Integer then Element.new(exact, unit)
+    when CArray  then exact.timedelta(unit: unit)
+    else exact
+    end
+  end
+  private :exact_sum_relift
+
+  # @overload accumulate(*args, **opts)
+  #   Returns the sum of durations in the storage's integer type (int64),
+  #   added without a range check: a sum past int64 wraps.  {#sum} gives
+  #   the same answer when it fits and raises RangeError when it does not.
+  #   @return [Element, CATimedelta]
+  def accumulate(*args, **opts)
+    with_surface_fill(opts) { |o| round_and_relift(parent.accumulate(*args, **o)) }
   end
 
+  # @overload cumsum(axis: nil)
+  #   Returns the running sum of durations as a {CATimedelta} on `self`'s
+  #   unit.  A masked cell holds the running sum, as {CArray#cumsum} does.
+  #   The running sum is exact: the unit counts are added in int64, as
+  #   {#sum} adds them.
+  #   @return [CATimedelta]
+  #   @raise [RangeError] if any cell of the running sum does not fit int64.
+  def cumsum(*args, **opts)
+    exact_sum_relift(parent.send(:cumsum_in_own_type, *args, **opts),
+                     parent.cumsum(*args, **opts))
+  end
+
+  # @overload prod(*)
+  #   Not supported: a product of durations has the units of a power of
+  #   time, which no type represents.
+  #   @raise [CArray::DataTypeError] always.
+  def prod(*); raise CArray::DataTypeError, "CATimedelta#prod is ill-defined (powers of time units)"; end
+
+  # @overload cumprod(*)
+  #   Not supported, for the same reason as {#prod}.
+  #   @raise [CArray::DataTypeError] always.
+  def cumprod(*); raise CArray::DataTypeError, "CATimedelta#cumprod is ill-defined (powers of time units)"; end
+
   # @overload mean(axis: nil, **opts)
   #   Returns the mean duration rounded to the nearest unit count.
   #   @return [Element, CATimedelta]
   def mean(*args, **opts)
-    round_and_relift(parent.mean(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.mean(*args, **o)) }
   end
 
   # median / percentile / quantile / stddev / stddevp report on this array's
@@ -1431,7 +1997,7 @@ class CATimedelta
   #   Returns the median duration on `self`'s unit.
   #   @return [Element, CATimedelta]
   def median(*args, **opts)
-    round_and_relift(parent.median(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.median(*args, **o)) }
   end
 
   # @overload percentile(*p, axis: nil, **opts)
@@ -1440,7 +2006,7 @@ class CATimedelta
   #   two or more give an Array).
   #   @return [Element, CATimedelta, Array<Element>, Array<CATimedelta>]
   def percentile(*args, **opts)
-    round_and_relift(parent.percentile(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.percentile(*args, **o)) }
   end
 
   # @overload quantile(axis: nil, **opts)
@@ -1448,7 +2014,7 @@ class CATimedelta
   #   `self`'s unit.
   #   @return [Array<Element>, Array<CATimedelta>]
   def quantile(*args, **opts)
-    round_and_relift(parent.quantile(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.quantile(*args, **o)) }
   end
 
   # @overload stddev(axis: nil, **opts)
@@ -1457,7 +2023,7 @@ class CATimedelta
   #   the precision matters.
   #   @return [Element, CATimedelta]
   def stddev(*args, **opts)
-    round_and_relift(parent.stddev(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.stddev(*args, **o)) }
   end
 
   # @overload stddevp(axis: nil, **opts)
@@ -1465,7 +2031,7 @@ class CATimedelta
   #   {#stddev}.
   #   @return [Element, CATimedelta]
   def stddevp(*args, **opts)
-    round_and_relift(parent.stddevp(*args, **opts))
+    with_surface_fill(opts) { |o| round_and_relift(parent.stddevp(*args, **o)) }
   end
 
   def round_and_relift(r)
@@ -1482,39 +2048,21 @@ class CATimedelta
   #   Not supported: the variance of durations has squared-time units, which
   #   no type represents -- the same reason {CATime#variance} refuses.  Use
   #   {#stddev} for the spread as a duration.
-  #   @raise [TypeError] always.
+  #   @raise [CArray::DataTypeError] always.
   def variance(*)
-    raise TypeError, "CATimedelta#variance is ill-defined (squared-time units); use stddev"
+    raise CArray::DataTypeError, "CATimedelta#variance is ill-defined (squared-time units); use stddev"
   end
 
   # @overload variancep(*)
   #   Not supported, for the same reason as {#variance}.  Use {#stddevp}.
-  #   @raise [TypeError] always.
+  #   @raise [CArray::DataTypeError] always.
   def variancep(*)
-    raise TypeError, "CATimedelta#variancep is ill-defined (squared-time units); use stddevp"
-  end
-
-  # min / max ride the core reduce Face gate (ORDERABLE storage descent +
-  # output re-lift, see ext/mkkernel.rb face_gate: :relift); the inherited
-  # CArray#min / #max return the Element / CATimedelta shapes directly.
-  # minmax has no core gate, so re-lift both extremes here.
-
-  # @overload minmax(*axes, **opts)
-  #   Returns the shortest and longest duration as a `[min, max]` pair.
-  #   @return [Array(Element, Element), Array(CATimedelta, CATimedelta)]
-  def minmax(*args, **opts)
-    lo, hi = parent.minmax(*args, **opts)
-    [relift_extremum(lo), relift_extremum(hi)]
+    raise CArray::DataTypeError, "CATimedelta#variancep is ill-defined (squared-time units); use stddevp"
   end
 
-  def relift_extremum(r)
-    case r
-    when Integer then Element.new(r, unit)
-    when CArray  then r.timedelta(unit: unit)
-    else r
-    end
-  end
-  private :relift_extremum
+  # min / max / minmax ride the core reduce Face gate (ORDERABLE storage
+  # descent + output re-lift); the inherited methods return the Element /
+  # CATimedelta shapes directly.
   # @!endgroup
 
   # sort / partition ride the core sort Face gate (ORDERABLE storage
@@ -1535,6 +2083,34 @@ class CATimedelta
   #   @param operand [CATimedelta, CATimedelta::Element]
   #   @return [CATimedelta] in self's unit.
   #   @raise [TypeError, ArgumentError] on an unreconcilable operand / unit.
+  # Returns `[self, other]` in one unit, the finer grid of the two, which
+  # holds every value of both exactly.  A lookup between two duration
+  # arrays of different units meets there, so it does not depend on which
+  # array is the receiver.  A calendar and a fixed-length duration have no
+  # common unit and raise.
+  # @api private
+  def in_common_unit_with (other)
+    return [self, other] if other.unit == unit
+    unless CATimeUnitAlgebra.same_group?(unit, other.unit)
+      raise ArgumentError,
+            "cannot compare a #{unit} duration with a #{other.unit} duration: " \
+            "a calendar length (months, years) has no fixed length in days"
+    end
+    u = CATimeUnitAlgebra.finer(unit, other.unit)
+    [to_unit(u), other.to_unit(u)]
+  end
+
+  private def common_unit (a, b)
+    CATimeUnitAlgebra.finer(a, b)
+  end
+
+  # One duration as a length-1 duration array in its own unit, or nil.
+  private def lift_value (operand)
+    if operand.is_a?(CATimedelta::Element)
+      CATimedelta.wrap(CA_INT64([operand.value]), unit: operand.unit)
+    end
+  end
+
   def to_comparable (operand)
     case operand
     when CATimedelta
@@ -1544,15 +2120,19 @@ class CATimedelta
     when CATimedelta::Element
       lifted = CATimedelta.wrap(CA_INT64([operand.value]), unit: operand.unit)
       to_comparable(lifted)
+    when Array, CArray
+      # Durations written one by one, or an array that is not a duration
+      # array (an object column of elements), read value by value.
+      reconcile_values(operand)
     else
       raise TypeError,
             "CATimedelta cannot reconcile #{operand.class} " \
-            "(use ca.parent to compare the raw int64 storage directly)"
+            "(compare #ticks for the raw int64 storage)"
     end
   end
 
-  # @overload scalar_to_storage(surface)
-  #   Write-direction counterpart of storage_to_scalar: brings a surface
+  # @overload element_to_storage(surface)
+  #   Write-direction counterpart of storage_to_element: brings a surface
   #   value object into this Face's int64 storage (count in self's unit) so a
   #   scalar store round-trips with a fetch.  A {Element} is reconciled to
   #   self's unit via {#to_comparable} (lossless discipline; a `Time` /
@@ -1563,7 +2143,7 @@ class CATimedelta
   #   @return [Integer, Object] the storage-domain value, or `surface`
   #     unchanged for a pass-through type.
   #   @raise [TypeError, ArgumentError] on an unreconcilable surface / unit.
-  def scalar_to_storage (surface)
+  def element_to_storage (surface)
     case surface
     when Integer, String
       surface
@@ -1609,6 +2189,17 @@ class CATimedelta
     end
     CATimeUnitAlgebra.finer(unit, ou)
   end
+
+  # inspect's name for the array: the class and the tick, which the storage
+  # type name (fixlen[8]) does not tell.
+  private def inspect_label
+    "#{self.class}[#{unit}]"
+  end
+
+  # inspect's cell: the duration in the base unit of the tick.
+  private def inspect_cell_formatter
+    lambda { |e| "#{e.value * e.unit.count}#{e.unit.base}" }
+  end
 end
 
 # Reads a time literal (Time / DateTime / Integer unix-seconds / String) into
@@ -1621,39 +2212,153 @@ module CATimeLiteral
 
   # Date fields of a String literal, UTC.  Ruby's Date._parse does not read
   # the calendar-grid forms CATime#to_s prints -- "2019-09" comes back as a
-  # month of 20 with a zone, and a bare "2019" as a month and a day -- so
-  # those two are read here and everything else is left to Date._parse.
+  # month of 20 with a zone, and a bare "2019" as a month and a day -- nor an
+  # hour alone after the date ("2024-01-01T05", ISO 8601 reduced to the
+  # hour), so those are read here and everything else is left to Date._parse.
+  # Date._parse passes over what it cannot read, so text with a time after
+  # the date that comes back without an hour is refused rather than read as
+  # midnight.
   #
   # What Date._parse returns is then checked, because an out-of-range field
   # used to flow into the civil kernel and normalise into a different date:
   # "201909" is a valid YYMMDD to Ruby (2020-19-09, which landed on 2021-07),
   # and "2019-02-31" landed on 2019-03-03.  A missing finer field is not an
   # error -- a year or a year-month names the head of that period.
+  # %s and %Q give the seconds since the epoch, not the date's fields;
+  # they are spelled out as the UTC date and time they name.
+  def epoch_fields(h)
+    return h unless h && h[:seconds] && !h[:year]
+    t = Time.at(h[:seconds]).utc
+    frac = h[:seconds] - h[:seconds].floor
+    { year: t.year, mon: t.month, mday: t.day, hour: t.hour, min: t.min,
+      sec: t.sec, sec_fraction: frac.zero? ? nil : Rational(frac), leftover: h[:leftover] }.compact
+  end
+
   def parse_date_fields(spec, format)
     h =
-      if format                             then Date._strptime(spec, format)
+      if format                             then epoch_fields(Date._strptime(spec, format))
       elsif spec =~ /\A(\d{4})-(\d{1,2})\z/ then { year: $1.to_i, mon: $2.to_i }
       elsif spec =~ /\A(\d{4})\z/           then { year: $1.to_i }
+      elsif (hour = hour_only_fields(spec)) then hour
       else                                       Date._parse(spec)
       end
+    h = resolve_day_of_year(h, spec) if h
     unless h && h[:year]
       raise ArgumentError, "cannot parse time #{spec.inspect}"
     end
+    if !format && !h[:hour] &&
+       (spec =~ /\d\s*T\s*\d/ || spec =~ /\A\s*[+-]?\d{4,}[-\/]\d{1,2}[-\/]\d{1,2}\s+\d/)
+      raise ArgumentError, "cannot parse time #{spec.inspect}: the time after the date is not read"
+    end
+    # Text left over after the format is not part of a time in that format.
+    if h[:leftover] && !h[:leftover].strip.empty?
+      raise ArgumentError,
+            "cannot parse time #{spec.inspect}: #{h[:leftover].inspect} is " \
+            "left over after #{format.inspect}"
+    end
     y, m, d = h[:year], h[:mon] || 1, h[:mday] || 1
     unless (1..12).cover?(m) && Date.valid_date?(y, m, d, Date::GREGORIAN)
       raise ArgumentError,
             "cannot parse time #{spec.inspect}: it reads as year #{y}, " \
             "month #{m}, day #{d}, which is not a date"
     end
+    # Hour 24 is the end of the day, 24:00:00, and nothing past it.
+    if h[:hour] == 24 && [h[:min], h[:sec], h[:sec_fraction]].any? { |v| v && v != 0 }
+      raise ArgumentError,
+            "cannot parse time #{spec.inspect}: hour 24 is only 24:00:00"
+    end
+    # A clock field out of range is refused rather than carried into the
+    # next one ("10:75" is not 11:15).  Second 60 is the leap second.
+    { hour: 24, min: 59, sec: 60 }.each do |key, top|
+      v = h[key]
+      next if v.nil? || (0..top).cover?(v)
+      raise ArgumentError,
+            "cannot parse time #{spec.inspect}: #{key} #{v} is out of range"
+    end
     h
   end
   private_class_method :parse_date_fields
 
+  # The month and day of a date written by its day of the year ("2024-015",
+  # %j), its ISO week ("2024-W03-1", %G-W%V-%u) or its week of the year
+  # (%U / %W with a weekday).  Date._parse and Date._strptime return those
+  # fields as they are written; left alone, the date would fall back to
+  # January 1.
+  def resolve_day_of_year(h, spec)
+    return h if h[:mon] || h[:mday]
+    date =
+      if h[:yday] && h[:year]
+        unless Date.valid_ordinal?(h[:year], h[:yday], Date::GREGORIAN)
+          raise ArgumentError,
+                "cannot parse time #{spec.inspect}: year #{h[:year]} has no day #{h[:yday]}"
+        end
+        Date.ordinal(h[:year], h[:yday], Date::GREGORIAN)
+      elsif h[:cwyear] && h[:cweek]
+        wd = h[:cwday] || 1
+        unless Date.valid_commercial?(h[:cwyear], h[:cweek], wd, Date::GREGORIAN)
+          raise ArgumentError,
+                "cannot parse time #{spec.inspect}: ISO year #{h[:cwyear]} " \
+                "has no week #{h[:cweek]}, day #{wd}"
+        end
+        Date.commercial(h[:cwyear], h[:cweek], wd, Date::GREGORIAN)
+      elsif h[:year] && (h[:wnum0] || h[:wnum1])
+        jan1 = Date.new(h[:year], 1, 1, Date::GREGORIAN)
+        wday = h[:wday] || (h[:cwday] && h[:cwday] % 7)
+        # Week 1 begins on the first Sunday (%U) or Monday (%W) of the year;
+        # the days before it are week 0.
+        if h[:wnum0]
+          first = jan1 + (7 - jan1.wday) % 7
+          d = first + (h[:wnum0] - 1) * 7 + (wday || 0)
+        else
+          first = jan1 + (8 - jan1.wday) % 7
+          d = first + (h[:wnum1] - 1) * 7 + ((wday || 1) + 6) % 7
+        end
+        unless d.year == h[:year]
+          raise ArgumentError,
+                "cannot parse time #{spec.inspect}: the week and weekday fall outside #{h[:year]}"
+        end
+        d
+      end
+    return h unless date
+    h.merge(year: date.year, mon: date.month, mday: date.day)
+  end
+  private_class_method :resolve_day_of_year
+
+  # "YYYY-MM-DDThh" with an optional zone ("Z", "+hh", "+hhmm", "+hh:mm").
+  def hour_only_fields(spec)
+    m = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2})(?:(Z)|([+-])(\d{2})(?::?(\d{2}))?)?\z/.match(spec)
+    return nil unless m
+    h = { year: m[1].to_i, mon: m[2].to_i, mday: m[3].to_i, hour: m[4].to_i }
+    raise ArgumentError, "cannot parse time #{spec.inspect}: hour #{h[:hour]}" if h[:hour] > 23
+    if m[6]
+      oh, om = m[7].to_i, m[8].to_i
+      raise ArgumentError, "cannot parse time #{spec.inspect}: offset" if oh > 23 || om > 59
+      h[:offset] = (oh * 3600 + om * 60) * (m[6] == "-" ? -1 : 1)
+    elsif m[5]
+      h[:offset] = 0
+    end
+    h
+  end
+  private_class_method :hour_only_fields
+
+  # An instant written outside CArray (Time / Date / DateTime / String) as a
+  # length-1 CATime in the coarsest of :s / :ms / :us / :ns that holds it
+  # exactly, so a comparison sees the instant it names and not that instant
+  # floored onto some other grid.  Finer than a nanosecond raises.
+  def exact_instant(spec)
+    sec = epoch_seconds(spec)
+    [:s, :ms, :us, :ns].each_with_index do |u, k|
+      ticks = sec * (10 ** (3 * k))
+      if ticks.denominator == 1
+        return CATime.wrap(CA_INT64([ticks.to_i]), unit: u)
+      end
+    end
+    raise ArgumentError, "#{spec.inspect} is finer than a nanosecond"
+  end
+
   # Exact Rational seconds since the Unix epoch for a start literal (Time /
-  # DateTime / Integer unix-seconds / String).  UTC default.
+  # Date / DateTime / Integer unix-seconds / String).  UTC default.
   def epoch_seconds(spec, format = nil)
-    require 'date'
-    require 'time'
     case spec
     when Time     then spec.to_r
     when Integer  then Rational(spec)
@@ -1680,6 +2385,8 @@ module CATimeLiteral
     else
       if defined?(DateTime) && spec.is_a?(DateTime)
         spec.to_time.to_r
+      elsif defined?(Date) && spec.is_a?(Date)
+        Rational(CATimeCivil.days_from_civil_1(spec.year, spec.month, spec.day) * 86400)
       else
         raise ArgumentError, "cannot parse time #{spec.class}"
       end
@@ -1688,8 +2395,6 @@ module CATimeLiteral
 
   # [year, month] (UTC) of a start literal, for a calendar-resolution grid.
   def year_month(spec, format = nil)
-    require 'date'
-    require 'time'
     case spec
     when Time    then t = spec.utc; [t.year, t.month]
     when Integer then t = Time.at(spec, in: 'UTC'); [t.year, t.month]
@@ -1727,6 +2432,273 @@ module CATimeLiteral
     end
   end
 
+  # A format :infer can choose: a strptime format, read strictly (see
+  # __strptime_fields__), and what the text carries (:date, :clock, or
+  # :fraction of a second).
+  TimeFormat = Struct.new(:format, :kind)
+
+  INFER_DATES = %w[%d/%m/%Y %m/%d/%Y %d-%m-%Y %m-%d-%Y %d.%m.%Y %d/%m/%y %m/%d/%y] +
+                ["%d %b %Y", "%d-%b-%Y", "%d-%b-%y", "%b %d, %Y", "%b %d %Y", "%Y%m%d"]
+  Ractor.make_shareable(INFER_DATES)
+
+  # A space in a format matches any run of spaces, none included.
+  INFER_CLOCKS = [
+    ["%H:%M", :clock], ["%H:%M:%S", :clock], ["%H:%M:%S.%N", :fraction],
+    ["%I:%M %p", :clock], ["%I:%M:%S %p", :clock],
+  ].freeze
+  Ractor.make_shareable(INFER_CLOCKS)
+
+  # A time after a date: none, or a clock with or without a zone. %z takes
+  # an offset, Z, UTC or GMT, not a zone named for a place (some of those
+  # names mean different offsets in different places).
+  INFER_TIMES = ([["", :date]] +
+    INFER_CLOCKS.flat_map { |clock, kind| [[" #{clock}", kind], [" #{clock} %z", kind]] }
+  ).freeze
+  Ractor.make_shareable(INFER_TIMES)
+
+  # A date written in Japanese, year first ("2024<year>1<month>2<day>"),
+  # takes a time in the same markers ("3<hour>4<minute>", "...5<second>")
+  # or with colons.
+  JA_YEAR, JA_MONTH, JA_DAY = "年", "月", "日"
+  JA_HOUR, JA_MINUTE, JA_SECOND = "時", "分", "秒"
+  [JA_YEAR, JA_MONTH, JA_DAY, JA_HOUR, JA_MINUTE, JA_SECOND].each { |s| Ractor.make_shareable(s) }
+  INFER_JA_TIMES = ([["", :date]] +
+    ([["%H#{JA_HOUR}%M#{JA_MINUTE}", :clock],
+      ["%H#{JA_HOUR}%M#{JA_MINUTE}%S#{JA_SECOND}", :clock]] + INFER_CLOCKS)
+      .map { |clock, kind| [" #{clock}", kind] }).freeze
+  Ractor.make_shareable(INFER_JA_TIMES)
+
+  INFER_FORMATS = (
+    INFER_DATES.product(INFER_TIMES).map { |date, (time, kind)|
+      TimeFormat.new(date + time, kind)
+    } +
+    INFER_JA_TIMES.map { |time, kind|
+      TimeFormat.new("%Y#{JA_YEAR}%m#{JA_MONTH}%d#{JA_DAY}#{time}", kind)
+    }
+  ).freeze
+  Ractor.make_shareable(INFER_FORMATS)
+  INFER_FORMAT_STRINGS = INFER_FORMATS.map(&:format).freeze
+  Ractor.make_shareable(INFER_FORMAT_STRINGS)
+
+  # The one format of INFER_FORMATS that the text of object array `x` is
+  # written in, `first` being its first present cell, as
+  # [format, fields, address]: the fields __strptime_fields__ read in it,
+  # and the address of the first cell not in it, or nil.
+  #
+  # The first cell gives the candidates and each later cell drops those it
+  # does not fit, until one is left. Each candidate is read over the whole
+  # array once, and the candidate a later cell leaves last is the one left:
+  # no candidate for the first cell or none left (the last ones dropped by
+  # one cell) raises CAFrame::UnreadableColumn, and more than one left at the
+  # end raises CAFrame::AmbiguousTimeFormat (CAFrame is its only caller). A cell
+  # after the choice that is not in the format is returned for the caller
+  # to report.
+  def infer_time_format(x, first)
+    candidates = CArray.__strptime_fits__(first, INFER_FORMAT_STRINGS)
+    if candidates.empty?
+      raise CAFrame::UnreadableColumn,
+            "cannot infer a time format from #{first.inspect}; " \
+            "pass a strptime format, or :mixed to guess at each cell"
+    end
+    runs = candidates.map do |i|
+      fields = x.__strptime_fields__(INFER_FORMATS[i].format, true)
+      [INFER_FORMATS[i], fields, fields[7].first || Float::INFINITY]
+    end
+    last = runs.map(&:last).max
+    left = runs.select { |run| run[2] == last }
+    if left.size > 1
+      if last == Float::INFINITY
+        formats = left.map { |run| run[0].format }
+        raise CAFrame::AmbiguousTimeFormat.new(
+                "#{first.inspect} could be read as " \
+                "#{formats.map(&:inspect).join(' or ')}, " \
+                "and no cell tells which; pass the format",
+                formats: formats)
+      end
+      raise CAFrame::UnreadableColumn,
+            "#{x.flatten[last].inspect} is not in the format of #{first.inspect}; " \
+            "pass a strptime format, or :mixed to guess at each cell"
+    end
+    f, fields, bad = left.first
+    [f, fields, bad == Float::INFINITY ? nil : bad]
+  end
+
+  # [kind, per] for __time_ticks_from_fields__: ticks of `per` nanoseconds
+  # (:fixed) or months (:calendar), or nil when `res` is finer than a
+  # nanosecond.
+  def tick_kind(res)
+    if CATimeUnitAlgebra::FIXED.key?(res.base)
+      per = res.tick_ratio * 1_000_000_000
+      kind = :fixed
+    else
+      per = res.tick_ratio
+      kind = :calendar
+    end
+    (per.denominator == 1 && per >= 1) ? [kind, per.to_i] : nil
+  end
+
+  # The ticks of every cell of `x` on the `res` grid, as an int64 array of
+  # x's shape (missing and, under on_error: :mask, unparseable cells
+  # masked), or nil when `res` is finer than a nanosecond. A strptime
+  # format that __strptime_fields__ reads is read for the whole array in C;
+  # otherwise each String is parsed into fields here. Either way the fields
+  # become ticks for the whole array at once, and a cell that is not a
+  # String goes through tick_index.
+  def ticks_from_cells(x, res, format, on_error, seconds: false)
+    kind, per = tick_kind(res)
+    return nil unless kind
+    if format.is_a?(String)
+      text = (x.data_type == CA_OBJECT && !x.face?) ? x : x.to_type(:object)
+      fields = text.__strptime_fields__(format, false)
+      return ticks_from_fields(fields, x, res, format, on_error) if fields
+    end
+    cells = x.flatten.to_a
+    n = cells.size
+    year = Array.new(n, 1970)
+    mon = Array.new(n, 1)
+    day = Array.new(n, 1)
+    sod = Array.new(n, 0)
+    frac = Array.new(n, 0)
+    off = Array.new(n, 0)
+    present = Array.new(n, 0)
+    direct = {}
+    cells.each_with_index do |s, i|
+      next if s.nil? || UNDEF.equal?(s)
+      begin
+        if s.is_a?(String)
+          h = parse_date_fields(s, format)
+          year[i] = h[:year]
+          mon[i] = h[:mon] || 1
+          day[i] = h[:mday] || 1
+          sod[i] = (h[:hour] || 0) * 3600 + (h[:min] || 0) * 60 + (h[:sec] || 0)
+          frac[i] = (h[:sec_fraction] * 1_000_000_000).floor if h[:sec_fraction]
+          off[i] = h[:offset] if h[:offset]
+          present[i] = 1
+        elsif s.is_a?(Integer) && format.nil?
+          # an Integer counts ticks of the unit given, or seconds when the
+          # unit is chosen from the values
+          direct[i] = seconds ? tick_index(s, res) : s
+        else
+          direct[i] = tick_index(s, res, format)
+        end
+      rescue ArgumentError, TypeError
+        raise if on_error == :raise
+      end
+    end
+    raw = CArray.__time_ticks_from_fields__(
+      CA_INT64(year), CA_INT64(mon), CA_INT64(day), CA_INT64(sod),
+      CA_INT64(frac), CA_INT64(off), CA_UINT8(present), kind, per)
+    check_ticks_fit(raw, present, present.count(1), res) { cells }
+    direct.each { |i, t| raw[i] = t }
+    raw.reshape(*x.shape)
+  end
+
+  # Ticks from what __strptime_fields__ read; the cells it deferred are
+  # read one by one through tick_index.
+  def ticks_from_fields(fields, x, res, format, on_error)
+    kind, per = tick_kind(res)
+    year, mon, day, sod, frac, off, present, unreadable, deferred, = fields
+    cells = nil
+    if on_error == :raise && !unreadable.empty?
+      cells = x.flatten.to_a
+      raise ArgumentError, "cannot parse time #{cells[unreadable.first].inspect}"
+    end
+    raw = CArray.__time_ticks_from_fields__(year, mon, day, sod, frac, off,
+                                            present, kind, per)
+    check_ticks_fit(raw, present, present.sum, res) { cells ||= x.flatten.to_a }
+    unless deferred.empty?
+      cells ||= x.flatten.to_a
+      deferred.each do |i|
+        raw[i] = tick_index(cells[i], res, format)
+      rescue ArgumentError, TypeError
+        raise if on_error == :raise
+      end
+    end
+    raw.reshape(*x.shape)
+  end
+
+  # A tick that does not fit int64 is out of range, not unparseable.
+  def check_ticks_fit(raw, present, present_count, res)
+    return if raw.count_not_masked >= present_count
+    cells = yield
+    i = (0...raw.elements).find { |k| present[k] == 1 && UNDEF.equal?(raw[k]) }
+    raise RangeError, "time #{cells[i].inspect} does not fit int64 ticks of #{res}"
+  end
+
+  # The unit CArray.time reads +x+ in when none is given: the finest any of
+  # its values shows (see the unit: of CArray.time), :s when none shows one.
+  def unit_shown(x, format)
+    cells = x.is_a?(CArray) ? x.flatten.to_a : [x]
+    text = cells.select { |v| v.is_a?(String) }
+    units = []
+    unless text.empty?
+      if format
+        units << format_unit(format)
+      else
+        unreadable = []
+        _, read = CA_OBJECT(text).__parse_time_text__(nil, unreadable, true)
+        units << read if read
+        unreadable.each do |i|
+          u = text_unit(text[i])
+          units << u if u
+        end
+      end
+    end
+    cells.each do |v|
+      case v
+      when Integer then units << :s
+      when CATime::Element then units << v.unit
+      when Time then units << CATimeLiteral.exact_instant(v).unit
+      when Date
+        units << (defined?(DateTime) && v.is_a?(DateTime) ? CATimeLiteral.exact_instant(v.to_time).unit : :D)
+      end
+    end
+    # A month beside a day is read on the fixed grid both instants reach,
+    # as two elements are compared (diff_unit); finer covers one group only.
+    units.map { |u| CATime::Resolution.parse(u) }
+         .reduce { |a, b| CATimeUnitAlgebra.diff_unit(a, b) } || CATime::Resolution.parse(:s)
+  end
+
+  # The unit a String read with Date._parse shows, or nil when it does not
+  # read (the reading raises or masks it later).
+  def text_unit(str)
+    h = Date._parse(str)
+    return nil unless h && h[:year]
+    return fraction_unit(h[:sec_fraction].denominator) if h[:sec_fraction]
+    (h[:hour] || h[:min] || h[:sec]) ? :s : :D
+  end
+
+  # The finest field a strptime format writes.
+  def format_unit(format)
+    if (m = format.match(/%(\d*)([LNQ])/))
+      return :ms if m[2] == "L" || m[2] == "Q"
+      digits = m[1].empty? ? 9 : m[1].to_i
+      return fraction_unit(10 ** digits)
+    end
+    format.match?(/%[-_0^#]*[sSTHIklMRrXcp]/) ? :s : :D
+  end
+
+  def fraction_unit(denominator)
+    digits = Math.log10(denominator).ceil
+    digits <= 3 ? :ms : digits <= 6 ? :us : :ns
+  end
+
+  # +x+ with each Integer replaced by its decimal digits as a String, for a
+  # format to read; a masked cell stays masked.
+  def integers_as_text(x)
+    case x
+    when Integer then x.to_s
+    when CArray
+      return x if x.face? || !(x.integer? || x.data_type == CA_OBJECT)
+      text = CArray.object(*x.shape)
+      cells = x.flatten.to_a
+      cells.each_with_index { |v, i| text[i] = v.is_a?(Integer) ? v.to_s : v }
+      text = text.reshape(*x.shape) if x.ndim > 1
+      text
+    else x
+    end
+  end
+
   # Single-literal build for {.time}: a 1-element CATime, honouring
   # the on_error policy (raise, or a masked cell).
   def to_time_array(literal, res, format, on_error)
@@ -1806,10 +2778,13 @@ class CArray
 
   # @overload time(x, unit: :s, format: nil, on_error: :raise)
   #   Builds a {CATime} on the `unit` grid from time value(s).  `x`
-  #   is either a single literal (Time / ISO 8601 String / Unix-seconds
-  #   Integer / DateTime) — giving a 1-element result — or a CArray of such
+  #   is either a single literal (Time / ISO 8601 String / Integer /
+  #   DateTime) — giving a 1-element result — or a CArray of such
   #   literals — giving a same-shape result parsed per cell.  Parsing is UTC
-  #   and DateTime-independent.
+  #   and DateTime-independent.  An Integer counts ticks of `unit` from
+  #   the epoch, so it is Unix seconds when `unit` is not given (also among
+  #   values that make the chosen unit finer):
+  #   `CArray.time(CA_INT64([0, 10]), unit: :m)` is 00:00 and 00:10.
   #
   #   A value that cannot be parsed raises by default (`on_error: :raise`);
   #   pass `on_error: :mask` to make it an UNDEF cell instead.  A masked /
@@ -1817,8 +2792,16 @@ class CArray
   #   becomes UNDEF, regardless of `on_error`.
   #   @param x [Time, String, Integer, DateTime, CATime::Element, Array, CArray] a literal, a
   #     Ruby Array of literals, or a CArray of literals.
-  #   @param unit [Resolution, Symbol, String] target grid resolution.
+  #   @param unit [Resolution, Symbol, String, nil] target grid resolution;
+  #     by default the finest the values show, so nothing they hold is cut
+  #     off: text written to the day is `:D`, to the second `:s`, with a
+  #     fraction `:ms` / `:us` / `:ns` by its digits (as
+  #     `CAFrame#parse_to_time` reads text); with a format, the finest field
+  #     the format writes; an Integer `:s`; a Time the finest
+  #     its value needs; a Date `:D`; an element its own unit.
   #   @param format [String, nil] optional strptime format for String input.
+  #     With a format, an Integer is read as its decimal digits
+  #     (`CArray.time(20240101, format: "%Y%m%d")`), not as a count of ticks.
   #   @param on_error [:raise, :mask] parse-failure policy (default `:raise`).
   #   @return [CATime] shape `[1]` for a literal, else `x`'s shape.
   #   @raise [ArgumentError] on an unparseable value when `on_error: :raise`.
@@ -1827,15 +2810,26 @@ class CArray
   #   CArray.time("2024-06-15", unit: :D)                    # 1-element
   #   CArray.time(%w[2024-01-01 2024-02-01], unit: :D)       # Ruby Array
   #   CArray.time(CA_OBJECT(["2024-01-01", "oops"]), unit: :D, on_error: :mask)
-  def self.time(x, unit: :s, format: nil, on_error: :raise)
-    res = CATime::Resolution.parse(unit)
+  def self.time(x, unit: nil, format: nil, on_error: :raise)
     unless %i[raise mask].include?(on_error)
       raise ArgumentError, "on_error: must be :raise or :mask (got #{on_error.inspect})"
     end
     x = CA_OBJECT(x) if x.is_a?(Array)   # Ruby Array of literals -> object CArray
+    # With a format, an Integer is the digits it is written with (20240101
+    # read as "%Y%m%d"), not a count of ticks: a format describes text.
+    x = CATimeLiteral.integers_as_text(x) if format
+    res = unit ? CATime::Resolution.parse(unit) : CATimeLiteral.unit_shown(x, format)
+    # Without a format, an Integer counts ticks of the unit from the epoch:
+    # seconds by default, minutes with unit: :m.
+    if format.nil?
+      return CA_INT64([x]).time(unit: res) if x.is_a?(Integer)
+      return (x.data_type == CA_INT64 ? x.copy : x).time(unit: res) if x.is_a?(CArray) && !x.face? && x.integer?
+    end
     unless x.is_a?(CArray)
       return CATimeLiteral.to_time_array(x, res, format, on_error)
     end
+    raw = CATimeLiteral.ticks_from_cells(x, res, format, on_error, seconds: unit.nil?)
+    return raw.time(unit: res) if raw
     raw = CArray.int64(*x.shape)
     x.each_index do |*idx|
       s = x[*idx]
@@ -1844,7 +2838,7 @@ class CArray
         next
       end
       begin
-        raw[*idx] = CATimeLiteral.tick_index(s, res, format)
+        raw[*idx] = s.is_a?(Integer) && format.nil? && unit ? s : CATimeLiteral.tick_index(s, res, format)
       rescue ArgumentError, TypeError
         raise if on_error == :raise
         raw[*idx] = UNDEF        # opt-in parse-mask
@@ -1861,8 +2855,10 @@ class CArray
   #   int64 array is built; the origin is not stored).
   #   @param unit [Resolution, Symbol, String] grid resolution.
   #   @param origin [Time, String, Integer, DateTime, CATime::Element, nil] base instant that
-  #     `self`'s indices are counted from (default: the Unix epoch).
+  #     `self`'s indices are counted from (default: the Unix epoch); an
+  #     Integer is Unix seconds.  It has to be a point of the `unit` grid.
   #   @return [CATime]
+  #   @raise [ArgumentError] when `origin` falls between two ticks of `unit`.
   #   @note An `int64` receiver is wrapped zero-copy.  A narrower integer type
   #     is widened to `int64` first (a copy); a `Float` / non-integer type
   #     raises (cast it explicitly if the truncation is intended).
@@ -1872,8 +2868,11 @@ class CArray
     if origin.nil?
       CATime.wrap(src, unit: res)
     else
-      o = CATimeLiteral.tick_index(origin, res)
-      (src + o).time(unit: res)
+      # The origin is a point of the grid: one between two ticks has no
+      # index, so it raises rather than moving to the tick before it.
+      origin = Time.at(origin, in: "UTC") if origin.is_a?(Integer)
+      o = CATimeGrid.resolve_origin_ticks(origin, res, res)
+      CATimeUnitAlgebra.checked_add(src, o).time(unit: res)
     end
   end
 
@@ -1899,6 +2898,13 @@ class CArray
             "array cannot be wrapped (cast it explicitly, e.g. " \
             "arr.int64.time(...), if a lossy conversion is intended)"
     end
+    if data_type == CA_UINT64
+      hi = max
+      if hi != UNDEF && hi > 2**63 - 1
+        raise RangeError,
+              "CATime / CATimedelta storage is int64; #{hi} does not fit"
+      end
+    end
     int64
   end
   private :as_int64_time_storage
@@ -2232,6 +3238,7 @@ class CATime
              m: "minutes", s: "seconds", ms: "milliseconds",
              us: "microseconds", ns: "nanoseconds", ps: "picoseconds",
              fs: "femtoseconds", as: "attoseconds" }.freeze
+    Ractor.make_shareable(WORD)
 
     # Storage resolutions to fall back on when the unit's own tick cannot
     # hold the origin exactly (a day grid anchored at 12:00 needs seconds).
@@ -2268,7 +3275,8 @@ class CATime
       @unit    = Resolution.parse(unit)
       @origin  = origin
       @storage = resolve_storage
-      @origin  = CArray.time(origin, unit: @storage)[0] if origin
+      # An Integer origin is an instant in Unix seconds, whatever the unit.
+      @origin  = CATimeLiteral.to_time_array(origin, @storage, nil, :raise)[0] if origin
       freeze
     end
 
@@ -2470,6 +3478,34 @@ class CATime
     snap(grid, unit: unit, origin: origin, direction: :floor)
   end
 
+  # @overload end_of(grid = nil, unit:, origin: nil)
+  #   Each element at the last tick of its bucket, on the array's own grid:
+  #   the bucket {#floor} gives the head of, one tick before the next head.
+  #   A day array's month ends on the month's last day, a second array's at
+  #   23:59:59 of it:
+  #
+  #     CArray.time(%w[2024-02-10 2024-03-31], unit: :D).end_of(unit: :M)
+  #     # => 2024-02-29, 2024-03-31
+  #
+  #   The bucket has to be a whole number of the array's ticks, since its
+  #   end is counted on that grid.
+  #   @return [CATime]
+  #   @raise [ArgumentError] when the bucket is finer than the grid or not a
+  #     whole number of its ticks.
+  def end_of(grid = nil, unit: nil, origin: nil)
+    step, origin = Grid.resolve(grid, unit, origin)
+    step = CATime::Resolution.parse(step)
+    per  = CATimeUnitAlgebra.ratio(step, self.unit)    # ticks of the grid per bucket
+    if per && !(per.denominator == 1 && per >= 1)
+      raise ArgumentError,
+            "end_of: a bucket of #{step} is not a whole number of the #{self.unit} " \
+            "grid's ticks, so its last tick is not on the grid"
+    end
+    head = floor(unit: step, origin: origin)
+    head + CATimedelta::Element.new(step.count, step.base) -
+      CATimedelta::Element.new(self.unit.count, self.unit.base)
+  end
+
   # @overload ceil(grid = nil, unit:, origin: nil)
   #   {#snap} with `direction: :ceil` -- each element at the bucket head at
   #   or after it (an element already on a boundary maps to itself).