carray 3.0.4 → 3.0.6

data/lib/carray/time.rb

@@ -113,6 +113,13 @@ module CATimeUnitAlgebra
     end
   end
 
+  # How a refusal names an operand: a Face by its class, any other array as
+  # a CArray (a lazy expression's node classes are not the user's), anything
+  # else by its class.
+  def operand_name(x)
+    ( x.is_a?(CArray) && !x.face? ) ? "CArray" : x.class.to_s
+  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
@@ -138,6 +145,20 @@ module CATimeUnitAlgebra
     end
   end
 
+  # A duration String added to or subtracted from a time, as one step of its
+  # own resolution: "15 minutes" is one 15-minute step, the duration
+  # CArray.int64(1).timedelta(unit: "15 minutes") is, so it lands on a
+  # "10 minutes" grid or is refused in the same way.  nil for anything else.
+  def step_operand(x)
+    return nil unless x.is_a?(String)
+    res = begin
+            CATime::Resolution.parse(x)
+          rescue ArgumentError
+            return nil
+          end
+    CATimedelta.wrap(CScalar.int64 { 1 }, unit: res)
+  end
+
   def scalar_instant(t, unit)
     v = begin
           convert_instant!(t.parent, t.unit, unit)[0]
@@ -1071,7 +1092,7 @@ class CATime
   #   resolution (see §4 of docs/CATime.md).
   #   @return [CArray]
   def ticks
-    parent
+    face_storage
   end
 
   # @overload to_unit(unit)
@@ -1101,7 +1122,10 @@ class CATime
   #   @raise [RangeError] when the widened ticks overflow int64.
   def to_unit(unit)
     to = CATime::Resolution.parse(unit)
-    CATimeUnitAlgebra.convert_instant_floor(parent, self.unit, to).time(unit: to)
+    # The conversion hands back the storage itself when the unit does not
+    # change; the result is a new array whichever unit is asked for.
+    return face_storage.copy.time(unit: to) if to == self.unit
+    CATimeUnitAlgebra.convert_instant_floor(face_storage, self.unit, to).time(unit: to)
   end
 
   # @overload +(other)
@@ -1116,7 +1140,9 @@ class CATime
   #   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.
+  #   such as `"3 days"` -- is added to every cell; a String is one step of
+  #   its own resolution, so `"15 minutes"` on a `"10 minutes"` grid raises
+  #   as `CArray.int64(1).timedelta(unit: "15 minutes")` does.
   #   @param other [CATimedelta, CATimedelta::Element, String]
   #     (or a MemoryView producer whose +to_ca+ gives one, such as an Arrow
   #     duration array)
@@ -1126,17 +1152,18 @@ class CATime
   #   @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
+    other = CATimeUnitAlgebra.step_operand(other) ||
+            CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
       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)
+      CATimeUnitAlgebra.checked_add(face_storage, d).time(unit: unit)
     when CATime
       raise TypeError, "CATime + CATime is ill-defined"
     else
-      raise TypeError, "CATime + #{given.class} is not allowed: add a duration " \
+      raise TypeError, "CATime + #{CATimeUnitAlgebra.operand_name(given)} is not allowed: add a duration " \
                        "(a CATimedelta, a CATimedelta::Element or a String such as \"3 days\")"
     end
   end
@@ -1155,21 +1182,22 @@ class CATime
   #   @raise [TypeError] on an unsupported operand.
   def -(other)
     given, other = other, CATimeUnitAlgebra.operand(other)
-    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
+    other = CATimeUnitAlgebra.step_operand(other) ||
+            CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when CATimedelta
       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)
+      CATimeUnitAlgebra.checked_sub(face_storage, d).time(unit: unit)
     when CATime
       u = CATimeUnitAlgebra.diff_unit(unit, other.unit)
-      a = CATimeUnitAlgebra.convert_instant!(parent, unit, u)
+      a = CATimeUnitAlgebra.convert_instant!(face_storage, unit, u)
       b = CATimeUnitAlgebra.convert_instant!(other.parent, other.unit, u)
       b = b[0] if other.scalar?
       CATimeUnitAlgebra.checked_sub(a, b).timedelta(unit: u)
     else
