carray 3.0.6 → 3.0.7

data/lib/carray/time.rb

@@ -623,8 +623,57 @@ module CATimeOperandValues
     in_common_unit_with(lifted)
   end
 
+  # @overload pmax(other)
+  #   The later time, or the longer duration, of each cell and `other`, cell
+  #   by cell: `other` is an array of the same kind and shape, or one value
+  #   (for a time a {CATime::Element}, a `Time`, a `Date`, `"2024-01-02"`; for
+  #   a duration a {CATimedelta::Element}, `"3 days"`) 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, CATimedelta, CATime::Element, CATimedelta::Element, Time, Date, String]
+  #   @return [CATime, CATimedelta]
+  #   @raise [TypeError] when `other` is not of this kind.
+  def pmax (other)
+    pick_by_order(other) { |a, b| a < b }
+  end
+
+  # @overload pmin(other)
+  #   The earlier time, or the shorter duration; see {#pmax}.
+  #   @param other [CATime, CATimedelta, CATime::Element, CATimedelta::Element, Time, Date, String]
+  #   @return [CATime, CATimedelta]
+  #   @raise [TypeError] when `other` is not of this kind.
+  def pmin (other)
+    pick_by_order(other) { |a, b| a > b }
+  end
+
+  # A time or a duration 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
+
   private
 
+  # `other` where the block says self's cell loses to it, else self's cell.
+  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
+
+  # Both branches of a selection in the unit a comparison meets them in, so
+  # the finer unit wins whichever branch it is.
+  def branches_in_common (x, y)
+    other, base = y.is_a?(CArray) && !y.scalar? ? [x, y] : [y, x]
+    return [x, y] if other.nil? || UNDEF.equal?(other)
+    a, b = base.comparable_pair(other)
+    b = b[0] unless other.is_a?(CArray) && !other.scalar?
+    base.equal?(y) ? [b, a] : [a, b]
+  end
+
   # 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.
@@ -739,13 +788,19 @@ class CATime
     # @return [String]
     def to_s
       case unit.base
-      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)
+      when :Y      then signed_past_four_digits(to_date.strftime("%Y"))
+      when :M      then signed_past_four_digits(to_date.strftime("%Y-%m"))
+      when :W, :D  then signed_past_four_digits(to_date.strftime("%Y-%m-%d"))
+      else              signed_past_four_digits(to_time.iso8601(fractional_second_digits))  # :h .. :as (time shown)
       end
     end
 
+    # A year past four digits carries its sign, which is what tells it from a
+    # date written without separators when the text is read back.
+    private def signed_past_four_digits (text)
+      text.start_with?("-") || to_date.year < 10000 ? text : "+#{text}"
+    end
+
     # @return [String] the instant plus its storage unit.
     def inspect
       tag = unit.count == 1 ? "#{value}#{unit.base}" : "#{value} @ #{unit}"
@@ -810,7 +865,7 @@ class CATime
     #   @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)
+      shifted_by_duration(one_step_of(td), 1)
     end
 
     # @overload -(other)
@@ -831,6 +886,10 @@ class CATime
         shifted_by_duration(other, -1)
       when CATime
         -(other - self)
+      when String, Time, Date
+        step = other.is_a?(String) ? one_step_of(other) : other
+        return shifted_by_duration(step, -1) unless step.equal?(other)
+        (CATime.wrap(CA_INT64([value]), unit: unit) - other)[0]
       else
         raise TypeError, "CATime::Element - #{other.class} is not allowed"
       end
@@ -851,6 +910,18 @@ class CATime
     # the duration is converted into it (truncated toward zero when finer; a
     # month or year duration on a fixed grid moves the date by months).
     # Mirrors the array CATime +/-.
+    # A String naming a duration ("3 days") as one step of it; anything else
+    # as it is.
+    def one_step_of(x)
+      return x unless x.is_a?(String)
+      res = begin
+              CATime::Resolution.parse(x)
+            rescue ArgumentError
+              return x
+            end
+      CATimedelta::Element.new(1, res)
+    end
+
     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)
@@ -1005,6 +1076,20 @@ class CATimedelta
     #   @return [CATimedelta::Element]
     def -(other) = combined_with_duration(other, -1)
 
