carray 3.0.1 → 3.0.2

data/lib/carray/window_iterator.rb

@@ -83,10 +83,10 @@ class CAWindowIterator < CAIterator
   def initialize (source, *ranges, bounds: :skip, fill_value: nil)
     if source.is_a?(CArray) && source.obj_type == CA_OBJ_WINDOW
       # Backward-compat: read geometry from a CAWindow view built by #window.
-      # start[i] = lo, dim[i] (window width) = w, so hi = lo + w - 1.
+      # start[i] = lo, shape[i] (window width) = w, so hi = lo + w - 1.
       win     = source
       @source = win.parent
-      widths  = win.count
+      widths  = win.shape
       @ranges = win.start.each_with_index.map { |lo, i| lo..(lo + widths[i] - 1) }
       # The legacy #window default is FILL (constant), whose value is the
       # view's fill_value; map that to a :constant margin.
@@ -298,19 +298,113 @@ class CAWindowIterator < CAIterator
   # unchanged.  `min_count:` / `fill_value:` pass straight to the core (the
   # boundary strictness + result fill knobs).
 
-  # @overload sum(min_count: nil, fill_value: nil)
-  #   Rolling sum, delegating to `sliding_view.sum(axis: window_axes)`.
+  # @!method sum(min_count: nil, fill_value: nil)
+  #   Rolling sum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
   #   @return [CArray] reference-shaped (or shrunk, for :truncate)
-  # @overload accumulate(min_count: nil, fill_value: nil)
-  #   Rolling sum in the source's own data type, wrapping at its width, as the
-  #   core `accumulate` does.  `sum` answers in the type the core promotes to
-  #   (float64 for integers), which for a window over bytes moves eight times
-  #   the bytes; this is the spelling for staying in the type when the window
-  #   cannot overflow it.
+  # @!method accumulate(min_count: nil, fill_value: nil)
+  #   Rolling sum kept in the source's own data type, wrapping at its
+  #   width, as the core `accumulate` does -- `sum` answers in the type
+  #   the core promotes to (float64 for integers).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method prod(min_count: nil, fill_value: nil)
+  #   Rolling product.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method mean(min_count: nil, fill_value: nil)
+  #   Rolling arithmetic mean.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method min(min_count: nil, fill_value: nil)
+  #   Rolling minimum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method max(min_count: nil, fill_value: nil)
+  #   Rolling maximum.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method variance(min_count: nil, fill_value: nil)
+  #   Rolling sample variance (divisor `n - 1`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method stddev(min_count: nil, fill_value: nil)
+  #   Rolling sample standard deviation (divisor `n - 1`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method all(min_count: nil, fill_value: nil)
+  #   Whether every cell of each rolling is true.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method any(min_count: nil, fill_value: nil)
+  #   Whether any cell of each rolling is true.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method variancep(min_count: nil, fill_value: nil)
+  #   Rolling population variance (divisor `n`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method stddevp(min_count: nil, fill_value: nil)
+  #   Rolling population standard deviation (divisor `n`).
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method minmax(min_count: nil, fill_value: nil)
+  #   Rolling minimum and maximum, found in one pass.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [Array<CArray>] the pair `[min, max]`, reference-shaped (or shrunk, for :truncate)
+  # @!method min_index(min_count: nil, fill_value: nil)
+  #   Rolling position of the minimum, local to the window axes.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
+  #   @return [CArray] reference-shaped (or shrunk, for :truncate)
+  # @!method max_index(min_count: nil, fill_value: nil)
+  #   Rolling position of the maximum, local to the window axes.
+  #   @param min_count [Integer, nil] fewest cells that must be present
+  #     for a result; a piece with fewer comes back masked.
+  #   @param fill_value [Object, nil] value to put in place of a masked
+  #     result instead of leaving it masked.
   #   @return [CArray] reference-shaped (or shrunk, for :truncate)
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any, fused minmax, and the window-local position
-  # min_index / max_index (index within the window axes).
   [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
    :variancep, :stddevp, :minmax, :min_index, :max_index].each do |op|
     class_eval <<~RUBY, __FILE__, __LINE__ + 1
@@ -873,13 +967,41 @@ class CAWindowIterator < CAIterator
           "sort of source addresses is ill-defined."
   end
 
