carray 3.0.1 → 3.0.3

data/yard-stubs/carray_median_percentile.rb

@@ -9,9 +9,16 @@ class CArray
   #   Returns the median of `self` along `axis` (or over all elements
   #   when `axis` is `nil`).
   #
-  #   Numeric arrays return a `Float`; `CA_OBJECT` arrays return the
-  #   result of Ruby `+` / `/` on the stored objects. Fixlen arrays
-  #   raise, since no numeric midpoint is defined.
+  #   Numeric arrays return a `Float`. A `CA_OBJECT` array answers in
+  #   its elements' own terms: the middle element itself, or the
+  #   average of two as `(lo + hi) * (1/2)`, so an Integer, Rational or
+  #   BigDecimal median is exact (`CA_OBJECT([1, 2]).median` is `3/2`).
+  #   Fixlen arrays raise, since no numeric midpoint is defined.
+  #
+  #   An even number of elements has no middle one, only the average of
+  #   two -- so an object array whose elements cannot be averaged (a
+  #   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
@@ -27,7 +34,8 @@ class CArray
   #     count is below `min_count`.
   #   @param keep_axis [Boolean]
   #   @return [Float, CArray, Object]
-  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @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
 
@@ -52,9 +60,17 @@ class CArray
   #   - `:nearest` — round-half-to-even to the nearer neighbor.
   #   - `:midpoint` — arithmetic mean of the two neighbors.
   #
-  #   Numeric arrays produce `Float` results; `CA_OBJECT` arrays
-  #   apply Ruby `+` / `/` / `*` on the stored objects. Fixlen
-  #   arrays raise.
+  #   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. A `CA_OBJECT` array
+  #   answers in its elements' own terms: a pick (`:lower`, `:higher`,
+  #   `:nearest`) is the element itself, and `:linear` / `:midpoint`
+  #   use the elements' arithmetic with an exact Rational weight, so an
+  #   exact element gives an exact answer. Fixlen arrays raise.
   #
   #   Masking, `min_count`, `fill_value`, and `keep_axis` follow the
   #   same rules as {#median}.
@@ -67,7 +83,9 @@ class CArray
   #     `:nearest`, `:midpoint`.
   #   @param keep_axis [Boolean]
   #   @return [Float, CArray, Object, Array<Float>, Array<CArray>, Array<Object>]
-  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @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

data/yard-stubs/carray_order.rb

@@ -30,13 +30,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 +55,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
@@ -105,9 +115,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 +133,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 +160,14 @@ 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), and an
+  #   Integer that does not fit an integer array raises `RangeError`.
+  #   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).
+  #
   #   `self` need not be sorted; this is a linear scan. For sorted
   #   data prefer {#bsearch}.
   #   @param val [Object]
@@ -170,10 +190,17 @@ class CArray
 
   # @overload search_nearest(val)
   #   Returns the flat address of the element of `self` whose value
-  #   is closest to `val`. For `:object` arrays, uses
-  #   `val.distance(other)` to compare.
+  #   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.
@@ -189,73 +216,6 @@ class CArray
   #   @return [CArray]
   def search_nearest_addr(val, axis: nil); end
 
