carray 3.0.0 → 3.0.2

data/yard-stubs/carray_mathfunc.rb

@@ -0,0 +1,45 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for the CAMath module functions defined in
+# ext/carray_mathfunc.c.  Most CAMath entries (atan2 / hypot / expm1
+# / log1p / copysign / logaddexp / nextafter / fmod / min / max) live
+# in lib/carray/math.rb and are documented at the source.  This file
+# covers only the C-defined module functions.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Namespace for math module functions that operate on CArray (and
+# auto-wrappable scalar) inputs.
+module CAMath
+  module_function
+
+  # @overload spherical_to_xyz(r, theta, phi)
+  #   Returns three CArrays `[x, y, z]` of cartesian coordinates
+  #   converted from spherical coordinates.  All inputs are coerced
+  #   to `:float64`; outputs are `:float64`.
+  #
+  #   `theta` is the polar angle from the `+z` axis in radians;
+  #   `phi` is the azimuthal angle in the `xy` plane in radians.
+  #   @param r [CArray, Numeric] radial distance.
+  #   @param theta [CArray, Numeric] polar angle (radians).
+  #   @param phi [CArray, Numeric] azimuthal angle (radians).
+  #   @return [Array<CArray>] `[x, y, z]`.
+  def spherical_to_xyz(r, theta, phi); end
+
+  # @overload xyz_to_spherical(x, y, z)
+  #   Returns three CArrays `[r, theta, phi]` of spherical
+  #   coordinates converted from cartesian coordinates.  All inputs
+  #   are coerced to `:float64`; outputs are `:float64`.
+  #   @param x [CArray, Numeric]
+  #   @param y [CArray, Numeric]
+  #   @param z [CArray, Numeric]
+  #   @return [Array<CArray>] `[r, theta, phi]`.
+  #   @raise [RuntimeError] when the build lacks `atan2`.
+  def xyz_to_spherical(x, y, z); end
+
+  # @overload lgamma(x)
+  #   Returns a `:float64` CArray of `log(|Γ(x)|)` for each element of
+  #   `x`.  `x` is coerced to `:float64`.
+  #   @param x [CArray, Numeric]
+  #   @return [CArray]
+  #   @raise [RuntimeError] when the build lacks `lgamma`.
+  def lgamma(x); end
+end

data/yard-stubs/carray_median_percentile.rb

