carray 3.0.0 → 3.0.2

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,34 @@
+# 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 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
+end

data/yard-stubs/carray_count.rb

@@ -0,0 +1,84 @@
+# 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 -- 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
+  #   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` 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`
+  #   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,228 @@
+# 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
+
+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
+