+    # @return [CATimedelta::Element] this duration with its sign reversed.
+    def -@ = Element.new(-value, unit)
+
+    # @return [CATimedelta::Element] the magnitude of this duration.
+    def abs = Element.new(value.abs, unit)
+
+    # @overload coerce(number)
+    #   Lets a duration stand on the right of a number, so `2 * d` is `d * 2`.
+    #   @param number [Numeric]
+    #   @return [Array]
+    def coerce (number)
+      [LeftFactor.new(number), self]
+    end
+
     # @overload *(n)
     #   Returns this duration scaled by an Integer.
     #   @param n [Integer]
@@ -1203,6 +1288,13 @@ class CATime
     end
   end
 
+  # The word form of {#+}.
+  # @return [CATime]
+  alias_method :add, :+
+  # The word form of {#-}.
+  # @return [CATime, CATimedelta]
+  alias_method :sub, :-
+
   # 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
@@ -1220,44 +1312,6 @@ class CATime
     CATimeUnitAlgebra.shift_months(face_storage, 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
@@ -1928,6 +1982,7 @@ class CATimedelta
   #   @raise [TypeError] on incompatible operands.
   def /(other)
     given, other = other, CATimeUnitAlgebra.operand(other)
+    other = CATimeUnitAlgebra.scalar_operand(other, unit) || other
     case other
     when Integer
       CATimeUnitAlgebra.trunc_divide(face_storage, other).timedelta(unit: unit)
@@ -1942,6 +1997,68 @@ class CATimedelta
     end
   end
 
+  # A number on the left of a duration: only `n * duration` has an answer.
+  class LeftFactor
+    def initialize (factor)
+      @factor = factor
+    end
+
+    def * (duration) = duration * @factor
+
+    def method_missing (op, duration, *)
+      raise TypeError, "#{@factor.class} #{op} #{duration.class} is not allowed"
+    end
+
+    def respond_to_missing? (*) = true
+  end
+  private_constant :LeftFactor
+
+  # @overload coerce(number)
+  #   Lets a duration stand on the right of a number, so `2 * td` is `td * 2`.
+  #   @param number [Numeric]
+  #   @return [Array]
+  def coerce (number)
+    number.is_a?(Numeric) ? [LeftFactor.new(number), self] : super
+  end
+
+  # @overload to_seconds
+  #   Each duration in seconds, exactly, as {Element#to_seconds} answers.
+  #   @return [CArray] an object array of Rational.
+  #   @raise [ArgumentError] for a :Y / :M unit, which has no exact seconds.
+  def to_seconds
+    unless CATimeUnitAlgebra::FIXED.key?(unit.base)
+      raise ArgumentError,
+            "CATimedelta #{unit} has no exact seconds (a :#{unit.base} is " \
+            "calendar-variable); use to_seconds_approx for an estimate"
+    end
+    ratio = unit.tick_ratio
+    face_storage.convert(:object) { |v| Rational(v) * ratio }
+  end
+
+  # @overload to_seconds_approx
+  #   Each duration in seconds by nominal lengths, as
+  #   {Element#to_seconds_approx} answers.
+  #   @return [CArray] float64.
+  def to_seconds_approx
+    face_storage.to_type(:float64) * (unit.count * (Element::UNIT_TO_SECONDS[unit.base] || 1))
+  end
+
+  # The word form of {#+}.
+  # @return [CATimedelta, CATime]
+  alias_method :add, :+
+  # The word form of {#-}.
+  # @return [CATimedelta]
+  alias_method :sub, :-
+  # The word form of {#*}.
+  # @return [CATimedelta]
+  alias_method :mul, :*
+  # The word form of {#/}.
+  # @return [CATimedelta, CArray]
+  alias_method :div, :/
+  # The word form of {#-@}.
+  # @return [CATimedelta]
+  alias_method :neg, :-@
+
   # Element-wise comparison (< <= > >= <=>) rides the core comparison Face
   # gate (ca_face_reconcile_comparison): the inherited CArray operators
   # descend to storage and reconcile a CATimedelta RHS in a different unit
@@ -2138,8 +2255,12 @@ class CATimedelta
 
   # 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)
+    case operand
+    when CATimedelta::Element
       CATimedelta.wrap(CA_INT64([operand.value]), unit: operand.unit)
+    when String
+      res = CATime::Resolution.parse(operand)
+      CATimedelta.wrap(CA_INT64([res.count]), unit: res.base)
     end
   end
 
@@ -2152,6 +2273,8 @@ class CATimedelta
     when CATimedelta::Element
       lifted = CATimedelta.wrap(CA_INT64([operand.value]), unit: operand.unit)
       to_comparable(lifted)
+    when String
+      to_comparable(lift_value(operand))
     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.
@@ -2169,7 +2292,8 @@ class CATimedelta
   #   scalar store round-trips with a fetch.  A {Element} is reconciled to
   #   self's unit via {#to_comparable} (lossless discipline; a `Time` /
   #   `DateTime` is an absolute instant, not a duration, so it raises there).
-  #   A bare Integer (the `.parent` raw-storage escape) and a String pass
+  #   A String that names a duration (`"3 days"`) is read as one.  A bare
+  #   Integer (the `.parent` raw-storage escape) and any other String pass
   #   through unchanged.
   #   @param surface [Element, Integer, String]
   #   @return [Integer, Object] the storage-domain value, or `surface`
@@ -2177,8 +2301,15 @@ class CATimedelta
   #   @raise [TypeError, ArgumentError] on an unreconcilable surface / unit.
   def element_to_storage (surface)
     case surface
-    when Integer, String
+    when Integer
       surface
+    when String
+      begin
+        to_comparable(surface).parent[0]
+      rescue ArgumentError => e
+        raise unless e.message.start_with?("invalid unit spec")
+        surface
+      end
     else
       to_comparable(surface).parent[0]
     end
@@ -2266,11 +2397,24 @@ module CATimeLiteral
       sec: t.sec, sec_fraction: frac.zero? ? nil : Rational(frac), leftover: h[:leftover] }.compact
   end
 
