carray 3.0.2 → 3.0.4

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.
@@ -30,13 +29,16 @@ class CArray
   # 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)
+  # @overload partition(kth, axis: nil, 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.
   #
+  #   Without `axis:` (or with `axis: nil`) `self` is flattened and
+  #   treated as one fiber, as {#sort} does; the result is 1-D.
+  #
   #   Negative `kth` counts from the end of the fiber
   #   (`-self.shape[axis] <= kth < self.shape[axis]`).
   #
@@ -52,32 +54,39 @@ class CArray
   #   among unmasked values.
   #
   #   @param kth [Integer] target fiber-local position along `axis`.
-  #   @param axis [Integer]
+  #   @param axis [Integer, nil] `nil` partitions the whole array.
   #   @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
+  def partition(kth, axis: nil, 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}.
+  # @overload partition_copy(kth, axis: nil, masked_position: :last)
+  #   Returns a fresh entity `CArray` partitioned along `axis` by the
+  #   same rule as {#partition}: the shape of `self`, or 1-D when `axis`
+  #   is omitted.
   #   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.
   #
+  #   A Face partitions in its surface order and comes back as the same
+  #   Face: one whose storage order is its surface order is selected on its
+  #   storage, a fixlen storage by byte order. A Face whose storage order is
+  #   not its surface order (e.g. {CACategorical}) raises.
+  #
   #   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 axis [Integer, nil] `nil` partitions the whole array.
   #   @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
+  #   @raise [ArgumentError] same conditions as {#partition}, or a Face that
+  #     is not orderable by its storage.
+  def partition_copy(kth, axis: nil, masked_position: :last); end
 
-  # @overload order(axis: nil, descending: false, method: :ordinal)
+  # @overload order(axis: nil, descending: false, method: :ordinal, kind: :quick)
   #   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
@@ -87,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
@@ -105,9 +116,11 @@ class CArray
   #   @param axis [Integer, nil]
   #   @param descending [Boolean]
   #   @param method [Symbol] `:ordinal` (default) or `:dense`.
+  #   @param kind [Symbol] `:quick` (default) or `:stable`, as for
+  #     {#sort_index}; a performance choice only.
   #   @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
+  def order(axis: nil, descending: false, method: :ordinal, kind: :quick); end
 
   # @!endgroup
 
@@ -121,7 +134,7 @@ class CArray
   #   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.
+  #   @raise [ArgumentError] 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.
@@ -148,6 +161,24 @@ class CArray
   #   to `val`. For float types, `eps` (default machine epsilon)
   #   sets the tolerance. 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), 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]
@@ -206,7 +237,8 @@ class CArray
   #   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.
+  #   returns NaN. A one-point axis has no segment: `val` equal to the
+  #   point is at 0, any other value is out of range.
   #
   #   `self` is coerced to `:float64` if it is not already. When
   #   `axis: nil`, `self` is flattened to 1-D first.

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.

data/yard-stubs/carray_scatter.rb

@@ -16,13 +16,20 @@ class CArray
   # Shared contract:
   #
   # - `addrs` is a CArray of any integer type (coerced to
-  #   `CA_SIZE`) or a Ruby Array.
+  #   `CA_SIZE`) or a Ruby Array. A float or complex CArray is
+  #   refused with `IndexError`, as `self[addrs]` refuses it.
   # - `vals` is a CArray of length matching `addrs` (coerced to
-  #   `self.data_type`), or a Numeric scalar broadcast to all
-  #   addresses.
-  # - Out-of-range `addrs[i]` (`< 0` or `>= self.elements`) raises
-  #   `IndexError`.
-  # - `self.data_type` must be numeric.
+  #   `self.data_type`), or a scalar broadcast to all addresses: any
+  #   Numeric, `true` / `false`, or `UNDEF`. The scalar is converted as
+  #   `self[i] = v` converts it, so a value that does not fit the type
+  #   raises (`RangeError`, `FloatDomainError` for NaN into an integer
+  #   type). A scalar `UNDEF` is a masked value.
+  # - A negative `addrs[i]` counts from the end. One out of range
+  #   raises `IndexError`; the pairs before it stay applied, through a
+  #   view as well.
+  # - `self.data_type` must be numeric. Complex is accepted by
+  #   every variant except {#scatter_min!} and {#scatter_max!},
+  #   since complex values have no order.
   #
   # Mask policy differs between the accumulate family and
   # {#scatter_replace!}: the accumulate variants skip the pair when
