carray 3.0.2 → 3.0.4

data/yard-stubs/ca_obj_bitfield.rb

@@ -19,24 +19,35 @@ class CArray
   # of the returned array.
   #
   # `range` may be an integer (a single bit — the resulting view has
-  # `data_type :boolean`) or a `Range` covering the bit positions.
-  # The `data_type` of the view is chosen from the bit width:
-  # 1 bit → `:boolean`, 2..8 → `:uint8`, 9..16 → `:uint16`,
-  # 17..32 → `:uint32`, 33..64 → `:uint64`.
-  #
-  # `type` is accepted but currently ignored (the width-derived type
-  # is always used).
+  # `data_type :boolean`) or a `Range` covering the bit positions.  A
+  # negative bit or range end counts from the last bit of the cell.
+  # A field is read with one 8-byte load from the byte it starts in, so
+  # it may not reach more than 64 bits past the start of that byte.
+  # `type` is the integer type the field is read as.  A signed type
+  # (`:int8` .. `:int64`) reads the field's top bit as its sign: the
+  # 3-bit field `0b101` is 5 as `:uint8` and -3 as `:int8`.  A type
+  # wider than the field only widens the value.  Without `type`, the
+  # 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`).
   #
   # @overload bitfield(range, type = nil)
   #   @param range [Integer, Range] bit position (single bit) or bit
   #     range within one parent cell.
-  #   @param type [Symbol, nil] reserved, currently ignored.
+  #   @param type [Symbol, Integer, nil] the integer type the field is
+  #     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, or when the bit length
-  #     is outside `1..64`.
-  #   @raise [ArgumentError] when the derived bit length exceeds the
-  #     resolved data type.
+  #     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
+  #     array.
+  #   @raise [ArgumentError] when `type` is narrower than the field
+  #     (or `:boolean` for a field of more than one bit).
+  #   @raise [CArray::DataTypeError] when `type` is not an integer type
+  #     or `:boolean`.
   def bitfield(range, type = nil); end
 
   # @!endgroup

data/yard-stubs/ca_obj_fake.rb

@@ -22,7 +22,7 @@ class CArray
   #   reinterpret the storage on purpose. A Numeric Face, whose surface *is*
   #   its storage, is unaffected.
   #   @param data_type [Symbol, Integer, Class, String]
-  #   @param bytes [Integer] element byte size for `:fixlen`.
+  #   @param bytes [Integer] element byte size for `:fixlen` (1 or more).
   #   @return [CAFake]
   #   @raise [TypeError] when `self` is a Face and the request would read its
   #     storage under another type.

data/yard-stubs/ca_obj_field.rb

@@ -18,8 +18,12 @@ class CArray
   #   @param bytes [Integer, nil] element size; required for `:fixlen`,
   #     inferred otherwise.
   #   @return [CAField]
-  #   @raise [RuntimeError] when `offset` is negative or the
+  #   @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

@@ -32,11 +32,12 @@ class CArray
   #     defaults to `self.bytes`.
   #   @param offset [Integer] offset in parent elements.
   #   @return [CARefer, CARecord]
-  #   @raise [RuntimeError] when the byte widths do not divide
+  #   @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 [RuntimeError] when reinterpreting a CA_OBJECT parent
-  #     with a non-object `data_type`.
+  #   @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)`).
   def refer(*argv); end
 
   # Returns a view of `self` with the requested shape.  Element
@@ -54,7 +55,7 @@ class CArray
   #   @return [CArray] the reshape view.
   #   @raise [ArgumentError] when the number of dims exceeds
   #     `CA_RANK_MAX`.
