carray 2.0.0 → 3.0.0

data/lib/carray/methods/index.rb

@@ -0,0 +1,39 @@
+class CArray
+
+  # @overload index(axis: 0)
+  #   Returns a writable int32 CArray holding the coordinate ramp
+  #   `[0, 1, ..., shape[axis] - 1]` along `axis`, in an open
+  #   broadcast shape: size `shape[axis]` on that axis and 1 on
+  #   every other axis (e.g. for `(d0, d1, d2)`, `index(axis: 1)`
+  #   returns `(1, d1, 1)`).
+  #
+  #   The result broadcasts against `self` in element-wise ops
+  #   without materialising the full shape. For the dense
+  #   full-shape grid use
+  #   `index(axis: k).broadcast_to(*shape)` or `CArray.meshgrid`.
+  #
+  #   @param axis [Integer] axis to vary (negative counts from the
+  #     end).
+  #   @return [CArray] writable int32 CArray; size 1 on every axis
+  #     except `axis`, which has size `shape[axis]`.
+  def index (axis: 0)
+    k = normalize_axis(axis, "index")
+    oshape = Array.new(ndim, 1)
+    oshape[k] = shape[k]
+    CArray.int32(*oshape).seq!
+  end
+
+  # @overload indices
+  #   Returns an Array of +ndim+ coordinate ramps, one per axis, each in
+  #   the open broadcast shape of {#index}.
+  #   @return [Array<CArray>] one open coordinate ramp per axis.
+  # @overload indices { |*ramps| ... }
+  #   Yields the +ndim+ open coordinate ramps as splat arguments.
+  #   @yield [*ramps] the per-axis open coordinate ramps.
+  #   @return [Object] the block's return value.
+  def indices
+    list = (0...ndim).map { |k| index(axis: k) }
+    block_given? ? yield(*list) : list
+  end
+
+end

data/lib/carray/methods/insert_block.rb