@@ -0,0 +1,103 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_median_percentile.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Statistics
+
+  # @overload median(axis: nil, min_count: 0, fill_value: nil, keep_axis: false)
+  #   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.
+  #
+  #   An even number of elements has no middle one, only the average of
+  #   two -- so an object array whose elements cannot be averaged (a
+  #   column of Strings) has a median at odd length and raises at even.
+  #   `percentile(50, method: :lower)` names an element either way.
+  #
+  #   Masked cells are excluded. Per-axis, each fiber uses only its own
+  #   present values; a fully masked fiber reduces to `UNDEF`. If the
+  #   count of not-masked cells (per fiber, or over all elements in the
+  #   flat form) is below `min_count`, that cell is `fill_value` (or
+  #   `UNDEF` when `fill_value` is `nil`).
+  #
+  #   With `keep_axis: true`, the reduced axis is retained with
+  #   length 1 rather than dropped.
+  #   @param axis [Integer, nil]
+  #   @param min_count [Integer] minimum not-masked count required.
+  #   @param fill_value [Object, nil] replacement when the not-masked
+  #     count is below `min_count`.
+  #   @param keep_axis [Boolean]
+  #   @return [Float, CArray, Object]
+  #   @raise [CArray::DataTypeError] for fixlen data_type, or for an even
+  #     number of elements whose objects cannot be averaged.
+  #   @raise [ArgumentError] on negative `min_count`.
+  def median(*); end
+
+  # @overload percentile(*p, axis: nil, min_count: 0, fill_value: nil,
+  #                      method: :linear, keep_axis: false)
+  #   Returns percentile values at each `p` (each in `[0, 100]`)
+  #   along `axis` or over all elements.
+  #
+  #   `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`.
+  #   With 2 or more `p` values the result is an `Array` whose length
+  #   matches the number of requested `p` values.
+  #
+  #   `method` picks the interpolation rule between adjacent order
+  #   statistics:
+  #
+  #   - `:linear` (default) — linear interpolation.
+  #   - `:lower` — floor to the smaller neighbor.
+  #   - `:higher` — ceil to the larger neighbor.
+  #   - `:nearest` — round-half-to-even to the nearer neighbor.
+  #   - `:midpoint` — arithmetic mean of the two neighbors.
+  #
+  #   The first three pick an element and the last two compute one, so
+  #   only the first three apply to a `CA_OBJECT` array whose elements
+  #   have no arithmetic: `:linear` and `:midpoint` raise there, and do
+  #   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.
+  #
+  #   Masking, `min_count`, `fill_value`, and `keep_axis` follow the
+  #   same rules as {#median}.
+  #   @param p [Numeric, Array<Numeric>, CArray] percentile targets in
+  #     `[0, 100]`.
+  #   @param axis [Integer, nil]
+  #   @param min_count [Integer]
+  #   @param fill_value [Object, nil]
+  #   @param method [Symbol] one of `:linear`, `:lower`, `:higher`,
+  #     `:nearest`, `:midpoint`.
+  #   @param keep_axis [Boolean]
+  #   @return [Float, CArray, Object, Array<Float>, Array<CArray>, Array<Object>]
+  #   @raise [CArray::DataTypeError] for fixlen data_type, or when an
+  #     interpolating `method` is asked to interpolate between objects
+  #     that have no arithmetic.
+  #   @raise [ArgumentError] on empty `p` list, `p` outside `[0, 100]`,
+  #     empty axis, unknown `method`, or invalid option combinations.
+  def percentile(*); end
+
+  # @overload quantile(axis: nil, keep_axis: false)
+  #   Returns the five quartile percentiles
+  #   `[p0, p25, p50, p75, p100]` — shorthand for
+  #   `percentile(0, 25, 50, 75, 100, axis: axis, keep_axis: keep_axis)`.
+  #   Accepts no positional arguments. Flat form returns
+  #   `Array<Float>` of length 5; per-axis form returns `Array<CArray>`
+  #   of length 5, each CArray reduced along `axis`.
+  #   @param axis [Integer, nil]
+  #   @param keep_axis [Boolean]
+  #   @return [Array<Float>, Array<CArray>]
+  #   @raise [ArgumentError] on any positional argument.
+  def quantile(*); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_memory_view.rb

