carray 3.0.2 → 3.0.3

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

@@ -10,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
@@ -18,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)
@@ -27,7 +27,7 @@ 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

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).
@@ -41,6 +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`.
   #   - `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_lazy.rb

@@ -17,7 +17,11 @@ class CArray
   #   materialise.  The marker is transient — a Ruby reference can
   #   re-consume it (`m = a.lazy; m.sqrt + m.sin`) without side
   #   effects on `self`.
-  #   @return [CALazyMarker]
+  #
+  #   A Face (`CATime`, `CACategorical`, a string array, ...) returns
+  #   `self`: a lazy tree computes on storage and would drop what the
+  #   Face means, so operations on a Face stay eager.
+  #   @return [CALazyMarker, CArray] the marker, or `self` for a Face
   def lazy; end
   # @!endgroup
 end

data/yard-stubs/carray_loop.rb

@@ -53,7 +53,10 @@ class CArray
 
   # @overload map!
   #   Replaces each element of `self` with the block's return value.
-  #   Mutates `self`.
+  #   Mutates `self`.  When the block raises or breaks part way, or
+  #   returns a value that cannot be stored, the cells already replaced
+  #   stay replaced -- through a view as well, which writes them back to
+  #   its parent.  The same holds for every `map_*!` below.
   #   @yieldparam elem [Object]
   #   @yieldreturn [Object] new value for the cell.
   #   @return [self]

data/yard-stubs/carray_mask.rb

@@ -74,7 +74,8 @@ class CArray
   #   Clears the mask state and overwrites the data at previously
   #   masked positions with `fill_value`. Mutates `self`.
   #   @param fill_value [Object] value to store at each previously
-  #     masked position. Cast to `self.data_type`.
+  #     masked position, converted as a store into `self` converts it.
+  #     `UNDEF` leaves the masked cells masked.
   #   @return [self]
   # @overload unmask(method:, axis: nil)
   #   Fills masked cells in place from neighbouring valid cells along
@@ -106,7 +107,8 @@ class CArray
   #
   #   Replaces the removed `unmask_copy(fill)` from 2.x.
   #   @param fill_value [Object] value to substitute at masked
-  #     positions. Cast to `self.data_type`.
+  #     positions, converted as a store into `self` converts it.
+  #     `UNDEF` leaves them masked (the copy keeps the mask).
   #   @return [CArray]
   # @overload strip_mask(method:, axis: nil)
   #   Returns a new array with masked cells filled from neighbouring
@@ -151,6 +153,8 @@ class CArray
   #   Flips the mask state of every element of `self` in place
   #   (masked ↔ not masked). Mutates `self`.
   #   @return [self]
+  #   @raise [FrozenError] if `self` is frozen or a view of a frozen array.
+  #   @raise [RuntimeError] if `self` is read-only (a lazy expression, for one).
   def invert_mask; end
 
   # @overload inherit_mask(*others)
@@ -174,23 +178,43 @@ class CArray
   # @overload count_masked
   #   Returns the total number of masked elements in `self`.
   #   @return [Integer]
-  # @overload count_masked(axis:)
+  # @overload count_masked(axis:, keep_axis: false, min_count: nil, fill_value: nil)
   #   Returns the per-slice count of masked elements along the given
   #   axis or axes. The result is an int64 CArray with `axis` removed
-  #   from `shape`.
+  #   from `shape` (kept as length 1 with `keep_axis: true`). Naming
+  #   every axis without `keep_axis:` returns an Integer, as the form
+  #   without `axis:` does. The answer is the same whether or not
+  #   `self` has a mask.
   #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
-  #   @return [CArray] int64 CArray.
+  #   @param keep_axis [Boolean] keep the reduced axes as length 1.
+  #   @param min_count [Integer, nil] cells with fewer than this many
+  #     elements are UNDEF.  A count of the mask reads every element,
+  #     masked or not, so this compares with the slice size.
+  #   @param fill_value [Object, nil] value written into UNDEF cells.
+  #   @return [CArray, Integer]
+  #   @raise [ArgumentError] if an axis is out of range, repeated, or
+  #     the axis list is empty.
   def count_masked(*, **); end
 
   # @overload count_not_masked
   #   Returns the total number of not-masked elements in `self`.
   #   @return [Integer]