-  #   @raise [RuntimeError] when the product does not equal
+  #   @raise [ArgumentError] when the product does not equal
   #     `self.elements` (with no placeholder), when the placeholder
   #     cannot be inferred, when more than one placeholder is
   #     given, or when a `nil` has no matching source axis.

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`.
@@ -38,7 +38,6 @@ class CArray
   #     shorter than `ndim` (missing axes default to `0`).
   #   @return [CARoll]
   #   @raise [ArgumentError] when more than `ndim` shifts are given.
-  #   @raise [IndexError] when any parent dimension is non-positive.
   def roll(*shifts); end
 
   # @!endgroup

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_stride.rb

@@ -20,7 +20,8 @@ class CArray
 
   # Returns a {CAStride} view of `self` with the given byte strides and
   # starting byte offset, inheriting the receiver's data type and element
-  # size.  Memory is shared with the receiver.
+  # size.  Memory is shared with the receiver, and a Face receiver stays the
+  # Face.
   #
   # This is a low-level escape hatch: the strides and offset are **not**
   # bounds-checked against the receiver's memory, so a combination that
@@ -46,7 +47,8 @@ class CArray
   #
   # Truncate mode: a trailing partial window is dropped rather than padded.
   # Memory is shared with the parent, and because windows overlap, one parent
-  # cell is visible from several positions of the view.
+  # cell is visible from several positions of the view.  A Face parent stays
+  # the Face.
   #
   # Reduce over the trailing `ndim` axes for a rolling statistic.
   #
@@ -70,7 +72,7 @@ class CArray
   # The window axes are inserted before the trailing axes, so the result rank
   # is `ndim + S`.  With `S == ndim` there are no trailing axes and the
   # result is identical to {#sliding_windows}.  Truncate mode; memory is
-  # shared with the parent.
+  # shared with the parent, and a Face parent stays the Face.
   #
   # @overload unfold(window, step: nil)
   # @overload unfold(w0, w1, ..., step: nil)
@@ -93,13 +95,14 @@ class CArray
   # tile size: nothing is truncated and no cell is aliased twice.  Reduce over
   # the trailing `ndim` axes (e.g. `v.mean(-1, -2)` for a 2-D parent) for
   # per-tile statistics such as pooling or block-wise aggregation.  Memory is
-  # shared with the parent.
+  # shared with the parent, and a Face parent stays the Face.
   #
   # @overload block_view(block)
   # @overload block_view(b0, b1, ...)
   #   @param block [Array<Integer>, Integer] tile length per axis, one per
   #     dimension, as an Array or as variadic arguments.
-  #   @return [CAStride] of rank `2 * ndim`.
+  #   @return [CAStride] of rank `2 * ndim` (the parent's Face class when
+  #     the parent is a Face).
   #   @raise [ArgumentError] when the tile count does not equal `ndim`, when
   #     a tile length is not positive, when an axis is not divisible by its
   #     tile length, or when `2 * ndim` exceeds `CA_RANK_MAX`.
@@ -148,8 +151,8 @@ class CArray
   # @overload flip(axis)
   # @overload flip(a0, a1, ...)
   # @overload flip([a0, a1, ...])
-  #   @param axis [Array<Integer>, Integer] axes to reverse; negative indices
-  #     count from the last axis.
+  #   @param axis [Array<Integer>, Integer, nil] axes to reverse; negative
+  #     indices count from the last axis. `flip(nil)` is the same as `flip`.
   #   @return [CAStride]
   #   @raise [ArgumentError] when an axis is out of range or repeated.
   def flip(*axis); end

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_transpose.rb

@@ -29,7 +29,7 @@ class CArray
   #   @param imap [Array<Integer>] permutation of `0 ... ndim`.
   #   @return [CATranspose]
   #   @raise [ArgumentError] when `imap.length != ndim`.
-  #   @raise [RuntimeError] when an entry of `imap` is out of range
+  #   @raise [ArgumentError] when an entry of `imap` is out of range
   #     or duplicated.
   def transpose(*imap); end
 

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,
@@ -48,9 +50,11 @@ class CArray
   #     is passed (the block form was removed in 3.0), or when `bounds` is
   #     `"periodic"` / `"reflect"` (both removed in 3.0; use {#roll} for a
   #     cyclic shift).
-  #   @raise [IndexError] when a range selects zero cells.
-  #   @raise [RuntimeError] when `bounds` conflicts with `fill_value: UNDEF`,
+  #   @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
@@ -82,9 +87,10 @@ class CArray
   #   Array of length `self.ndim`, so `i, j = ca.addr2index(x)` unpacks
   #   uniformly for scalar and vector inputs.
   #   @param addr [Integer, CArray] a flat address in `0...elements`,
-  #     or a CArray of such addresses (arbitrary shape).
+  #     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 [ArgumentError] when any `addr` is out of range.
+  #   @raise [IndexError] when any `addr` is out of range.
   def addr2index(addr); end
 
   # @overload index2addr(*index)
@@ -106,8 +112,8 @@ class CArray
   #   @param addr [Integer, CArray] a flat address or a CArray of them.
   #   @param shape [Array<Integer>] the row-major shape defining the grid.
   #   @return [Array<Integer>, Array<CArray>] one entry per axis.
-  #   @raise [ArgumentError] when any `addr` is out of range or `shape:`
-  #     is missing.
+  #   @raise [IndexError] when any `addr` is out of range.
+  #   @raise [ArgumentError] when `shape:` is missing.
   def self.addr2index(addr, shape:); end
 
   # @overload index2addr(*index, shape:)

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_broadcast.rb

@@ -23,7 +23,7 @@ class CArray
   #   @param shape [Array<Integer>] target shape, with
   #     `length >= self.ndim`.
   #   @return [CArray]
-  #   @raise [RuntimeError] if a source axis cannot be paired with a
+  #   @raise [ArgumentError] if a source axis cannot be paired with a
   #     target axis (cross-ndim expansion is intentionally strict —
   #     see {CArray.broadcast} for the explicit-`:_` axis
   #     declaration form).

data/yard-stubs/carray_cast.rb

@@ -8,57 +8,75 @@
 # is a top-level function that coerces `obj` (a CArray, Array,
 # Numeric, or anything castable) into a CArray of the named element
 # type, equivalent to `obj.to_ca.as_type(:<type>)`.
+#
+# These are casts, not shape spellings: `CA_INT32(3, 3)` is not the
+# `(3, 3)` array that `CArray.int32(3, 3)` builds, and is refused.
+# A `Range` accepts one more argument, the step, and that is the only
+# two-argument form:
+#
+#     CA_INT32(0..6)        # => [ 0, 1, 2, 3, 4, 5, 6 ]
+#     CA_INT32(0..6, 2)     # => [ 0, 2, 4, 6 ]
+#     CA_INT32(0, 2)        # ArgumentError
+#
+# A step of `0` raises `RuntimeError`.  A step given for anything but a
+# `Range`, or a third argument, raises `ArgumentError`.  An
+# `Enumerator::ArithmeticSequence` already carries its own step, so
+# `CA_INT32((0..6).step(2))` needs no second argument.
+#
+# `CA_FIXLEN` takes `bytes:` instead of a step; see {#CA_FIXLEN}.
 module Kernel
   # @!group CArray cast shorthands
 
   # Coerces `obj` into a `:boolean` CArray. @return [CArray]
-  def CA_BOOLEAN(obj); end
+  def CA_BOOLEAN(obj = nil, step = nil); end
   # Coerces `obj` into an `:int8` CArray. @return [CArray]
-  def CA_INT8(obj); end
+  def CA_INT8(obj = nil, step = nil); end
   # Coerces `obj` into a `:uint8` CArray. @return [CArray]
-  def CA_UINT8(obj); end
+  def CA_UINT8(obj = nil, step = nil); end
   # Coerces `obj` into an `:int16` CArray. @return [CArray]
-  def CA_INT16(obj); end
+  def CA_INT16(obj = nil, step = nil); end
   # Coerces `obj` into a `:uint16` CArray. @return [CArray]
-  def CA_UINT16(obj); end
+  def CA_UINT16(obj = nil, step = nil); end
   # Coerces `obj` into an `:int32` CArray. @return [CArray]
-  def CA_INT32(obj); end
+  def CA_INT32(obj = nil, step = nil); end
   # Coerces `obj` into a `:uint32` CArray. @return [CArray]
-  def CA_UINT32(obj); end
+  def CA_UINT32(obj = nil, step = nil); end
   # Coerces `obj` into an `:int64` CArray. @return [CArray]
-  def CA_INT64(obj); end
+  def CA_INT64(obj = nil, step = nil); end
   # Coerces `obj` into a `:uint64` CArray. @return [CArray]
-  def CA_UINT64(obj); end
+  def CA_UINT64(obj = nil, step = nil); end
   # Coerces `obj` into a `:float32` CArray. @return [CArray]
-  def CA_FLOAT32(obj); end
+  def CA_FLOAT32(obj = nil, step = nil); end
   # Coerces `obj` into a `:float64` CArray. @return [CArray]
-  def CA_FLOAT64(obj); end
+  def CA_FLOAT64(obj = nil, step = nil); end
   # Coerces `obj` into a `:cmplx64` CArray. @return [CArray]
-  def CA_CMPLX64(obj); end
+  def CA_CMPLX64(obj = nil, step = nil); end
   # Coerces `obj` into a `:cmplx128` CArray. @return [CArray]
-  def CA_CMPLX128(obj); end
+  def CA_CMPLX128(obj = nil, step = nil); end
   # Coerces `obj` into an `:object` CArray. @return [CArray]
-  def CA_OBJECT(obj); end
+  def CA_OBJECT(obj = nil, step = nil); end
   # Coerces `obj` into a `CA_SIZE` (platform native size) CArray.
   # @return [CArray]
-  def CA_SIZE(obj); end
-  # Coerces `obj` into a `:fixlen` CArray. @return [CArray]
-  def CA_FIXLEN(obj); end
+  def CA_SIZE(obj = nil, step = nil); end
+  # Coerces `obj` into a `:fixlen` CArray.  `bytes` defaults to the
+  # longest top-level element of an `Array`, or `0` for `nil`.
+  # @return [CArray]
+  def CA_FIXLEN(obj, bytes: nil); end
 
   # Alias of {#CA_UINT8}. @return [CArray]
-  def CA_BYTE(obj); end
+  def CA_BYTE(obj = nil, step = nil); end
   # Alias of {#CA_INT16}. @return [CArray]
-  def CA_SHORT(obj); end
+  def CA_SHORT(obj = nil, step = nil); end
   # Alias of {#CA_INT32}. @return [CArray]
-  def CA_INT(obj); end
+  def CA_INT(obj = nil, step = nil); end
   # Alias of {#CA_FLOAT32}. @return [CArray]
-  def CA_FLOAT(obj); end
+  def CA_FLOAT(obj = nil, step = nil); end
   # Alias of {#CA_FLOAT64}. @return [CArray]
-  def CA_DOUBLE(obj); end
+  def CA_DOUBLE(obj = nil, step = nil); end
   # Alias of {#CA_CMPLX64}. @return [CArray]
-  def CA_COMPLEX(obj); end
+  def CA_COMPLEX(obj = nil, step = nil); end
   # Alias of {#CA_CMPLX128}. @return [CArray]
-  def CA_DCOMPLEX(obj); end
+  def CA_DCOMPLEX(obj = nil, step = nil); end
 
   # @!endgroup
 end
@@ -71,17 +89,25 @@ class CArray
   # @overload to_type(data_type, bytes: nil)
   #   Returns a new entity holding the elements of `self` converted to
   #   `data_type` (an eager copy that owns its storage). Masked cells are
-  #   carried across. When `data_type` is a data_class (a CAStruct
-  #   subclass) the result is wrapped in CARecord.
+  #   carried across, and so are the attributes `self` shows (`attrs`).
+  #   When `data_type` is a data_class (a CAStruct subclass) the result
+  #   is wrapped in CARecord.
   #
   #   When `self` is an `:object` array and `data_type` is an integer or
-  #   float type, each cell is parsed with Ruby `Integer()` / `Float()`
-  #   rules and a cell that cannot be parsed becomes UNDEF (masked) rather
-  #   than a silent `0.0` or a raise. This is symmetric for float and int:
-  #   `nil`, `""`, `"xx"`, and (for int targets) a non-integer string such
-  #   as `"1.5"` all map to UNDEF. Explicit `nan` / `inf` / `infinity`
-  #   literals (optional sign, case-insensitive, matched as a whole token)
-  #   are kept as NaN / ±Infinity.
+  #   float type, a String cell is read as a decimal number, not as a Ruby
+  #   literal: `"010"` is 10, and `"0x10"` / `"1_000"` / `"0b11"` are not
+  #   numbers. An integer type takes a number whose value is exactly an
+  #   integer (`"1.0"`, `"1e3"`) but not `"1.5"`. A cell that cannot be
+  #   read becomes UNDEF (masked) rather than a silent `0.0` or a raise:
+  #   `nil`, `""`, `"xx"`, and a String integer the type cannot hold
+  #   (`"300"` into `:int8`) all map to UNDEF. Explicit `nan` / `inf` /
+  #   `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`.
@@ -187,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
@@ -198,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
@@ -337,7 +369,7 @@ class CArray
   #   primitive the binary operators use.
   #   @param other [CArray, Object] the second operand.
   #   @return [Array(CArray, CArray)]
-  #   @raise [RuntimeError] when the two data_types have no common type.
+  #   @raise [CArray::DataTypeError] when the two data_types have no common type.
   def cast_with(other); end
 
   # `coerce` is documented with its definition in ext/carray_operator.c;
@@ -376,10 +408,9 @@ class CArray
   #     `nil` keeps the source type (or `:object` when `other` is `nil`).
   #   @return [CArray]
   #   @raise [RuntimeError] when `other` is read-only, its MemoryView is
-  #     read-only, its `to_ca` refuses `writable: true`, or it cannot be
-  #     wrapped as a CArray.
-  #   @raise [TypeError] when `other#to_ca` returns something that is not a
-  #     CArray.
+  #     read-only, or its `to_ca` refuses `writable: true`.
+  #   @raise [TypeError] when `other` cannot be wrapped as a CArray, or
+  #     `other#to_ca` returns something that is not a CArray.
   #   @raise [ArgumentError] when `other#to_ca` does not accept `writable:`.
   #   @raise [TypeError] when `other` is a Face and `data_type` differs from
   #     its surface type.