-  # @overload locate_addr(ref)
-  #   Returns, for each element of `self`, the flat address into `ref`
-  #   where the value first occurs, or `UNDEF` where it is not present.
-  #   Builds a value-to-first-address map from `ref` in one pass (an
-  #   open-addressing hash, the same substrate as {#unique} /
-  #   {#value_counts}), then probes each element of `self`; no sort,
-  #   peak memory `O(distinct ref values)`.
-  #
-  #   The return is `ref`'s flat address (0 to `ref.elements - 1`),
-  #   so a multi-dimensional `ref` still yields a `self`-shaped
-  #   result of flat addresses; downstream reads (`ref[addr]`,
-  #   `model_var[addr]`, ...) apply it as a flat gather.
-  #
-  #   Works on numeric, `CA_OBJECT`, and `CA_FIXLEN` values, matching
-  #   the value-hash discovery family: numeric follows `==` with all
-  #   NaN collapsed to one value and `-0.0 == +0.0`; object follows
-  #   Ruby `hash` / `eql?` with Float NaN collapsed; fixlen follows
-  #   byte equality. When `ref` holds duplicate values the returned
-  #   address is the earliest (appearance-order) occurrence. Masked
-  #   cells of `ref` do not enter the map but still occupy their flat
-  #   address; masked cells of `self` are `UNDEF` in the result.
-  #
-  #   Typical use is time-axis lookup: compute the address once
-  #   against a reference axis, then reuse it to gather from many
-  #   `ref`-shaped variables without repeating the lookup.
-  #
-  #   Implemented in Ruby (see `lib/carray/methods/locate_addr.rb`)
-  #   over the `__locate_addr__` hash-lane kernel; `self` is coerced
-  #   to `ref`'s data type within the same family (cross-family raises).
-  #   @param ref [CArray] reference values to match against; any
-  #     shape (used as flat).
-  #   @return [CArray] `:int64` flat addresses into `ref`, same shape
-  #     as `self`; unmatched cells are masked.
-  def locate_addr(ref); end
-
-  # @overload locate_nearest_addr(ref, direction: :round, tolerance: nil)
-  #   Returns, for each element of `self`, the flat address into `ref`
-  #   of the nearest reference value. Continuous sibling of
-  #   {#locate_addr}; uses `linear_section` + rounding for non-exact
-  #   matching against a sorted `ref`.
-  #
-  #   Out-of-range cells of `self` (outside `ref`'s span) mask through
-  #   the pipeline: `linear_section` returns NaN, `mask_invalid`
-  #   propagates that as `UNDEF`, rounding and the int64 cast carry
-  #   the mask, and `project` scatters it into the final positions.
-  #   `mask_invalid` runs before rounding because `CArray#round` maps
-  #   NaN to 0 and would otherwise silently match `ref[0]`.
-  #
-  #   `tolerance:` (default `nil`) sets a maximum accepted absolute
-  #   distance between `self[i]` and its matched `ref` value. When
-  #   `|ref[addr] - self[i]| > tolerance`, the result cell is masked.
-  #   Use for accuracy-controlled matching (e.g. "an observation
-  #   snaps to a time step only if within N seconds").
-  #
-  #   Implemented in Ruby (see `lib/carray/methods/locate_addr.rb`).
-  #   @param ref [CArray] 1-D sorted reference grid to match against.
-  #   @param direction [Symbol] `:round`, `:floor`, or `:ceil` —
-  #     rounding applied to the fractional position.
-  #   @param tolerance [Numeric, nil] maximum accepted `|self - ref|`
-  #     distance; cells beyond this are masked. `nil` disables the
-  #     check.
-  #   @return [CArray] `:int64` flat addresses into `ref`, same shape
-  #     as `self`; out-of-range and beyond-tolerance cells are masked.
-  #   @raise [ArgumentError] when `direction` is not one of the
-  #     accepted symbols.
-  def locate_nearest_addr(ref, direction: :round, tolerance: nil); end
-
   # @!endgroup
 
   # @!group Sorting and searching
@@ -266,7 +226,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_scatter.rb

@@ -19,10 +19,13 @@ class CArray
   #   `CA_SIZE`) or a Ruby Array.
   # - `vals` is a CArray of length matching `addrs` (coerced to
   #   `self.data_type`), or a Numeric scalar broadcast to all
-  #   addresses.
+  #   addresses. A complex `self` also takes a Complex scalar.
   # - Out-of-range `addrs[i]` (`< 0` or `>= self.elements`) raises
-  #   `IndexError`.
-  # - `self.data_type` must be numeric.
+  #   `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 +76,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 +87,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)

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

@@ -10,30 +10,33 @@ class CArray
 
   # @overload each_slab(axis:)
   #   Yields each slab of `self` (a view along the axes NOT in `axis`) to
-  #   the block and returns `self`.  The slab is a live view valid only
-  #   for the duration of the block — capturing it across iterations sees
-  #   the last slab's data.
+  #   the block and returns `self`.  The slab is valid only for the
+  #   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.
   # @overload each_slab(axis:)
   #   Returns an Enumerator when no block is given.
   #   @param axis [Integer, Array<Integer>, nil] the slab axis or axes
   #     (`nil` = the whole view as a single slab).
   #   @return [self, Enumerator]