@@ -0,0 +1,99 @@
+# Block insert / delete pair (insert_block / delete_block): grow or shrink
+# an array by inserting or removing a block region along each axis.
+
+class CArray
+
+  # @overload insert_block(offset, bsize, &block)
+  #   Returns a new CArray obtained by inserting a block of size
+  #   `bsize` (per axis) at `offset`, growing the array.
+  #
+  #   Per axis, `offset` accepts `0..shape[i]` (equal to `shape[i]`
+  #   appends at the end) and a negative value counts from the end;
+  #   `bsize[i]` must be non-negative. Inserted cells are filled by
+  #   the block's return value, or left at the type's default when
+  #   no block is given. Preserves fixlen bytes and Face identity
+  #   (built on the storage layout, re-wrapped via `face_lift`).
+  #   The `offset` array is not mutated.
+  #
+  #   @param offset [Array<Integer>] insertion offset per axis.
+  #   @param bsize [Array<Integer>] block size per axis.
+  #   @yieldreturn [Object] fill value for the inserted cells.
+  #   @return [CArray] grown copy.
+  #   @raise [ArgumentError] on `ndim` mismatch or out-of-range
+  #     offset / size.
+  def insert_block (offset, bsize, &block)
+    if offset.size != ndim or bsize.size != ndim
+      raise ArgumentError, "ndim mismatch"
+    end
+    offset = offset.dup           # normalize without mutating the caller's array
+    newdim = shape
+    grids = shape.map{|d| CArray.int32(d) }
+    ndim.times do |i|
+      offset[i] += shape[i] if offset[i] < 0
+      if offset[i] < 0 or offset[i] > shape[i] or bsize[i] < 0
+        raise ArgumentError, "invalid offset or size at axis #{i}"
+      end
+      if bsize[i] > 0
+        newdim[i] += bsize[i]
+      end
+      grids[i][0...offset[i]].seq! if offset[i] > 0
+      # offset == dim (append) leaves nothing on the upper side to shift.
+      grids[i][offset[i]..-1].seq!(offset[i]+bsize[i]) if offset[i] < shape[i]
+    end
+    # Build at the storage layout (preserving bytes for fixlen / Face),
+    # then re-wrap as the same Face.
+    face_parent = self.face? ? self : nil
+    src = self
+    src = src.parent while src.face?
+    dt    = src.data_type
+    bytes = (dt == :fixlen) ? src.bytes : nil
+    out = CArray.new(dt, newdim, bytes: bytes)
+    if block_given?
+      sel = out.true
+      sel[*grids] = 0
+      out[sel] = block.call
+    end
+    out[*grids] = src
+    out = out.face_lift(face_parent) if face_parent
+    return out
+  end
+
+  # @overload delete_block(offset, bsize)
+  #   Returns a new CArray obtained by deleting a block of `bsize`
+  #   cells (per axis) starting at `offset`, shrinking the array.
+  #
+  #   Per axis, `offset` accepts `0..shape[i]-1` (negative counts
+  #   from the end) and `bsize[i]` must be non-negative with
+  #   `offset[i] + bsize[i] <= shape[i]`. Bytes and Face identity
+  #   are preserved naturally because the result is built by
+  #   fancy-index copy of `self`. The `offset` array is not mutated.
+  #
+  #   @param offset [Array<Integer>] start of the block per axis.
+  #   @param bsize [Array<Integer>] block size per axis.
+  #   @return [CArray] shrunk copy.
+  #   @raise [ArgumentError] on `ndim` mismatch or out-of-range
+  #     offset / size.
+  def delete_block (offset, bsize)
+    if offset.size != ndim or bsize.size != ndim
+      raise ArgumentError, "ndim mismatch"
+    end
+    offset = offset.dup           # normalize without mutating the caller's array
+    newdim = shape
+    grids  = []
+    ndim.times do |i|
+      offset[i] += shape[i] if offset[i] < 0
+      if bsize[i] < 0 or offset[i] < 0 or offset[i] >= shape[i] or
+          offset[i] + bsize[i] > shape[i]
+        raise ArgumentError, "invalid offset or size at axis #{i}"
+      end
+      newdim[i] -= bsize[i]
+      grids[i] = CArray.int32(newdim[i])
+      grids[i][0...offset[i]].seq! if offset[i] > 0
+      if offset[i] + bsize[i] < shape[i]
+        grids[i][offset[i]..-1].seq!(offset[i]+bsize[i])
+      end
+    end
+    return self[*grids].copy
+  end
+
+end

data/lib/carray/methods/is_in.rb

