carray 3.0.0 → 3.0.1

data/yard-stubs/ca_obj_field.rb

@@ -0,0 +1,45 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CArray#field defined in ext/ca_obj_field.c.  The CAField
+# class shell lives in yard-stubs/ruby_carray.rb.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Views
+
+  # @overload field(offset, data_type, bytes: nil)
+  #   Returns a {CAField} view of one field of a fixlen-record `self`.
+  #   The view has the same shape as `self`; each element is the
+  #   `bytes`-wide slice of element type `data_type` at byte `offset`
+  #   within the corresponding record.  No data is copied; writes go
+  #   through to `self`.
+  #   @param offset [Integer] byte offset of the field within one record.
+  #   @param data_type [Symbol, Integer] element type symbol or constant.
+  #     `:object` is not allowed.
+  #   @param bytes [Integer, nil] element size; required for `:fixlen`,
+  #     inferred otherwise.
+  #   @return [CAField]
+  #   @raise [RuntimeError] when `offset` is negative or the
+  #     `offset + bytes` window falls outside one parent record.
+  # @overload field(offset, template)
+  #   Returns a CARefer over a {CAField}: takes `template.elements *
+  #   template.bytes` bytes at `offset` and exposes them with
+  #   `template`'s element type and trailing shape.
+  #   @param offset [Integer]
+  #   @param template [CArray] element type and trailing shape donor.
+  #   @return [CArray]
+  # @overload field(offset, data_class)
+  #   Returns a `CARecord` wrapping a {CAField} so the result carries
+  #   `data_class`'s encode/decode dispatch.
+  #   @param offset [Integer]
+  #   @param data_class [Class] e.g. a CAStruct subclass.
+  #   @return [CArray]
+  # @overload field(name)
+  #   Returns the field named `name`.  Delegates to the parent's Face
+  #   layer (`rb_ca_face_field`); resolution depends on the record
+  #   schema attached to `self`.
+  #   @param name [Symbol, String]
+  #   @return [CArray]
+  def field(*); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_grid.rb

@@ -0,0 +1,35 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/ca_obj_grid.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+#
+# CAGrid itself is an internal (:nodoc:) view class; only the CArray#grid
+# entry point is user-facing.
+
+class CArray
+  # @!group Views
+  # @overload grid(*selectors)
+  #   Returns a coordinate-selected view of `self`: one selector per
+  #   axis picks a set of parent indices along that axis, and the view
+  #   is their Cartesian product.  The output size along axis `k` is the
+  #   number of indices selected for that axis.
+  #
+  #   Each selector is one of:
+  #   - `nil` — the whole axis, in order.
+  #   - an integer `Range` — a contiguous sub-range along the axis.
+  #   - a `CArray` of integer indices — gather exactly those parent
+  #     indices (arbitrary order; duplicates produce duplicated cells).
+  #   - a boolean `CArray` — the indices where it is true.
+  #
+  #   A masked index `CArray` selects only its not-masked cells.  The
+  #   view is writable; scattering back to overlapping cells (from
+  #   duplicate indices) is last-write-wins.
+  #
+  #   @param selectors [Array<nil, Range, CArray>] one selector per axis.
+  #   @return [CArray] the grid view.
+  #   @raise [ArgumentError] when more selectors than `ndim` are given.
+  #   @raise [IndexError] when a selected index is out of range.
+  #   @raise [RuntimeError] when a selector is a plain Ruby `Array`
+  #     (not supported; pass a CArray of indices instead).
+  def grid(*selectors); end
+  # @!endgroup
+end

data/yard-stubs/ca_obj_refer.rb

