carray 3.0.0 → 3.0.1

data/yard-stubs/carray_copy.rb

@@ -0,0 +1,79 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_copy.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Copy and conversion
+
+  # @overload copy
+  #   Returns a fresh entity CArray with the same shape, `data_type`,
+  #   element values, and mask state as `self`. Always allocates and
+  #   copies, even when `self` is already an entity.
+  #
+  #   Use `copy` when you need an array you own and can mutate
+  #   without affecting any source.
+  #   @return [CArray] independent entity.
+  #   @example A view's copy is independent of its source
+  #     a = CArray.float64(4).seq
+  #     v = a[1..2]
+  #     b = v.copy
+  #     b[0] = 99
+  #     a   # => [0.0, 1.0, 2.0, 3.0]   # untouched
+  def copy; end
+
+  # @overload to_ca(writable: false)
+  #   Returns `self` as a CArray, doing the least work possible.
+  #
+  #   For a CArray (entity or data view), `to_ca` returns `self`
+  #   unchanged — **no copy is made**. Use {#copy} when you need an
+  #   independent owned array. Mutating the result of `to_ca` may
+  #   therefore mutate the source.
+  #
+  #   `to_ca` is the universal "give me a CArray" entry point. It is
+  #   also defined on `Array` / `Range` / `Enumerator::ArithmeticSequence`
+  #   (each builds a 1-D CArray) and on lazy views (`CAMonOp`, `CABinOp`,
+  #   …) where it forces evaluation into a fresh entity.
+  #
+  #   Because it converts as cheaply as it can — sharing storage where it
+  #   can, copying where it must — the result alone does not tell you
+  #   whether writes to it reach the source. `writable: true` is how a
+  #   caller states that they do have to: an implementation that can only
+  #   hand back a detached copy raises instead of returning one, so a
+  #   write is never swallowed silently. For a CArray, `self` shares its
+  #   storage by construction, so the only refusal here is a read-only
+  #   receiver. This is the contract {CArray.wrap_writable} duck-types on.
+  #   @param writable [Boolean] when true, demand a result whose writes
+  #     reach the source.
+  #   @return [CArray] `self` (no copy).
+  #   @raise [RuntimeError] when `writable: true` and `self` is read-only.
+  def to_ca(writable: false); end
+
+  # @overload template
+  #   Returns a freshly allocated CArray with the same shape and
+  #   `data_type` as `self`, filled with zeros. The new array is an
+  #   entity and carries no mask.
+  #   @return [CArray]
+  # @overload template(data_type, bytes: 0)
+  #   Returns a freshly allocated CArray with the same shape as
+  #   `self` but the given `data_type`, filled with zeros.
+  #   @param data_type [Symbol] target element type
+  #     (e.g. `:int32`, `:float64`, `:fixlen`).
+  #   @param bytes [Integer] element byte size; required for
+  #     `:fixlen`, ignored for numeric types.
+  #   @return [CArray]
+  # @overload template { value }
+  #   With a 0-arity block, fills every element of the result with
+  #   the block's return value (broadcast). Equivalent to
+  #   `template.tap { |t| t[] = value }`.
+  #   @yieldreturn [Object] value to broadcast to every element.
+  #   @return [CArray]
+  # @overload template { |*idx| ... }
+  #   With a block of arity > 0, calls the block once per cell with
+  #   the multi-dimensional index `*idx` and stores the result.
+  #   @yieldparam idx [Array<Integer>] per-axis indices.
+  #   @yieldreturn [Object]
+  #   @return [CArray]
+  def template(*, **, &block); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_core.rb