-      raise TypeError, "CATime - #{given.class} is not allowed: subtract a duration " \
+      raise TypeError, "CATime - #{CATimeUnitAlgebra.operand_name(given)} 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
@@ -1189,7 +1217,7 @@ class CATime
   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)
+    CATimeUnitAlgebra.shift_months(face_storage, unit, months).time(unit: unit)
   end
 
   # @overload pmax(other)
@@ -1255,8 +1283,9 @@ class CATime
   # they run on the storage ticks and round the result back to the nearest
   # tick of `unit`.  A caller who needs a finer answer declares the grid
   # first (`t.to_unit(:ms).mean`) -- the same rule linear_fetch follows.
-  # Rounding is to nearest, not toward zero: a truncating round would flip
-  # the direction of the error at the epoch.
+  # Rounding is to nearest, and a tie goes to the later tick: rounding half
+  # away from zero would send a tie later after 1970 and earlier before it,
+  # so moving the data by whole days would change the answer.
 
   # @overload mean(axis: nil, **opts)
   #   Returns the centroid time on `self`'s unit (§8), rounded to the
@@ -1492,7 +1521,7 @@ class CATime
   #   @return [Element, CATime] an {Element} for a scalar `addr`, `nil` when
   #     that single answer is undetermined.
   def linear_fetch (addr, **opts)
-    r = parent.float64.linear_fetch(addr, **opts)
+    r = face_storage.float64.linear_fetch(addr, **opts)
     case r
     when CArray
       # mask_invalid before the int64 cast: the cast turns a NaN into 0, which
@@ -1523,7 +1552,7 @@ class CATime
   def to_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')}
+      face_storage.convert(:object) {|v| Time.at(v * f, in: 'UTC')}
     else                                         # calendar: exact granule midnight
       (days_since_epoch * 86400).convert(:object) {|v| Time.at(v, in: 'UTC')}
     end
@@ -1557,8 +1586,8 @@ class CATime
   # @return [CArray]
   def year
     case unit.base
-    when :Y then parent * unit.count + 1970
-    when :M then (parent * unit.count + 1970 * 12) / 12
+    when :Y then face_storage * unit.count + 1970
+    when :M then (face_storage * unit.count + 1970 * 12) / 12
     else CATimeCivil.civil_from_days(days_since_epoch)[0]
     end
   end
@@ -1568,9 +1597,9 @@ class CATime
   # @return [CArray] integer.
   def month
     case unit.base
-    when :Y then parent * 0 + 1
+    when :Y then face_storage * 0 + 1
     when :M
-      mo = parent * unit.count + 1970 * 12
+      mo = face_storage * unit.count + 1970 * 12
       mo % 12 + 1
     else CATimeCivil.civil_from_days(days_since_epoch)[1]
     end
@@ -1581,7 +1610,7 @@ class CATime
   # @return [CArray] integer.
   def day
     case unit.base
-    when :Y, :M then parent * 0 + 1
+    when :Y, :M then face_storage * 0 + 1
     else CATimeCivil.civil_from_days(days_since_epoch)[2]
     end
   end
@@ -1704,7 +1733,7 @@ class CATime
   # writes to_unit(:D) first) -- and the result is rounded back to a tick.
   def reduce_on_own_grid(op, kind, args, opts)
     with_surface_fill(opts) do |o|
-      round_and_relift(parent.public_send(op, *args, **o), kind)
+      round_and_relift(face_storage.public_send(op, *args, **o), kind)
     end
   end
 
@@ -1714,14 +1743,15 @@ class CATime
   def round_and_relift(r, kind)
     case r
     when Numeric
-      v = r.round
+      v = kind == :timedelta ? r.round : (r + 0.5).floor
       kind == :timedelta ? CATimedelta::Element.new(v, unit) : Element.new(v, unit)
     when CArray
       # A cell with no answer arrives masked and the mask survives the cast.
       # NaN does not: it has no int64 image, so a `fill_value: Float::NAN`
       # cell would cast to garbage bits.  mask_invalid turns it into UNDEF,
       # which is what "no answer" means here.