+  # Date._parse drops the sign of a year on its own or before a month, a day
+  # of the year or a week, and reads a year below 100 as this century's, so
+  # those are read here.
+  def year_first_fields(spec)
+    case spec
+    when /\A([-+]\d{4,})\z/                then { year: $1.to_i }
+    when /\A([-+]\d{4,})-(\d{1,2})\z/       then { year: $1.to_i, mon: $2.to_i }
+    when /\A([-+]?\d{4,})-(\d{3})\z/        then { year: $1.to_i, yday: $2.to_i }
+    when /\A([-+]?\d{4,})-W(\d{2})-(\d)\z/  then { cwyear: $1.to_i, cweek: $2.to_i, cwday: $3.to_i }
+    end
+  end
+
   def parse_date_fields(spec, format)
     h =
       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 (year_first = year_first_fields(spec)) then year_first
       elsif (hour = hour_only_fields(spec)) then hour
       else                                       Date._parse(spec)
       end

data/lib/carray/window_iterator.rb

@@ -70,6 +70,8 @@ class CAWindowIterator < CAIterator
   #   forward-looking).  `bounds:` selects the margin policy (`:skip` /
   #   `:nearest` / `:truncate`).  `fill_value:` is a constant margin value
   #   (an escape for `:constant` padding); when given it overrides `:skip`.
+  #   Over a categorical or a const string, which hold no new value, it has
+  #   to be a value some cell already holds.
   #
   #   For backward compatibility `initialize(window_view)` with no ranges
   #   accepts a CAWindow view (the old `CAWindowIterator.new(a.window(...))`
@@ -82,6 +84,8 @@ class CAWindowIterator < CAIterator
   #   @param ranges [Array<Range>] per-axis offset ranges.
   #   @param bounds [Symbol] `:skip` / `:nearest` / `:truncate`.
   #   @param fill_value [Object, nil] constant margin value, overriding :skip.
+  #   @raise [ArgumentError] when a categorical or const string source holds
+  #     no cell with `fill_value` (raised when the windows are first read).
   def initialize (source, *ranges, bounds: :skip, fill_value: nil)
     if ranges.empty? && source.is_a?(CArray) && source.obj_type == CA_OBJ_WINDOW
       # Backward-compat: read geometry from a CAWindow view built by #window.