@@ -0,0 +1,72 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CArray#refer, #reshape, #flatten defined in ext/ca_obj_refer.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+#
+# The CARefer class shell lives in yard-stubs/ruby_carray.rb.
+
+class CArray
+  # @!group Views
+
+  # Returns a {CARefer} view of `self` — a strided reinterpretation
+  # of the parent's memory.  With no arguments the view has the same
+  # `data_type`, shape and `bytes` as `self`; the second form
+  # accepts a different `data_type` (or a data_class), and optional
+  # `bytes:` / `offset:` keywords so the view exposes the parent's
+  # bytes as elements of a different width.
+  #
+  # `bytes:` must divide `parent.bytes` (or vice versa) so element
+  # boundaries align.  `offset:` is measured in parent elements.
+  # The total byte extent of the view must fit inside `self`.
+  #
+  # When `data_type` is a data_class, the result is wrapped in a
+  # `CARecord` so field projection continues to work.
+  #
+  # @overload refer
+  #   @return [CARefer] a same-shape same-width alias of `self`.
+  # @overload refer(data_type, dim = nil, bytes: nil, offset: 0)
+  #   @param data_type [Integer, Symbol, Class] target data type or
+  #     a data_class.
+  #   @param dim [Array<Integer>, nil] target shape; `nil` reuses
+  #     `self.shape` (only valid when the byte width is unchanged).
+  #   @param bytes [Integer, nil] target byte width per element;
+  #     defaults to `self.bytes`.
+  #   @param offset [Integer] offset in parent elements.
+  #   @return [CARefer, CARecord]
+  #   @raise [RuntimeError] when the byte widths do not divide
+  #     evenly, when `offset` is negative, or when the requested
+  #     view extends past the parent's data.
+  #   @raise [RuntimeError] when reinterpreting a CA_OBJECT parent
+  #     with a non-object `data_type`.
+  def refer(*argv); end
+
+  # Returns a view of `self` with the requested shape.  Element
+  # count must match (`-1` or `:~` may stand in for one axis, whose
+  # size is inferred); `nil` copies the corresponding axis from
+  # `self`.  When the reshape can be expressed as strides over
+  # `self`'s deepest non-CAStride ancestor, the result is a
+  # {CAStride}; otherwise a {CARefer}.
+  #
+  # @overload reshape(*newdim)
+  #   @param newdim [Array<Integer, nil, Symbol>] target shape.
+  #     Integers are axis sizes; `nil` copies from `self` in
+  #     position order (mirrored from the end after the placeholder);
+  #     `-1` or `:~` marks the auto-infer placeholder (at most one).
+  #   @return [CArray] the reshape view.
+  #   @raise [ArgumentError] when the number of dims exceeds
+  #     `CA_RANK_MAX`.
+  #   @raise [RuntimeError] when the product does not equal
+  #     `self.elements` (with no placeholder), when the placeholder
+  #     cannot be inferred, when more than one placeholder is
+  #     given, or when a `nil` has no matching source axis.
+  def reshape(*newdim); end
+
+  # Returns a 1-D view of all cells in row-major order — a
+  # {CAStride} when the flatten reduces to pure strides over the
+  # deepest ancestor, otherwise a {CARefer}.
+  #
+  # @overload flatten
+  #   @return [CArray] the 1-D view.
+  def flatten; end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_roll.rb

@@ -0,0 +1,45 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CARoll and CArray#roll defined in ext/ca_obj_roll.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Cyclic-shift view of the parent.  Same shape as the parent; each
+# axis `k` is rotated by `shift[k]` cells (modulo `parent.dim[k]`).
+# All parent cells alias through the view exactly once, so writes
+# through the view reach the parent.
+#
+# `CARoll` is a `typedef` of {CATile}: the class hierarchy places it
+# under {CATile}, and the operation table is a copy of `ca_tile_func`
+# with the shift-specific slots overridden.
+class CARoll < CATile
+end
+
+# Mask companion of {CARoll}.
+# @private
+class CARollMask < CARoll
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CARoll} view of `self` cyclically shifted by
+  # `shifts[k]` along each axis `k`.  Positive shifts move cell `i`
+  # of the parent to position `i + shift`; negative shifts move it
+  # the other way.  Each `shift[k]` is normalised into
+  # `[0, self.dim[k])` before use, so any integer is accepted.
+  #
+  # Fewer args than `ndim` treats the missing axes as `shift = 0`.
+  # More args than `ndim` raises `ArgumentError`.
+  #
+  # The in-place idiom is `ca[] = ca.roll(...)`; there is no `roll!`.
+  # For a non-cyclic translation with a fill value use {#shift}.
+  #
+  # @overload roll(*shifts)
+  #   @param shifts [Array<Integer>] one shift per axis; may be
+  #     shorter than `ndim` (missing axes default to `0`).
+  #   @return [CARoll]
+  #   @raise [ArgumentError] when more than `ndim` shifts are given.
+  #   @raise [IndexError] when any parent dimension is non-positive.
+  def roll(*shifts); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_shift.rb

