carray 2.0.1 → 3.0.1

data/yard-stubs/ca_obj_byte_swap.rb

@@ -0,0 +1,56 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CAByteSwap and CArray#swap_bytes / #endian defined in
+# ext/ca_obj_byte_swap.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Byte-order-reversed view of the parent.  Same shape and byte
+# width as the parent; each cell exposes the byte-reversed
+# interpretation.  For primitive numeric parents `CArray#swap_bytes`
+# routes through `CAMonOp` instead, so a CAByteSwap instance is
+# usually seen only for `CA_FIXLEN` parents.
+#
+# Writes through the view flow back to the parent on detach
+# (byte-swap is involutive).
+class CAByteSwap < CAView
+end
+
+class CArray
+  # @!group Views
+
+  # Returns a lazy view of `self` whose cells are byte-swapped
+  # versions of the parent cells.  Materialises on attach.
+  # Primitive numeric parents get a `CAMonOp` view; `CA_FIXLEN`
+  # parents (with or without a data_class) get a {CAByteSwap} view.
+  #
+  # For eager copy semantics use `arr.swap_bytes.to_ca`.  The
+  # in-place idiom is `ca[] = ca.swap_bytes`; there is no
+  # `swap_bytes!`.
+  #
+  # @overload swap_bytes
+  #   @return [CArray] byte-swapped view of `self`.
+  #   @raise [CADataTypeError] when `self.data_type` is `CA_OBJECT`
+  #     (object arrays cannot be byte-swapped).
+  def swap_bytes; end
+
+  # Returns a view of `self` in the requested byte order.
+  #
+  # `byte_order` is one of:
+  # - `:preserve` / `:native` — identity, since CArrays are stored
+  #   host-endian.
+  # - `:big` — identity on big-endian hosts, otherwise a byte-swap
+  #   view.
+  # - `:little` — identity on little-endian hosts, otherwise a
+  #   byte-swap view.
+  #
+  # The keyword set matches `BulkMemoryView.from(producer, endian:)`.
+  #
+  # @overload endian(byte_order)
+  #   @param byte_order [Symbol] one of `:preserve`, `:native`,
+  #     `:big`, `:little`.
+  #   @return [CArray] `self` or a byte-swap view.
+  #   @raise [ArgumentError] when `byte_order` is not one of the
+  #     accepted symbols.
+  def endian(byte_order); end
+
+  # @!endgroup
+end

data/yard-stubs/ca_obj_fake.rb

@@ -0,0 +1,31 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/ca_obj_fake.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# CAFace-family data_type reinterpret view.  Presents its parent with a
+# different `data_type` (and, for `:fixlen`, a different `bytes`);
+# reads and writes cast on the fly.  Storage is shared with the
+# parent.
+class CAFake < CAView
+end
+
+class CArray
+  # @!group Views
+  # @overload fake(data_type, bytes: 0)
+  #   Returns a {CAFake} view of `self` whose element type is
+  #   `data_type` (and `bytes:` for `:fixlen`).  Reads and writes go
+  #   through the cast table, so the returned view shares storage
+  #   with `self` but exposes it under a different data_type.
+  #   A Face refuses: its cells do not mean their storage bytes, so
+  #   reading them under another type hands back what the surface exists to
+  #   hide. Use {CArray#to_type} for the values, or `face.parent.fake` to
+  #   reinterpret the storage on purpose. A Numeric Face, whose surface *is*
+  #   its storage, is unaffected.
+  #   @param data_type [Symbol, Integer, Class, String]
+  #   @param bytes [Integer] element byte size for `:fixlen`.
+  #   @return [CAFake]
+  #   @raise [TypeError] when `self` is a Face and the request would read its
+  #     storage under another type.
+  def fake(data_type, bytes: 0); end
+  # @!endgroup
+end

data/yard-stubs/ca_obj_farray.rb

@@ -0,0 +1,32 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for CAFarray and CArray#farray defined in ext/ca_obj_farray.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Column-major (Fortran-order) view of a row-major parent.  Pure
+# `CAStride` typedef: the parent's bytes are reread with dimension
+# order reversed (`view.shape[k] == parent.shape[ndim-1-k]`).  No
+# data is copied; writes go through to the parent.
+class CAFarray < CAStride
+end
+
+# Mask companion of {CAFarray}.
+# @private
+class CAFarrayMask < CAFarray
+end
+
+class CArray
+  # @!group Views
+
+  # @overload farray
+  #   Returns a {CAFarray} view of `self` that exposes the same memory
+  #   in column-major (Fortran) order.  The shape is `self.shape`
+  #   reversed; element `view[i_0, ..., i_{n-1}]` aliases parent
+  #   element `self[i_{n-1}, ..., i_0]`.
+  #
+  #   Useful for interop with column-major consumers (LAPACK, Fortran
+  #   libraries) without copying.
+  #   @return [CAFarray]
+  def farray; end
+
+  # @!endgroup
+end

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