carray 3.0.3 → 3.0.5

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

@@ -27,6 +27,13 @@ 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.
+  #
+  #   On a Face the data slot is read through the Face. A {CACategorical}
+  #   cell excluded by the sentinel code has no label, so its value reads
+  #   as `nil` (the codes are in `codes`).
   #   @return [CArray]
   def value; end
 
@@ -35,6 +42,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 +55,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.
@@ -91,7 +109,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
@@ -162,8 +184,11 @@ class CArray
   #   of `self` and the masks of each array in `others`. Mutates
   #   `self`.
   #   @param others [Array<CArray>] arrays whose mask states are
-  #     OR-ed into `self`. Non-CArray arguments are ignored.
+  #     OR-ed into `self`.
   #   @return [self]
+  #   @raise [ArgumentError] if an array in `others` other than a scalar
+  #     has a different number of elements from `self`.
+  #   @raise [TypeError] if an argument is not a CArray.
   def inherit_mask(*others); end
 
   # @overload inherit_mask_replace(*others)
@@ -173,6 +198,8 @@ 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 a different number of elements from `self`.
   def inherit_mask_replace(*others); end
 
   # @overload count_masked
@@ -226,7 +253,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

@@ -11,6 +11,11 @@
 # builds a node in the expression tree instead of evaluating, and the
 # eager and lazy paths are required to agree element for element.
 #
+# The transcendental functions call the platform's C math library, so
+# their last bits, and the complex functions' answers at special values
+# (signed zeros, infinities, NaN), follow that library and can differ
+# between operating systems.
+#
 # See yard-stubs/README.md and yard-stubs/STYLE.md.
 
 class CArray
@@ -125,7 +130,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:
@@ -572,6 +603,8 @@ class CArray
   #   Returns each element of `self` with the magnitude it already has
   #   and the sign of the matching element of `other`. The sign of a
   #   zero is respected, so `copysign` distinguishes `-0.0` from `0.0`.
+  #   The sign of a NaN that a computation produced (`sqrt(-1)`,
+  #   `Inf * 0`) depends on the CPU: x86 sets it, ARM does not.
   #   Accepts float and `:object` arrays only, as {#atan2}.
   #   @param other [CArray, Numeric] sign source, broadcast to
   #     `self.shape`.
@@ -657,8 +690,8 @@ class CArray
   # @overload pmax(other)
   #   Returns the element-wise larger of `self` and `other`, ignoring
   #   `NaN`: where one element is `NaN` the other is returned, and only
-  #   two `NaN`s give `NaN`. This is C's `fmax`. For the form that lets
-  #   a `NaN` win see {#maximum}.
+  #   two `NaN`s give `NaN`. Of `-0.0` and `0.0` the result is `0.0`,
+  #   in either order. For the form that lets a `NaN` win see {#maximum}.
   #   @param other [CArray, Numeric] the other operand, broadcast to
   #     `self.shape`.
   #   @return [CArray] result of the promoted `data_type` of the two
@@ -671,7 +704,8 @@ class CArray
 
   # @overload pmin(other)
   #   Returns the element-wise smaller of `self` and `other`, ignoring
-  #   `NaN`. The counterpart of {#pmax}.
+  #   `NaN`. Of `-0.0` and `0.0` the result is `-0.0`, in either order.
+  #   The counterpart of {#pmax}.
   #   @param other [CArray, Numeric] the other operand.
   #   @return [CArray]
   #   @raise [CArray::DataTypeError] for a complex array.
@@ -903,7 +937,9 @@ class CArray
   # @overload signbit
   #   Returns a boolean array that is true where an element carries a
   #   negative sign bit. A negative zero is true, which distinguishes
-  #   `-0.0` from `0.0` where a `< 0` comparison cannot.
+  #   `-0.0` from `0.0` where a `< 0` comparison cannot. On a NaN that a
+  #   computation produced (`sqrt(-1)`, `Inf * 0`) the answer depends on
+  #   the CPU: x86 sets the sign bit, ARM does not.
   #   @return [CArray] `:boolean`.
   #   @raise [CArray::DataTypeError] for a complex array.
   #   @example

