carray 3.0.1 → 3.0.3

data/yard-stubs/ca_obj_block.rb

@@ -10,7 +10,8 @@ class CABlock
   # @overload size0
   #   Returns the parent dimension sizes that the block is carved
   #   from (one Integer per axis).  Distinct from `shape`, which is
-  #   the block's own shape (= `count` after step / stride logic).
+  #   the block's own shape (= what it exposes after step / stride
+  #   logic).
   #   @return [Array<Integer>]
   def size0; end
 
@@ -26,12 +27,6 @@ class CABlock
   #   @return [Array<Integer>]
   def step; end
 
-  # @overload count
-  #   Returns the per-axis number of elements the block exposes.
-  #   Same as `shape`.
-  #   @return [Array<Integer>]
-  def count; end
-
   # @overload offset
   #   Returns the block's base flat offset into the parent (in
   #   element units), set at construction and adjusted as start[]

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,7 +18,7 @@ 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.
   # @overload field(offset, template)
   #   Returns a CARefer over a {CAField}: takes `template.elements *

data/yard-stubs/ca_obj_refer.rb

@@ -32,10 +32,10 @@ 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
+  #   @raise [CArray::DataTypeError] when reinterpreting a CA_OBJECT parent
   #     with a non-object `data_type`.
   def refer(*argv); end
 
@@ -54,7 +54,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

@@ -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_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_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

@@ -20,7 +20,14 @@ class CArray
   # axis, which may extend past either end of the parent.  Cells inside the
   # 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.
+  # them instead.  A write that lands outside the parent has no cell to land
+  # in and is discarded.
+  #
+  # 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
+  # `pad` with no allocation (`fill_value:` is its `constant`, `bounds:
+  # :nearest` its `edge`).  {#windows} is the different, plural thing: one
+  # such window anchored on every cell, folded.
   #
   # Only unit-step ranges are accepted, and each range must run forward, so
   # the `0..-1` end-relative notation cannot be used here.
@@ -30,7 +37,8 @@ class CArray
   #     must equal `self.ndim`.
   #   @param fill_value [Object] value given to out-of-range cells; `UNDEF`
   #     masks them instead.
-  #   @param bounds [String] what an out-of-range index means: `"fill"`
+  #   @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,
   #     `"ruby"` reads negative indices from the far end, `"strict"` raises.
   #     `"mask"` masks the cell but warns — pass `fill_value: UNDEF` instead.
@@ -40,8 +48,7 @@ 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.
   def window(*ranges, fill_value: 0, bounds: "fill"); end
 

data/yard-stubs/carray_access.rb

@@ -22,7 +22,7 @@ class CArray
   #   - Integer CArray — fancy gather (index array); shape follows the
   #     index array.
   #   - `:_` — newaxis: insert a size-1 axis at this position.
-  #   - `:*` / `:%` — repeat / tiling sugar.
+  #   - `:%` — repeat / tiling sugar.
   #   - `:>` — slab axis: wrap the result in a `CASlabIterator`.
   #   - a member name Symbol — project a struct field (see `CARecord`).
   #
@@ -82,9 +82,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 +107,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_broadcast.rb

@@ -23,9 +23,9 @@ 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
+  #     see {CArray.broadcast} for the explicit-`:_` axis
   #     declaration form).
   #   @example
   #     a = CArray.float64(3) { [1.0, 2.0, 3.0] }

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,21 @@ 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.
   #   @param data_type [Symbol, Integer, Class, String] target element type.
   #   @param bytes [Integer, nil] element width in bytes, required for
   #     `:fixlen`.
@@ -337,7 +359,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 +398,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 +466,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 +502,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,6 +67,10 @@ 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
@@ -67,7 +78,8 @@ class CArray
   #   `read(n, buf = nil)`.
   #   @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

data/yard-stubs/carray_copy.rb

@@ -8,10 +8,15 @@ class CArray
   # @overload copy
   #   Returns a fresh entity CArray with the same shape, `data_type`,
   #   element values, and mask state as `self`. Always allocates and
-  #   copies, even when `self` is already an entity.
+  #   copies, even when `self` is already an entity. The copy gets the
+  #   attributes `self` shows (`attrs`) as its own.
   #
   #   Use `copy` when you need an array you own and can mutate
-  #   without affecting any source.
+  #   without affecting any source. It is the only way to copy a
+  #   CArray: `to_ca` returns `self`, and `dup` / `clone` on a view
+  #   return another view onto the same storage, so writing to any of
+  #   them writes to the source. Don't use `dup`, `clone` or `to_ca`
+  #   to copy.
   #   @return [CArray] independent entity.
   #   @example A view's copy is independent of its source
   #     a = CArray.float64(4).seq
@@ -59,7 +64,7 @@ class CArray
   #   @param data_type [Symbol] target element type
   #     (e.g. `:int32`, `:float64`, `:fixlen`).
   #   @param bytes [Integer] element byte size; required for
-  #     `:fixlen`, ignored for numeric types.
+  #     `:fixlen` (1 or more), ignored for numeric types.
   #   @return [CArray]
   # @overload template { value }
   #   With a 0-arity block, fills every element of the result with

data/yard-stubs/carray_core.rb

@@ -3,64 +3,6 @@
 # See yard-stubs/README.md and yard-stubs/STYLE.md.
 
 class CArray
