carray 3.0.2 → 3.0.4

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,17 +64,19 @@ 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
   #   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_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).
+  #     `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)

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

@@ -27,6 +27,9 @@ class CArray
   #   mask (`value_array? == true`).
   #
   #   Use this to read or write the data slot of masked elements.
+  #   Nothing in a value array is masked, so `unmask` on it does nothing,
+  #   while a write that would mask a cell (`UNDEF`, `mask=`,
+  #   `invert_mask`) raises TypeError.
   #   @return [CArray]
   def value; end
 
@@ -35,6 +38,11 @@ class CArray
   #   element is `1` where `self` is masked and `0` where it is not.
   #   The returned view itself cannot carry a mask.
   #
+  #   The mask of a view is a view over its parent's mask: it follows
+  #   later changes to the parent's mask, and so does its `dup` or
+  #   `clone`, which is another view onto the same parent mask (a write
+  #   to it lands in the parent's mask). Use `copy` for a mask of its own.
+  #
   #   Returns `0` (Integer) if `self` has no mask array attached.
   #   @return [CArray, Integer]
   def mask; end
@@ -43,6 +51,12 @@ class CArray
   #   Sets the mask array of `self` to `new_mask`. Allocates the mask
   #   array first if `self` does not yet have one. Cannot be called on
   #   a value array or a mask array.
+  #
+  #   `mask=` replaces the whole mask with `new_mask`. A masked cell of
+  #   `new_mask` makes the cell masked, as a masked value does in any
+  #   store. To mask the cells where a condition holds, prefer
+  #   `self[cond] = UNDEF`. There a masked cell of `cond` selects nothing,
+  #   as it does in any index.
   #   @param new_mask [CArray, Boolean, Integer] mask values. A
   #     non-CArray value is broadcast and stored elementwise; a CArray
   #     of any type is coerced to boolean.
@@ -74,7 +88,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
@@ -90,7 +105,11 @@ class CArray
   #     linearly by index from the two bracketing valid cells (numeric
   #     data_type, or a time Face — `CATime` / `CATimedelta` interpolate
   #     through their own `linear_fetch`, so the filled values stay on the
-  #     array's unit and are rounded to it).
+  #     array's unit and are rounded to it). An integer array takes the
+  #     nearest integer, half away from zero (`[190, _, _, 341]` fills
+  #     `240, 291`). The interpolation runs in float64, so in an int64
+  #     array with values beyond 2**53 the filled cells may be off by the
+  #     float64 spacing there; the valid cells are not touched.
   #   @param axis [Integer, nil] scan axis (single axis). `nil` flattens.
   #   @return [self]
   def unmask(*, method: nil, axis: nil); end
@@ -106,7 +125,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 +171,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)
@@ -160,6 +182,8 @@ class CArray
   #   @param others [Array<CArray>] arrays whose mask states are
   #     OR-ed into `self`. Non-CArray arguments are ignored.
   #   @return [self]
+  #   @raise [ArgumentError] if an array in `others` other than a scalar
+  #     has fewer elements than `self`.
   def inherit_mask(*others); end
 
   # @overload inherit_mask_replace(*others)
@@ -169,28 +193,50 @@ class CArray
   #   @param others [Array<CArray>] arrays whose mask states form the
   #     new mask of `self`.
   #   @return [self]
+  #   @raise [ArgumentError] if an array in `others` other than a scalar
+  #     has fewer elements than `self`.
   def inherit_mask_replace(*others); end
 
   # @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
@@ -202,7 +248,9 @@ class CArray
   #   In-place equivalent: `ca[:eq, v] = UNDEF`.
   #
   #   Replaces the removed `maskout(v)` from 2.x.
-  #   @param v [Object] value to mask. Cast to `self.data_type`.
+  #   `v` is compared as {#eq} compares it, by value: `1.5` masks nothing
+  #   in an integer array, and `-1` does not mask `255` in a `uint8` one.
+  #   @param v [Object] value to mask.
   #   @return [CArray]
   def mask_eq(v); end
 

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 ]
@@ -122,7 +125,33 @@ class CArray
   #   keeps its sign.  Masked elements stay masked.  An `:object`
   #   array delegates to each element's `#round`.
   #   @return [CArray] same `data_type` as `self`.
-  def round; end
+  # @overload round(ndigits)
+  #   Returns a new array with each element rounded to `ndigits` decimal
+  #   digits, to the value Ruby's `Float#round(ndigits)` gives for a float
+  #   element and `Integer#round(ndigits)` for an integer one, half away
+  #   from zero: `CA_FLOAT64([1.005, 2.675]).round(2)` is `[1.01, 2.68]`,
+  #   as `1.005.round(2)` and `2.675.round(2)` are.  A negative `ndigits`
+  #   rounds to tens, hundreds, ...: `CA_INT32([125, -125]).round(-1)` is
+  #   `[130, -130]`.  The result keeps `self`'s `data_type`, so a float
+  #   array stays float for every `ndigits`, and a `:float32` element is
+  #   rounded from its own value.  `NaN` and the infinities are left as
+  #   they are.  Masked elements stay masked.  An `:object` array calls
+  #   each element's `round(ndigits)`.  `round(0)` is `round`.
+  #   @param ndigits [Integer] decimal digits to keep; negative rounds to
+  #     the left of the decimal point.
+  #   @return [CArray] same `data_type` as `self`.
+  #   @raise [TypeError] if `ndigits` is not an Integer.
+  #   @raise [RangeError] if a rounded integer does not fit the
+  #     `data_type` (`CA_INT8([125]).round(-1)`).
+  #   @raise [CArray::DataTypeError] for a complex or fixed-length array.
+  def round(ndigits = nil); end
+
+  # @overload round!(ndigits = nil)
+  #   Rounds `self` in place, as {#round} does.  A boolean array can not
+  #   hold the rounded values and raises when `ndigits` is given.
+  #   @param ndigits [Integer, nil] decimal digits to keep.
+  #   @return [self]
+  def round!(ndigits = nil); end
 
   # @overload frac
   #   Returns a new array of the fractional part of each element:
@@ -215,7 +244,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 +270,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 +767,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 +790,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 +896,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 +1081,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 +1131,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
@@ -25,7 +27,9 @@ class CArray
   #   `UNDEF` when `fill_value` is `nil`).
   #
   #   With `keep_axis: true`, the reduced axis is retained with
-  #   length 1 rather than dropped.
+  #   length 1 rather than dropped. Along the only axis of a 1-D array
+  #   the result is a bare value, as `sum(axis: 0)` is (a one-cell array
+  #   with `keep_axis: true`).
   #   @param axis [Integer, nil]
   #   @param min_count [Integer] minimum not-masked count required.
   #   @param fill_value [Object, nil] replacement when the not-masked
@@ -45,7 +49,8 @@ class CArray
   #   `p` may be given as individual positional arguments, a single
   #   `Array<Numeric>`, or a single 1-D `CArray`. When the effective
   #   `p` count (after flattening) is 1, the result is unwrapped:
-  #   flat form returns a `Float`, per-axis form returns a `CArray`.
+  #   flat form returns a `Float`, per-axis form returns a `CArray`
+  #   (a bare value along the only axis of a 1-D array, as {#median}).
   #   With 2 or more `p` values the result is an `Array` whose length
   #   matches the number of requested `p` values.
   #
@@ -64,9 +69,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}.