data/yard-stubs/carray_median_percentile.rb

@@ -27,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
@@ -47,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.
   #

data/yard-stubs/carray_memory_view.rb

@@ -7,13 +7,14 @@ class CArray
     # @!group MemoryView interop
 
     # @overload memory_view_available?(obj)
-    #   Returns `true` if `obj` exposes the Ruby `rb_memory_view`
-    #   protocol and a view can be acquired from it. Lightweight probe
-    #   used to gate {.from_memory_view} / {.wrap_memory_view} calls.
+    #   Returns `true` if `obj` is a MemoryView producer (Ruby's
+    #   `rb_memory_view_available_p`). Lightweight probe used to gate
+    #   {.from_memory_view} / {.wrap_memory_view} calls; it does not
+    #   acquire a view.
     #
-    #   Returning `true` does not guarantee acquisition will succeed —
-    #   a producer may still refuse a particular flag combination at
-    #   acquisition time.
+    #   Returning `true` does not guarantee the import succeeds — the
+    #   producer may still refuse the view, or offer a format CArray
+    #   does not read.
     #   @param obj [Object] any object (typically a foreign array such
     #     as `Numo::NArray`, `Arrow::Array`, a `bytearray`, or a
     #     CArray).
@@ -26,6 +27,7 @@ class CArray
     # @overload memory_view_reject_reason(obj)
     #   Returns a String explaining why CArray's MemoryView producer
     #   refuses to export `obj`, or `nil` if no problem is detected.
+    #   For an object that is not a CArray it returns `nil`.
     #
     #   Diagnostic only; useful when {.memory_view_available?} returns
     #   `false` on a CArray and the generic "memory view not available"
@@ -34,8 +36,8 @@ class CArray
     #   (mask propagation, non-contiguous strided view, etc.) call this
     #   to print a human-readable reason.
     #   @param obj [Object]
-    #   @return [String, nil] reason text, or `nil` when acquisition
-    #     would succeed.
+    #   @return [String, nil] reason text, or `nil` when the export
+    #     would succeed or `obj` is not a CArray.
     def memory_view_reject_reason(obj); end
 
     # @overload from_memory_view(src, data_type: nil, mask: nil)
@@ -46,15 +48,20 @@ class CArray
     #
     #   For typeless producers (format `nil`, e.g. byte blobs from
     #   `IO#read`), `data_type:` is required and the byte buffer is
-    #   reinterpreted as that data type with `ndim = 1`. For typed
+    #   reinterpreted as that data type with `ndim = 1`; a typeless
+    #   producer whose own layout is strided is refused. For typed
     #   producers `data_type:` is optional; when given it must match
     #   the producer's format.
     #
     #   `mask:` accepts a paired buffer-protocol source whose shape
-    #   matches `src` and whose item size is 1 (PEP 3118 `?` / `B` /
-    #   `b`). The mask bytes are copied into the canonical
+    #   matches `src` and whose item size is 1 (`?` / `B` / `C` /
+    #   `b` / `c`). The mask bytes are copied into the canonical
     #   `CA_BOOLEAN` mask slot with non-zero coerced to `1`. The copy
-    #   is independent of both buffers after the call.
+    #   is independent of both buffers after the call. A boolean
+    #   producer's bytes other than 0 and 1 are read as true.
+    #
+    #   The result is a plain `CArray` whatever the receiver; a
+    #   receiver other than `CArray` or a `CAWrap` raises `TypeError`.
     #   @param src [Object] any MemoryView producer.
     #   @param data_type [Symbol, Integer, Class, nil] target data
     #     type. Required for typeless producers; optional (must match
@@ -63,7 +70,11 @@ class CArray
     #     source. Must match `src.shape` and use a 1-byte/element
     #     format.
     #   @return [CArray] independent copy; not a `CAWrap`.
+    #   @raise [TypeError] if the receiver is neither `CArray` nor a
+    #     `CAWrap`.
     #   @raise [ArgumentError] if `src` is not a MemoryView producer,