@@ -0,0 +1,114 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_core.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Attach lifecycle
+  #
+  # The `attach` / `attach!` family is an internal lifecycle API used
+  # by library authors writing CArray-aware C extensions. End users
+  # should not normally need to call these methods — view algebra and
+  # `CArray#[]` / `[]=` handle attach/sync transparently.
+  #
+  # The block-form `attach` (no sync on exit) and `attach!` (sync on
+  # exit) wrap a body of code so that the underlying memory block is
+  # guaranteed to be materialized while the block runs and is
+  # released afterward. The dunder forms (`__attach__`, `__sync__`,
+  # `__detach__`) expose the raw three-step protocol for callers that
+  # cannot use a block.
+
+  # @overload attach { ... }
+  #   Attaches `self`, yields, and detaches on block exit. No sync
+  #   is performed.
+  #   @yield
+  #   @return [Object] the block's return value.
+  def attach; end
+
+  # @overload attach! { ... }
+  #   Attaches `self`, yields, then syncs and detaches on block exit.
+  #   Use this form when the block mutates `self.ptr` and you need
+  #   the changes flushed back to the parent.
+  #   @yield
+  #   @return [Object] the block's return value.
+  def attach!; end
+
+  # @private
+  # @overload __attach__
+  #   Raw attach: materializes the memory block of `self` and leaves
+  #   it attached. Caller is responsible for the matching
+  #   `__detach__` (and `__sync__`, if changes were made).
+  #
+  #   Prefer the block form {#attach!} unless block scope is
+  #   impossible.
+  #   @return [self]
+  #   @api private
+  def __attach__; end
+
+  # @private
+  # @overload __sync__
+  #   Raw sync: writes any pending changes in `self.ptr` back to the
+  #   parent. Requires `self` to be currently attached.
+  #   @return [self]
+  #   @api private
+  def __sync__; end
+
+  # @private
+  # @overload __detach__
+  #   Raw detach: releases the memory block paired with `__attach__`.
+  #   @return [self]
+  #   @api private
+  def __detach__; end
+
+  # @!endgroup
+
+  # @!group Attributes
+
+  # @overload members
+  #   Returns the ordered list of member names for `self.data_class`.
+  #   Only valid when `self` carries a `data_class` (e.g. a
+  #   `CARecord`).
+  #   @return [Array<Symbol>]
+  #   @raise [RuntimeError] if `self` has no `data_class`.
+  def members; end
+
+  # @overload fields
+  #   Returns one field view per member of `self.data_class`, in
+  #   declaration order. Each entry is a CArray sharing storage with
+  #   `self`.
+  #   @return [Array<CArray>]
+  #   @raise [RuntimeError] if `self` has no `data_class`.
+  def fields; end
+
+  # @overload fields_at(*names)
+  #   Returns the field views for the named members of
+  #   `self.data_class`, in the given order.
+  #   @param names [Array<Symbol, String, Integer>] member names or
+  #     positional indices.
+  #   @return [Array<CArray>]
+  #   @raise [RuntimeError] if `self` has no `data_class`.
+  def fields_at(*names); end
+
+  # @!endgroup
+
+  class << self
+    # @!group Attach lifecycle
+
+    # @overload attach(*arrays) { ... }
+    #   Attaches every CArray in `arrays`, yields, and detaches them
+    #   in reverse order on block exit. No sync is performed.
+    #   @param arrays [Array<CArray>]
+    #   @yield
+    #   @return [Object] the block's return value.
+    def attach(*arrays); end
+
+    # @overload attach!(*arrays) { ... }
+    #   Attaches every CArray in `arrays`, yields, then syncs and
+    #   detaches each on block exit.
+    #   @param arrays [Array<CArray>]
+    #   @yield
+    #   @return [Object] the block's return value.
+    def attach!(*arrays); end
+
+    # @!endgroup
+  end
+end

data/yard-stubs/carray_count.rb