@@ -282,15 +286,32 @@ class CAWindowIterator < CAIterator
   def pad_face (src, lefts, rights, mode, value)
     storage = src.__send__(:face_storage)
     if mode == :constant && !value.nil?
-      cell = src.__send__(:blank_like, [1])
-      cell[0] = value
-      padded = pad_source(storage, lefts, rights, :constant, cell.parent[0])
+      padded = pad_source(storage, lefts, rights, :constant, margin_storage(src, storage, value))
     else
       padded = pad_source(storage, lefts, rights, mode, value)
     end
     padded.face_lift(src)
   end
 
+  # The storage of a `:constant` margin value.  A Face that holds new values
+  # turns the value into storage; one that holds none (a const string's
+  # records index a shared pool, a categorical's codes index its labels) can
+  # only repeat the storage of a cell that already holds the value.
+  def margin_storage (src, storage, value)
+    if src.__send__(:holds_new_values?)
+      cell = src.__send__(:blank_like, [1])
+      cell[0] = value
+      return cell.parent[0]
+    end
+    hit = src.eq(value).where
+    if hit.elements == 0
+      raise ArgumentError,
+            "windows: fill_value #{value.inspect} is not a value of this " \
+            "#{src.class}, which can only repeat a value it already holds"
+    end
+    storage.flatten[hit[0]]
+  end
+
   # Edge-replicate the margins of a padded buffer whose interior already holds
   # the source.  Per axis, the left margin rows copy the first interior row and
   # the right margin rows copy the last; done axis by axis over the whole
@@ -567,11 +588,15 @@ class CAWindowIterator < CAIterator
     return nil unless op == :mean || OFFSET_FOLD.key?(op)
     # The elementwise kernels act on a Face's storage; its reductions are its own.
     return nil if @source.face?
+    # Fixed-length cells have no elementwise kernels and no neutral value.
+    return nil if @source.data_type == CA_FIXLEN
+    # An undefined constant margin is a masked one, which a fold must skip.
+    return nil if @fill_value.equal?(UNDEF)
     return nil if @widths.any? { |width| width > OFFSET_FOLD_MAX_WIDTH }
-    return nil if neutral_value(op).nil?
     # pmin / pmax let NaN lose, so a window holding only NaN would fold to the
     # neutral value; the core answers NaN there.
     return nil if (op == :min || op == :max) && source_has_nan?
+    return nil if neutral_value(op).nil?
 
     folded = op == :mean ? fold_mean : accumulate_offsets(op)
     folded = mask_empty_windows(folded) if EMPTY_WINDOW_IS_UNDEFINED.include?(op)
@@ -640,6 +665,7 @@ class CAWindowIterator < CAIterator
   end
 
   def source_has_nan?
+    return true if @bounds == :constant && @fill_value.is_a?(Float) && @fill_value.nan?
     return false unless @source.float? || @source.data_type == CA_OBJECT
     @source.is_nan.any
   end
@@ -659,9 +685,9 @@ class CAWindowIterator < CAIterator
   # What stands in for a cell the fold must not see: a margin the boundary
   # policy does not fill, or a masked cell of the source.  For sum, prod, all
   # and any that is the operation's identity.  For min and max it is any value
-  # that cannot win, and the array's own extreme is one -- so no table of
-  # per-type limits is needed.  Nil means there is none to be had (a source
-  # masked everywhere), and the caller delegates instead.
+  # that cannot win, and the extreme of the array and its constant margin is
+  # one -- so no table of per-type limits is needed.  Nil means there is none
+  # to be had (a source masked everywhere), and the caller delegates instead.
   def neutral_value (op)
     @neutral_value ||= {}
     return @neutral_value[op] if @neutral_value.key?(op)
@@ -678,7 +704,11 @@ class CAWindowIterator < CAIterator
 
   def source_extreme (op)
     value = @source.send(op)