@@ -0,0 +1,163 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for singleton methods defined in ext/carray_memory_view.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  class << self
+    # @!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.
+    #
+    #   Returning `true` does not guarantee acquisition will succeed —
+    #   a producer may still refuse a particular flag combination at
+    #   acquisition time.
+    #   @param obj [Object] any object (typically a foreign array such
+    #     as `Numo::NArray`, `Arrow::Array`, a `bytearray`, or a
+    #     CArray).
+    #   @return [Boolean]
+    #   @example
+    #     CArray.memory_view_available?(CArray.int32(3))      # => true
+    #     CArray.memory_view_available?("plain string")        # => false
+    def memory_view_available?(obj); end
+
+    # @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.
+    #
+    #   Diagnostic only; useful when {.memory_view_available?} returns
+    #   `false` on a CArray and the generic "memory view not available"
+    #   error does not say which link in the parent chain caused the
+    #   reject. Consumers that need to debug an alias-chain reject
+    #   (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.
+    def memory_view_reject_reason(obj); end
+
+    # @overload from_memory_view(src, data_type: nil, mask: nil)
+    #   Returns a new `CArray` that owns an independent copy of `src`'s
+    #   buffer. Accepts both contiguous and strided producers; strided
+    #   sources are gathered into a freshly allocated row-major
+    #   buffer.
+    #
+    #   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
+    #   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
+    #   `CA_BOOLEAN` mask slot with non-zero coerced to `1`. The copy
+    #   is independent of both buffers after the call.
+    #   @param src [Object] any MemoryView producer.
+    #   @param data_type [Symbol, Integer, Class, nil] target data
+    #     type. Required for typeless producers; optional (must match
+    #     producer format) for typed ones.
+    #   @param mask [Object, nil] optional paired mask MemoryView
+    #     source. Must match `src.shape` and use a 1-byte/element
+    #     format.
+    #   @return [CArray] independent copy; not a `CAWrap`.
+    #   @raise [ArgumentError] if `src` is not a MemoryView producer,
+    #     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
+    #     validation.
+    #   @example Copy from a strided source
+    #     a = CArray.int32(4, 3).seq
+    #     b = CArray.from_memory_view(a.transpose)
+    #     b.shape    # => [3, 4]
+    #     b.equal?(a)  # => false
+    #   @example Copy paired (data, mask) — independent of source
+    #     data = CArray.uint8(3) { |i| i }
+    #     mask = CArray.boolean(3) { |i| i.zero? ? 1 : 0 }
+    #     c = CArray.from_memory_view(data, mask: mask)
+    #     c.has_mask?   # => true
+    #     data[0] = 99  # source change does not reach c
+    def from_memory_view(src, data_type: nil, mask: nil); end
+
+    # @overload wrap_memory_view(src, data_type: nil, mask: nil)
+    #   Returns a `CAWrap` (or `CAStride` for strided producers) that
+    #   borrows `src`'s buffer zero-copy. Writes through the wrap
+    #   reach the source buffer; external changes to the source are
+    #   visible through the wrap.
+    #
+    #   The borrowed view is kept alive for the lifetime of the
+    #   returned object via internal ivars; the source is released
+    #   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
+    #   (including negative strides where the producer offers them).
+    #   Typeless producers (format `nil`) require `data_type:` and are
+    #   reinterpreted with `ndim = 1`.
+    #
+    #   `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.
+    #
+    #   The receiver picks the class of the result. Called on `CArray`
+    #   it builds a `CAWrap`; called on a subclass of `CAWrap` it
+    #   builds that subclass, so a gem bridging a foreign buffer can
+    #   name where the array came from without writing a C extension.
+    #   Any other receiver raises `TypeError`, and a strided producer
+    #   raises `ArgumentError` when a subclass was asked for, since the
+    #   result would be a `CAStride` rather than the named class.
+    #
+    #   The class marks the provenance of the returned object only. A
+    #   view derived from it is a `CABlock` or a `CAStride` like any
+    #   other — a slice of a borrowed image is no longer that image —
+    #   so do not build an API that expects the class to survive view
+    #   algebra. For semantic identity that does survive it, see
+    #   {file:docs/topics/CAFace.md CAFace}.
+    #   @param src [Object] any MemoryView producer.
+    #   @param data_type [Symbol, Integer, Class, nil] target data
+    #     type, same rules as {.from_memory_view}.
+    #   @param mask [Object, nil] optional paired mask MemoryView
+    #     source.
+    #   @return [CAWrap, CAStride] zero-copy borrowed view of `src`.
+    #     A `CAStride` is returned when `src` is strided (and `mask:`
+    #     is not given); otherwise a `CAWrap`, or the subclass of
+    #     `CAWrap` the method was called on.
+    #   @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
+    #     `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:`
+    #     is combined with a strided data source — that combination
+    #     is not supported in this release.
+    #   @example Zero-copy write propagation
+    #     a = CArray.int32(4).seq
+    #     w = CArray.wrap_memory_view(a)
+    #     w[0] = 999
+    #     a[0]   # => 999
+    #   @example Paired masked wrap
+    #     data = CArray.uint8(3) { |i| i + 10 }
+    #     mask = CArray.boolean(3) { 0 }
+    #     w = CArray.wrap_memory_view(data, mask: mask)
+    #     w[1] = UNDEF      # writes the source mask buffer
+    #     mask[1]           # => 1
+    #   @example Naming where a borrowed buffer came from
+    #     class VipsPixels < CAWrap
+    #       def image ; instance_variable_get(:@vips_image) ; end
+    #     end
+    #     v = VipsPixels.wrap_memory_view(bmv)
+    #     v.class            # => VipsPixels
+    #     v[0..1, nil].class # => CABlock  (the class does not descend)
+    def wrap_memory_view(src, data_type: nil, mask: nil); end
+
+    # @!endgroup
+  end
+end

data/yard-stubs/carray_order.rb