@@ -73,6 +80,8 @@ class CArray
   #   @param addrs [CArray, Array<Integer>]
   #   @param vals [CArray, Numeric]
   #   @return [self]
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type`.
   def scatter_min!(addrs, vals); end
 
   # @overload scatter_max!(addrs, vals)
@@ -82,6 +91,8 @@ class CArray
   #   @param addrs [CArray, Array<Integer>]
   #   @param vals [CArray, Numeric]
   #   @return [self]
+  #   @raise [CArray::DataTypeError] for a non-numeric or complex
+  #     `data_type`.
   def scatter_max!(addrs, vals); end
 
   # @overload scatter_replace!(addrs, vals)
@@ -94,11 +105,12 @@ class CArray
   #   result is written back many times.
   #
   #   Unlike the arithmetic `scatter_*!` family, `self` may be
-  #   **boolean** (assignment does not widen), and `true` / `false`
-  #   are accepted as scalar `vals` alongside numeric scalars.
+  #   **boolean** (assignment does not widen); `true` / `false` (or
+  #   `1` / `0`) are its scalar values. A scalar `UNDEF` masks every
+  #   addressed cell.
   #
   #   @param addrs [CArray, Array<Integer>]
-  #   @param vals [CArray, Numeric, true, false]
+  #   @param vals [CArray, Numeric, true, false, UNDEF]
   #   @return [self]
   def scatter_replace!(addrs, vals); end
 

data/yard-stubs/carray_segment.rb

@@ -0,0 +1,72 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_segment.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Index and address conversion
+  #
+  # A flat sequence cut into consecutive segments has three
+  # representations, and these methods convert between them:
+  #
+  #   lengths         [2, 0, 3]         one count per segment
+  #   offsets         [0, 2, 2, 5]      every boundary, both ends included
+  #   segment index   [0, 0, 2, 2, 2]   the segment each element is in
+  #
+  # Segment `c` spans `offsets[c]...offsets[c + 1]`, so there is no
+  # special case for the last segment and none for an empty one.
+  #
+  # Both methods compute in int64 and return int64, so a total beyond
+  # 2**53 stays exact. They accept a CArray of any integer or boolean
+  # data type (views included, read in flatten order) or an Array of
+  # Integers, and refuse masked cells: a masked length is not a count,
+  # and a masked offset is not a position.
+
+  # @overload segment_offsets(lengths:)
+  #   Returns the boundaries of segments with the given lengths: `0`
+  #   first, then the running total. `k` lengths give `k + 1` offsets,
+  #   so no lengths give `[0]`.
+  #
+  #     CArray.segment_offsets(lengths: [2, 0, 3])   # => [0, 2, 2, 5]
+  #
+  #   @param lengths [CArray, Array<Integer>] one count per segment.
+  #   @return [CArray] int64, one element more than `lengths`.
+  #   @raise [ArgumentError] for a negative length, a masked length,
+  #     or a non-Integer in an Array.
+  #   @raise [CArray::DataTypeError] for a non-integer data type.
+  #   @raise [RangeError] when the total overflows int64.
+  def self.segment_offsets(lengths:); end
+
+  # @overload segment_index(lengths:)
+  #   Returns, for each element of the cut sequence, the segment it
+  #   belongs to. A segment of length 0 contributes no elements, so
+  #   its number does not appear.
+  #
+  #     CArray.segment_index(lengths: [2, 0, 3])   # => [0, 0, 2, 2, 2]
+  #
+  #   The same as `CArray.int64(k).seq.repeat(lengths)`, as an owned
+  #   array rather than a view.
+  #   @param lengths [CArray, Array<Integer>] one count per segment.
+  #   @return [CArray] int64, `lengths.sum` elements.
+  #
+  # @overload segment_index(offsets:)
+  #   The same from boundaries. The offsets need not start at 0: the
+  #   offsets of a range cut out of a longer table start where that
+  #   range starts, and the result then covers
+  #   `offsets[0]...offsets[-1]` with the segments numbered from 0.
+  #
+  #     CArray.segment_index(offsets: [0, 2, 2, 5])   # => [0, 0, 2, 2, 2]
+  #     CArray.segment_index(offsets: [4, 6, 6, 9])   # => [0, 0, 2, 2, 2]
+  #
+  #   @param offsets [CArray, Array<Integer>] `k + 1` non-decreasing
+  #     boundaries.
+  #   @return [CArray] int64, `offsets[-1] - offsets[0]` elements.
+  #
+  # @raise [ArgumentError] for a negative length, decreasing or empty
+  #   offsets, a masked cell, a non-Integer in an Array, or unless
+  #   exactly one of `lengths:` and `offsets:` is given.
+  # @raise [CArray::DataTypeError] for a non-integer data type.
+  # @raise [RangeError] when the total length overflows int64.
+  def self.segment_index(lengths: nil, offsets: nil); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_slab.rb

@@ -14,7 +14,8 @@ class CArray
   #   duration of the block — capturing it across iterations sees the last
   #   slab's data — and it is read-only: writing through it raises.  To
   #   produce values per slab use `map_slab` or `reduce_slab`; to write in
-  #   place, assign through the array itself.
+  #   place, assign through the array itself.  Over a Face (`CATime`, a
+  #   record type) the slab is that Face.
   # @overload each_slab(axis:)
   #   Returns an Enumerator when no block is given.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes
@@ -28,7 +29,10 @@ class CArray
   #   Returns a new CArray built by replacing each slab of `self` with the
   #   block's result.  The block receives the slab view and must return a
   #   value of the same shape as the slab (a CArray or scalar); the results
-  #   are written into the output at the same positions.
+  #   are written into the output at the same positions, and a masked
+  #   cell of the block's result is masked in the output.  Over a Face the
+  #   slab is that Face, and the output is too unless `data_type:` is
+  #   given; a read-only Face answers in `:object` cells.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes.
   #   @param data_type [Symbol, Integer, Class, nil] output data type
   #     (defaults to `self`'s data type).
@@ -47,6 +51,10 @@ class CArray
   #   Per-element form (`init:` given): the block receives `(acc, x)` for
   #   each element of the slab and returns the new accumulator; the final
   #   accumulator per slab fills the output.
+  #
+  #   `UNDEF` from the block masks that output cell.  Over a Face the slab
+  #   (and each element) is that Face's, and the output is that Face unless
+  #   `data_type:` is given; a read-only Face answers in `:object` cells.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes.
   #   @param init [Object] the initial accumulator (selects the
   #     per-element form).

data/yard-stubs/carray_sort.rb

@@ -115,6 +115,43 @@ class CArray
   #     `:stable`.
   def sort_addr(axis: nil, kind: :quick, masked_position: :last); end
 
+  # @overload sort_index(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns, for each fiber along `axis`, the positions within the
+  #   fiber that put it in ascending order: `:int64`, shaped like
+  #   `self`. For a 1-D array, `a[a.sort_index]` is `a` sorted.
+  #
+  #   Without `axis:` (or with `axis: nil`) `self` is flattened and
+  #   treated as one fiber, as {#sort} does: the result is 1-D with
+  #   `self.elements` entries, and `a.flatten[a.sort_index]` is
+  #   `a.sort`.
+  #
+  #   The sort is **stable**: cells that compare equal keep their
+  #   input order, whichever `kind:` is chosen, so sorting by one key
+  #   and then stably by another orders by the second key first and
+  #   the first within it. `kind:` is a performance characteristic
+  #   only:
+  #
+  #   - `:quick` (default) — introsort with mergesort escape.
+  #   - `:stable` — bottom-up mergesort.
+  #
+  #   NaN and masked cells cannot be compared with the rest and are
+  #   placed at one end of each fiber: NaN after the numbers, masked
+  #   cells at the end `masked_position:` names (`:last`, default, or
+  #   `:first`). Relative order within the masked cells is unspecified.
+  #
+  #   Takes numeric data types, boolean, `CA_FIXLEN` (byte order),
+  #   `CA_OBJECT` (`<=>` per pair), and an ordered Face such as
+  #   `CATime`. Complex values have no order.
+  #   @param axis [Integer, nil] axis along which fibers run; negative
+  #     counts from the end. `nil` sorts the whole array.
+  #   @param kind [Symbol] `:quick` or `:stable`.
+  #   @param masked_position [Symbol] `:last` (default) or `:first`.
+  #   @return [CArray] `:int64` positions within each fiber.
+  #   @raise [ArgumentError] when `kind:` is neither `:quick` nor
+  #     `:stable`, or `axis` is out of range.
+  #   @raise [CArray::DataTypeError] for a complex `data_type`.
+  def sort_index(axis: nil, kind: :quick, masked_position: :last); end
+
   # @!group Index and address conversion
 
   # @overload axis2addr(indices, axis: 0)
@@ -142,23 +179,27 @@ class CArray
   #   is a one-liner on top of `flatten[axis2addr(...)]`.
   #
   #   Shape rule: `indices.ndim == self.ndim`, and
-  #   `indices.dim[j] == self.dim[j]` for all `j != axis`;
-  #   `indices.dim[axis]` is free.
+  #   `indices.shape[j] == self.shape[j]` for all `j != axis`;
+  #   `indices.shape[axis]` is free.
   #
   #   `indices` data_type: any integer kind (zero-copy when
   #   already `:int64`). Negative indices: Python-style
-  #   (`-1` == last). Out-of-range indices raise `RangeError`.
-  #   Negative `axis:` is Python-style.
+  #   (`-1` == last). Out-of-range indices raise `IndexError`.
+  #   Negative `axis:` is Python-style.  A masked index gives a
+  #   masked address (its stored value is not read), so
+  #   `take_along_axis` answers `UNDEF` there and `put_along_axis`
+  #   writes nothing there.
   #
   #   @param indices [CArray] integer-typed axis-local positions.
   #   @param axis [Integer] axis along which `indices` are
   #     interpreted.
   #   @return [CArray] `:int64` view-flat addresses, same shape as
   #     `indices`.
-  #   @raise [RangeError] when an index is out of range after
-  #     negative normalization.
-  #   @raise [ArgumentError] for shape / ndim / data_type
-  #     violations.
+  #   @raise [IndexError] when an index is out of range after
+  #     negative normalization, or `indices` is a float or complex
+  #     array.
+  #   @raise [ArgumentError] for shape / ndim violations, or a
+  #     boolean / object `indices`.
   def axis2addr(indices, axis: 0); end
 
   # @!endgroup

data/yard-stubs/carray_test.rb

@@ -6,8 +6,9 @@ class CArray
   # @!group Index and address conversion
 
   # @overload valid_index?(*idx)
-  #   Returns `true` if the given index tuple is in range for `self`.
-  #   The number of indices must equal `ndim`.
+  #   Returns `true` if the given index tuple names a cell of `self`,
+  #   that is, if `self[*idx]` would not raise. A negative index counts
+  #   from the end of its axis. The number of indices must equal `ndim`.
   #   @param idx [Array<Integer>] one index per axis.
   #   @return [Boolean]
   #   @raise [ArgumentError] if the number of indices does not match
@@ -15,7 +16,8 @@ class CArray
   def valid_index?(*idx); end
 
   # @overload valid_addr?(addr)
-  #   Returns `true` if `addr` is in range `0...elements` for `self`.
+  #   Returns `true` if `addr` names a cell of `self`: `0...elements`, or
+  #   a negative address counting from the end (`-elements..-1`).
   #   @param addr [Integer] flat address into the contiguous element
   #     sequence.
   #   @return [Boolean]
@@ -36,6 +38,13 @@ class CArray
   #   `data_class`, `data_type`, mask state, and elementwise values as
   #   `self`. NaN values compare unequal (IEEE semantics), so two
   #   arrays with NaN at the same position are not `==`.
+  #
+  #   A Face (a time, string or categorical array) equals only a Face of
+  #   its own class, and is compared by its values: two time arrays of
+  #   different units holding the same instants are `==`, as are two
+  #   categoricals with the same labels at each cell whatever the order
+  #   of their vocabularies. A Face is never `==` to an array that is not
+  #   one, even when the bytes match.
   #   @param other [Object]
   #   @return [Boolean]
   def ==(other); end
@@ -46,6 +55,9 @@ class CArray
   #   are compared bitwise (for numeric types) or via `Object#eql?`
   #   (for `:object` arrays). Unlike `==`, `NaN.eql?(NaN)` holds, so
   #   two mask-free arrays with NaN at the same positions are `eql?`.
+  #   Two Faces are `eql?` only when they are of the same class, share
+  #   their state (a time array's unit, a categorical's labels) and hold
+  #   the same storage.
   #
   #   Guarantees `a.eql?(b)` ⇒ `a.hash == b.hash`.
   #   @param other [Object]