@@ -0,0 +1,141 @@
+class CArray
+
+  # @overload is_in(values)
+  #   Returns a boolean CArray of the same shape as `self`, `true` at
+  #   each cell whose value appears in the set `values`.
+  #
+  #   `values` is treated as a set, not as an operand to broadcast: it
+  #   may be any shape (or an Array / Range) and is flattened to a
+  #   single seen-set, so its shape need not match `self`. Only one
+  #   argument is accepted; to test a few immediate values pass an
+  #   Array (`a.is_in([0, -1])`).
+  #
+  #   When `self` and `values` have different numeric dtypes they are
+  #   promoted to a common type first (the same promotion binops use,
+  #   {CArray.result_type}), so membership is value-correct across
+  #   dtypes (e.g. an int cell equals a float set element of the same
+  #   value, and a fractional set element never truncates onto an int
+  #   cell). Genuinely incompatible dtypes (e.g. numeric vs fixlen)
+  #   raise.
+  #
+  #   Membership is value-based and shares the distinctness of the
+  #   value-hash discovery family ({#unique} / {#value_counts}):
+  #   numeric follows `==` with all NaN collapsed to one value and
+  #   -0.0 == +0.0; `CA_OBJECT` follows Ruby `hash` / `eql?` with Float
+  #   NaN collapsed; `CA_FIXLEN` follows byte equality.
+  #
+  #   Masked cells of `values` do not enter the set. Masked cells of
+  #   `self` stay masked in the result (membership is unknown), so
+  #   `is_in` propagates `self`'s mask like an element-wise comparison.
+  #
+  #   For a per-fiber "does this fiber contain any of these values"
+  #   reduction, compose with {#any}: `a.is_in(values).any(axis: k)`.
+  #
+  #   @param values [CArray, Array, Range] the set to test membership
+  #     against. Promoted with `self` to a common dtype.
+  #   Between two time arrays the question is about instants, not ticks:
+  #   `values` is reconciled into `self`'s unit first, so a `:D` array and an
+  #   `:h` array match on the instants they share.  The same holds for the set
+  #   operations below, whose results come back as `self`'s own type.
+  #
+  #   @return [CArray] boolean CArray of the same shape as `self`.
+  def is_in (values)
+    a, b = promote_value_set(values)
+    a.__send__(:__is_in__, b)
+  end
+
+  # @overload intersection(other, sort: false)
+  #   Returns a 1-D CArray of the distinct values appearing in both
+  #   `self` and `other`, in `self`'s first-appearance order.
+  #
+  #   Value-based, sharing the distinctness of the discovery family
+  #   (see {#is_in}); `self` and `other` are promoted to a common dtype.
+  #   Masked cells of either array do not participate. The result is
+  #   always flat, like {#unique}, because the distinct values of a
+  #   fiber vary in number.
+  #
+  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param sort [Boolean] when true, return the values sorted
+  #     ascending instead of in first-appearance order.
+  #   @return [CArray] 1-D CArray of the common distinct values.
+  def intersection (other, sort: false)
+    a, b = promote_value_set(other)
+    r = a.__send__(:__intersection__, b)
+    sort ? r.sort : r
+  end
+
+  # @overload difference(other, sort: false)
+  #   Returns a 1-D CArray of the distinct values in `self` that are
+  #   absent from `other`, in `self`'s first-appearance order.
+  #   See {#intersection} for the shared semantics and options.
+  #
+  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param sort [Boolean] when true, return the values sorted ascending.
+  #   @return [CArray] 1-D CArray of the self-only distinct values.
+  def difference (other, sort: false)
+    a, b = promote_value_set(other)
+    r = a.__send__(:__difference__, b)
+    sort ? r.sort : r
+  end
+
+  # @overload union(other, sort: false)
+  #   Returns a 1-D CArray of the distinct values appearing in either
+  #   `self` or `other`, in self-then-other first-appearance order.
+  #   See {#intersection} for the shared semantics and options.
+  #
+  #   @param other [CArray, Array, Range] promoted with `self`.
+  #   @param sort [Boolean] when true, return the values sorted ascending
+  #     (a merged, ordered set — e.g. a common time axis).
+  #   @return [CArray] 1-D CArray of the combined distinct values.
+  def union (other, sort: false)
+    a, b = promote_value_set(other)
+    r = a.__send__(:__union__, b)
+    sort ? r.sort : r
+  end
+
+  private
+
+  # Reconcile a set-valued argument with self to a common data_type via
+  # CArray.result_type (the single-source promotion rule the eager binop and
+  # lazy CABinOp share), returning [self', set']. Only dtypes are reconciled,
+  # never shapes: unlike the binop coercion (cast_self_or_other) the set's
+  # shape never broadcasts against self's, so a size-1 self keeps its shape.
+  # result_type raises for genuinely incompatible dtypes (numeric vs fixlen).
+  #
+  # A bare Array / Range has no intrinsic dtype, so the common type is inferred
+  # from self and the individual elements (result_type classifies each scalar).
+  # This keeps a fractional literal from truncating onto an int self, and an
+  # int literal from boxing a float self into the object lane (where Float 2.0
+  # is not eql? Integer 2). A CArray argument uses its own dtype; any other
+  # operand (Numo, a MemoryView producer, ...) comes in through wrap_readonly,
+  # the canonical type-coercion entry, so its format's dtype drives the promote.
+  def promote_value_set (values)
+    case values
+    when Array then return promote_elements(values)
+    when Range then return promote_elements(values.to_a)
+    end
+    set = values.is_a?(CArray) ? values : CArray.wrap_readonly(values)
+    return [self, set] if set.data_type == data_type   # common fast path
+    t = CArray.result_type(self, set)
+    [coerce_self(t), set.to_type(t)]
+  end
+
+  # Bare Array / Range against numeric self: infer the common numeric type
+  # from self and the elements (each classified by result_type), so a
+  # fractional literal promotes self to float instead of truncating. Against
+  # object / fixlen self the elements are values, not dtype specifiers (a
+  # String is a value, not a type name), so build the set in self's dtype.
+  def promote_elements (elems)
+    if data_type == CA_OBJECT || data_type == CA_FIXLEN
+      [self, elems.to_ca.to_type(data_type)]
+    else
+      t = CArray.result_type(self, *elems)
+      [coerce_self(t), elems.to_ca.to_type(t)]
+    end
+  end
+
+  def coerce_self (t)
+    CArray.result_type(self) == t ? self : to_type(t)
+  end
+
+end