@@ -0,0 +1,252 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_order.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Sorting and searching
+
+  # @overload project(idx, lval = nil, uval = nil)
+  #   Returns a new array whose elements are taken from `self` at
+  #   the positions named by `idx`. `idx` is a CArray of flat
+  #   addresses into `self`; the result has the shape of `idx`.
+  #
+  #   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.
+  #
+  #   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.
+  #   @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).
+  #   @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.
+  def project(idx, lval = nil, uval = nil); end
+
+  # sort / sort_copy stubs live in yard-stubs/carray_sort.rb (same
+  # file split as ext/carray_sort.c <-> ext/carray_order.c).
+
+  # @overload partition(kth, axis: 0, masked_position: :last)
+  #   Returns a `CARemap` view of `self` permuted along `axis` so that
+  #   the element at fiber-local position `kth` is in its final sorted
+  #   place, every element before it is `<=` it, and every element
+  #   after it is `>=` it. Order within the two regions is unspecified.
+  #   Average `O(n)` per fiber via quickselect.
+  #
+  #   Negative `kth` counts from the end of the fiber
+  #   (`-self.shape[axis] <= kth < self.shape[axis]`).
+  #
+  #   Supports numeric (`i8`..`f64`), boolean (as its `0`/`1` value,
+  #   `false` < `true`), `CA_FIXLEN` (memcmp lexicographic order), and
+  #   `CA_OBJECT` (via `<=>` per pair).
+  #
+  #   Mask handling matches {#sort}: masked cells are an incomparable
+  #   sentinel, excluded from the kth-selection and clustered at
+  #   `masked_position:`. A `kth` landing in the masked cluster needs
+  #   no selection (unspecified order, same contract as the `<` / `>`
+  #   regions); a `kth` landing in the unmasked range selects properly
+  #   among unmasked values.
+  #
+  #   @param kth [Integer] target fiber-local position along `axis`.
+  #   @param axis [Integer]
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] `CARemap` view of `self`.
+  #   @raise [ArgumentError] when `kth` is out of range.
+  def partition(kth, axis: 0, masked_position: :last); end
+
+  # @overload partition_copy(kth, axis: 0, masked_position: :last)
+  #   Returns a fresh entity `CArray` with the same shape as `self`,
+  #   partitioned along `axis` by the same rule as {#partition}.
+  #   Bypasses the `CARemap` scatter layer for cases where an entity
+  #   is wanted directly. Same dispatch (numeric / boolean / `CA_FIXLEN` /
+  #   `CA_OBJECT`), same `kth` and `masked_position:` semantics.
+  #   Masked input delegates to {#partition} + copy.
+  #
+  #   Float NaN policy: NaN cells are pre-partitioned to the tail. If
+  #   `kth` falls within the finite slice, quickselect runs over the
+  #   finite cells; otherwise the kth cell is already NaN.
+  #
+  #   @param kth [Integer]
+  #   @param axis [Integer]
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] fresh entity.
+  #   @raise [ArgumentError] same conditions as {#partition}.
+  def partition_copy(kth, axis: 0, masked_position: :last); end
+
+  # @overload order(axis: nil, descending: false, method: :ordinal)
+  #   Returns each cell's rank among the other cells along `axis`
+  #   (`0` = smallest). When `axis` is omitted, `self` is flattened
+  #   first (global rank). Sugar over `rank_index` (built on the
+  #   same sort machinery as `sort_index`); the inverse relationship
+  #   is `self.order == self.sort_index.sort_index`.
+  #
+  #   `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
+  #     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.
+  #
+  #   Masked cells are excluded from ranking (own cell becomes UNDEF,
+  #   like `rank_index`); `descending:`/`method:` apply to the
+  #   remaining unmasked cells.
+  #   @param axis [Integer, nil]
+  #   @param descending [Boolean]
+  #   @param method [Symbol] `:ordinal` (default) or `:dense`.
+  #   @return [CArray] `:int64` ranks, shape == `self.shape`.
+  #   @raise [ArgumentError] when `method:` is neither `:ordinal` nor `:dense`.
+  def order(axis: nil, descending: false, method: :ordinal); end
+
+  # @!endgroup
+
+  # @!group Sorting and searching
+
+  # @overload bsearch(val)
+  #   Returns the flat address of `val` in `self` via binary search.
+  #   `self` must be sorted along its single (flat) axis. 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.
+  #   @param val [Numeric, CArray]
+  #   @return [Integer, CArray, nil]
+  #   @raise [RuntimeError] if `self` has any masked element.
+  # @overload bsearch(val, axis:)
+  #   Per-fiber binary search along `axis`. Returns a CArray of
+  #   axis-local positions, one per fiber.
+  #   @param val [Numeric, CArray]
+  #   @param axis [Integer]
+  #   @return [CArray]
+  def bsearch(val, axis: nil); end
+
+  # @overload bsearch_addr(val)
+  #   Equivalent to {#bsearch} when `axis:` is omitted (the flat
+  #   case already returns a flat address).
+  #   @param val [Numeric, CArray]
+  #   @return [Integer, CArray, nil]
+  # @overload bsearch_addr(val, axis:)
+  #   Per-fiber binary search along `axis`, returning flat addresses
+  #   rather than axis-local positions.
+  #   @param val [Numeric, CArray]
+  #   @param axis [Integer]
+  #   @return [CArray]
+  def bsearch_addr(val, axis: nil); end
+
+  # @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.
+  #
+  #   `self` need not be sorted; this is a linear scan. For sorted
+  #   data prefer {#bsearch}.
+  #   @param val [Object]
+  #   @param eps [Float, nil]
+  #   @return [Integer, nil]
+  # @overload search(val, eps = nil, axis:)
+  #   Per-fiber linear search along `axis`. Returns axis-local
+  #   positions.
+  #   @return [CArray]
+  def search(val, eps = nil, axis: nil); end
+
+  # @overload search_addr(val, eps = nil)
+  #   Equivalent to {#search} when `axis:` is omitted.
+  #   @return [Integer, nil]
+  # @overload search_addr(val, eps = nil, axis:)
+  #   Per-fiber linear search along `axis`, returning flat
+  #   addresses rather than axis-local positions.
+  #   @return [CArray]
+  def search_addr(val, eps = nil, axis: nil); end
+
+  # @overload search_nearest(val)
+  #   Returns the flat address of the element of `self` whose value
+  #   is closest to `val`.
+  #
+  #   In an `:object` array the distance is `val.distance(other)` when
+  #   `val` answers `#distance`, and `(val - other).abs` when it is a
+  #   number. Anything else -- a String, say -- has no distance and
+  #   raises `CArray::DataTypeError`; use {#search} or {#bsearch} for an
+  #   exact match.
+  #   @param val [Object]
+  #   @return [Integer, nil]
+  #   @raise [CArray::DataTypeError] when `val` is neither a number nor
+  #     answers `#distance`.
+  # @overload search_nearest(val, axis:)
+  #   Per-fiber nearest-value search along `axis`. Returns
+  #   axis-local positions.
+  #   @return [CArray]
+  def search_nearest(val, axis: nil); end
+
+  # @overload search_nearest_addr(val)
+  #   Equivalent to {#search_nearest} when `axis:` is omitted.
+  #   @return [Integer, nil]
+  # @overload search_nearest_addr(val, axis:)
+  #   Per-fiber nearest-value search along `axis`, returning flat
+  #   addresses rather than axis-local positions.
+  #   @return [CArray]
+  def search_nearest_addr(val, axis: nil); end
+
+  # @!endgroup
+
+  # @!group Sorting and searching
+
+  # @overload linear_section(val, axis: nil, method: :binary)
+  #   Returns the fractional position of `val` within `self` (treated
+  #   as a coordinate axis), interpolating linearly between the two
+  #   bracketing samples. The integer part of the returned address is
+  #   the index of the lower bracket, the fractional part is the
+  #   interpolation weight toward the next sample. Out-of-range `val`
+  #   returns NaN.
+  #
+  #   `self` is coerced to `:float64` if it is not already. When
+  #   `axis: nil`, `self` is flattened to 1-D first.
+  #
+  #   `method:` selects the search backend:
+  #   - `:binary` (default) — bisection. `O(log N)` per query.
+  #     Assumes an ascending (sorted) axis; returns NaN on
+  #     descending data.
+  #   - `:linear` — sign-product scan. `O(N)` per query but handles
+  #     both ascending and descending monotone axes correctly.
+  #
+  #   See {#linear_fetch} for the inverse operation (fractional
+  #   address to interpolated value).
+  #   @param val [Numeric, CArray]
+  #   @param axis [Integer, nil]
+  #   @param method [Symbol] `:binary` or `:linear`.
+  #   @return [Float, CArray]
+  #   @raise [ArgumentError] when `method:` is neither `:binary` nor
+  #     `:linear`.
+  def linear_section(val, axis: nil, method: :binary); end
+
+  # @overload linear_fetch(addr, axis: nil)
+  #   Returns the value of `self` (treated as a coordinate axis) at
+  #   the fractional position `addr`, interpolating linearly between
+  #   the two bracketing samples. The inverse of {#linear_section}.
+  #
+  #   `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.
+  #
+  #   Because this half of the pair returns a *value* rather than a
+  #   position, a Face axis gets its Face back: `CATime#linear_fetch` /
+  #   `CATimedelta#linear_fetch` return a time on the axis's own unit
+  #   (rounded to that grid, UNDEF out of range) instead of raw ticks.
+  #   @param addr [Float, CArray] fractional position(s) into `self`.
+  #   @param axis [Integer, nil]
+  #   @return [Float, CArray]
+  #   @see file:docs/topics/LinearInterpolation.md
+  def linear_fetch(addr, axis: nil); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_random.rb