-  # @overload count_not_masked(axis:)
-  #   Returns the per-slice count of not-masked elements along the
-  #   given axis or axes. The result is an int64 CArray with `axis`
-  #   removed from `shape`.
+  # @overload count_not_masked(axis:, keep_axis: false, min_count: nil, fill_value: nil)
+  #   Returns the per-slice count of not-masked elements along the given
+  #   axis or axes. The result is an int64 CArray with `axis` removed
+  #   from `shape` (kept as length 1 with `keep_axis: true`). Naming
+  #   every axis without `keep_axis:` returns an Integer, as the form
+  #   without `axis:` does. The answer is the same whether or not
+  #   `self` has a mask.
   #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
-  #   @return [CArray] int64 CArray.
+  #   @param keep_axis [Boolean] keep the reduced axes as length 1.
+  #   @param min_count [Integer, nil] cells with fewer than this many
+  #     elements are UNDEF.  A count of the mask reads every element,
+  #     masked or not, so this compares with the slice size.
+  #   @param fill_value [Object, nil] value written into UNDEF cells.
+  #   @return [CArray, Integer]
+  #   @raise [ArgumentError] if an axis is out of range, repeated, or
+  #     the axis list is empty.
   def count_not_masked(*, **); end
 
   # @!endgroup

data/yard-stubs/carray_math.rb

@@ -25,12 +25,15 @@ class CArray
   #   division is true division, as Ruby's `Float#/` is, so that
   #   identity is an integer one. Boolean arrays participate as their
   #   0/1 storage. Masked elements stay masked, and a masked cell is
-  #   never divided.
+  #   never divided. The signed minimum divided by `-1` does not fit and
+  #   is answered as the wrapped negation: `MIN / -1` is `MIN`.
   #   @param other [CArray, Numeric] divisor, broadcast to `self.shape`.
   #   @return [CArray] result of the promoted `data_type` of the two
   #     operands.
   #   @raise [ZeroDivisionError] when an integer divisor is `0`. Float
   #     division returns `Infinity` or `NaN` instead.
+  #   @raise [RangeError] when an Integer `other` does not fit the
+  #     integer `data_type` of `self`.
   #   @example
   #     CA_INT32([-7, -1, 7]) / 3      # => [ -3, -1, 2 ]
   #     CA_DOUBLE([-7.0]) / 3.0        # => [ -2.3333333333333335 ]
@@ -215,7 +218,7 @@ class CArray
   # @overload rcp_mul(other)
   #   Returns `other` divided element-wise by `self` -- the reciprocal
   #   of {#/} in operand order, so that scaling a constant by an array
-  #   needs no temporary.
+  #   needs no temporary. Integer division floors, as {#/} does.
   #   @param other [CArray, Numeric] dividend, broadcast to `self.shape`.
   #   @return [CArray] result of the promoted `data_type` of the two
   #     operands.
@@ -241,12 +244,12 @@ class CArray
   #
   #   A numeric array keeps its `data_type`; a complex array returns the
   #   real magnitude at that complex type's own width, so a `:cmplx64`
-  #   yields `:float32` just as {#real} and {#imag} do. For the form
-  #   that keeps a complex array complex (magnitude with a zero
-  #   imaginary part) use {#abs_i}, which also accepts `:object`.
-  #   @return [CArray] `self`'s `data_type` for numeric input; the real
-  #     component type for complex input.
-  #   @raise [CArray::DataTypeError] for a boolean or `:object` array.
+  #   yields `:float32` just as {#real} and {#imag} do. An `:object`
+  #   array calls each cell's `abs`. For the form that keeps a complex
+  #   array complex (magnitude with a zero imaginary part) use {#abs_i}.
+  #   @return [CArray] `self`'s `data_type` for numeric and `:object`
+  #     input; the real component type for complex input.
+  #   @raise [CArray::DataTypeError] for a boolean array.
   #   @example
   #     CA_CMPLX64([Complex(3, 4)]).abs      # => [ 5.0 ]  (:float32)
   def abs; end
@@ -738,7 +741,8 @@ class CArray
   #   comparison) and `:object` (Ruby `==`) `data_type`. A masked
   #   element yields a masked result rather than `false`. Floating
   #   point equality is exact here; for a tolerant comparison see