data/lib/carray/methods/join.rb

@@ -0,0 +1,90 @@
+class CArray
+
+  # @overload join(sep = nil)
+  #   Flat form.  Stringifies and concatenates every element of `self`
+  #   (as if `to_a.flatten.join(sep)`).  Returns a String.
+  #
+  # @overload join(sep = "", axis:, keep_axis: false)
+  #   Per-axis form.  Reduces `axis` into strings, one per fiber along
+  #   that axis, and returns the result as a CArray with `axis` removed
+  #   (or set to 1 when `keep_axis: true`).  Composable — call `join`
+  #   again on the result to collapse another axis or fold to a String.
+  #
+  #   For a 1-D `self`, the axis form fully reduces and returns the
+  #   String directly (matching the flat form and the reduction
+  #   convention).
+  #
+  #   @param sep [String] separator between elements along the axis.
+  #   @param axis [Integer] axis to reduce (negative allowed).
+  #   @param keep_axis [Boolean] keep the reduced axis as length 1.
+  #   @return [CArray, String] a CArray of strings, or a String when
+  #     `self` is 1-D.
+  #
+  # @example Flat form
+  #   a = CArray.object(3, 3).seq("a", :succ)
+  #   a.join            # => "abcdefghi"
+  #   a.join(",")       # => "a,b,c,d,e,f,g,h,i"
+  #
+  # @example Per-axis form
+  #   a = CArray.int32(3, 3).seq
+  #   a.join(" ", axis: 1)               # → CArray["0 1 2", "3 4 5", "6 7 8"]
+  #   a.join(" ", axis: 1).join("\n")    # => "0 1 2\n3 4 5\n6 7 8"
+  #
+  # @note The 2.x multi-separator form `a.join("\n", ",")` was removed
+  #   in 3.0; use the axis form and chain, e.g.
+  #   `a.join(",", axis: 1).join("\n")`.
+  def join (*argv, axis: nil, keep_axis: false)
+    if argv.size > 1
+      raise ArgumentError,
+            "join accepts at most one positional separator " \
+            "(the 2.x multi-separator form was removed in 3.0; " \
+            "use axis: for per-axis join and chain)"
+    end
+    sep = argv.first  # nil or String
+
+    if axis.nil?
+      return sep.nil? ? to_a.join : to_a.join(sep)
+    end
+
+    ax = Integer(axis)
+    ax += ndim if ax < 0
+    if ax < 0 || ax >= ndim
+      raise ArgumentError,
+            "axis #{axis.inspect} out of range for ndim=#{ndim}"
+    end
+
+    sep_str = sep || ""
+
+    # Bring `ax` to the innermost position so we can iterate fibers as
+    # rows of a 2-D reshape.  transpose returns a view; reshape may
+    # materialize on non-contig, which is fine for this formatting op.
+    if ax == ndim - 1
+      t = self
+    else
+      order = (0...ndim).to_a
+      order << order.delete_at(ax)
+      t = transpose(*order)
+    end
+    inner = t.shape[-1]
+    outer_n = t.elements / inner  # 1 when ndim == 1
+    flat = t.reshape(outer_n, inner)
+
+    strings = Array.new(outer_n) { |i| flat[i, nil].to_a.join(sep_str) }
+
+    if ndim == 1
+      # Full reduction: return the String directly, or a length-1
+      # CArray when keep_axis was requested.
+      return keep_axis ? CA_OBJECT([strings.first]) : strings.first
+    end
+
+    result_shape = shape.dup
+    if keep_axis
+      result_shape[ax] = 1
+    else
+      result_shape.delete_at(ax)
+    end
+
+    CA_OBJECT(strings).reshape(*result_shape)
+  end
+
+end