+    #     if its shape is negative, too large, or does not fit in the
+    #     bytes it reports,
     #     if `data_type:` is missing for a typeless source, if
     #     `data_type:` conflicts with the producer's format, or if
     #     the supplied `mask:` fails shape / data type / contiguity
@@ -92,19 +103,23 @@ class CArray
     #   when the wrap is garbage-collected.
     #
     #   Contiguous typed producers return a `CAWrap`. Strided typed
-    #   producers return a `CAStride` layered on an inner `CAWrap` of
-    #   the producer's first byte, preserving the full stride pattern
+    #   producers return a `CAStride` over a byte `CAWrap` of the
+    #   bytes its elements reach, preserving the full stride pattern
     #   (including negative strides where the producer offers them).
     #   Typeless producers (format `nil`) require `data_type:` and are
-    #   reinterpreted with `ndim = 1`.
+    #   reinterpreted with `ndim = 1`; a strided typeless producer is
+    #   refused. A boolean producer must hold 0 or 1 in every byte.
     #
     #   `mask:` accepts a paired buffer-protocol source whose shape
-    #   matches `src` and whose item size is 1 (PEP 3118 `?` / `B` /
-    #   `b`). The mask buffer is borrowed; writes to either side
-    #   propagate, and the mask MemoryView is released when the wrap
-    #   is collected. In this release, `mask:` requires a row-major
-    #   contiguous data source and a row-major contiguous mask
-    #   buffer.
+    #   matches `src` and whose item size is 1 (`?` / `B` / `C` /
+    #   `b` / `c`), holding 0 or 1 in every byte. The mask buffer is
+    #   borrowed; writes to either side propagate, and the mask
+    #   MemoryView is released when the wrap is collected. In this
+    #   release, `mask:` requires a row-major contiguous data source
+    #   and a row-major contiguous mask buffer that shares no bytes
+    #   with the data. A read-only mask makes the whole array
+    #   read-only, since a store writes the mask cell of each element
+    #   it stores.
     #
     #   The receiver picks the class of the result. Called on `CArray`
     #   it builds a `CAWrap`; called on a subclass of `CAWrap` it
@@ -132,10 +147,12 @@ class CArray
     #   @raise [TypeError] if the receiver is neither `CArray` nor a
     #     subclass of `CAWrap`.
     #   @raise [ArgumentError] if `src` is not a MemoryView producer,
-    #     if `data_type:` is missing for a typeless source, if
+    #     if its shape is negative, too large, or does not fit in the
+    #     bytes it reports, if a boolean buffer holds a byte other than
+    #     0 and 1, if `data_type:` is missing for a typeless source, if
     #     `data_type:` conflicts with the producer's format, or if
     #     the supplied `mask:` fails validation (shape / ndim /
-    #     data type / item_size / contiguity). Also raises when `mask:`
+    #     data type / item_size / contiguity / overlap with the data). Also raises when `mask:`
     #     is combined with a strided data source — that combination
     #     is not supported in this release.
     #   @example Zero-copy write propagation

data/yard-stubs/carray_order.rb

@@ -12,16 +12,15 @@ class CArray
   #
   #   Out-of-range positions are filled with `lval` (below-range) and
   #   `uval` (above-range); when `lval` is given alone, it fills
-  #   both. Without either, out-of-range positions are masked.
+  #   both. Without either, out-of-range positions are masked, and so
+  #   they are with a fill of `UNDEF`.
   #
   #   When `self` is a Face (CATime / CATimedelta / CACategorical),
-  #   the result is the same Face type, carrying the unit / labels; the
-  #   gather runs on the underlying storage and misses become UNDEF. Fill
-  #   (`lval` / `uval`) is not supported for a Face and raises ArgumentError
-  #   — omit the fill args to get UNDEF at misses.
+  #   the result is the same Face type, carrying the unit / labels, and a
+  #   fill is one of its values (a time for a CATime).
   #   @param idx [CArray] flat addresses, of any shape.