@@ -445,20 +476,30 @@ class CArray
   #     data_type inferred (3 -> `:int64`, 3.14 -> `:float64`,
   #     1+2i -> `:cmplx128`, ...)
   #
-  #   Values and data_type representations promote uniformly. Integer args
-  #   are interpreted as *values*, not as data_type codes:
+  #   The arrays and data_type representations promote together. A
+  #   scalar (a value, or a CScalar) then joins their type the way it
+  #   does beside an operator: one of the same kind takes that type
+  #   (`result_type(float32_array, 0.1)` is `:float32`, as
+  #   `float32_array + 0.1` is), one of another kind promotes
+  #   (`result_type(int32_array, 1.5)` is `:float64`), and an Integer
+  #   that does not fit an integer type takes `:int64`. With no array or
+  #   data_type representation, every argument promotes by its own type.
+  #
+  #   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
   #   `result_type(CA_INT64)` to be explicit about data_type intent.
   #   @param args [Array<CArray, Symbol, String, Class, Object>] operands.
   #   @return [Symbol]
   #   @raise [ArgumentError] when called with no arguments.
-  #   @raise [RuntimeError] when two inputs are mutually incompatible
+  #   @raise [CArray::DataTypeError] when two inputs are mutually incompatible
   #     (e.g. `:object` with `:fixlen`).
   #   @example
   #     CArray.result_type(:int32, :float32)  #=> :float32
   #     CArray.result_type(3, 3.14)           #=> :float64
   #     CArray.result_type(true, 3)           #=> :int64