@@ -0,0 +1,43 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CAShift and CArray#shift defined in ext/ca_obj_shift.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Translated view of the parent along each axis.  Pure `CAWindow`
+# typedef: only the obj_type tag differs.  No data is copied; in-range
+# cells alias the parent, out-of-range cells take the fill value (or are
+# masked).
+class CAShift < CAWindow
+end
+
+# Mask companion of {CAShift}.
+# @private
+class CAShiftMask < CAShift
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CAShift} view of `self` translated by `shifts` along each
+  # axis (one shift per dimension; a positive shift moves cell `i` of the
+  # parent to position `i + shift`).  Out-of-range cells take `fill_value`
+  # (default `0`); passing `fill_value: UNDEF` masks them instead of
+  # filling.  In-range cells alias the parent, so writes through the view
+  # reach the parent.
+  #
+  # The in-place idiom is `ca[] = ca.shift(...)`; there is no `shift!`.
+  # For a cyclic (wrap-around) shift use {#roll}, which returns a `CARoll`
+  # view.
+  #
+  # @overload shift(*shifts, fill_value: 0)
+  #   @param shifts [Array<Integer>] one shift per axis; the count must
+  #     equal `self.ndim`.
+  #   @param fill_value [Object] value written to out-of-range cells;
+  #     `UNDEF` masks them instead.
+  #   @return [CAShift]
+  #   @raise [ArgumentError] when the number of shifts does not equal
+  #     `ndim`, when the removed `:roll` option is given, or when a block
+  #     is passed (the block form was removed in 3.0).
+  def shift(*shifts, fill_value: 0); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_stride.rb