-  #   @param lval [Object, nil] fill for indices `< 0` (non-Face only).
-  #   @param uval [Object, nil] fill for indices `>= self.elements` (non-Face only).
+  #   @param lval [Object, nil] fill for indices `< 0`.
+  #   @param uval [Object, nil] fill for indices `>= self.elements`.
   #   @return [CArray] a fresh array shaped like `idx`; a Face of the same
   #     type when `self` is a Face.
   #   @raise [ArgumentError] if `lval` / `uval` is given and `self` is a Face.
@@ -97,17 +96,19 @@ class CArray
   #   `method:` selects how ties are ranked:
   #
   #   - `:ordinal` (default) — every cell gets a distinct rank; ties
-  #     are broken by original position (stable). This is a total
-  #     order: no two cells ever compare equal.
-  #   - `:dense` — tied values share one rank (no gaps). Useful as a
-  #     `sort_addr` priority key: an `:ordinal` key never ties, so a
-  #     lower-priority key after it is never consulted; a `:dense` key
+  #     are broken by original position (stable), the earlier cell first
+  #     in both directions. This is a total order: no two cells ever
+  #     compare equal.
+  #   - `:dense` — tied values share one rank (no gaps). Every NaN is
+  #     one value and shares one rank, placed after the numbers. Useful
+  #     as a `sort_addr` priority key: an `:ordinal` key never ties, so
+  #     a lower-priority key after it is never consulted; a `:dense` key
   #     preserves the tie so it is.
   #
-  #   `descending:` negates the rank order (`(n-1) - rank`, `n` =
-  #   fiber element count minus masked cells). This composes correctly
-  #   with `method: :dense`: ties stay tied after the transform, and
-  #   group-to-group order still reverses.
+  #   `descending:` ranks the largest value `0`; NaN comes after the
+  #   numbers in both directions. Tied cells keep their
+  #   original order under `:ordinal` and share a rank under `:dense`, so
+  #   dense ranks stay without gaps.
   #
   #   Masked cells are excluded from ranking (own cell becomes UNDEF,
   #   like `rank_index`); `descending:`/`method:` apply to the
@@ -127,7 +128,8 @@ class CArray
 
   # @overload bsearch(val)
   #   Returns the flat address of `val` in `self` via binary search.
-  #   `self` must be sorted along its single (flat) axis. Returns
+  #   `self` must be sorted along its single (flat) axis. Of several
+  #   equal cells, the first one's address is returned. Returns
   #   `nil` if `val` is not present. When `val` is a CArray, returns
   #   a CArray of `:int64` addresses (one per element of `val`),
   #   with `UNDEF` at positions where the value is not present.
@@ -158,16 +160,27 @@ class CArray
   # @overload search(val, eps = nil)
   #   Returns the flat address of the first element of `self` equal
   #   to `val`. For float types, `eps` (default machine epsilon)
-  #   sets the tolerance. Returns `nil` if no match.
+  #   sets the tolerance; a negative or NaN `eps` raises
+  #   `ArgumentError`. Returns `nil` if no match.
   #
   #   `val` is compared in the type both share, as `self.eq(val)`
   #   compares: an integer array searched with a Float is compared in
-  #   float64 (so `3.9` does not match `3`, and `eps` applies), and an
-  #   Integer that does not fit an integer array raises `RangeError`.
+  #   float64 (so `3.9` does not match `3`, and `eps` applies), a pair of
+  #   mixed sign is compared by value (`-1` does not find `255`), and an
+  #   Integer an integer array cannot hold matches nothing.
   #   The same holds for {#bsearch} and {#search_nearest}. On an
   #   `:object` array a cell matches when it is `==` to `val`, as {#eq}
   #   compares (so `1` matches `1.0`, which {#is_in} does not).
   #
+  #   An `UNDEF` `val`, or a masked cell of a CArray `val`, finds
+  #   nothing: `nil`, or `UNDEF` in that cell of the result.  The same
+  #   holds for {#bsearch} and {#search_nearest}.
+  #
+  #   A time array (`CATime`, `CATimedelta`) takes a value of another
+  #   unit, a `Time` or a String: when it is off the array's grid the
+  #   two are compared in the finer unit, so it matches nothing (and
+  #   {#search_nearest} finds the nearest cell).
+  #
   #   `self` need not be sorted; this is a linear scan. For sorted
   #   data prefer {#bsearch}.
   #   @param val [Object]