-      iv = r.round.mask_invalid.int64
+      near = kind == :timedelta ? r.round : (r + 0.5).floor
+      iv = near.mask_invalid.int64
       kind == :timedelta ? iv.timedelta(unit: unit) : iv.time(unit: unit)
     when Array
       r.map {|x| round_and_relift(x, kind)}
@@ -1781,7 +1811,7 @@ class CATimedelta
   #   measured in this array's resolution (see {CATime#ticks}).
   #   @return [CArray]
   def ticks
-    parent
+    face_storage
   end
 
   # @overload to_unit(unit)
@@ -1803,7 +1833,9 @@ class CATimedelta
   #   @raise [RangeError] when the widened ticks overflow int64.
   def to_unit(unit)
     to = CATime::Resolution.parse(unit)
-    CATimeUnitAlgebra.convert_scale_trunc(parent, self.unit, to).timedelta(unit: to)
+    # As CATime#to_unit: a new array even when the unit does not change.
+    return face_storage.copy.timedelta(unit: to) if to == self.unit
+    CATimeUnitAlgebra.convert_scale_trunc(face_storage, self.unit, to).timedelta(unit: to)
   end
 
   # @overload +(other)
@@ -1821,16 +1853,16 @@ class CATimedelta
     case other
     when CATimedelta
       u = common_duration_unit(other.unit)