-  #   @see file:docs/SlabIterator.md SlabIterator
-  #   @see file:docs/drafts/11_slab_iteration.md Slab iteration
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
+  #   @see file:guides/users/11_slab_iteration.md Slab iteration
   def each_slab(axis:); end
 
   # @overload map_slab(axis:, data_type: nil)
   #   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.
   #   @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).
   #   @return [CArray]
   #   @raise [ArgumentError] when the block result's shape does not match
   #     the slab.
-  #   @see file:docs/SlabIterator.md SlabIterator
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
   def map_slab(axis:, data_type: nil); end
 
   # @overload reduce_slab(axis:, data_type: nil)
@@ -50,7 +53,7 @@ class CArray
   #     per-element form).
   #   @param data_type [Symbol, Integer, Class, nil] output data type.
   #   @return [CArray] the reduced array (slab axes collapsed).
-  #   @see file:docs/SlabIterator.md SlabIterator
+  #   @see file:docs/topics/SlabIterator.md SlabIterator
   def reduce_slab(axis:, init: nil, data_type: nil); end
 
   # @!endgroup

data/yard-stubs/carray_sort.rb

@@ -67,11 +67,13 @@ class CArray
   #   along `axis`. Use this when you want an independent array
   #   rather than a view.
   #
-  #   Unmasked numeric paths use a per-fiber gather + sort +
-  #   scatter, bypassing the `CARemap` scatter layer that `sort`
-  #   uses. `CA_FIXLEN` and masked input both materialize the
-  #   `sort` view instead (same shape, ordering, and
-  #   `masked_position:` semantics as {#sort}).
+  #   It takes whatever {#sort} takes: numeric (`i8`..`f64`),
+  #   `CA_BOOLEAN`, `CA_FIXLEN` and `CA_OBJECT`, masked or not.
+  #
+  #   Unmasked `i8`..`f64` uses a per-fiber gather + sort + scatter,
+  #   bypassing the `CARemap` scatter layer that `sort` uses.
+  #   Everything else materializes the `sort` view instead (same
+  #   shape, ordering, and `masked_position:` semantics as {#sort}).
   #   @param axis [Integer, nil]
   #   @param kind [Symbol] `:quick` or `:stable`.
   #   @param masked_position [Symbol] `:last` (default) or `:first`.
@@ -113,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)
@@ -145,15 +184,18 @@ class CArray
   #
   #   `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
+  #   @raise [IndexError] when an index is out of range after
   #     negative normalization.
   #   @raise [ArgumentError] for shape / ndim / data_type
   #     violations.

data/yard-stubs/carray_test.rb

@@ -36,6 +36,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 +53,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]

data/yard-stubs/carray_utils.rb

@@ -67,31 +67,5 @@ class CArray
     def guess_type_and_bytes(type_spec, bytes = nil); end
 
     # @!endgroup
-
-    # @!group String scanning (internal)
-
-    # @overload _scan_float(str, fill_value = nil)
-    #   Parses `str` as a single double-precision float. Returns
-    #   `fill_value` (or `NaN` if `fill_value` is nil) when `str` is
-    #   `nil` or unparseable. Internal helper used by text-format I/O
-    #   readers; end users should prefer Ruby's `Float()` /
-    #   `String#to_f`.
-    #   @param str [String, nil]
-    #   @param fill_value [Float, nil]
-    #   @return [Float]
-    #   @api private
-    def _scan_float(str, fill_value = nil); end
-
-    # @overload _scan_int(str, fill_value = nil)
-    #   Parses `str` as a single integer. Returns `fill_value`
-    #   (or `0` if `fill_value` is nil) when `str` is `nil` or
-    #   unparseable. Internal helper used by text-format I/O readers.
-    #   @param str [String, nil]
-    #   @param fill_value [Integer, nil]
-    #   @return [Integer]
-    #   @api private
-    def _scan_int(str, fill_value = nil); end
-
-    # @!endgroup
   end
 end