@@ -0,0 +1,79 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stub for CArray#count defined in ext/carray_count.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Statistics
+
+  # @overload count(axis: nil)
+  #   With no value argument, returns the number of present (not-masked)
+  #   cells — the arity-0 rung of the dispatch ladder, answering "how
+  #   many are there".  Forwards to {#count_not_masked} (which stays as
+  #   an explicit, self-documenting named method).
+  #
+  #   @param axis [Integer, Array<Integer>, nil] reduction axis or
+  #     axes; `nil` reduces fully.
+  #   @return [Integer, CArray] `Integer` when `axis` is `nil`,
+  #     otherwise a `CArray` of int64 with the given axes collapsed.
+  #
+  # @overload count(v, axis: nil, min_count: 0, fill_value: nil)
+  #   Returns the number of cells of `self` that equal `v`, with
+  #   mask-aware reduction along `axis`.
+  #
+  #   `count` is an orthogonal arity-dispatch ladder (like Ruby's
+  #   `Array#count`): no argument counts present cells, `count(UNDEF)`
+  #   counts masked cells, and `count(v)` counts cells equal to `v`.
+  #   Mask-cardinality and value-match are distinct concepts, so the
+  #   overloading is unambiguous.
+  #
+  #   Dispatch:
+  #   - no argument: forwards to {#count_not_masked} (present-cell
+  #     count).
+  #   - `v == UNDEF`: forwards to {#count_masked} (UNDEF is mask-state
+  #     vocabulary, not a value).
+  #   - `v` is a CArray: broadcasts; each `v[k]` is counted
+  #     independently and stacked into a result whose trailing axes
+  #     have shape `v.shape`.  Not supported when `self.data_type` is
+  #     `:boolean`.
+  #   - `self.data_type == :boolean`: `v` must be `true` / `false`, or
+  #     the integer literal `1` (= true) / `0` (= false) — boolean
+  #     stores 0/1, so `count(1)` == `count(true)`.  Any other value
+  #     (`2`, `1.0`, `nil`, …) raises `TypeError`.
+  #   - `self` is numeric, `v` is scalar: `v` must be numeric (true /
+  #     false are rejected).
+  #
+  #   When `axis` is `nil` (default), reduces over all axes and
+  #   returns an `Integer`.  Otherwise reduces along the given
+  #   axis / axes and returns a `CArray`.
+  #
+  #   An empty or fully-masked reduction returns `0`: a count has
+  #   identity `0`, so the count over no cells is `0`, not `UNDEF`
+  #   (pass `min_count:` to get `UNDEF` below a threshold instead).
+  #
+  #   `:fixlen` and `:object` data types raise `CArray::DataTypeError`.
+  #
+  #   A time array counts by its own values: `CATime` / `CATimedelta`
+  #   descend to their storage and reconcile `v` into their unit, so `v`
+  #   may be an element of the array, another time array (in any unit that
+  #   converts exactly), or a Ruby `Time` / `DateTime`.  A bare storage
+  #   number is refused — use `ca.parent.count(n)` to count raw ticks.
+  #
+  #   @param v [Object, CArray] value (or array of values) to count.
+  #     `UNDEF` is treated as a mask-state query.
+  #   @param axis [Integer, Array<Integer>, nil] reduction axis or
+  #     axes; `nil` reduces fully.
+  #   @param min_count [Integer] minimum number of non-masked cells
+  #     required per reduced slice; slices below the threshold come
+  #     back masked.  Accepted only by the value-argument form
+  #     (`count(v)`); the no-argument form accepts `axis:` only.
+  #   @param fill_value [Object, nil] replacement for masked output
+  #     cells; `nil` leaves them masked.  Value-argument form only.
+  #   @return [Integer, CArray]
+  #   @raise [TypeError] when `v`'s type does not match the dispatch
+  #     rule above.
+  #   @raise [CArray::DataTypeError] when `self.data_type` is
+  #     `:fixlen` or `:object`.
+  def count(*args, axis: nil, min_count: 0, fill_value: nil); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_element.rb