data/lib/carray/methods/locate_addr.rb

@@ -0,0 +1,47 @@
+class CArray
+
+  # User-facing YARD docs for #locate_addr and #locate_nearest_addr live
+  # in yard-stubs/carray_order.rb (grouped with the search family).
+
+  def locate_addr (ref)
+    ref = ref.to_ca unless ref.is_a?(CArray)
+    # Put self and ref in a common lane via the single-source promotion rule
+    # (CArray.result_type), so a fractional query against an int ref is compared
+    # at the promoted type instead of truncating (1.5 no longer matches 1).
+    # to_type is elementwise and order-preserving, so the addresses stay valid
+    # indices into ref. result_type raises for cross-family input.
+    t = CArray.result_type(self, ref)
+    q = (data_type     == t) ? self : to_type(t)
+    r = (ref.data_type == t) ? ref  : ref.to_type(t)
+    q.send(:__locate_addr__, r)
+  end
+
+  def locate_nearest_addr (ref, direction: :round, tolerance: nil)
+    unless [:round, :floor, :ceil].include?(direction)
+      raise ArgumentError,
+            "locate_nearest_addr: direction must be :round / :floor / " \
+            ":ceil (got #{direction.inspect})"
+    end
+    ri = ref.sort_addr
+    rs = ref[ri]
+    sec = rs.linear_section(self)
+    unless sec.is_a?(CArray)
+      # A single-element (scalar-like) self makes linear_section collapse to
+      # its scalar-query path, which returns a bare Float (or nil when out of
+      # range) instead of a CArray.  Rebuild a self-shaped float64 CArray so
+      # the mask_invalid -> direction -> project pipeline stays array-valued
+      # and the returned addr array matches self's shape.
+      fill = CArray.float64(*shape)
+      fill[] = sec.nil? ? UNDEF : sec
+      sec = fill
+    end
+    si = sec.mask_invalid.send(direction).int64
+    idx = ri.project(si)
+    if tolerance
+      dist = (ref.project(idx) - self).abs
+      idx[dist > tolerance] = UNDEF
+    end
+    idx
+  end
+
+end

data/lib/carray/methods/mask_duplicates.rb

@@ -0,0 +1,41 @@
+class CArray
+
+  # @overload mask_duplicates(axis: nil)
+  #   Returns a shape-preserving copy of `self` with the mask set at
+  #   every cell whose value duplicates an earlier-seen one; the
+  #   first occurrence is kept.
+  #
+  #   With `axis: nil` duplicates are detected in flatten (row-major)
+  #   order across the whole array. With `axis: k` duplicates are
+  #   detected per-fiber along axis `k`, independently for each
+  #   fiber. Marking duplicates (not compressing) is what makes the
+  #   per-axis form expressible: fibers may hold different numbers of
+  #   distinct values, so a compressed result would be ragged.
+  #
+  #   Distinctness matches the value-hash discovery family. Numeric:
+  #   `==` with all NaN collapsed to one value (so the second and
+  #   later NaN are duplicates) and -0.0 == +0.0. `CA_OBJECT` /
+  #   `CA_FIXLEN`: Ruby `eql?` / `hash` (distinct NaN objects stay
+  #   distinct). Masked input cells stay masked and do not participate
+  #   in duplicate judging. Both `axis: nil` and `axis: k` work.
+  #
+  #   @param axis [Integer, nil] axis to detect duplicates along;
+  #     `nil` uses flatten order.
+  #   @return [CArray] shape-preserving copy of `self` with
+  #     duplicates masked.
+  def mask_duplicates (axis: nil)
+    dup =
+      if axis.nil?
+        # One seen-set over the flattened array, then restore shape.
+        flatten.send(:__mask_duplicates__, 0).reshape(*shape)
+      else
+        # Per-fiber single-pass seen-set hash (C __mask_duplicates__): one lane
+        # per dtype family (integer widen, float bitwise key with NaN collapse,
+        # object rb_hash + rb_eql, fixlen byte-hash + memcmp, boolean via the
+        # uint8 lane). O(distinct) memory, no sort/gather/scatter buffers.
+        __mask_duplicates__(normalize_axis(axis, "mask_duplicates"))
+      end
+    mask_where(dup)
+  end
+
+end