-  # @overload cumsum
-  # @overload cumprod
-  # @overload cummax
-  # @overload cummin
-  # @overload cumcount
-  #   Not supported for a window iterator: a segment scan writes a per-cell
-  #   running statistic, which is single-valued only when each cell belongs to
+  # @!method cumsum
+  #   Not supported for a window iterator.  A segment scan writes a per-cell
+  #   running sum, which is single-valued only when each cell belongs to
+  #   exactly one piece.  Overlapping windows put a cell in many windows, so
+  #   there is no single running value.  Raises NotImplementedError, exactly as
+  #   {#map} / {#sort_addr} do (min / max reductions stay available: a single
+  #   winner is well-defined).
+  #   @raise [NotImplementedError]
+  # @!method cumprod
+  #   Not supported for a window iterator.  A segment scan writes a per-cell
+  #   running product, which is single-valued only when each cell belongs to
+  #   exactly one piece.  Overlapping windows put a cell in many windows, so
+  #   there is no single running value.  Raises NotImplementedError, exactly as
+  #   {#map} / {#sort_addr} do (min / max reductions stay available: a single
+  #   winner is well-defined).
+  #   @raise [NotImplementedError]
+  # @!method cummax
+  #   Not supported for a window iterator.  A segment scan writes a per-cell
+  #   running maximum, which is single-valued only when each cell belongs to
+  #   exactly one piece.  Overlapping windows put a cell in many windows, so
+  #   there is no single running value.  Raises NotImplementedError, exactly as
+  #   {#map} / {#sort_addr} do (min / max reductions stay available: a single
+  #   winner is well-defined).
+  #   @raise [NotImplementedError]
+  # @!method cummin
+  #   Not supported for a window iterator.  A segment scan writes a per-cell
+  #   running minimum, which is single-valued only when each cell belongs to
+  #   exactly one piece.  Overlapping windows put a cell in many windows, so
+  #   there is no single running value.  Raises NotImplementedError, exactly as
+  #   {#map} / {#sort_addr} do (min / max reductions stay available: a single
+  #   winner is well-defined).
+  #   @raise [NotImplementedError]
+  # @!method cumcount
+  #   Not supported for a window iterator.  A segment scan writes a per-cell
+  #   running count of present cells, which is single-valued only when each cell belongs to
   #   exactly one piece.  Overlapping windows put a cell in many windows, so
   #   there is no single running value.  Raises NotImplementedError, exactly as
   #   {#map} / {#sort_addr} do (min / max reductions stay available: a single

data/lib/carray.rb

@@ -16,6 +16,7 @@ end
 # interpolation, so compute programs that never print a CArray skip it.
 require 'carray/construct'
 require 'carray/data_type_extension'
+require 'carray/data_type_limits'  # MIN / MAX / TINY / EPSILON on the typed classes
 # carray/stack is loaded lazily via autoload_carray (entry-method stubs).
 # CAStack is C-defined so its constant is always present; only the Ruby
 # composition surface (stack/meld/montage/split/append) needs the file.
@@ -29,6 +30,7 @@ require 'carray/meld_reduce'    # CAMeld per-parent reduce fast path (sum/mean/m
 # carray/ordering CIFY (2026-06-21): translated to ext/carray_order.c
 
 require 'carray/math'
+require 'carray/rng'    # CArray::Rng: the generator its C is shared from
 # carray/clip_cast CIFY (2026-06-23): translated to ext/carray_cast.c
 require 'carray/complex' # real / imag accessors; MUST precede carray/lazy
                          # (lazy aliases real/imag at load time)

data/yard-stubs/ca_obj_block.rb

@@ -10,7 +10,8 @@ class CABlock
   # @overload size0
   #   Returns the parent dimension sizes that the block is carved
   #   from (one Integer per axis).  Distinct from `shape`, which is
-  #   the block's own shape (= `count` after step / stride logic).
+  #   the block's own shape (= what it exposes after step / stride
+  #   logic).
   #   @return [Array<Integer>]
   def size0; end
 
@@ -26,12 +27,6 @@ class CABlock
   #   @return [Array<Integer>]
   def step; end
 
-  # @overload count
-  #   Returns the per-axis number of elements the block exposes.
-  #   Same as `shape`.
-  #   @return [Array<Integer>]
-  def count; end
-
   # @overload offset
   #   Returns the block's base flat offset into the parent (in
   #   element units), set at construction and adjusted as start[]

data/yard-stubs/ca_obj_window.rb

@@ -20,7 +20,14 @@ class CArray
   # 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.