@@ -0,0 +1,108 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_element.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Element access
+  #
+  # `elem_*` methods are low-level single-cell operations. They
+  # accept `idx` as either an Integer (flat address into the
+  # row-major element sequence) or an `Array<Integer>` (one index
+  # per axis). They bypass the broadcasting and view-construction
+  # paths used by `[]` / `[]=`, and are the right tool for
+  # tight per-cell loops where allocation matters.
+
+  # @overload elem_swap(idx1, idx2)
+  #   Exchanges the values (and mask states, if any) at positions
+  #   `idx1` and `idx2`. Mutates `self`.
+  #   @param idx1 [Integer, Array<Integer>]
+  #   @param idx2 [Integer, Array<Integer>]
+  #   @return [self]
+  def elem_swap(idx1, idx2); end
+
+  # @overload elem_copy(idx1, idx2)
+  #   Copies the value (and mask state) at `idx1` into the cell at
+  #   `idx2`. The source cell is unchanged. Mutates `self`.
+  #   @param idx1 [Integer, Array<Integer>] source position.
+  #   @param idx2 [Integer, Array<Integer>] destination position.
+  #   @return [self]
+  def elem_copy(idx1, idx2); end
+
+  # @overload elem_store(idx, value)
+  #   Stores `value` (cast to `self.data_type`) at position `idx`,
+  #   clearing the mask state at that cell. Passing `UNDEF` masks
+  #   the cell.
+  #   @param idx [Integer, Array<Integer>]
+  #   @param value [Object]
+  #   @return [Object] `value`.
+  def elem_store(idx, value); end
+
+  # @overload elem_fetch(idx)
+  #   Returns the value at position `idx` (cast back to the
+  #   appropriate Ruby type). Returns `UNDEF` if the cell is masked.
+  #   Returns `nil` if `self.empty?`.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [Object, nil]
+  def elem_fetch(idx); end
+
+  # @overload elem_incr(idx)
+  #   Increments the value at `idx` by 1 in place. Mutates `self`.
+  #   Masked cells are skipped.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [self]
+  def elem_incr(idx); end
+
+  # @overload elem_decr(idx)
+  #   Decrements the value at `idx` by 1 in place. Mutates `self`.
+  #   Masked cells are skipped.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [self]
+  def elem_decr(idx); end
+
+  # @overload elem_min(idx, v)
+  #   Updates the cell at `idx` to `min(self[idx], v)`. Mutates `self`.
+  #
+  #   Masked cells are skipped. NaN follows the `fmin` rule (NaN is
+  #   treated as missing: `min(NaN, v) == v`, `min(x, NaN) == x`).
+  #   @param idx [Integer, Array<Integer>]
+  #   @param v [Numeric]
+  #   @return [self]
+  #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
+  def elem_min(idx, v); end
+
+  # @overload elem_max(idx, v)
+  #   Updates the cell at `idx` to `max(self[idx], v)`. Mutates `self`.
+  #
+  #   Masked cells are skipped. NaN follows the `fmax` rule.
+  #   @param idx [Integer, Array<Integer>]
+  #   @param v [Numeric]
+  #   @return [self]
+  #   @raise [CArray::DataTypeError] for non-numeric `data_type`.
+  def elem_max(idx, v); end
+
+  # @!endgroup
+
+  # @!group Element access
+
+  # @overload elem_masked?(idx)
+  #   Returns `true` if the cell at `idx` is masked.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [Boolean]
+  def elem_masked?(idx); end
+
+  # @overload elem_mask(idx)
+  #   Marks the cell at `idx` as masked. Allocates the mask array if
+  #   `self` does not yet have one. Mutates `self`.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [self]
+  def elem_mask(idx); end
+
+  # @overload elem_unmask(idx)
+  #   Clears the mask state at `idx`, leaving the stored data
+  #   unchanged. Mutates `self`.
+  #   @param idx [Integer, Array<Integer>]
+  #   @return [self]
+  def elem_unmask(idx); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_generate.rb