@@ -0,0 +1,181 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CAStride and the CArray view constructors defined in
+# ext/ca_obj_stride.c.  See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Generic strided view of the parent: each cell is addressed as
+# `base_offset + Σ idx[k] * strides[k]` bytes from the parent's buffer, with
+# byte strides that may be negative or zero.  That is enough to express axis
+# permutation, reshape, stepped slicing and broadcasting, so most view
+# classes are CAStride subclasses and inherit its behaviour unchanged.
+class CAStride < CAView
+end
+
+# Mask companion of {CAStride}.
+# @private
+class CAStrideMask < CAStride
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CAStride} view of `self` with the given byte strides and
+  # starting byte offset, inheriting the receiver's data type and element
+  # size.  Memory is shared with the receiver.
+  #
+  # This is a low-level escape hatch: the strides and offset are **not**
+  # bounds-checked against the receiver's memory, so a combination that
+  # addresses outside it reads or writes past the buffer.  Prefer the
+  # derived constructors ({#sliding_windows}, {#block_view}, {#flip},
+  # {#diagonal}) when one of them expresses the layout.
+  #
+  # @overload as_strided(shape:, strides:, offset: 0)
+  #   @param shape [Array<Integer>] axis lengths.
+  #   @param strides [Array<Integer>] byte stride per axis, same length as
+  #     `shape`; negative values are allowed.
+  #   @param offset [Integer] byte offset from the receiver's buffer to the
+  #     `[0, ..., 0]` element.
+  #   @return [CAStride]
+  #   @raise [ArgumentError] when `shape:` or `strides:` is missing, when
+  #     their lengths differ, or when the rank is 0 or above `CA_RANK_MAX`.
+  def as_strided(shape:, strides:, offset: 0); end
+
+  # Returns a {CAStride} view of overlapping windows over every axis.  A
+  # parent of shape `[d0, ..., dN-1]` becomes a view of shape
+  # `[(d0-w0)/s0+1, ..., (dN-1-wN-1)/sN-1+1, w0, ..., wN-1]`, where `wi` is
+  # the window length on axis `i` and `si` the step.
+  #
+  # Truncate mode: a trailing partial window is dropped rather than padded.
+  # Memory is shared with the parent, and because windows overlap, one parent
+  # cell is visible from several positions of the view.
+  #
+  # Reduce over the trailing `ndim` axes for a rolling statistic.
+  #
+  # @overload sliding_windows(window, step: nil)
+  # @overload sliding_windows(w0, w1, ..., step: nil)
+  #   @param window [Array<Integer>, Integer] window length per axis, one per
+  #     dimension, as an Array or as variadic arguments.
+  #   @param step [Array<Integer>, Integer, nil] stride between windows per
+  #     axis; `nil` means 1 on every axis.
+  #   @return [CAStride] of rank `2 * ndim`.
+  #   @raise [ArgumentError] when the window count does not equal `ndim`,
+  #     when a window or step is not positive, when a window is longer than
+  #     its axis, or when `2 * ndim` exceeds `CA_RANK_MAX`.
+  def sliding_windows(*window, step: nil); end
+
+  # Returns a {CAStride} view of overlapping windows over the leading `S`
+  # axes, with the remaining `ndim - S` trailing axes riding along untouched
+  # at their original strides — {#sliding_windows} generalised to arrays that
+  # carry non-spatial dimensions such as channels.
+  #
+  # The window axes are inserted before the trailing axes, so the result rank
+  # is `ndim + S`.  With `S == ndim` there are no trailing axes and the
+  # result is identical to {#sliding_windows}.  Truncate mode; memory is
+  # shared with the parent.
+  #
+  # @overload unfold(window, step: nil)
+  # @overload unfold(w0, w1, ..., step: nil)
+  #   @param window [Array<Integer>, Integer] window length for each of the
+  #     leading axes; its size chooses how many axes are slid over.
+  #   @param step [Array<Integer>, Integer, nil] stride between windows;
+  #     `nil` means 1.
+  #   @return [CAStride] of rank `ndim + window.size`.
+  #   @raise [ArgumentError] when the window count is not between 1 and
+  #     `ndim`, when a window or step is not positive, when a window is
+  #     longer than its axis, or when `ndim + S` exceeds `CA_RANK_MAX`.
+  def unfold(*window, step: nil); end
+
+  # Returns a {CAStride} view of non-overlapping tiles.  A parent of shape
+  # `[d0, ..., dN-1]` becomes a view of shape
+  # `[d0/b0, ..., dN-1/bN-1, b0, ..., bN-1]`, where `bi` is the tile length
+  # on axis `i`.
+  #
+  # Unlike {#sliding_windows} each parent dimension must divide evenly by its
+  # tile size: nothing is truncated and no cell is aliased twice.  Reduce over
+  # the trailing `ndim` axes (e.g. `v.mean(-1, -2)` for a 2-D parent) for
+  # per-tile statistics such as pooling or block-wise aggregation.  Memory is
+  # shared with the parent.
+  #
+  # @overload block_view(block)
+  # @overload block_view(b0, b1, ...)
+  #   @param block [Array<Integer>, Integer] tile length per axis, one per
+  #     dimension, as an Array or as variadic arguments.
+  #   @return [CAStride] of rank `2 * ndim`.
+  #   @raise [ArgumentError] when the tile count does not equal `ndim`, when
+  #     a tile length is not positive, when an axis is not divisible by its
+  #     tile length, or when `2 * ndim` exceeds `CA_RANK_MAX`.
+  def block_view(*block); end
+
+  # Returns a `CATranspose` view in which the given axes are moved to the
+  # front, in the order given, with the remaining axes following in their
+  # original order — a thin alias over `transposed` that names the intent
+  # "bring these axes to the front, keep the rest as the inner slice".
+  #
+  # @example
+  #   a = CArray.float64(3, 4, 5).seq
+  #   a.dim_view(0, 2)    # shape [3, 5, 4]
+  #   a.dim_view(1)       # shape [4, 3, 5]
+  #   a.dim_view(-1)      # shape [5, 3, 4]
+  #
+  # @overload dim_view(axes)
+  # @overload dim_view(a0, a1, ...)
+  #   @param axes [Array<Integer>, Integer] axes to bring to the front;
+  #     negative indices count from the last axis.
+  #   @return [CATranspose]
+  #   @raise [ArgumentError] when no axis is given, when more axes are given
+  #     than `ndim`, or when an axis is out of range or repeated.
+  def dim_view(*axes); end
+
+  # Returns a {CAStride} view with the listed axes reversed (a negative
+  # stride on each); with no argument every axis is reversed.  Memory is
+  # shared with the parent, so writes through the view propagate.
+  #
+  # This is the named counterpart of the indexer form
+  # `ca[-1..0, nil, -1..0]` — both produce a true negative-stride view with
+  # no copy.  Use `flip` when the axis list is parametric or when the named
+  # intent reads better than the slice form.  There is no `flip!`; the
+  # in-place idiom is `ca[] = ca.flip`.
+  #
+  # `reverse` is an alias of `flip`.
+  #
+  # @example
+  #   a = CArray.float64(4, 5).seq
+  #   a.flip              # every axis reversed
+  #   a.flip(0)           # row order reversed
+  #   a.flip(-1)          # same as a.flip(1)
+  #   a.flip([0, 1])      # Array form
+  #
+  # @overload flip
+  # @overload flip(axis)
+  # @overload flip(a0, a1, ...)
+  # @overload flip([a0, a1, ...])
+  #   @param axis [Array<Integer>, Integer] axes to reverse; negative indices
+  #     count from the last axis.
+  #   @return [CAStride]
+  #   @raise [ArgumentError] when an axis is out of range or repeated.
+  def flip(*axis); end
+
+  # Returns a {CAStride} view of one diagonal of the parent.  For a 2-D
+  # parent of shape `[m, n]` this is a 1-D view of length
+  # `min(m, n - offset)` for `offset >= 0`, or `min(m + offset, n)` for
+  # `offset < 0`.
+  #
+  # For a higher-rank parent, the two axes named by `axis:` collapse into a
+  # single diagonal axis appended at the **end** of the result, and the
+  # remaining axes keep their order in front.  Memory is shared with the
+  # parent.
+  #
+  # @overload diagonal(offset = 0, axis: [0, 1])
+  #   @param offset [Integer] signed shift from the main diagonal; positive
+  #     selects a super-diagonal, negative a sub-diagonal.  An offset larger
+  #     than the relevant axis yields an empty view rather than an error.
+  #     May be passed positionally or as `offset:`, but not both.
+  #   @param axis [Array<Integer>] the two distinct axes to take the diagonal
+  #     over; negative indices count from the last axis.
+  #   @return [CAStride]
+  #   @raise [ArgumentError] when the parent has fewer than two dimensions,
+  #     when `offset` is given both positionally and as a keyword, or when
+  #     `axis:` is not two distinct in-range axes.
+  def diagonal(offset = 0, axis: [0, 1]); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_tile.rb