-    value.equal?(UNDEF) ? nil : value
+    return nil if value.equal?(UNDEF)
+    return value unless @bounds == :constant
+    margin = @fill_value || 0
+    margin = margin ? 1 : 0 if @source.boolean?   # the core answers 0 or 1
+    [value, margin].public_send(op)
   end
 
   # The buffer the offsets are read from: the source with its margins filled
@@ -722,13 +752,19 @@ class CAWindowIterator < CAIterator
   # real values, so the count is the whole window and one Integer says it;
   # `:skip` counts the in-bounds offsets, which is separable -- the count on
   # one axis depends on that axis alone.  A masked source has to be counted for
-  # real, by accumulating over the same offsets.
+  # real, by accumulating over the same offsets; a cell of a constant margin
+  # counts once, whatever its value.
   def window_cell_counts
     return @window_cell_counts unless @window_cell_counts.nil?
     @window_cell_counts =
       if @source.has_mask?
-        accumulate_offsets(:sum, pad_for(@source.is_not_masked.int64, 0),
-                           :add!, CA_INT64)
+        present = @source.is_not_masked.int64
+        present = if @bounds == :constant
+                    pad_source(present, @lefts, @rights, :constant, 1)
+                  else
+                    pad_for(present, 0)
+                  end
+        accumulate_offsets(:sum, present, :add!, CA_INT64)
       elsif @bounds != :skip
         @widths.inject(:*)
       else
@@ -806,7 +842,7 @@ class CAWindowIterator < CAIterator
     return count_not_masked(**kw) if args.empty?
     # The sliding_windows view is a CAStride, so its #count is not shadowed;
     # dispatch CArray#count explicitly anyway, matching the family regularity.