data/lib/carray/methods/meshgrid.rb

@@ -0,0 +1,91 @@
+class CArray
+
+  # @overload meshgrid(*axes, indexing: "xy", copy: true, sparse: false)
+  #   Returns coordinate matrices built from 1-D coordinate vectors.
+  #
+  #   Given N 1-D vectors, produces N arrays each broadcasting one
+  #   input axis across the others. Useful for evaluating a function
+  #   on a grid.
+  #
+  #   With `indexing: "xy"` (default) the first two axes are swapped
+  #   in the output shape (matrix-style convention): `meshgrid(x, y)`
+  #   gives outputs of shape `[y.elements, x.elements]`. With
+  #   `indexing: "ij"` input order is preserved:
+  #   `meshgrid(x, y, indexing: "ij")` gives outputs of shape
+  #   `[x.elements, y.elements]`. For more than two axes only the
+  #   first two are swapped under `"xy"`; the remaining axes follow
+  #   input order in both modes.
+  #
+  #   When `copy` is true (default) each output is a materialised
+  #   CArray; when false, view chains (CARepeat / CAUnboundRepeat)
+  #   are returned. When `sparse` is true the outputs are
+  #   CAUnboundRepeat views that broadcast on demand, saving memory
+  #   for large grids.
+  #
+  #   If a block is given, yields the resulting arrays as splat
+  #   arguments and returns the block's value.
+  #
+  #   Each axis goes through {CArray.wrap_readonly}, so a coordinate
+  #   vector may be given as anything that entry point accepts (a
+  #   CArray, an Array, a Range, a Numeric, a MemoryView producer, an
+  #   object answering `ca` / `to_ca`); its own data type is kept.
+  #
+  #   @param axes [Array<CArray, Array, Object>] 1-D coordinate vectors.
+  #   @param indexing [String] `"xy"` or `"ij"`.
+  #   @param copy [Boolean] materialise each output when true.
+  #   @param sparse [Boolean] return broadcast-on-demand views when true.
+  #   @yieldparam grids [Array<CArray>] the resulting coordinate arrays.
+  #   @return [Array<CArray>] the coordinate arrays, or the block's
+  #     return value.
+  #   @raise [ArgumentError] when `indexing` is neither `"xy"` nor `"ij"`,
+  #     or when a coordinate vector is not 1-D.
+  #   @example
+  #     x = CA_FLOAT64([1.0, 2.0, 3.0])
+  #     y = CA_FLOAT64([10.0, 20.0])
+  #     xx, yy = CArray.meshgrid(x, y)
+  #     xx.shape        # => [2, 3]
+  #     yy.to_a         # => [[10.0, 10.0, 10.0], [20.0, 20.0, 20.0]]
+  def self.meshgrid (*axes, indexing: "xy", copy: true, sparse: false, &block)
+    unless %w[xy ij].include?(indexing)
+      raise ArgumentError, %{indexing option should be one of "xy" and "ij"}
+    end
+
+    # Each axis is negotiable, so no target type is imposed here; a
+    # CArray comes back as itself and anything else is brought in with
+    # its own data type.
+    axes = axes.map.with_index do |axis, k|
+      a = CArray.wrap_readonly(axis)
+      unless a.ndim == 1
+        raise ArgumentError,
+              "coordinate vector #{k} should be 1-D (got #{a.ndim}-D)"
+      end
+      a
+    end
+
+    ndim = axes.size
+
+    # dest[k] = output axis position that input axis k populates.
+    # "xy" swaps the first two; everything else is in input order.
+    dest = (0...ndim).to_a
+    dest[0], dest[1] = 1, 0 if indexing == "xy" && ndim >= 2
+
+    # Output shape: each output axis i takes its size from the input
+    # axis that maps there.
+    out_shape = Array.new(ndim)
+    axes.each_with_index { |a, k| out_shape[dest[k]] = a.size }
+
+    list = axes.map.with_index do |axis, k|
+      d = dest[k]
+      idx = if sparse
+              Array.new(ndim) { |i| i == d ? nil : :* }
+            else
+              out_shape.dup.tap { |s| s[d] = :% }
+            end
+      view = axis[*idx]
+      copy ? view.copy : view
+    end
+
+    block ? block.call(*list) : list
+  end
+
+end