+  # them instead.  A write that lands outside the parent has no cell to land
+  # in and is discarded.
+  #
+  # A range wider than its axis is how an array is **padded**: `a.window(-1..
+  # a.dim0, -1..a.dim1)` puts a one-cell border all round, which is NumPy's
+  # `pad` with no allocation (`fill_value:` is its `constant`, `bounds:
+  # :nearest` its `edge`).  {#windows} is the different, plural thing: one
+  # such window anchored on every cell, folded.
   #
   # Only unit-step ranges are accepted, and each range must run forward, so
   # the `0..-1` end-relative notation cannot be used here.
@@ -30,7 +37,8 @@ class CArray
   #     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"`
+  #   @param bounds [String, Symbol] what an out-of-range index means; a
+  #     Symbol says the same as the String, matching {#windows}: `"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.

data/yard-stubs/carray_access.rb

@@ -22,7 +22,7 @@ class CArray
   #   - Integer CArray — fancy gather (index array); shape follows the
   #     index array.
   #   - `:_` — newaxis: insert a size-1 axis at this position.
-  #   - `:*` / `:%` — repeat / tiling sugar.
+  #   - `:%` — repeat / tiling sugar.
   #   - `:>` — slab axis: wrap the result in a `CASlabIterator`.
   #   - a member name Symbol — project a struct field (see `CARecord`).
   #

data/yard-stubs/carray_broadcast.rb

@@ -25,7 +25,7 @@ class CArray
   #   @return [CArray]
   #   @raise [RuntimeError] if a source axis cannot be paired with a
   #     target axis (cross-ndim expansion is intentionally strict —
-  #     see {CArray.broadcast} for the explicit-`:_` / `:*` axis
+  #     see {CArray.broadcast} for the explicit-`:_` axis
   #     declaration form).
   #   @example
   #     a = CArray.float64(3) { [1.0, 2.0, 3.0] }

data/yard-stubs/carray_core.rb

@@ -3,64 +3,6 @@
 # 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
@@ -89,26 +31,4 @@ class CArray
   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

@@ -40,7 +40,10 @@ class CArray
   #     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).
+  #     false are rejected -- they are the boolean array's domain).
+  #   - `self.data_type == :object`, `v` is scalar: cells equal to `v`
+  #     by Ruby `==`, so `count(1)` and `count(1.0)` agree, and `true` /
+  #     `false` / `nil` are ordinary values to count.
   #
   #   When `axis` is `nil` (default), reduces over all axes and
   #   returns an `Integer`.  Otherwise reduces along the given
@@ -50,7 +53,9 @@ class CArray
   #   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`.
+  #   `:fixlen` compares the whole cell by `memcmp`, with a short String
+  #   query padded out to the cell width -- so a 4-byte cell holding
+  #   `"a\0\0\0"` is counted by `count("a")`.
   #
   #   A time array counts by its own values: `CATime` / `CATimedelta`
   #   descend to their storage and reconcile `v` into their unit, so `v`

data/yard-stubs/carray_lazy.rb

@@ -21,3 +21,208 @@ class CArray
   def lazy; end
   # @!endgroup
 end
+
+class CAMonOp
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A one-operand element-wise operation holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+
+class CABinOp
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A two-operand element-wise operation holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+
+class CATriOp
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A three-operand element-wise operation holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+
+class CAMonCmp
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A one-operand element-wise predicate holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+
+class CABinCmp
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A two-operand element-wise comparison holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+
+class CALazyMarker
+  # @!group Copy and conversion
+
+  # @overload to_ca
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   A lazy marker holds no data of its own, so there is nothing to
+  #   hand over unevaluated: unlike `CArray#to_ca`, which returns
+  #   `self`, this materialises -- the Ruby `Enumerable#to_a` /
+  #   lazy `force` convention.
+  #
+  #   The entity is detached from the operands, so writes to it reach
+  #   nothing. `writable: true` is therefore refused rather than
+  #   answered with a result that would swallow them.
+  #   @param writable [Boolean] whether the caller needs writes to
+  #     land back in the source; only `false` can be satisfied.
+  #   @return [CArray] a newly evaluated entity.
+  #   @raise [RuntimeError] when `writable: true` is requested.
+  def to_ca(writable: false); end
+
+  # @overload copy
+  #   Evaluates the expression and returns the result as a new entity.
+  #
+  #   If an expression evaluator is registered through
+  #   {CArray.expression_evaluator} it is asked first; the ordinary
+  #   element-wise walk is what happens when it declines, when none is
+  #   registered, or when the array is small enough that walking is
+  #   the faster answer.
+  #   @return [CArray] a newly evaluated entity.
+  def copy; end
+
+  # @!endgroup
+end
+