@@ -0,0 +1,89 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_random.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Random
+
+  # @overload random!(rng: nil)
+  #   A float array: samples `[0.0, 1.0)`.  An integer array: raises
+  #   (a range is required).
+  # @overload random!(high, rng: nil)
+  #   Samples `[0, high)` (Ruby `rand` / Numo `.rand` shorthand).
+  # @overload random!(low, high, rng: nil)
+  #   Samples `[low, high)` (Numo positional convention).
+  # @overload random!(range, rng: nil)
+  #   Samples from a Ruby Range: `a..b` closed, `a...b` half-open.
+  #   An integer array honors the endpoint distinction (dice: `1..6`
+  #   yields values in `1..6` including 6; `1...6` yields `1..5`).
+  #   For a float array, closed and half-open are equivalent at the
+  #   sampler level (endpoint probability ≈ 2^-53), matching
+  #   NumPy/SciPy convention — `..` is accepted for syntax but the
+  #   endpoint is not enforced at the mantissa.
+  #
+  #   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.
+  #
+  #   @param low [Numeric] lower bound (inclusive).
+  #   @param high [Numeric] upper bound (exclusive).
+  #   @param range [Range] closed (`a..b`) or half-open (`a...b`).
+  #   @param rng [Random, nil] RNG instance; nil uses the per-ractor
+  #     default RNG.
+  #   @return [self]
+  #   @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.
+  def random!(*args, rng: nil); end
+
+  # @overload random(rng: nil)
+  # @overload random(high, rng: nil)
+  # @overload random(low, high, rng: nil)
+  # @overload random(range, rng: nil)
+  #   Non-bang variant: returns a newly templated array filled by
+  #   `random!`.  Accepts the same argument forms.
+  #   @return [CArray]
+  def random(*args, rng: nil); end
+
+  # @overload randomn!(rng: nil)
+  #   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.
+  #   @param rng [Random, nil] RNG instance; nil uses the per-ractor
+  #     default RNG.
+  #   @return [self]
+  #   @raise [CArray::DataTypeError] for non-float / non-complex arrays.
+  def randomn!(rng: nil); end
+
+  # @overload randomn(rng: nil)
+  #   Non-bang variant: returns a newly templated array filled by
+  #   `randomn!`.
+  #   @return [CArray]
+  def randomn(rng: nil); end
+
+  # @!endgroup
+
+  # @!group Random
+
+  # @overload shuffle!(axis: nil, rng: nil)
+  #   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).
+  #   @param axis [Integer, nil] axis to permute along; nil = flat.
+  #   @param rng [Random, nil] RNG instance; nil uses the per-ractor
+  #     default RNG.
+  #   @return [self]
+  #   @raise [ArgumentError] if `axis` is out of range.
+  def shuffle!(axis: nil, rng: nil); end
+
+  # @overload shuffle(axis: nil, rng: nil)
+  #   Non-bang variant: returns a shuffled copy of `self`.
+  #   @return [CArray]
+  def shuffle(axis: nil, rng: nil); end
+
+  # @!endgroup
+end