carray 3.0.3 → 3.0.4

data/lib/carray/window_iterator.rb

@@ -71,9 +71,11 @@ class CAWindowIterator < CAIterator
   #   `:nearest` / `:truncate`).  `fill_value:` is a constant margin value
   #   (an escape for `:constant` padding); when given it overrides `:skip`.
   #
-  #   For backward compatibility `initialize(window_view)` accepts a CAWindow
-  #   view (the old `CAWindowIterator.new(a.window(...))` form): the geometry
-  #   (offset ranges, bounds, fill value) is read back from the view.
+  #   For backward compatibility `initialize(window_view)` with no ranges
+  #   accepts a CAWindow view (the old `CAWindowIterator.new(a.window(...))`
+  #   form): the geometry (offset ranges, bounds, fill value) is read back
+  #   from the view.  Given ranges, a CAWindow view is rolled over like any
+  #   other array.
   #
   #   @param source [CArray, CAWindow] the array to roll over, or a CAWindow
   #     view to read the geometry from.
@@ -81,7 +83,7 @@ class CAWindowIterator < CAIterator
   #   @param bounds [Symbol] `:skip` / `:nearest` / `:truncate`.
   #   @param fill_value [Object, nil] constant margin value, overriding :skip.
   def initialize (source, *ranges, bounds: :skip, fill_value: nil)
-    if source.is_a?(CArray) && source.obj_type == CA_OBJ_WINDOW
+    if ranges.empty? && source.is_a?(CArray) && source.obj_type == CA_OBJ_WINDOW
       # Backward-compat: read geometry from a CAWindow view built by #window.
       # start[i] = lo, shape[i] (window width) = w, so hi = lo + w - 1.
       win     = source
@@ -198,7 +200,7 @@ class CAWindowIterator < CAIterator
     buffer = padded_entity
     wanted = @ndim.times.map { |k| @origins[k]...(@origins[k] + @shape[k] + @widths[k] - 1) }
     return buffer if wanted.each_with_index.all? { |range, k|
-      range.begin.zero? && range.end == buffer.dim[k]
+      range.begin.zero? && range.end == buffer.shape[k]
     }
     buffer[*wanted]
   end
@@ -269,9 +271,9 @@ class CAWindowIterator < CAIterator
   # the Face's own.  A buffer of the Face's surface type could not take the
   # margin values at all.
   def pad_face (src, lefts, rights, mode, value)
-    storage = src.__send__(:__face_storage__)
+    storage = src.__send__(:face_storage)
     if mode == :constant && !value.nil?
-      cell = src.__send__(:__blank_like__, [1])
+      cell = src.__send__(:blank_like, [1])
       cell[0] = value
       padded = pad_source(storage, lefts, rights, :constant, cell.parent[0])
     else
@@ -472,6 +474,28 @@ class CAWindowIterator < CAIterator
     RUBY
   end
 
+  # @!method first
+  #   Rolling first present value, in row-major order within the window;
+  #   UNDEF for a window with none (the UNDEF margin of `:skip` is not
+  #   present, so a window over the edge starts at its first source cell).
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method last
+  #   Rolling last present value; UNDEF for a window with none.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method nunique
+  #   Rolling number of distinct present values (int64); 0 for a window with
+  #   none.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  #
+  # These take no `min_count:` or `fill_value:`, as the core ones do not.
+  [:first, :last, :nunique].each do |op|
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{op} (**kw)
+        sliding_view.#{op}(axis: @window_axes, **CAIterator.reduce_keywords(:#{op}, kw))
+      end
+    RUBY
+  end
+
   # @overload min_addr
   #   Rolling flat SOURCE address of the window minimum — which source cell holds
   #   it, so `source.reshape(source.elements)[sw.min_addr]` are the window minima.
@@ -517,6 +541,12 @@ class CAWindowIterator < CAIterator
                   :min  => :pmin!, :max  => :pmax!,
                   :all  => :and!,  :any  => :or! }.freeze
 
+  # A boolean accumulates as the core's does, by parity, so its kernel is xor.
+  def offset_fold_kernel (op)
+    return :xor! if op == :accumulate && @source.data_type == CA_BOOLEAN
+    OFFSET_FOLD.fetch(op)
+  end
+
   # Widest window this path takes on any one axis.
   OFFSET_FOLD_MAX_WIDTH = 5
 