-    CArray.instance_method(:count).bind_call(sliding_view, *args, axis: @window_axes,
+    count_cells(sliding_view, *args, axis: @window_axes,
                                              **CAIterator.reduce_keywords(:count, kw))
   end
 

data/yard-stubs/ca_obj_bitfield.rb

@@ -30,7 +30,10 @@ class CArray
   # narrowest unsigned type that holds the field is used: 1 bit →
   # `:boolean`, 2..8 → `:uint8`, 9..16 → `:uint16`, 17..32 → `:uint32`,
   # 33..64 → `:uint64`.  A write keeps the low bits of the value that
-  # fit the field, signed or not (-3 into a 3-bit field is `0b101`).
+  # fit the field, signed or not, for an Integer of any size (-3 into a
+  # 3-bit field is `0b101`, 300 is `0b100`).  The same holds for a view
+  # taken of the field (a slice, an index, a mask selection).  A String
+  # is read as a decimal integer, a Float through `Integer()`.
   #
   # @overload bitfield(range, type = nil)
   #   @param range [Integer, Range] bit position (single bit) or bit

data/yard-stubs/ca_obj_refer.rb

@@ -35,6 +35,9 @@ class CArray
   #   @raise [ArgumentError] when the byte widths do not divide
   #     evenly, when `offset` is negative, or when the requested
   #     view extends past the parent's data.
+  #   @raise [TypeError] on a Face, for a data type that is neither its
+  #     surface type nor its storage type: `to_type` gives the values,
+  #     `parent.refer` the raw storage.
   #   @raise [CArray::DataTypeError] when reinterpreting a CA_OBJECT parent
   #     with a non-object `data_type`, or a parent of another data type as
   #     `:boolean` (a boolean cell holds 0 or 1; compare instead, `ne(0)`).

data/yard-stubs/ca_obj_window.rb

@@ -54,7 +54,8 @@ class CArray
   #     or when `bounds` is not a recognised value.
   #   @raise [IndexError] when `bounds` is `"strict"` and a range reaches
   #     outside `self`, or `"ruby"` and a range reaches past the end or
-  #     before the first cell counted from the end.
+  #     before the first cell counted from the end, or `"nearest"` and a
+  #     range takes cells of an axis of length 0.
   def window(*ranges, fill_value: 0, bounds: "fill"); end
 
   # @!endgroup

data/yard-stubs/carray_access.rb

@@ -90,7 +90,8 @@ class CArray
   #     or a CArray of such addresses (arbitrary shape).  A negative
   #     address counts from the end.
   #   @return [Array<Integer>, Array<CArray>] one entry per axis.
-  #   @raise [IndexError] when any `addr` is out of range.
+  #   @raise [IndexError] when any `addr` is out of range, or when `addr` is
+  #     float, complex, object or boolean.
   def addr2index(addr); end
 
   # @overload index2addr(*index)
@@ -101,7 +102,8 @@ class CArray
   #   must match that shape).  Mask propagates from the inputs.
   #   @param index [Array<Integer, CArray>] one entry per axis.
   #   @return [Integer, CArray] the flat address(es).
-  #   @raise [IndexError] on an out-of-range index.
+  #   @raise [IndexError] on an out-of-range index, or an index array that
+  #     is float, complex, object or boolean.
   #   @raise [ArgumentError] on shape mismatch between non-scalar inputs.
   def index2addr(*index); end
 

data/yard-stubs/carray_cast.rb

@@ -490,6 +490,12 @@ class CArray
   #   that does not fit an integer type takes `:int64`. With no array or
   #   data_type representation, every argument promotes by its own type.
   #
+  #   This is the type an operator computes in: `int32_array + float32_array`
+  #   is `:float32`. Arrays joined value for value ({CArray.stack},
+  #   {CArray.meld}, {CArray.concatenate}) take the type {.promote_list}
+  #   gives, which is `:float64` for that pair, since `float32` does not
+  #   hold every `int32` exactly.
+  #
   #   Integer args are interpreted as *values*, not as data_type codes:
   #   `result_type(8)` returns `:int64` because the value 8 is an Integer,
   #   not because a data_type code equals 8. Use `result_type(:int64)` or

data/yard-stubs/carray_count.rb

@@ -36,6 +36,9 @@ class CArray
   #     count).
   #   - `v == UNDEF`: forwards to {#count_masked} (UNDEF is mask-state
   #     vocabulary, not a value).
+  #   - `v` is `nil`, a String, a Symbol or another value that is not a
+  #     number, on an array that is not `:object` or `:fixlen`: `0`.  It
+  #     is no value of such an array, so no cell equals it.
   #   - `v` is a CArray: broadcasts; each `v[k]` is counted
   #     independently and stacked into a result whose trailing axes
   #     have shape `v.shape`.  Not supported when `self.data_type` is
@@ -43,9 +46,9 @@ class CArray
   #   - `self.data_type == :boolean`: `v` must be `true` / `false`, or
   #     the integer literal `1` (= true) / `0` (= false) — boolean
   #     stores 0/1, so `count(1)` == `count(true)`.  Any other value
-  #     (`2`, `1.0`, `nil`, …) raises `TypeError`.
-  #   - `self` is numeric, `v` is scalar: `v` must be numeric (true /
-  #     false are rejected -- they are the boolean array's domain).
+  #     (`2`, `1.0`, …) raises `TypeError`.
+  #   - `self` is numeric, `v` is scalar: `true` and `false` are the
+  #     numbers `1` and `0`, as they are to {#eq}.
   #     `v` (a scalar or an array) is compared in the type it and the
   #     array match in, as {#eq} compares: `CA_INT32([1, 2]).count(1.5)`
   #     is `0`, `CA_UINT8([255]).count(-1)` is `0` (-1 is not 255), and an

data/yard-stubs/carray_math.rb

@@ -784,6 +784,11 @@ class CArray
   #   point equality is exact here; for a tolerant comparison see
   #   {#is_close} (absolute) or {#is_equiv} (relative). Integers compare
   #   by value, as for {#<}.
+  #
+  #   `eq(UNDEF)` asks the mask, as {#is_masked} does. `nil`, a String, a
+  #   Symbol or another value that is not a number is no value of a numeric
+  #   or boolean array, so `eq` is false in every cell there; an `:object`
+  #   or `:fixlen` array compares it like any other value.
   #   @param other [CArray, Numeric, Object] comparand, broadcast to
   #     `self.shape`.
   #   @return [CArray] `:boolean`, same shape as `self`.

data/yard-stubs/carray_order.rb

@@ -24,6 +24,7 @@ class CArray
   #   @return [CArray] a fresh array shaped like `idx`; a Face of the same
   #     type when `self` is a Face.
   #   @raise [ArgumentError] if `lval` / `uval` is given and `self` is a Face.
+  #   @raise [IndexError] when `idx` is float, complex, object or boolean.
   def project(idx, lval = nil, uval = nil); end
 
   # sort / sort_copy stubs live in yard-stubs/carray_sort.rb (same
@@ -176,6 +177,11 @@ class CArray
   #   nothing: `nil`, or `UNDEF` in that cell of the result.  The same
   #   holds for {#bsearch} and {#search_nearest}.
   #
+  #   `nil` is no value of an array that is not `:object`, so it finds
+  #   nothing there; an `:object` array looks for it like any other value.
+  #   {#bsearch} and {#search_nearest} need an order or a distance, which
+  #   `nil` does not have, and raise.
+  #
   #   A time array (`CATime`, `CATimedelta`) takes a value of another
   #   unit, a `Time` or a String: when it is off the array's grid the
   #   two are compared in the finer unit, so it matches nothing (and

data/yard-stubs/carray_scatter.rb

@@ -45,7 +45,8 @@ class CArray
   #   @param addrs [CArray, Array<Integer>]
   #   @param vals [CArray, Numeric]
   #   @return [self]
-  #   @raise [IndexError] for out-of-range addresses.
+  #   @raise [IndexError] for out-of-range addresses, or when `addrs` is
+  #     float, complex, object or boolean.
   #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
   def scatter_add!(addrs, vals); end
 

data/yard-stubs/carray_test.rb

@@ -13,6 +13,7 @@ class CArray
   #   @return [Boolean]
   #   @raise [ArgumentError] if the number of indices does not match
   #     `ndim`.
+  #   @raise [TypeError] if an index is not an Integer.
   def valid_index?(*idx); end
 
   # @overload valid_addr?(addr)
@@ -21,11 +22,16 @@ class CArray
   #   @param addr [Integer] flat address into the contiguous element
   #     sequence.
   #   @return [Boolean]
+  #   @raise [TypeError] if `addr` is not an Integer.
   def valid_addr?(addr); end
 
   # @overload same_shape?(other)
-  #   Returns `true` if `other` has the same shape as `self`.
-  #   @param other [CArray]
+  #   Returns `true` if `other` has the same shape as `self`. Only the
+  #   shape is compared, whatever the data types of the two. A scalar has
+  #   the same shape as any array. An `other` that is not a CArray is read
+  #   as an object array: a nested Array by its nesting, anything else as
+  #   a scalar.
+  #   @param other [CArray, Object]
   #   @return [Boolean]
   def same_shape?(other); end
 
@@ -55,9 +61,10 @@ class CArray
   # @overload eql?(other)
   #   Returns `true` under Hash-invariant semantics: `data_class`,
   #   `data_type`, shape, and mask state must all match, and elements
-  #   are compared bitwise (for numeric types) or via `Object#eql?`
-  #   (for `:object` arrays), so -0.0 and 0.0 differ and two NaNs are
-  #   `eql?` only with the same bits.
+  #   are compared bitwise (for numeric types) or, for `:object` arrays, via
+  #   `Object#eql?` with an object equal to itself first, as in
+  #   `Array#eql?`. In a numeric array -0.0 and 0.0 differ and two NaNs
+  #   are `eql?` only with the same bits.
   #   Two Faces are `eql?` only when they are of the same class, share
   #   their state (a time array's unit, a categorical's labels) and hold
   #   the same storage.
@@ -72,7 +79,13 @@ class CArray
   #   `ndim`, `bytes`, `elements`, shape, scalar-ness, and mask
   #   presence; for unmasked arrays, samples the leading 64 bytes of
   #   data. Masked arrays skip the data sample.
+  #
+  #   An `:object` array samples the `#hash` of its cells, so an array in
+  #   a cell is hashed in turn. {#==}, {#eql?} and `Marshal.dump` walk into
+  #   cells the same way, and all of them refuse arrays nested more than
+  #   256 levels deep.
   #   @return [Integer]
+  #   @raise [ArgumentError] when object cells nest more than 256 levels.
   def hash; end
 
   # @!endgroup