@@ -0,0 +1,29 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/ca_obj_tile.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Tiled repetition view.  Output shape is `parent.dim[k] * reps[k]`
+# along each axis; every tile is a full-parent alias, so writes to
+# overlapping cells are last-write-wins.
+class CATile < CAView
+end
+
+# Mask companion of {CATile}.
+# @private
+class CATileMask < CATile
+end
+
+class CArray
+  # @!group Views
+  # @overload tile(*reps)
+  #   Returns a {CATile} view of `self` tiled `reps[k]` times along
+  #   each axis `k`.  Accepts either positional args
+  #   (`a.tile(2, 3)`) or a single array (`a.tile([2, 3])`); the
+  #   number of reps must equal `ndim`.
+  #   @param reps [Array<Integer>] repetition count per axis.
+  #   @return [CATile]
+  #   @raise [ArgumentError] when the number of reps does not match `ndim`.
+  #   @raise [IndexError] when any `reps[k]` is not positive.
+  def tile(*reps); end
+  # @!endgroup
+end

data/yard-stubs/ca_obj_transpose.rb

@@ -0,0 +1,40 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CATranspose and CArray#transpose / #T defined in
+# ext/ca_obj_transpose.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Permuted-axis view of the parent.  Pure `CAStride` typedef: only
+# the dim / stride layout differs.  No data is copied; writes go
+# through to the parent.
+class CATranspose < CAStride
+end
+
+# Mask companion of {CATranspose}.
+# @private
+class CATransposeMask < CATranspose
+end
+
+class CArray
+  # @!group Views
+
+  # @overload transpose
+  #   Returns a {CATranspose} view of `self` with the dimension order
+  #   reversed (`view.shape[k] == self.shape[ndim-1-k]`).
+  #   @return [CATranspose]
+  # @overload transpose(*imap)
+  #   Returns a {CATranspose} view of `self` permuted by `imap`, a
+  #   permutation of `0 ... self.ndim`.  Element
+  #   `view[i_0, ..., i_{n-1}]` aliases parent element with axis `k`
+  #   sourced from `i` at position `imap[k]`.
+  #   @param imap [Array<Integer>] permutation of `0 ... ndim`.
+  #   @return [CATranspose]
+  #   @raise [ArgumentError] when `imap.length != ndim`.
+  #   @raise [RuntimeError] when an entry of `imap` is out of range
+  #     or duplicated.
+  def transpose(*imap); end
+
+  # Alias of {#transpose}.
+  def T(*imap); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_window.rb