@@ -524,7 +554,7 @@ class CAWindowIterator < CAIterator
   # 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__
-    need = CArray.__min_count_need__(op, min_count, 0)
+    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.
     return nil if @source.face?
@@ -538,7 +568,7 @@ class CAWindowIterator < CAIterator
     folded = mask_empty_windows(folded) if EMPTY_WINDOW_IS_UNDEFINED.include?(op)
     folded = apply_min_count(folded, need)
     # A `fill_value:` on the call replaces a result that came out undefined.
-    CArray.__reduce_fill__(folded, fill_value)
+    CArray.__fill_undefined_result_cells__(folded, fill_value)
   end
 
   # The mean is the sum over the same offsets, divided by the number of cells
@@ -551,13 +581,14 @@ class CAWindowIterator < CAIterator
       divisor = counts.copy
       divisor[counts.eq(0)] = 1
     end
+    # coerce: the mean's fixed compute type
     accumulate_offsets(:sum).to_type(offset_fold_data_type(:mean)) / divisor
   end
 
   # Walks the window offsets, accumulating each shifted plane into the result.
   def accumulate_offsets (op, base = nil, kernel = nil, data_type = nil)
     base      ||= offset_fold_base(op)
-    kernel    ||= OFFSET_FOLD.fetch(op)
+    kernel    ||= offset_fold_kernel(op)
     data_type ||= offset_fold_data_type(op)
     accumulator = nil
     offset_grid.each do |offset|
@@ -604,7 +635,7 @@ class CAWindowIterator < CAIterator
     @source.is_nan.any
   end
 
-  # A result only where the window held `need` cells (CArray.__min_count_need__).
+  # A result only where the window held `need` cells (CArray.__present_cells_needed_per_result_cell__).
   def apply_min_count (folded, need)
     return folded if need == 0
     counts = window_cell_counts
@@ -708,7 +739,7 @@ class CAWindowIterator < CAIterator
   def offset_fold_data_type (op)
     @offset_fold_data_type ||= {}
     @offset_fold_data_type[op] ||=
-      CArray.new(@source.data_type, [1, 1], bytes: @source.bytes).send(op, axis: [1]).data_type
+      CAIterator.core_probe(@source).public_send(op, axis: [1]).data_type
   end
 
   # Every offset within the window, as a list of per-axis positions into the
@@ -752,7 +783,7 @@ class CAWindowIterator < CAIterator
     end
     addr[oob] = UNDEF unless @bounds == :nearest
     addr[mi.is_masked.eq(1)] = UNDEF if mi.has_mask?
-    CArray.__reduce_fill__(addr, kw[:fill_value])
+    CArray.__fill_undefined_result_cells__(addr, kw[:fill_value])
   end
 
   public