+  #     CArray.result_type(CA_INT8([1]), 1)   #=> :int8
+  #     CArray.result_type(CA_INT8([1]), 300) #=> :int64
   def self.result_type(*args); end
 
   # @overload promote_list(list, data_type: nil)
@@ -471,8 +512,12 @@ class CArray
   #   elements passes through (CAStack lifts it), unless the class is not
   #   portable (CAConstString) or the elements disagree on state
   #   (CATime with different units); a list of primitives is
-  #   promoted via {.result_type} + {.wrap_readonly}; a mix of Face and
-  #   non-Face, or heterogeneous Face classes, is rejected.
+  #   promoted via {.result_type} + {.wrap_readonly}, except that a list
+  #   mixing signed and unsigned integers takes a type that holds both
+  #   (`uint8` with `int8` is `int16`, 64-bit pairs are `:object`), and an
+  #   integer of 32 bits or more beside `float32` takes `float64`, since
+  #   the arrays are joined value for value; a mix of Face and non-Face,
+  #   or heterogeneous Face classes, is rejected.
   #
   #   With an explicit primitive `data_type`: all-primitive elements are
   #   wrapped read-only to the requested type; any Face element is

data/yard-stubs/carray_conversion.rb

@@ -38,6 +38,13 @@ class CArray
 
   # @!group Copy and conversion
 
+  # On a Face (`CATime`, `CACategorical`, `CAConstString`, ...) the
+  # bytes are its storage, and none of its state is written: not the
+  # unit of a `CATime`, not the labels of a `CACategorical`. A
+  # `CAConstString` cell is a `(start, end)` pair into its own byte
+  # pool, so its strings are not written at all; call
+  # `to_fixlen_string` first to dump the text.
+  #
   # @overload dump_binary
   #   Returns a new binary String containing the raw element bytes of
   #   `self` in row-major order.
@@ -60,14 +67,20 @@ class CArray
   #   @return [String]
   def to_s; end
 
+  # On a Face the bytes are read into its storage, and its state is
+  # the receiver's own: load into a Face set up with the same state
+  # (unit, labels) that was in force when the bytes were dumped.
+  #
   # @overload load_binary(io)
   #   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 short read or size mismatch.
+  #   @raise [RuntimeError] on a short read.
+  #   @raise [ArgumentError] when a String source is not the array's size.
   #   @raise [CArray::DataTypeError] if `self.data_type` is
   #     `:object`.
   def load_binary(io); end