data/lib/carray/methods/mode.rb

@@ -0,0 +1,126 @@
+class CArray
+
+  # @overload is_mode(axis: nil)
+  #   Returns a shape-preserving boolean CArray, true at every cell
+  #   that holds a modal value — a value whose occurrence count equals
+  #   the maximum count. This is the first-class primitive of the mode
+  #   family: rather than returning the mode *value* (whose count is
+  #   data-dependent when there are ties), it marks every occurrence of
+  #   every most-frequent value, so ties are never silently broken.
+  #
+  #   ```
+  #   CA_INT32([1, 1, 2, 2, 3]).is_mode  # => [1, 1, 1, 1, 0]  (1 and 2 tie)
+  #   ```
+  #
+  #   With `axis: nil` the frequency is over the whole array; with
+  #   `axis: k` it is per fiber along axis `k`, independently. The
+  #   result is always the input shape, so — unlike returning the mode
+  #   value — the per-axis form has no ragged-length problem. Select the
+  #   modal cells with `a[a.is_mode]` / `a[a.is_mode(axis: k)]` (the
+  #   {#mask_duplicates} idiom); reduce further with `.min` / `.unique`.
+  #
+  #   Mode is only meaningful for discrete or binned data: raw float is
+  #   almost all unique, so `is_mode` would mark just the single lowest
+  #   cell (count 1). Bin first (`bin` / `histogram` / `categorize`).
+  #
+  #   Masked cells do not participate and are marked false. An empty or
+  #   all-masked fiber marks every cell false (mode has no identity; it
+  #   never raises). Numeric distinctness follows the discovery family
+  #   (all NaN collapse to one value, -0.0 == +0.0); `CA_OBJECT` /
+  #   `CA_FIXLEN` follow Ruby `eql?` / `hash`.
+  #
+  #   @param axis [Integer, nil] axis to take the mode along; `nil` uses
+  #     the whole array.
+  #   @return [CArray] boolean CArray of `self.shape`.
+  def is_mode (axis: nil)
+    # Per-fiber two-pass frequency table (C __is_mode__), one lane per dtype
+    # family (numeric widen / NaN collapse, object rb_hash + rb_eql, fixlen
+    # byte-hash + memcmp). Ties are all marked; masked cells stay false.
+    if axis.nil?
+      flatten.send(:__is_mode__, 0).reshape(*shape)
+    else
+      __is_mode__(normalize_axis(axis, "is_mode"))
+    end
+  end
+
+  # @overload mode(axis: nil)
+  #   Returns the distinct modal values — the most frequent value(s),
+  #   ascending. All values that tie for the highest count are returned
+  #   (matching pandas `Series.mode`), because {#is_mode} does not break
+  #   ties; `mode` is the value-form consumer of that primitive, read
+  #   straight from the frequency table.
+  #
+  #   With `axis: nil` the result is a 1-D CArray of the distinct modal
+  #   values over the whole array (empty when all-masked).
+  #
+  #   With `axis: k` the per-fiber mode counts are ragged, so — like
+  #   per-axis `quantile` — the result is an `Array` of reduced CArrays.
+  #   Element `j` holds each fiber's `j`-th smallest modal value, masked
+  #   where a fiber has fewer than `j + 1` modes; the Array length is the
+  #   widest fiber's mode count. So `mode(axis: k)[0]` is the smallest
+  #   mode of each fiber (a plain reduced CArray). To get the rectangular
+  #   mask-padded form, stack them: `CArray.stack(a.mode(axis: k), axis: k)`.
+  #   An all-masked array yields an empty Array.
+  #
+  #   Only meaningful for discrete / binned data: raw float is almost all
+  #   unique, so every value is modal and the per-axis Array grows to the
+  #   fiber length. Bin first. Same NaN / mask semantics as {#is_mode}.
+  #
+  #   @param axis [Integer, nil] axis to take the mode along; `nil` uses
+  #     the whole array.
+  #   @return [CArray, Array<CArray>] 1-D CArray (flat) or an Array of
+  #     reduced CArrays, one per mode rank (per-axis).
+  def mode (axis: nil)
+    return __mode_flat if axis.nil?
+    k = normalize_axis(axis, "mode")
+
+    # Numeric: the C frequency-table kernel emits the ragged Array<CArray>
+    # directly (reduced CArrays, self.shape with axis k dropped). A 1-D input
+    # reduces to length-1 CArrays, unwrapped to scalars like flat quantile.
+    unless data_type == CA_OBJECT || data_type == CA_FIXLEN
+      cols = __mode_axis__(k)
+      return ndim == 1 ? cols.map { |col| col[0] } : cols
+    end
+
+    # Object / fixlen (rare): per-fiber Ruby path, reusing the flat mode as the
+    # single source of what counts as a mode. Move axis k to the innermost
+    # position and fold the rest to one outer axis, so each row is a fiber.
+    perm = (0...ndim).to_a
+    perm.delete(k)
+    perm << k
+    a2    = (ndim == 1) ? self : transpose(*perm).copy   # (outer..., L)
+    outer = a2.shape[0...-1]
+    m     = outer.empty? ? 1 : outer.inject(:*)
+    flat2 = a2.reshape(m, a2.shape[-1])
+    lists = Array.new(m) { |r| flat2[r, nil].__send__(:__mode_flat).to_a }
+
+    # K = widest fiber's mode count. Emit K reduced CArrays (like quantile's
+    # per-axis Array<CArray>): slot j holds each fiber's j-th smallest mode,
+    # masked where a fiber has fewer than j+1 modes. Stack them to get the
+    # rectangular mask-padded form: CArray.stack(result, axis: k).
+    kk = lists.map(&:size).max || 0
+    (0...kk).map do |j|
+      # Take the column shape from self rather than building it from data_type:
+      # it carries the element width a fixlen array needs, and it keeps a Face
+      # (a time array), whose cells then accept the surface values in `lists`.
+      col = flat2[nil, 0].copy
+      col[] = UNDEF
+      m.times { |r| col[r] = lists[r][j] if j < lists[r].size }
+      outer.empty? ? col[0] : col.reshape(*outer)
+    end
+  end
+
+  private
+
+  # Flat mode: the distinct modal values ascending, 1-D CArray of self's dtype.
+  # The single source of what counts as a mode (per-axis reuses it per fiber).
+  # The distinct values with the maximum count, read from the frequency table
+  # (value_counts, which covers numeric / object / fixlen), then sorted
+  # ascending. value_counts already skips masked cells.
+  def __mode_flat
+    values, counts = value_counts
+    return values if values.elements == 0
+    values[counts.eq(counts.max)].sort
+  end
+
+end