-      a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
+      a = CATimeUnitAlgebra.convert_scale!(face_storage, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
       b = b[0] if other.scalar?
       CATimeUnitAlgebra.checked_add(a, b).timedelta(unit: u)
     when CATime
       return other + self unless other.scalar?   # commutative -> time's unit
-      d = CATimeUnitAlgebra.duration_on_grid(parent, unit, other.unit)
+      d = CATimeUnitAlgebra.duration_on_grid(face_storage, unit, other.unit)
       CATimeUnitAlgebra.checked_add(d, other.parent[0]).time(unit: other.unit)
     else
-      raise TypeError, "CATimedelta + #{given.class} is not allowed"
+      raise TypeError, "CATimedelta + #{CATimeUnitAlgebra.operand_name(given)} is not allowed"
     end
   end
 
@@ -1848,12 +1880,12 @@ class CATimedelta
     case other
     when CATimedelta
       u = common_duration_unit(other.unit)
-      a = CATimeUnitAlgebra.convert_scale!(parent, unit, u)
+      a = CATimeUnitAlgebra.convert_scale!(face_storage, unit, u)
       b = CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
       b = b[0] if other.scalar?
       CATimeUnitAlgebra.checked_sub(a, b).timedelta(unit: u)
     else
-      raise TypeError, "CATimedelta - #{given.class} is not allowed"
+      raise TypeError, "CATimedelta - #{CATimeUnitAlgebra.operand_name(given)} is not allowed"
     end
   end
 
@@ -1862,14 +1894,14 @@ class CATimedelta
   #   unit.
   #   @return [CATimedelta]
   def abs
-    parent.abs.timedelta(unit: unit)
+    face_storage.abs.timedelta(unit: unit)
   end
 
   # @overload -@
   #   Returns each duration with its sign reversed, on the same unit.
   #   @return [CATimedelta]
   def -@
-    (-parent).timedelta(unit: unit)
+    (-face_storage).timedelta(unit: unit)
   end
 
   # @overload *(other)
@@ -1879,8 +1911,8 @@ class CATimedelta
   #   @raise [TypeError] when `other` is not an Integer.
   def *(other)
     case other
-    when Integer then CATimeUnitAlgebra.checked_mul(parent, other).timedelta(unit: unit)
-    else raise TypeError, "CATimedelta * #{other.class} is not allowed (Integer only)"
+    when Integer then CATimeUnitAlgebra.checked_mul(face_storage, other).timedelta(unit: unit)
+    else raise TypeError, "CATimedelta * #{CATimeUnitAlgebra.operand_name(other)} is not allowed (Integer only)"
     end
   end
 
@@ -1898,13 +1930,13 @@ class CATimedelta
     given, other = other, CATimeUnitAlgebra.operand(other)
     case other
     when Integer
-      CATimeUnitAlgebra.trunc_divide(parent, other).timedelta(unit: unit)
+      CATimeUnitAlgebra.trunc_divide(face_storage, 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.convert_scale!(parent, unit, u).to_type(:float64) /
+      CATimeUnitAlgebra.convert_scale!(face_storage, unit, u).to_type(:float64) /
         CATimeUnitAlgebra.convert_scale!(other.parent, other.unit, u)
     else raise TypeError, "CATimedelta / #{given.class} is not allowed"
     end
@@ -1926,7 +1958,7 @@ class CATimedelta
   #     reduction, if any of its cells does not).
   def sum(*args, **opts)
     with_surface_fill(opts) { |o|
-      exact_sum_relift(parent.accumulate(*args, **o), parent.sum(*args, **o))
+      exact_sum_relift(face_storage.accumulate(*args, **o), face_storage.sum(*args, **o))
     }
   end
 
@@ -1955,7 +1987,7 @@ class CATimedelta
   #   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)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.accumulate(*args, **o)) }
   end
 
   # @overload cumsum(axis: nil)
@@ -1966,8 +1998,8 @@ class CATimedelta
   #   @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))
+    exact_sum_relift(face_storage.send(:cumsum_in_own_type, *args, **opts),
+                     face_storage.cumsum(*args, **opts))
   end
 
   # @overload prod(*)
@@ -1985,7 +2017,7 @@ class CATimedelta
   #   Returns the mean duration rounded to the nearest unit count.
   #   @return [Element, CATimedelta]
   def mean(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.mean(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.mean(*args, **o)) }
   end
 
   # median / percentile / quantile / stddev / stddevp report on this array's
@@ -1997,7 +2029,7 @@ class CATimedelta
   #   Returns the median duration on `self`'s unit.
   #   @return [Element, CATimedelta]
   def median(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.median(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.median(*args, **o)) }
   end
 
   # @overload percentile(*p, axis: nil, **opts)
@@ -2006,7 +2038,7 @@ class CATimedelta
   #   two or more give an Array).
   #   @return [Element, CATimedelta, Array<Element>, Array<CATimedelta>]
   def percentile(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.percentile(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.percentile(*args, **o)) }
   end
 
   # @overload quantile(axis: nil, **opts)
@@ -2014,7 +2046,7 @@ class CATimedelta
   #   `self`'s unit.
   #   @return [Array<Element>, Array<CATimedelta>]
   def quantile(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.quantile(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.quantile(*args, **o)) }
   end
 
   # @overload stddev(axis: nil, **opts)
@@ -2023,7 +2055,7 @@ class CATimedelta
   #   the precision matters.
   #   @return [Element, CATimedelta]
   def stddev(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.stddev(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.stddev(*args, **o)) }
   end
 
   # @overload stddevp(axis: nil, **opts)
@@ -2031,7 +2063,7 @@ class CATimedelta
   #   {#stddev}.
   #   @return [Element, CATimedelta]
   def stddevp(*args, **opts)
-    with_surface_fill(opts) { |o| round_and_relift(parent.stddevp(*args, **o)) }
+    with_surface_fill(opts) { |o| round_and_relift(face_storage.stddevp(*args, **o)) }
   end
 
   def round_and_relift(r)
@@ -2168,7 +2200,7 @@ class CATimedelta
   #   @return [Element, CATimedelta] an {Element} for a scalar `addr`, `nil`
   #     when that single answer is undetermined.
   def linear_fetch (addr, **opts)
-    r = parent.float64.linear_fetch(addr, **opts)
+    r = face_storage.float64.linear_fetch(addr, **opts)
     case r
     when CArray  then r.mask_invalid.round.int64.timedelta(unit: unit)
     when Numeric then r.to_f.nan? ? nil : Element.new(r.round, unit)
@@ -3464,8 +3496,18 @@ class CATime
       fl = o + q * step_ticks
       return bucket_head_as_time(fl + step_ticks * n.ne(fl), mul, su)
     when :round
-      r = d - q * step_ticks                      # 0 <= r < step_ticks
-      q = q + r.ge((step_ticks + 1) / 2)          # ties -> future; no 2*d / 2*r
+      if mul == 1 and [:M, :Y].include?(su.base)
+        # A month or year tick is the start of its month or year, so the
+        # nearest head is by the instant, measured in days.
+        fl   = o + q * step_ticks
+        here = days_since_epoch
+        lo   = fl.time(unit: su).send(:days_since_epoch)
+        hi   = (fl + step_ticks).time(unit: su).send(:days_since_epoch)
+        q    = q + (hi - here).le(here - lo)      # ties -> future
+      else
+        r = d - q * step_ticks                    # 0 <= r < step_ticks
+        q = q + r.ge((step_ticks + 1) / 2)        # ties -> future; no 2*d / 2*r
+      end
     end
     bucket_head_as_time(o + q * step_ticks, mul, su)
   end
@@ -3517,8 +3559,10 @@ class CATime
   # @overload round(grid = nil, unit:, origin: nil)
   #   {#snap} with `direction: :round` -- each element at its nearest bucket
   #   head, ties toward the future.  Exact for odd `step_ticks` (no half-tick
-  #   loss).  For a calendar bucket the nearest head is by absolute tick
-  #   distance (month lengths vary), ties toward the future.
+  #   loss).  For a calendar bucket the nearest head is by the instant (month
+  #   lengths vary), ties toward the future.  A month or year storage tick
+  #   stands for the start of its month or year, so a `:M` array rounds as
+  #   the same dates on `:D` do: 1889-07 to the year is 1889.
   #   @return [CATime]
   def round(grid = nil, unit: nil, origin: nil)
     snap(grid, unit: unit, origin: origin, direction: :round)
@@ -3604,7 +3648,7 @@ class CATime
 
   # Storage ticks lifted into the numerator grid (see {#resolve_timestep_grid}).
   def storage_ticks_in_numerator_grid(mul)
-    mul == 1 ? parent : CATimeUnitAlgebra.widen(parent, mul)
+    mul == 1 ? face_storage : CATimeUnitAlgebra.widen(face_storage, mul)
   end
 
   # A bucket head computed in numerator ticks, back as a {CATime} in the
@@ -3638,15 +3682,15 @@ class CATime
   # an empty array, or one whose every cell is masked.
   def raise_if_int64_overflow(su, mul, o, step_ticks = nil, kind = nil)
     return unless mul > 1 or FINE_UNITS.include?(su.base)
-    min = parent.min
+    min = face_storage.min
     return if min == UNDEF
     lo  = Integer(min) * mul
-    hi  = Integer(parent.max) * mul
+    hi  = Integer(face_storage.max) * mul
     chk = ->(v, w) { CATimeGrid.check_int64_range(v, w) }
     chk.(lo, "ticks in bucket resolution")
     chk.(hi, "ticks in bucket resolution")
-    chk.(lo - o, "parent - origin")
-    chk.(hi - o, "parent - origin")
+    chk.(lo - o, "face_storage - origin")
+    chk.(hi - o, "face_storage - origin")
     if kind
       chk.(bucket_head_ticks(lo, o, step_ticks, kind), "bucket head")
       chk.(bucket_head_ticks(hi, o, step_ticks, kind), "bucket head")
@@ -3674,22 +3718,22 @@ class CATime
     case res.base
     when :Y
       ones = CArray.int64(*shape) { 1 }
-      CATimeCivil.days_from_civil(parent * res.count + 1970, ones, ones)
+      CATimeCivil.days_from_civil(face_storage * res.count + 1970, ones, ones)
     when :M
-      mo = parent * res.count + 1970 * 12
+      mo = face_storage * res.count + 1970 * 12
       y  = mo / 12
       m  = mo - y * 12 + 1
       CATimeCivil.days_from_civil(y, m, CArray.int64(*shape) { 1 })
-    when :W then parent * res.count * 7
-    when :D then parent * res.count
+    when :W then face_storage * res.count * 7
+    when :D then face_storage * res.count
     else                                                   # fixed sub-day storage
       day = CATime::Resolution.new(1, :D)
       r   = CATimeUnitAlgebra.ratio(day, res)          # storage ticks per day
       if r.denominator == 1
-        parent / r.numerator
+        face_storage / r.numerator
       else                                                 # non-day-aligned tick
         tr = res.tick_ratio                                # seconds / tick
-        parent * tr.numerator / (86400 * tr.denominator)
+        face_storage * tr.numerator / (86400 * tr.denominator)
       end
     end
   end
@@ -3702,9 +3746,9 @@ class CATime
   # calendar-storage element has no intra-day field, so it collapses to 0.
   def clock_field(fu)
     r = CATimeUnitAlgebra.ratio(unit, CATime::Resolution.new(1, fu))  # fu ticks / storage tick
-    return parent * 0 if r.nil?                            # calendar storage: no clock field
-    fi = r.denominator == 1 ? parent * r.numerator         # epoch-relative fu index
-                            : parent * r.numerator / r.denominator
+    return face_storage * 0 if r.nil?                            # calendar storage: no clock field
+    fi = r.denominator == 1 ? face_storage * r.numerator         # epoch-relative fu index
+                            : face_storage * r.numerator / r.denominator
     cycle = fu == :h ? 24 : 60                             # hour 0..23; min/sec 0..59
     fi % cycle
   end
@@ -3725,12 +3769,12 @@ class CATime
     return k if kind == :index
     head = CATimeGrid.calendar_bucket_head_ticks(k, st, su, origin)
     return head.time(unit: su) if kind == :floor
-    return parent.eq(head)          if kind == :on
+    return face_storage.eq(head)          if kind == :on
     head_next = CATimeGrid.calendar_bucket_head_ticks(k + 1, st, su, origin)
     sel =                                # boolean 0/1: pick head_next?
       case kind
-      when :ceil  then parent.ne(head)                 # on-boundary keeps head
-      when :round then (head_next - parent).le(parent - head)  # nearest, ties -> future
+      when :ceil  then face_storage.ne(head)                 # on-boundary keeps head
+      when :round then (head_next - face_storage).le(face_storage - head)  # nearest, ties -> future
       end
     (head + (head_next - head) * sel).time(unit: su)
   end

data/lib/carray/window_iterator.rb

@@ -106,6 +106,14 @@ class CAWindowIterator < CAIterator
             "windows: expected #{@source.ndim} ranges (one per axis), " \
             "got #{@ranges.size}"
     end
+    # Each window is read through a view with one axis per anchor and one
+    # per cell in the window, twice the source's rank.
+    if 2 * @source.ndim > CA_RANK_MAX
+      raise ArgumentError,
+            "windows: a rank #{@source.ndim} array would need #{2 * @source.ndim} " \
+            "axes for its windows, beyond the limit of #{CA_RANK_MAX}; " \
+            "windows works up to rank #{CA_RANK_MAX / 2}"
+    end
     @ranges = @ranges.each_with_index.map { |r, k| window_offsets(r, k) }
 
     @sndim  = @source.ndim
@@ -151,14 +159,15 @@ class CAWindowIterator < CAIterator
 
   # ---- padded entity + sliding_windows view -----------------------------
   #
-  # The engine: pad the source once (:skip -> UNDEF, :nearest -> edge, :constant
+  # The engine: pad the source (:skip -> UNDEF, :nearest -> edge, :constant
   # -> value; :truncate does not pad), then take a sliding_windows view.  Both
-  # are memoised: every named reduction reuses the one pad + one view.
+  # are kept for one call, so the helpers a reduction runs share one pad and
+  # one view, and the next call pads the source as it is then.
 
   # @overload sliding_view
   #   Returns the sliding_windows view feeding the reductions.  For :truncate
   #   this is the source's own view (zero-copy); otherwise it is the view over
-  #   the padded entity.
+  #   a padded copy made from the source as it is at this call.
   #   @return [CArray]
   def sliding_view
     @sliding_view ||= @shape.include?(0) ? no_windows : anchored_buffer.sliding_windows(*@widths)
@@ -553,7 +562,7 @@ class CAWindowIterator < CAIterator
   # Runs the fold by offset, or returns nil when this window is not one it can
   # answer for -- in which case the caller delegates as before.
   def fold_by_offset (op, min_count, fill_value = nil)
-    return nil unless CArray.__fast_paths_enabled__
+    return nil unless CArray.__fast_paths_enabled__(:window_fold_by_offset)
     need = CArray.__present_cells_needed_per_result_cell__(op, min_count, 0)
     return nil unless op == :mean || OFFSET_FOLD.key?(op)
     # The elementwise kernels act on a Face's storage; its reductions are its own.
@@ -1150,6 +1159,9 @@ class CAWindowIterator < CAIterator
       yield idx
     end
   end
+
+  read_source_per_call :@sliding_view, :@padded_entity, :@neutral_value,
+                       :@offset_fold_base, :@window_cell_counts
 end
 
 

data/yard-stubs/ca_obj_array.rb

@@ -244,7 +244,8 @@ class CScalar
   # @!group Construction
 
   # @overload initialize(data_type)
-  #   Allocates a CScalar (0-D CArray) of the given `data_type`.
+  #   Allocates a CScalar of the given `data_type`: one cell on one axis
+  #   (`ndim` 1, `shape` `[1]`).
   #   @param data_type [Symbol, Integer, Class, String]
   #   @return [self]
   # @overload initialize(data_type, bytes:)
@@ -269,6 +270,30 @@ class CScalar
 
   # @!endgroup
 
+  # @!group Indexing and slicing
+
+  # @overload []
+  # @overload [](0)
+  #   Reads the scalar's value.  A CScalar is one cell and takes no index:
+  #   `s[]` and `s[0]` both name that cell, and any other index (another
+  #   integer, a range, `nil`, an index array, a symbol) is refused.  A view
+  #   of the scalar, such as `s.refer(s.data_type, [1])`, takes the usual
+  #   indexes.
+  #   @return [Object] the value, or `UNDEF` if it is masked.
+  #   @raise [ArgumentError] when any other index is given.
+  def [](*index); end
+
+  # @overload []=(value)
+  # @overload []=(0, value)
+  #   Writes the scalar's value.  `s[] = v` and `s[0] = v` both write it;
+  #   any other index is refused.
+  #   @param value [Object] the value, or `UNDEF` to mask the cell.
+  #   @return [Object] value
+  #   @raise [ArgumentError] when any other index is given.
+  def []=(*index_and_value); end
+
+  # @!endgroup
+
   class << self
     # @!group Construction (typed shorthands)
 

data/yard-stubs/ca_obj_transpose.rb

@@ -23,14 +23,15 @@ class CArray
   #   @return [CATranspose]
   # @overload transpose(*imap)
   #   Returns a {CATranspose} view of `self` permuted by `imap`, a
-  #   permutation of `0 ... self.ndim`.  Element
-  #   `view[i_0, ..., i_{n-1}]` aliases parent element with axis `k`
-  #   sourced from `i` at position `imap[k]`.
+  #   permutation of `0 ... self.ndim`; a negative axis counts from the
+  #   end.  Element `view[i_0, ..., i_{n-1}]` aliases parent element with
+  #   axis `k` sourced from `i` at position `imap[k]`.
   #   @param imap [Array<Integer>] permutation of `0 ... ndim`.
   #   @return [CATranspose]
   #   @raise [ArgumentError] when `imap.length != ndim`.
   #   @raise [ArgumentError] when an entry of `imap` is out of range
-  #     or duplicated.
+  #     or names an axis given before.
+  #   @raise [TypeError] when an entry of `imap` is not an Integer.
   def transpose(*imap); end
 
   # Alias of {#transpose}.

data/yard-stubs/carray_attribute.rb

@@ -103,7 +103,9 @@ class CArray
 
   # @overload parent
   #   Returns the parent CArray of `self`, or `nil` if `self` has no
-  #   parent (i.e. is an entity).
+  #   parent (i.e. is an entity). For a Face (CATime, CARecord, ...) it
+  #   is a read-only view of the storage; a Face whose storage may be
+  #   written names a method for it (`CATime#ticks`).
   #   @return [CArray, nil]
   def parent; end