@@ -190,7 +203,10 @@ class CArray
 
   # @overload search_nearest(val)
   #   Returns the flat address of the element of `self` whose value
-  #   is closest to `val`.
+  #   is closest to `val`. Of several equally close elements, the one
+  #   at the lowest address wins, as {#search} answers the first match
+  #   (`[0, 2, 4].search_nearest(1)` is 0). {#locate_nearest_addr}
+  #   rounds a position instead, and answers the larger value on a tie.
   #
   #   In an `:object` array the distance is `val.distance(other)` when
   #   `val` answers `#distance`, and `(val - other).abs` when it is a
@@ -257,7 +273,9 @@ class CArray
   #   `self` is coerced to `:float64` if it is not already. When
   #   `axis: nil`, `self` is flattened to 1-D first.
   #
-  #   Out-of-range `addr` returns NaN.
+  #   A position with no answer -- out of range, or between samples one
+  #   of which is NaN -- gives `nil` for a scalar `addr` and NaN in the
+  #   cell of an array result.
   #
   #   Because this half of the pair returns a *value* rather than a
   #   position, a Face axis gets its Face back: `CATime#linear_fetch` /
@@ -269,5 +287,94 @@ class CArray
   #   @see file:docs/topics/LinearInterpolation.md
   def linear_fetch(addr, axis: nil); end
 
+  # @overload nlargest(n, axis: nil)
+  #   Returns the `n` largest values, largest first. Without `axis:` the
+  #   array is read flat; with it, each fiber along `axis` gives its own
+  #   `n` and the axis keeps length `n`. A NaN and a masked cell lose to
+  #   every value; when fewer cells remain than `n`, the result is
+  #   shorter (or, per fiber, ends in UNDEF).
+  #   @param n [Integer] how many values, 0 or more.
+  #   @param axis [Integer, nil]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `n` is negative.
+  def nlargest(n, axis: nil); end
+
+  # @overload nsmallest(n, axis: nil)
+  #   Returns the `n` smallest values, smallest first. As {#nlargest}
+  #   otherwise.
+  #   @param n [Integer]
+  #   @param axis [Integer, nil]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `n` is negative.
+  def nsmallest(n, axis: nil); end
+
+  # @overload nlargest_index(n, axis:)
+  #   Returns, along `axis`, the axis-local positions of each fiber's `n`
+  #   largest values, largest first (`take_along_axis` reads the values
+  #   back). `axis:` is required.
+  #   @param n [Integer]
+  #   @param axis [Integer]
+  #   @return [CArray] `:int64` positions.
+  #   @raise [ArgumentError] when `axis:` is missing or `n` is negative.
+  def nlargest_index(n, axis:); end
+
+  # @overload nsmallest_index(n, axis:)
+  #   As {#nlargest_index}, for the `n` smallest values.
+  #   @param n [Integer]
+  #   @param axis [Integer]
+  #   @return [CArray] `:int64` positions.
+  #   @raise [ArgumentError] when `axis:` is missing or `n` is negative.
+  def nsmallest_index(n, axis:); end
+
+  # @overload sort_by_key(key, axis: 0)
+  #   Returns `self` reordered along `axis` by the order of `key` (an
+  #   array of `self`'s shape): `self[key.sort_addr(axis:)]`.
+  #   @param key [CArray] the values to order by.
+  #   @param axis [Integer]
+  #   @return [CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def sort_by_key(key, axis: 0); end
+
+  # @overload max_by_key(key, axis: nil)
+  #   Returns the value of `self` where `key` is largest: one value, or
+  #   one per fiber along `axis`. UNDEF where there is no cell to compare.
+  #   @param key [CArray] the values to compare, of `self`'s shape.
+  #   @param axis [Integer, nil]
+  #   @return [Object, CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def max_by_key(key, axis: nil); end
+
+  # @overload min_by_key(key, axis: nil)
+  #   As {#max_by_key}, where `key` is smallest.
+  #   @param key [CArray]
+  #   @param axis [Integer, nil]
+  #   @return [Object, CArray]
+  #   @raise [ArgumentError] when `key`'s shape differs from `self`'s.
+  def min_by_key(key, axis: nil); end
+
+  # @overload take_along_axis(indices, axis: 0)
+  #   Returns the values of `self` at axis-local `indices` along `axis`
+  #   (`indices` has `self`'s shape except along `axis`), as the
+  #   `*_index(axis:)` methods answer them. A masked index reads UNDEF.
+  #   @param indices [CArray] integer positions along `axis`.
+  #   @param axis [Integer]
+  #   @return [CArray]
+  def take_along_axis(indices, axis: 0); end
+
+  # @overload put_along_axis(indices, values, axis: 0)
+  #   Writes `values` into `self` at axis-local `indices` along `axis`,
+  #   the inverse of {#take_along_axis}. A masked index writes nothing.
+  #   @param indices [CArray] integer positions along `axis`.
+  #   @param values [CArray, Object]
+  #   @param axis [Integer]
+  #   @return [self]
+  def put_along_axis(indices, values, axis: 0); end
+
+  # @overload range
+  #   Returns `min..max` of `self` from one pass (`UNDEF..UNDEF` when no
+  #   cell takes part).
+  #   @return [Range]
+  def range; end
+
   # @!endgroup
 end