-  #   {#is_close} (absolute) or {#is_equiv} (relative).
+  #   {#is_close} (absolute) or {#is_equiv} (relative). Integers compare
+  #   by value, as for {#<}.
   #   @param other [CArray, Numeric, Object] comparand, broadcast to
   #     `self.shape`.
   #   @return [CArray] `:boolean`, same shape as `self`.
@@ -760,6 +764,11 @@ class CArray
   #   Accepts numeric, boolean, `:fixlen` (byte order, shorter first on
   #   a common prefix) and `:object` (Ruby `<`) `data_type`s. Complex
   #   arrays have no ordering and raise.
+  #
+  #   Integers compare by value: an unsigned array against a signed one
+  #   answers as the Integers would (`CA_UINT64([7]) < CA_INT64([-7])`
+  #   is false), and so does an Integer the array's type cannot hold
+  #   (`CA_UINT8([0]) > -1` is true).
   #   @param other [CArray, Numeric, Object] comparand, broadcast to
   #     `self.shape`.
   #   @return [CArray] `:boolean`, same shape as `self`.
@@ -861,8 +870,11 @@ class CArray
   #   Returns a boolean array that is true where an element is `NaN`.
   #   @return [CArray] `:boolean`, same shape as `self`.
   #   @raise [CArray::DataTypeError] for a boolean array.
-  #   @raise [NoMethodError] for an `:object` array whose elements do
-  #     not respond to `#nan?`.
+  #   On an `:object` array an Integer or a Rational element is never
+  #   `NaN`; other elements answer through `#nan?`.
+  #   @raise [NoMethodError] for an `:object` array with an element that
+  #     is not an Integer, a Rational or a Float and does not respond to
+  #     `#nan?`.
   def is_nan; end
 
   # @overload is_inf
@@ -1043,7 +1055,7 @@ class CArray
   #   Applies {#abs} to `self` in place, keeping `self`'s
   #   `data_type`.
   #   @return [self]
-  #   @raise [RuntimeError] for a boolean array.
+  #   @raise [CArray::DataTypeError] for a boolean array.
   def abs!; end
 
   # @overload abs_i!
@@ -1093,7 +1105,7 @@ class CArray
   #   Applies {#arg} to `self` in place, keeping `self`'s
   #   `data_type`.
   #   @return [self]
-  #   @raise [RuntimeError] for an integer or boolean array, whose
+  #   @raise [CArray::DataTypeError] for an integer or boolean array, whose
   #     `data_type` cannot hold the widened result -- {#arg} promotes it
   #     instead of raising.
   def arg!; end

data/yard-stubs/carray_median_percentile.rb

@@ -9,9 +9,11 @@ class CArray
   #   Returns the median of `self` along `axis` (or over all elements
   #   when `axis` is `nil`).
   #
-  #   Numeric arrays return a `Float`; `CA_OBJECT` arrays return the
-  #   result of Ruby `+` / `/` on the stored objects. Fixlen arrays
-  #   raise, since no numeric midpoint is defined.
+  #   Numeric arrays return a `Float`. A `CA_OBJECT` array answers in
+  #   its elements' own terms: the middle element itself, or the
+  #   average of two as `(lo + hi) * (1/2)`, so an Integer, Rational or
+  #   BigDecimal median is exact (`CA_OBJECT([1, 2]).median` is `3/2`).
+  #   Fixlen arrays raise, since no numeric midpoint is defined.
   #
   #   An even number of elements has no middle one, only the average of
   #   two -- so an object array whose elements cannot be averaged (a
@@ -64,9 +66,11 @@ class CArray
   #   so only when the requested `p` actually falls between two
   #   elements (`percentile(50)` of five Strings still answers).
   #
-  #   Numeric arrays produce `Float` results; `CA_OBJECT` arrays
-  #   apply Ruby `+` / `/` / `*` on the stored objects. Fixlen
-  #   arrays raise.
+  #   Numeric arrays produce `Float` results. A `CA_OBJECT` array
+  #   answers in its elements' own terms: a pick (`:lower`, `:higher`,
+  #   `:nearest`) is the element itself, and `:linear` / `:midpoint`
+  #   use the elements' arithmetic with an exact Rational weight, so an
+  #   exact element gives an exact answer. Fixlen arrays raise.
   #
   #   Masking, `min_count`, `fill_value`, and `keep_axis` follow the
   #   same rules as {#median}.