@@ -0,0 +1,66 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_generate.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Scatter and generation
+
+  # @overload where
+  #   Returns a fresh 1-D CArray of flat addresses where `self` is
+  #   non-zero (or `true`). Masked positions are excluded.
+  #   Non-boolean arrays are first coerced to boolean.
+  #   @return [CArray] 1-D, `:int64` (`ca_size_t`).
+  #   @example
+  #     CArray.int32(5) { [0, 1, 0, 2, 0] }.where.to_a
+  #     # => [1, 3]
+  def where; end
+
+  # @!endgroup
+
+  # @!group Scatter and generation
+
+  # @overload seq!
+  #   Fills `self` in row-major order with `0, 1, 2, ...`. Mutates
+  #   `self` and clears any mask.
+  #   @return [self]
+  # @overload seq!(init_val)
+  #   Fills `self` in row-major order with `init_val`, `init_val + 1`,
+  #   `init_val + 2`, ... Mutates `self`.
+  #   @param init_val [Numeric]
+  #   @return [self]
+  # @overload seq!(init_val, step)
+  #   Fills `self` in row-major order with `init_val`, `init_val +
+  #   step`, `init_val + 2*step`, ...
+  #
+  #   For `:object` arrays only, `step` may be a Symbol naming the
+  #   stepping method to invoke on the previous element (e.g. `:succ`).
+  #   @param init_val [Numeric, Object]
+  #   @param step [Numeric, Symbol]
+  #   @return [self]
+  # @overload seq!(init_val = 0, step = 1, axis:)
+  #   Fills `self` with a progression that runs along `axis` and repeats
+  #   across the other axes: the cell value depends only on its
+  #   coordinate along `axis`. `axis` must be a single integer (a
+  #   negative value counts from the end); multi-axis fills are not
+  #   supported.
+  #   @param init_val [Numeric, Object]
+  #   @param step [Numeric, Symbol]
+  #   @param axis [Integer] the axis the progression runs along.
+  #   @return [self]
+  #   @raise [ArgumentError] if `axis` is out of range or not a single
+  #     integer.
+  def seq!(*); end
+
+  # @overload seq(init_val = 0, step = 1, axis: nil)
+  #   Equivalent to `dup.seq!(init_val, step, axis: axis)`. Returns a
+  #   fresh array of the same shape and `data_type` as `self`, filled
+  #   with a sequence (flat by default, or along `axis` when given).
+  #   @param init_val [Numeric, Object]
+  #   @param step [Numeric, Symbol]
+  #   @param axis [Integer, nil] the axis the progression runs along,
+  #     or `nil` for a flat row-major fill.
+  #   @return [CArray]
+  def seq(*); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_lazy.rb

@@ -0,0 +1,23 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_lazy.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Zero-cost marker view that dispatches subsequent element-wise ops
+# into the lazy CAMonOp / CABinOp tree instead of evaluating eagerly.
+# Read-only; `.to_ca` materialises.
+class CALazyMarker < CAView
+end
+
+class CArray
+  # @!group Views
+  # @overload lazy
+  #   Returns a {CALazyMarker} view wrapping `self`.  Subsequent
+  #   element-wise ops on the marker (`m.sqrt`, `m + 1`, ...) build
+  #   a lazy expression tree; call `.to_ca` on the result to
+  #   materialise.  The marker is transient — a Ruby reference can
+  #   re-consume it (`m = a.lazy; m.sqrt + m.sin`) without side
+  #   effects on `self`.
+  #   @return [CALazyMarker]
+  def lazy; end
+  # @!endgroup
+end

data/yard-stubs/carray_loop.rb