@@ -1063,13 +1094,51 @@ class CAWindowIterator < CAIterator
   #   winner is well-defined).
   #   @raise [NotImplementedError]
   [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|
-    define_method(op) do |*, **|
+    # define_method: a refusal that names itself in its own message
+    define_method(op, &Ractor.make_shareable(proc do |*, **|
       raise NotImplementedError,
             "#{self.class} has no #{op}: a segment scan needs each cell to " \
             "belong to exactly one piece, but overlapping windows share cells, " \
             "so a per-cell running value is ill-defined; use reduce for a " \
             "custom per-window fold."
-    end
+    end))
+  end
+
+  # @!method lag(n = 1)
+  #   Not supported for a window iterator. A lag writes each cell the value
+  #   some steps earlier in its piece, which needs each cell to have one
+  #   position in one piece; overlapping windows put a cell in many windows.
+  #   Use `source.lag(n, axis:)` for the lag along an axis.
+  #   @raise [NotImplementedError]
+  def lag (*)
+    raise NotImplementedError,
+          "#{self.class} has no lag: a cell belongs to many overlapping windows, " \
+          "so it has no single position to step back from; use " \
+          "source.lag(n, axis:) for the lag along an axis."
+  end
+
+  # @!method strip_mask
+  #   Not supported for a window iterator: a cell belongs to many overlapping
+  #   windows, so it has no single value to be filled with. Use
+  #   `source.strip_mask(method:, axis:)` for a fill along an axis.
+  #   @raise [NotImplementedError]
+  def strip_mask (*, **)
+    raise NotImplementedError,
+          "#{self.class} has no strip_mask: a cell belongs to many overlapping " \
+          "windows, so it has no single fill; use source.strip_mask(method:, axis:) " \
+          "for a fill along an axis."
+  end
+
+  # @!method order
+  #   Not supported for a window iterator: a cell belongs to many overlapping
+  #   windows, so it has no single rank. Use `source.order(axis:)` for the
+  #   rank along an axis.
+  #   @raise [NotImplementedError]
+  def order (*, **)
+    raise NotImplementedError,
+          "#{self.class} has no order: a cell belongs to many overlapping windows, " \
+          "so it has no single rank; use source.order(axis:) for the rank along " \
+          "an axis."
   end
 
   private
@@ -1095,7 +1164,44 @@ class CArray
   #   @param bounds [Symbol] `:skip` / `:nearest` / `:truncate`.
   #   @param fill_value [Object, nil] constant margin value.
   #   @return [CAWindowIterator]
-  def windows (*ranges, bounds: :skip, fill_value: nil)
+  # @overload windows(on:, before: nil, after: nil, exclude: :lower, by: nil, interval: nil, at: nil)
+  #   Returns a {CAKeyWindowIterator}: a window per value bounded by a width
+  #   of the key `on` (a time, a duration or a number) instead of a count of
+  #   cells.  The window of a value whose key is t holds the values whose
+  #   key lies between t - before and t + after; `exclude:` leaves out the
+  #   lower end (default), the upper end, both or neither.  `by:` keeps
+  #   each window within the values with the same by keys, and `interval:`
+  #   gives the key's grid step for {CAKeyWindowIterator#is_complete}.  A
+  #   value whose key is masked, NaN or infinite is in no window and has no
+  #   window.  `at:` places the windows at those points of the key instead
+  #   of at the values, one answer per point (a grid of points gives
+  #   windows on a grid); it cannot be given with `by:`.
+  #
+  #     temp.windows(on: time, before: "1 hour").mean
+  #     temp.windows(on: time, at: hours, after: "3 hours", exclude: :upper).mean
+  #   @return [CAKeyWindowIterator]
+  def windows (*ranges, on: nil, **key_window)
+    unless on.nil?
+      unless ranges.empty?
+        raise ArgumentError, "windows: give offset ranges or on:, not both"
+      end
+      given = [:bounds, :fill_value] & key_window.keys
+      unless given.empty?
+        raise ArgumentError,
+              "windows: #{given.map { |k| "#{k}:" }.join(', ')} " \
+              "belong to offset windows; a window on a key has no padding " \
+              "(a row with no window answers UNDEF)"
+      end
+      require "carray/key_windows"
+      return CAKeyWindowIterator.new(self, on: on, **key_window)
+    end
+    bounds     = key_window.delete(:bounds) { :skip }
+    fill_value = key_window.delete(:fill_value)
+    unless key_window.empty?
+      raise ArgumentError,
+            "windows: #{key_window.keys.map { |k| "#{k}:" }.join(', ')} " \
+            "need on:, the key the widths are measured on"
+    end
     if ranges.size == 1 && ranges[0].is_a?(CArray) && ranges[0].obj_type == CA_OBJ_WINDOW
       return CAWindowIterator.new(ranges[0])
     end

data/lib/carray.rb

@@ -2,6 +2,10 @@
 
 require 'carray_ext'
 
+# Errors name the method the user called: the outermost frame of the library
+# before the user's code, and the library's Ruby frames are the ones here.
+CArray.send(:library_root=, __dir__)
+
 # Top-level CAMath module -- math namespace for CArrays.
 # `CAMath.sin(ca)` works because module functions inherited
 # from Math (via include) accept any object that responds to
@@ -49,6 +53,9 @@ require 'carray/string_operation_extension'  # shared StringOperationMixin (must
 require 'carray/const_string'   # CAConstString construction surface
 require 'carray/string'         # CAString construction surface
 require 'carray/fixlen_string'  # CAFixlenString construction surface
+# Loaded here, not on first use: Ruby's own error messages call #inspect, and
+# a Ractor other than the main one cannot load a file.
+require 'carray/inspect'
 # CArray.format lives in carray/methods/string_format.rb, autoloaded on first call
 
 # carray/frame is loaded lazily via autoload_carray (CAFrame / GroupedFrame

data/yard-stubs/ca_obj_bitfield.rb

@@ -39,7 +39,7 @@ class CArray
   #     read as, or `nil` for the narrowest unsigned type.
   #   @return [CABitfield]
   #   @raise [IndexError] when `range` extends past the parent's bit
-  #     width, when the range has a step != 1, when the bit length
+  #     width, when the range descends or has a step != 1, when the bit length
   #     is outside `1..64`, or when the field reaches more than 64 bits
   #     past the start of its first byte.
   #   @raise [CArray::DataTypeError] when `self` is an object or complex

data/yard-stubs/ca_obj_field.rb

@@ -20,6 +20,10 @@ class CArray
   #   @return [CAField]
   #   @raise [ArgumentError] when `offset` is negative or the
   #     `offset + bytes` window falls outside one parent record.
+  #   @raise [CArray::DataTypeError] when a field of a numeric array is
+  #     asked for as `:boolean` (a boolean cell holds 0 or 1; compare
+  #     instead, `ne(0)`). A record's boolean member is a field of a
+  #     fixlen array and is allowed.
   # @overload field(offset, template)
   #   Returns a CARefer over a {CAField}: takes `template.elements *
   #   template.bytes` bytes at `offset` and exposes them with

data/yard-stubs/ca_obj_grid.rb

@@ -14,22 +14,33 @@ class CArray
   #   number of indices selected for that axis.
   #
   #   Each selector is one of:
-  #   - `nil` — the whole axis, in order.
-  #   - an integer `Range` — a contiguous sub-range along the axis.
   #   - a `CArray` of integer indices — gather exactly those parent
   #     indices (arbitrary order; duplicates produce duplicated cells).
-  #   - a boolean `CArray` — the indices where it is true.
+  #   - a boolean `CArray` as long as its axis — the indices where it is
+  #     true.
+  #   - any other key, read as the indexer reads it in a block
+  #     reference: `nil` the whole axis, a `Range` /
+  #     `ArithmeticSequence` / Array form its run (a range ending before
+  #     it starts reads backwards), the rubber marker (`false` / `:~`)
+  #     as many whole axes as it stands for, and an `Integer` one cell,
+  #     whose axis is then dropped from the view.
   #
-  #   A masked index `CArray` selects only its not-masked cells.  The
-  #   view is writable; scattering back to overlapping cells (from
+  #   A masked cell of an index `CArray` selects nothing: the position
+  #   stays in the view and reads as masked (`UNDEF`), and a write to it
+  #   is dropped, as in {#project} and {#gather_nd}.  A masked cell of a
+  #   boolean selector selects nothing either, so it adds no position.
+  #   The view is writable; scattering back to overlapping cells (from
   #   duplicate indices) is last-write-wins.
   #
-  #   @param selectors [Array<nil, Range, CArray>] one selector per axis.
+  #   @param selectors [Array<nil, Integer, Range, Array, CArray>] one
+  #     selector per axis.
   #   @return [CArray] the grid view.
-  #   @raise [ArgumentError] when more selectors than `ndim` are given.
-  #   @raise [IndexError] when a selected index is out of range.
-  #   @raise [RuntimeError] when a selector is a plain Ruby `Array`
-  #     (not supported; pass a CArray of indices instead).
+  #   @raise [ArgumentError] when more selectors than `ndim` are given, a
+  #     boolean selector is not as long as its axis, or a masked index
+  #     selects from a view of a value array or a mask array (which can
+  #     not carry the mask that shows it).
+  #   @raise [IndexError] when a selected index is out of range, or a
+  #     selector is not a position (a String, a Float with a fraction).
   def grid(*selectors); end
   # @!endgroup
 end

data/yard-stubs/ca_obj_refer.rb

@@ -36,7 +36,8 @@ class CArray
   #     evenly, when `offset` is negative, or when the requested
   #     view extends past the parent's data.
   #   @raise [CArray::DataTypeError] when reinterpreting a CA_OBJECT parent
-  #     with a non-object `data_type`.
+  #     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)`).
   def refer(*argv); end
 
   # Returns a view of `self` with the requested shape.  Element

data/yard-stubs/ca_obj_roll.rb

@@ -3,7 +3,7 @@
 # See yard-stubs/README.md and yard-stubs/STYLE.md.
 
 # Cyclic-shift view of the parent.  Same shape as the parent; each
-# axis `k` is rotated by `shift[k]` cells (modulo `parent.dim[k]`).
+# axis `k` is rotated by `shift[k]` cells (modulo `parent.shape[k]`).
 # All parent cells alias through the view exactly once, so writes
 # through the view reach the parent.
 #
@@ -25,7 +25,7 @@ class CArray
   # `shifts[k]` along each axis `k`.  Positive shifts move cell `i`
   # of the parent to position `i + shift`; negative shifts move it
   # the other way.  Each `shift[k]` is normalised into
-  # `[0, self.dim[k])` before use, so any integer is accepted.
+  # `[0, self.shape[k])` before use, so any integer is accepted.
   #
   # Fewer args than `ndim` treats the missing axes as `shift = 0`.
   # More args than `ndim` raises `ArgumentError`.

data/yard-stubs/ca_obj_shift.rb

@@ -22,7 +22,11 @@ class CArray
   # parent to position `i + shift`).  Out-of-range cells take `fill_value`
   # (default `0`); passing `fill_value: UNDEF` masks them instead of
   # filling.  In-range cells alias the parent, so writes through the view
-  # reach the parent.
+  # reach the parent.  A write to an out-of-range cell has no cell to land
+  # in and is discarded; under `fill_value: UNDEF` such a cell stays masked
+  # through `unmask` too.  The default `0` is the storage value, so for a time
+  # array it is 1970-01-01, for a CAString `""`; `ts - ts.shift(1,
+  # fill_value: UNDEF)` leaves the first difference missing.
   #
   # The in-place idiom is `ca[] = ca.shift(...)`; there is no `shift!`.
   # For a cyclic (wrap-around) shift use {#roll}, which returns a `CARoll`

data/yard-stubs/ca_obj_tile.rb

@@ -2,7 +2,7 @@
 # Stubs for methods defined in ext/ca_obj_tile.c.
 # See yard-stubs/README.md and yard-stubs/STYLE.md.
 
-# Tiled repetition view.  Output shape is `parent.dim[k] * reps[k]`
+# Tiled repetition view.  Output shape is `parent.shape[k] * reps[k]`
 # along each axis; every tile is a full-parent alias, so writes to
 # overlapping cells are last-write-wins.
 class CATile < CAView

data/yard-stubs/ca_obj_window.rb

@@ -21,7 +21,8 @@ class CArray
   # parent alias it, so writes through the view reach the parent; cells
   # outside take `fill_value` (default `0`), and `fill_value: UNDEF` masks
   # them instead.  A write that lands outside the parent has no cell to land
-  # in and is discarded.
+  # in and is discarded; under `fill_value: UNDEF` such a cell stays masked
+  # through `unmask` too.
   #
   # A range wider than its axis is how an array is **padded**: `a.window(-1..
   # a.dim0, -1..a.dim1)` puts a one-cell border all round, which is NumPy's
@@ -35,8 +36,9 @@ class CArray
   # @overload window(*ranges, fill_value: 0, bounds: "fill")
   #   @param ranges [Array<Range, Integer>] one range per axis; the count
   #     must equal `self.ndim`.
-  #   @param fill_value [Object] value given to out-of-range cells; `UNDEF`
-  #     masks them instead.
+  #   @param fill_value [Object] value given to out-of-range cells, written
+  #     as a store writes it (a Time for a time array; a CAString's default
+  #     is `""`); `UNDEF` masks them instead.
   #   @param bounds [String, Symbol] what an out-of-range index means; a
   #     Symbol says the same as the String, matching {#windows}: `"fill"`
   #     (default) uses `fill_value`, `"nearest"` clamps to the edge cell,
@@ -50,6 +52,9 @@ class CArray
   #     cyclic shift).
   #   @raise [ArgumentError] when `bounds` conflicts with `fill_value: UNDEF`,
   #     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.
   def window(*ranges, fill_value: 0, bounds: "fill"); end
 
   # @!endgroup

data/yard-stubs/carray_access.rb

@@ -20,7 +20,9 @@ class CArray
   #   - Range — a contiguous (or stepped, via a stepped Range) sub-range.
   #   - boolean CArray — masked selection along that axis.
   #   - Integer CArray — fancy gather (index array); shape follows the
-  #     index array.
+  #     index array.  A masked cell of the index array selects nothing and
+  #     keeps its place: it reads as masked, and a write to it has no cell
+  #     to land in and is discarded.
   #   - `:_` — newaxis: insert a size-1 axis at this position.
   #   - `:%` — repeat / tiling sugar.
   #   - `:>` — slab axis: wrap the result in a `CASlabIterator`.
@@ -45,6 +47,9 @@ class CArray
   #
   #   Assignment through a slab iterator (`:>`) is not supported — use a
   #   block index (e.g. `ca[range, nil] = val`) or `each_slab`.
+  #
+  #   A store that raises may leave part of the destination written: its
+  #   values and its mask after the raise are not specified.
   #   @param index [Array<Integer, Range, nil, CArray, Symbol>] one entry
   #     per axis (or a single flat address).
   #   @param value [Object, Array, CArray] the value(s) to store, or

data/yard-stubs/carray_attribute.rb

@@ -35,11 +35,6 @@ class CArray
   #   @return [Integer]
   def ndim; end
 
-  # @overload rank
-  #   @deprecated Use {#ndim}.
-  #   @return [Integer]
-  def rank; end
-
   # @overload bytes
   #   Returns the byte size of one element. Equals
   #   `CArray.sizeof(data_type)` for numeric types; for fixed-length

data/yard-stubs/carray_cast.rb

@@ -104,6 +104,10 @@ class CArray
   #   `infinity` (optional sign, any case) are kept as NaN / ±Infinity for
   #   float types. A cell that is not a String goes through `Integer()` /
   #   `Float()` as before.
+  #
+  #   From a float or complex array to an integer type, a NaN cell (in
+  #   either part) becomes UNDEF. A finite value outside the integer type
+  #   is converted as the machine's C converts it.
   #   @param data_type [Symbol, Integer, Class, String] target element type.
   #   @param bytes [Integer, nil] element width in bytes, required for
   #     `:fixlen`.
@@ -209,6 +213,10 @@ class CArray
   #   target. Use {#to_type} instead for parse-with-mask (an unparseable
   #   cell becomes UNDEF). The `CA_<TYPE>(obj)` construction shorthands
   #   take this same non-masking path.
+  #   From a float or complex array to an integer type, reading a NaN cell
+  #   raises FloatDomainError, as storing NaN into an integer array does; a
+  #   masked NaN cell (left by {#mask_invalid}) reads UNDEF. {#to_type}
+  #   makes a NaN cell UNDEF instead.
   #   A Face refuses: reinterpreting its storage would hand back the
   #   bytes its surface exists to hide (the serial instead of the time, the
   #   descriptor instead of the string), and no view decodes a surface. Take
@@ -220,6 +228,8 @@ class CArray
   #   @return [CAFake]
   #   @raise [TypeError] when `self` is a Face and the request would read its
   #     storage under another type.
+  #   @raise [FloatDomainError] when a NaN cell that is not masked is read
+  #     into an integer type.
   def as_type(data_type, bytes: nil); end
 
   # @overload as_boolean

data/yard-stubs/carray_conversion.rb

@@ -75,7 +75,8 @@ class CArray
   #   Reads `ca_length(self)` bytes from `io` and overwrites the
   #   element data of `self` in row-major order. `io` may be a
   #   `String` of the exact size, or any object responding to
-  #   `read(n, buf = nil)`.
+  #   `read(n, buf = nil)`. Into a boolean array, a non-zero byte is
+  #   read as 1 (true).
   #   @param io [String, IO, #read]
   #   @return [self]
   #   @raise [RuntimeError] on a short read.

data/yard-stubs/carray_copy.rb

@@ -69,12 +69,14 @@ class CArray
   # @overload template { value }
   #   With a 0-arity block, fills every element of the result with
   #   the block's return value (broadcast). Equivalent to
-  #   `template.tap { |t| t[] = value }`.
+  #   `template.tap { |t| t[] = value }`.  On a Face the value is
+  #   stored as a store writes it (a String for a CAString).
   #   @yieldreturn [Object] value to broadcast to every element.
   #   @return [CArray]
   # @overload template { |*idx| ... }
   #   With a block of arity > 0, calls the block once per cell with
-  #   the multi-dimensional index `*idx` and stores the result.
+  #   the multi-dimensional index `*idx` and stores the result, as a
+  #   store writes it.
   #   @yieldparam idx [Array<Integer>] per-axis indices.
   #   @yieldreturn [Object]
   #   @return [CArray]

data/yard-stubs/carray_count.rb

@@ -46,10 +46,10 @@ class CArray
   #     (`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).
-  #     On an integer array a Float `v`, or a `v` array of a wider
-  #     type, is compared in the type the two share, as {#eq} compares:
-  #     `CA_INT32([1, 2]).count(1.5)` is `0`.  An Integer `v` that does
-  #     not fit the array raises `RangeError`.
+  #     `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
+  #     Integer the array's type cannot hold is counted `0` times.
   #   - `self.data_type == :object`, `v` is scalar: cells equal to `v`
   #     by Ruby `==`, so `count(1)` and `count(1.0)` agree, and `true` /
   #     `false` / `nil` are ordinary values to count.

data/yard-stubs/carray_element.rb

@@ -40,9 +40,10 @@ class CArray
   # @overload elem_fetch(idx)
   #   Returns the value at position `idx` (cast back to the
   #   appropriate Ruby type). Returns `UNDEF` if the cell is masked.
-  #   Returns `nil` if `self.empty?`.
+  #   A negative index counts from the end.
   #   @param idx [Integer, Array<Integer>]
-  #   @return [Object, nil]
+  #   @return [Object]
+  #   @raise [IndexError] if `idx` names no cell, an empty array included.
   def elem_fetch(idx); end
 
   # @overload elem_incr(idx)
@@ -67,7 +68,10 @@ class CArray
   #   @param idx [Integer, Array<Integer>]
   #   @param v [Numeric]
   #   @return [self]
-  #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type` (complex values have no order).
+  #   @raise [RangeError] when `v` wins but does not fit the type, as
+  #     `self[idx] = v` raises.
   def elem_min(idx, v); end
 
   # @overload elem_max(idx, v)
@@ -77,7 +81,9 @@ class CArray
   #   @param idx [Integer, Array<Integer>]
   #   @param v [Numeric]
   #   @return [self]
-  #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type`.
+  #   @raise [RangeError] when `v` wins but does not fit the type.
   def elem_max(idx, v); end
 
   # @!endgroup

data/yard-stubs/carray_generate.rb

@@ -8,8 +8,12 @@ class CArray
   # @overload where
   #   Returns a fresh 1-D CArray of flat addresses where `self` is
   #   non-zero (or `true`). Masked positions are excluded.
-  #   Non-boolean arrays are first coerced to boolean.
+  #   An integer, float or complex array selects its non-zero cells
+  #   (NaN is non-zero). Any other array that is not boolean is cast to
+  #   boolean, which takes only `0`, `1`, `true` and `false`.
   #   @return [CArray] 1-D, `:int64` (`ca_size_t`).
+  #   @raise [CArray::DataTypeError, TypeError] if an array that is not
+  #     boolean, integer, float or complex cannot be cast to boolean.
   #   @example
   #     CArray.int32(5) { [0, 1, 0, 2, 0] }.where.to_a
   #     # => [1, 3]
@@ -32,8 +36,15 @@ class CArray
   #   Fills `self` in row-major order with `init_val`, `init_val +
   #   step`, `init_val + 2*step`, ...
   #
+  #   On an integer array an `init_val` or `step` that is not an Integer
+  #   (a Float, a Rational) makes each cell `init_val + step*i` cut
+  #   toward zero, as a store takes a float: `int32.seq(0.5, 0.5)` is
+  #   `[0, 1, 1, 2]`.  The first and last values must fit the type.
+  #
   #   For `:object` arrays only, `step` may be a Symbol naming the
   #   stepping method to invoke on the previous element (e.g. `:succ`).
+  #   A CAString takes only a run of Strings (`s.seq!("a", :succ)`), as a
+  #   store into it does.
   #   @param init_val [Numeric, Object]
   #   @param step [Numeric, Symbol]
   #   @return [self]
@@ -49,6 +60,15 @@ class CArray
   #   @return [self]
   #   @raise [ArgumentError] if `axis` is out of range or not a single
   #     integer.
+  #   @raise [RangeError] for an integer array, if `init_val` does not fit
+  #     its type, or an Integer `step` is larger than the type can hold. An
+  #     unsigned array takes a negative step (a descending run). A run of
+  #     Integers that passes the end of the type wraps, as integer
+  #     arithmetic does; a real run (a Float or Rational argument) whose
+  #     first or last value does not fit raises.
+  #   @raise [FloatDomainError] for an integer array given a NaN argument.
+  #   @raise [TypeError] if `init_val` or `step` is not a number (a Symbol
+  #     `step` on an `:object` array excepted).
   def seq!(*); end
 
   # @overload seq(init_val = 0, step = 1, axis: nil)