data/yard-stubs/carray_random.rb

@@ -24,7 +24,10 @@ class CArray
   #   Fills `self` with uniform random numbers in-place and returns
   #   `self`.  Boolean arrays fill 0/1 at 50% probability, ignoring
   #   any range argument.  Complex arrays sample real and imaginary
-  #   parts independently from the same range.
+  #   parts independently from the same range.  An integer array takes
+  #   Integer bounds whose every value fits its type (the whole range
+  #   of the type included); a float array takes finite bounds.  Every
+  #   cell gets a value, so the mask is cleared, as by `seq!` or `fill`.
   #
   #   @param low [Numeric] lower bound (inclusive).
   #   @param high [Numeric] upper bound (exclusive).
@@ -35,7 +38,11 @@ class CArray
   #   @raise [CArray::DataTypeError] for `:object` / `:fixlen` arrays.
   #   @raise [ArgumentError] when an integer array is called with no
   #     range, when `low >= high`, when a Range is combined with a
-  #     second positional argument, or when a Range endpoint is nil.
+  #     second positional argument, when a Range endpoint is nil, or
+  #     when a float bound is NaN or infinite.
+  #   @raise [TypeError] when an integer array is given a non-Integer
+  #     bound.
+  #   @raise [RangeError] when the integer range does not fit the type.
   def random!(*args, rng: nil); end
 
   # @overload random(rng: nil)
@@ -51,7 +58,7 @@ class CArray
   #   Fills `self` with standard normal `N(0, 1)` samples via
   #   Box-Muller and returns `self`. Restricted to float / complex
   #   data types; complex fills real and imaginary parts as two
-  #   independent normals per cell.
+  #   independent normals per cell.  The mask is cleared.
   #   @param rng [Random, nil] RNG instance; nil uses the per-ractor
   #     default RNG.
   #   @return [self]
@@ -72,7 +79,9 @@ class CArray
   #   Fisher-Yates permutes `self` in-place and returns `self`.
   #   Without `axis:`, shuffles all cells as if flattened. With
   #   `axis:`, permutes slices along that axis (the trailing
-  #   sub-slab is treated as a byte chunk and swapped whole).
+  #   sub-slab is treated as a byte chunk and swapped whole). The mask
+  #   moves with the values: a masked cell stays masked wherever it
+  #   lands.
   #   @param axis [Integer, nil] axis to permute along; nil = flat.
   #   @param rng [Random, nil] RNG instance; nil uses the per-ractor
   #     default RNG.