@@ -0,0 +1,49 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CAWindow and CArray#window defined in ext/ca_obj_window.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Sliding rectangular view of the parent whose cells may fall outside it.
+# In-range cells alias the parent, out-of-range cells take the fill value
+# (or are masked).  {CAShift} is the same view expressed as a translation.
+class CAWindow < CAView
+end
+
+# Mask companion of {CAWindow}.
+# @private
+class CAWindowMask < CAWindow
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a {CAWindow} view of `self` covering `ranges` — one range per
+  # axis, which may extend past either end of the parent.  Cells inside the
+  # parent alias it, so writes through the view reach the parent; cells
+  # outside take `fill_value` (default `0`), and `fill_value: UNDEF` masks
+  # them instead.
+  #
+  # Only unit-step ranges are accepted, and each range must run forward, so
+  # the `0..-1` end-relative notation cannot be used here.
+  #
+  # @overload window(*ranges, fill_value: 0, bounds: "fill")
+  #   @param ranges [Array<Range, Integer>] one range per axis; the count
+  #     must equal `self.ndim`.
+  #   @param fill_value [Object] value given to out-of-range cells; `UNDEF`
+  #     masks them instead.
+  #   @param bounds [String] what an out-of-range index means: `"fill"`
+  #     (default) uses `fill_value`, `"nearest"` clamps to the edge cell,
+  #     `"ruby"` reads negative indices from the far end, `"strict"` raises.
+  #     `"mask"` masks the cell but warns — pass `fill_value: UNDEF` instead.
+  #   @return [CAWindow]
+  #   @raise [ArgumentError] when the number of ranges does not equal `ndim`,
+  #     when a range has a step other than 1 or runs backwards, when a block
+  #     is passed (the block form was removed in 3.0), or when `bounds` is
+  #     `"periodic"` / `"reflect"` (both removed in 3.0; use {#roll} for a
+  #     cyclic shift).
+  #   @raise [IndexError] when a range selects zero cells.
+  #   @raise [RuntimeError] when `bounds` conflicts with `fill_value: UNDEF`,
+  #     or when `bounds` is not a recognised value.
+  def window(*ranges, fill_value: 0, bounds: "fill"); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_access.rb