@@ -0,0 +1,140 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_loop.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Iteration
+
+  # @overload each
+  #   Yields each element of `self` once in row-major (flat address)
+  #   order. Returns an Enumerator when no block is given.
+  #   @yieldparam elem [Object]
+  #   @return [self, Enumerator]
+  def each; end
+
+  # @overload each_addr
+  #   Yields each flat address `0...elements` once. Returns an
+  #   Enumerator when no block is given.
+  #   @yieldparam addr [Integer]
+  #   @return [self, Enumerator]
+  def each_addr; end
+
+  # @overload each_index
+  #   Yields each multi-dimensional index of `self` once in row-major
+  #   order.  Block receives one Integer per axis (variadic, not a
+  #   single Array); use `|*idx|` to collect them.  Returns an
+  #   Enumerator when no block is given.
+  #   @yieldparam idx [Integer] one Integer per axis.
+  #   @return [self, Enumerator]
+  def each_index; end
+
+  # @overload each_with_addr
+  #   Yields each `(element, flat-address)` pair in row-major order.
+  #   Returns an Enumerator when no block is given.
+  #   @yieldparam elem [Object]
+  #   @yieldparam addr [Integer]
+  #   @return [self, Enumerator]
+  def each_with_addr; end
+
+  # @overload each_with_index
+  #   Yields each element followed by its multi-dimensional index
+  #   components in row-major order.  Block signature is
+  #   `|elem, i, j, ...|` (one Integer per axis, not a single Array);
+  #   use `|elem, *idx|` to collect them.  Returns an Enumerator when
+  #   no block is given.
+  #   @yieldparam elem [Object]
+  #   @yieldparam idx [Integer] one Integer per axis.
+  #   @return [self, Enumerator]
+  def each_with_index; end
+
+  # @!endgroup
+
+  # @!group Iteration
+
+  # @overload map!
+  #   Replaces each element of `self` with the block's return value.
+  #   Mutates `self`.
+  #   @yieldparam elem [Object]
+  #   @yieldreturn [Object] new value for the cell.
+  #   @return [self]
+  def map!; end
+
+  # @overload map_addr!
+  #   Replaces each element of `self` with the block's return value;
+  #   the block receives the flat address rather than the current
+  #   value. Mutates `self`.
+  #   @yieldparam addr [Integer]
+  #   @yieldreturn [Object]
+  #   @return [self]
+  def map_addr!; end
+
+  # @overload map_index!
+  #   Replaces each element of `self` with the block's return value;
+  #   the block receives the multi-dimensional index components
+  #   (`|i, j, ...|`, one Integer per axis; use `|*idx|` to collect
+  #   them) rather than the current value.  Mutates `self`.
+  #   @yieldparam idx [Integer] one Integer per axis.
+  #   @yieldreturn [Object]
+  #   @return [self]
+  def map_index!; end
+
+  # @overload map_with_addr!
+  #   Replaces each element of `self` with the block's return value;
+  #   the block receives `(element, flat-address)`. Mutates `self`.
+  #   @yieldparam elem [Object]
+  #   @yieldparam addr [Integer]
+  #   @yieldreturn [Object]
+  #   @return [self]
+  def map_with_addr!; end
+
+  # @overload map_with_index!
+  #   Replaces each element of `self` with the block's return value;
+  #   the block receives the element followed by its multi-dim index
+  #   components (`|elem, i, j, ...|`; use `|elem, *idx|` to collect
+  #   the index).  Mutates `self`.
+  #   @yieldparam elem [Object]
+  #   @yieldparam idx [Integer] one Integer per axis.
+  #   @yieldreturn [Object]
+  #   @return [self]
+  def map_with_index!; end
+
+  # @overload collect!
+  #   Alias of {#map!}.
+  def collect!; end
+
+  # @overload collect_addr!
+  #   Alias of {#map_addr!}.
+  def collect_addr!; end
+
+  # @overload collect_index!
+  #   Alias of {#map_index!}.
+  def collect_index!; end
+
+  # @overload collect_with_addr!
+  #   Alias of {#map_with_addr!}.
+  def collect_with_addr!; end
+
+  # @overload collect_with_index!
+  #   Alias of {#map_with_index!}.
+  def collect_with_index!; end
+
+  # @!endgroup
+
+  class << self
+    # @!group Iteration
+
+    # @overload each_index(*shape) { |*idx| ... }
+    #   Yields each multi-dimensional index inside the box `0...d`
+    #   for each `d` in `shape`, in row-major order. Independent of
+    #   any CArray instance.
+    #   @param shape [Array<Integer>] one extent per axis.
+    #   @yieldparam idx [Array<Integer>] one index per axis.
+    #   @return [Object] the block's last return value.
+    #   @example
+    #     CArray.each_index(3, 2) { |i, j| print "(#{i} #{j}) " }
+    #     # (0 0) (0 1) (1 0) (1 1) (2 0) (2 1)
+    def each_index(*shape); end
+
+    # @!endgroup
+  end
+end