-  # @!group Attach lifecycle
-  #
-  # The `attach` / `attach!` family is an internal lifecycle API used
-  # by library authors writing CArray-aware C extensions. End users
-  # should not normally need to call these methods — view algebra and
-  # `CArray#[]` / `[]=` handle attach/sync transparently.
-  #
-  # The block-form `attach` (no sync on exit) and `attach!` (sync on
-  # exit) wrap a body of code so that the underlying memory block is
-  # guaranteed to be materialized while the block runs and is
-  # released afterward. The dunder forms (`__attach__`, `__sync__`,
-  # `__detach__`) expose the raw three-step protocol for callers that
-  # cannot use a block.
-
-  # @overload attach { ... }
-  #   Attaches `self`, yields, and detaches on block exit. No sync
-  #   is performed.
-  #   @yield
-  #   @return [Object] the block's return value.
-  def attach; end
-
-  # @overload attach! { ... }
-  #   Attaches `self`, yields, then syncs and detaches on block exit.
-  #   Use this form when the block mutates `self.ptr` and you need
-  #   the changes flushed back to the parent.
-  #   @yield
-  #   @return [Object] the block's return value.
-  def attach!; end
-
-  # @private
-  # @overload __attach__
-  #   Raw attach: materializes the memory block of `self` and leaves
-  #   it attached. Caller is responsible for the matching
-  #   `__detach__` (and `__sync__`, if changes were made).
-  #
-  #   Prefer the block form {#attach!} unless block scope is
-  #   impossible.
-  #   @return [self]
-  #   @api private
-  def __attach__; end
-
-  # @private
-  # @overload __sync__
-  #   Raw sync: writes any pending changes in `self.ptr` back to the
-  #   parent. Requires `self` to be currently attached.
-  #   @return [self]
-  #   @api private
-  def __sync__; end
-
-  # @private
-  # @overload __detach__
-  #   Raw detach: releases the memory block paired with `__attach__`.
-  #   @return [self]
-  #   @api private
-  def __detach__; end
-
-  # @!endgroup
-
   # @!group Attributes
 
   # @overload members
@@ -68,7 +10,7 @@ class CArray
   #   Only valid when `self` carries a `data_class` (e.g. a
   #   `CARecord`).
   #   @return [Array<Symbol>]
-  #   @raise [RuntimeError] if `self` has no `data_class`.
+  #   @raise [TypeError] if `self` has no `data_class`.
   def members; end
 
   # @overload fields
@@ -76,7 +18,7 @@ class CArray
   #   declaration order. Each entry is a CArray sharing storage with
   #   `self`.
   #   @return [Array<CArray>]
-  #   @raise [RuntimeError] if `self` has no `data_class`.
+  #   @raise [TypeError] if `self` has no `data_class`.
   def fields; end
 
   # @overload fields_at(*names)
@@ -85,30 +27,8 @@ class CArray
   #   @param names [Array<Symbol, String, Integer>] member names or
   #     positional indices.
   #   @return [Array<CArray>]
-  #   @raise [RuntimeError] if `self` has no `data_class`.
+  #   @raise [TypeError] if `self` has no `data_class`.
   def fields_at(*names); end
 
   # @!endgroup
-
-  class << self
-    # @!group Attach lifecycle
-
-    # @overload attach(*arrays) { ... }
-    #   Attaches every CArray in `arrays`, yields, and detaches them
-    #   in reverse order on block exit. No sync is performed.
-    #   @param arrays [Array<CArray>]
-    #   @yield
-    #   @return [Object] the block's return value.
-    def attach(*arrays); end
-
-    # @overload attach!(*arrays) { ... }
-    #   Attaches every CArray in `arrays`, yields, then syncs and
-    #   detaches each on block exit.
-    #   @param arrays [Array<CArray>]
-    #   @yield
-    #   @return [Object] the block's return value.
-    def attach!(*arrays); end
-
-    # @!endgroup
-  end
 end

data/yard-stubs/carray_count.rb

@@ -26,6 +26,11 @@ class CArray
   #   Mask-cardinality and value-match are distinct concepts, so the
   #   overloading is unambiguous.
   #
+  #   On an `:object` array a cell counts when it is `==` to `v` (so `1`
+  #   and `1.0` match), as {#eq} compares; the hash-based family
+  #   ({#is_in}, {#value_counts}) uses `eql?` instead, as Ruby's
+  #   `Array#uniq` does.
+  #
   #   Dispatch:
   #   - no argument: forwards to {#count_not_masked} (present-cell
   #     count).
@@ -40,7 +45,14 @@ class CArray
   #     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).
+  #     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`.
+  #   - `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.
   #
   #   When `axis` is `nil` (default), reduces over all axes and
   #   returns an `Integer`.  Otherwise reduces along the given
@@ -50,7 +62,9 @@ class CArray
   #   identity `0`, so the count over no cells is `0`, not `UNDEF`
   #   (pass `min_count:` to get `UNDEF` below a threshold instead).
   #
-  #   `:fixlen` and `:object` data types raise `CArray::DataTypeError`.
+  #   `:fixlen` compares the whole cell by `memcmp`, with a short String
+  #   query padded out to the cell width -- so a 4-byte cell holding
+  #   `"a\0\0\0"` is counted by `count("a")`.
   #
   #   A time array counts by its own values: `CATime` / `CATimedelta`
   #   descend to their storage and reconcile `v` into their unit, so `v`