@@ -0,0 +1,131 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_access.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+#
+# The indexer surface (`[]` / `[]=`) is large; the per-form detail lives in
+# the user guides (see the @see links) rather than being duplicated here.
+
+class CArray
+  # @!group Indexing and slicing
+
+  # @overload [](*index)
+  #   Returns a view of `self` (or a single element) selected by one
+  #   `index` per axis.  Every array-returning form is a view onto the
+  #   original storage — writing through it reaches the source.
+  #
+  #   Accepted per-axis index forms:
+  #   - Integer — one position (negative counts from the end); an
+  #     all-Integer index returns the single element (masked -> UNDEF).
+  #   - `nil` — the whole axis.
+  #   - Range — a contiguous (or stepped, via a stepped Range) sub-range.
+  #   - boolean CArray — masked selection along that axis.
+  #   - Integer CArray — fancy gather (index array); shape follows the
+  #     index array.
+  #   - `:_` — newaxis: insert a size-1 axis at this position.
+  #   - `:*` / `:%` — repeat / tiling sugar.
+  #   - `:>` — slab axis: wrap the result in a `CASlabIterator`.
+  #   - a member name Symbol — project a struct field (see `CARecord`).
+  #
+  #   A single flat Integer (fewer indices than `ndim`) addresses the
+  #   array in row-major flat order.
+  #   @param index [Array<Integer, Range, nil, CArray, Symbol>] one entry
+  #     per axis (or a single flat address).
+  #   @return [CArray, Object] a view for a slicing form, or the element
+  #     value (or `UNDEF` if masked) for an all-scalar index.
+  #   @raise [IndexError] on an out-of-range index or an unrecognised form.
+  #   @see file:docs/drafts/02_indexing_and_slicing.md Indexing and slicing
+  #   @see file:docs/drafts/16_indexer_reference.md Indexer reference
+  def [](*index); end
+
+  # @overload []=(*index, value)
+  #   Sets the cells of `self` selected by `index` (same per-axis forms as
+  #   {#[]}) to `value`.  `value` may be a scalar (broadcast), an Array, or
+  #   a CArray whose element count matches the selection; assigning `UNDEF`
+  #   masks the selected cells.
+  #
+  #   Assignment through a slab iterator (`:>`) is not supported — use a
+  #   block index (e.g. `ca[range, nil] = val`) or `each_slab`.
+  #   @param index [Array<Integer, Range, nil, CArray, Symbol>] one entry
+  #     per axis (or a single flat address).
+  #   @param value [Object, Array, CArray] the value(s) to store, or
+  #     `UNDEF` to mask.
+  #   @return [Object] `value`.
+  #   @raise [IndexError] on an out-of-range index or an unsupported form.
+  #   @see file:docs/drafts/16_indexer_reference.md Indexer reference
+  def []=(*index, value); end
+
+  # @!endgroup
+
+  # @!group Indexing and slicing
+
+  # @overload fill(value)
+  #   Sets every element of `self` to `value` and clears any mask.
+  #   @param value [Object] the fill value.
+  #   @return [self]
+  def fill(value); end
+
+  # @overload fill_copy(value)
+  #   Returns a copy of `self` with every element set to `value`.
+  #   @param value [Object] the fill value.
+  #   @return [CArray] the filled copy.
+  def fill_copy(value); end
+
+  # @!endgroup
+
+  # @!group Index and address conversion
+
+  # @overload addr2index(addr)
+  #   Unravels a flat row-major address into per-axis indices, sized by
+  #   `self.shape`.  With an Integer `addr` returns N Integers; with a
+  #   CArray of addresses returns N CArrays of the same shape as `addr`
+  #   (mask propagated per cell).  In both cases the return is a Ruby
+  #   Array of length `self.ndim`, so `i, j = ca.addr2index(x)` unpacks
+  #   uniformly for scalar and vector inputs.
+  #   @param addr [Integer, CArray] a flat address in `0...elements`,
+  #     or a CArray of such addresses (arbitrary shape).
+  #   @return [Array<Integer>, Array<CArray>] one entry per axis.
+  #   @raise [ArgumentError] when any `addr` is out of range.
+  def addr2index(addr); end
+
+  # @overload index2addr(*index)
+  #   Folds per-axis indices into flat row-major address(es), using
+  #   `self.shape`.  With all-Integer indices returns a single Integer;
+  #   when any index is a CArray, returns a CArray of addresses whose
+  #   shape follows the first non-scalar input (other non-scalar inputs
+  #   must match that shape).  Mask propagates from the inputs.
+  #   @param index [Array<Integer, CArray>] one entry per axis.
+  #   @return [Integer, CArray] the flat address(es).
+  #   @raise [IndexError] on an out-of-range index.
+  #   @raise [ArgumentError] on shape mismatch between non-scalar inputs.
+  def index2addr(*index); end
+
+  # @overload addr2index(addr, shape:)
+  #   Class-form of {#addr2index} that takes an explicit `shape:` rather
+  #   than reading it from a receiver.  Useful for coordinate arithmetic
+  #   without allocating a template CArray.
+  #   @param addr [Integer, CArray] a flat address or a CArray of them.
+  #   @param shape [Array<Integer>] the row-major shape defining the grid.
+  #   @return [Array<Integer>, Array<CArray>] one entry per axis.
+  #   @raise [ArgumentError] when any `addr` is out of range or `shape:`
+  #     is missing.
+  def self.addr2index(addr, shape:); end
+
+  # @overload index2addr(*index, shape:)
+  #   Class-form of {#index2addr}.
+  #   @param index [Array<Integer, CArray>] one entry per axis.
+  #   @param shape [Array<Integer>] the row-major shape defining the grid.
+  #   @return [Integer, CArray] the flat address(es).
+  #   @raise [ArgumentError] on out-of-range index, shape mismatch, or
+  #     missing `shape:`.
+  def self.index2addr(*index, shape:); end
+
+  # @overload normalize_index(idx)
+  #   Returns a canonical form of the index array `idx` classified against
+  #   `self`'s shape (scalars normalised, `nil` for whole axes, `[start,
+  #   count, step]` for blocks).  Used to inspect how an index resolves.
+  #   @param idx [Array] the raw index spec.
+  #   @return [Array] the normalised per-axis index.
+  def normalize_index(idx); end
+
+  # @!endgroup
+end