carray 3.0.0 → 3.0.1

data/yard-stubs/carray_mask.rb

@@ -0,0 +1,259 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_mask.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Masking
+
+  # @overload has_mask?
+  #   Returns `true` if `self` has a mask array attached. Note that a
+  #   present mask may still have every entry set to "not masked".
+  #   @return [Boolean]
+  def has_mask?; end
+
+  # @overload any_masked?
+  #   Returns `true` if at least one element of `self` is masked.
+  #   @return [Boolean]
+  def any_masked?; end
+
+  # @overload all_masked?
+  #   Returns `true` if every element of `self` is masked.
+  #   @return [Boolean]
+  def all_masked?; end
+
+  # @overload value
+  #   Returns a new view that exposes the underlying data of `self`,
+  #   bypassing the mask. The returned view itself cannot carry a
+  #   mask (`value_array? == true`).
+  #
+  #   Use this to read or write the data slot of masked elements.
+  #   @return [CArray]
+  def value; end
+
+  # @overload mask
+  #   Returns a new boolean view of the mask state of `self`. Each
+  #   element is `1` where `self` is masked and `0` where it is not.
+  #   The returned view itself cannot carry a mask.
+  #
+  #   Returns `0` (Integer) if `self` has no mask array attached.
+  #   @return [CArray, Integer]
+  def mask; end
+
+  # @overload mask=(new_mask)
+  #   Sets the mask array of `self` to `new_mask`. Allocates the mask
+  #   array first if `self` does not yet have one. Cannot be called on
+  #   a value array or a mask array.
+  #   @param new_mask [CArray, Boolean, Integer] mask values. A
+  #     non-CArray value is broadcast and stored elementwise; a CArray
+  #     of any type is coerced to boolean.
+  #   @return [Object] `new_mask`.
+  def mask=(new_mask); end
+
+  # @overload is_masked
+  #   Returns a new boolean CArray of the same shape as `self`, with
+  #   `1` at masked positions and `0` elsewhere.
+  #   @return [CArray]
+  def is_masked; end
+
+  # @overload is_not_masked
+  #   Returns a new boolean CArray of the same shape as `self`, with
+  #   `1` at not-masked positions and `0` elsewhere.
+  #   @return [CArray]
+  def is_not_masked; end
+
+  # `unmask` clears a mask by *supplying values*. The value source is
+  # either a constant (the positional `fill_value`) or a scan `method:`
+  # that derives values from neighbouring valid cells (mask gap-fill).
+  # The two are mutually exclusive: passing both raises `ArgumentError`.
+  #
+  # @overload unmask
+  #   Clears the mask state of every element of `self`, leaving the
+  #   stored data values untouched. Mutates `self`.
+  #   @return [self]
+  # @overload unmask(fill_value)
+  #   Clears the mask state and overwrites the data at previously
+  #   masked positions with `fill_value`. Mutates `self`.
+  #   @param fill_value [Object] value to store at each previously
+  #     masked position. Cast to `self.data_type`.
+  #   @return [self]
+  # @overload unmask(method:, axis: nil)
+  #   Fills masked cells in place from neighbouring valid cells along
+  #   `axis` (gap-fill), then clears the filled cells' mask. Mutates
+  #   `self`. Leading (`:forward`) / trailing (`:backward`) runs of
+  #   masked cells with no value to carry, and cells outside the valid
+  #   range (`:linear`), stay masked — so a mask may remain.
+  #   @param method [Symbol] fill rule:
+  #     `:forward` / `:ffill` carries the last valid value forward;
+  #     `:backward` / `:bfill` carries the next valid value backward
+  #     (defined for every data_type — numeric, complex, bool, object,
+  #     fixlen, and Face); `:linear` interpolates each masked cell
+  #     linearly by index from the two bracketing valid cells (numeric
+  #     data_type, or a time Face — `CATime` / `CATimedelta` interpolate
+  #     through their own `linear_fetch`, so the filled values stay on the
+  #     array's unit and are rounded to it).
+  #   @param axis [Integer, nil] scan axis (single axis). `nil` flattens.
+  #   @return [self]
+  def unmask(*, method: nil, axis: nil); end
+
+  # `strip_mask` is the copy form of `unmask`: it returns a new array
+  # rather than mutating `self`, supplying values either from a constant
+  # `fill_value` or a scan `method:`. The two are mutually exclusive.
+  #
+  # @overload strip_mask(fill_value)
+  #   Returns a new array with the same shape and `data_type` as
+  #   `self`, with no mask attached, and `fill_value` substituted at
+  #   positions that were masked in `self`. `self` is not modified.
+  #
+  #   Replaces the removed `unmask_copy(fill)` from 2.x.
+  #   @param fill_value [Object] value to substitute at masked
+  #     positions. Cast to `self.data_type`.
+  #   @return [CArray]
+  # @overload strip_mask(method:, axis: nil)
+  #   Returns a new array with masked cells filled from neighbouring
+  #   valid cells along `axis` (gap-fill). `self` is not modified.
+  #   Residual (leading / trailing / out-of-range) masked cells that
+  #   cannot be filled stay masked in the returned array.
+  #   @param method [Symbol] fill rule: `:forward` / `:ffill`,
+  #     `:backward` / `:bfill` (any data_type), or `:linear` (numeric or a
+  #     time Face). See {#unmask} for the full description.
+  #   @param axis [Integer, nil] scan axis (single axis). `nil` flattens.
+  #   @return [CArray]
+  def strip_mask(*, method: nil, axis: nil); end
+
+  # `first` / `last` are the reduction sibling of the `:forward` / `:backward`
+  # hold (see {#unmask}): instead of filling a whole fiber they return the one
+  # first / last **valid** (unmasked) value. For an unmasked array they
+  # degrade to the first / last element. Works for every data_type.
+  #
+  # @overload first(axis: nil, keep_axis: false)
+  #   Returns the first valid (unmasked) value along `axis`, skipping masked
+  #   cells. Identity-less: a fiber with no valid cell (all masked, or empty)
+  #   yields UNDEF. To substitute a default instead, complete at the call
+  #   site — `a.first(axis: 0).strip_mask(v)`.
+  #   @param axis [Integer, Array<Integer>, nil] reduce axis / axes; `nil`
+  #     reduces the whole array to a scalar.
+  #   @param keep_axis [Boolean] keep the reduced axis as a size-1 axis.
+  #   @return [Object, CArray] a scalar for a full reduce (UNDEF if no valid
+  #     cell), otherwise a reduced CArray.
+  def first(axis: nil, keep_axis: false); end
+
+  # @overload last(axis: nil, keep_axis: false)
+  #   Returns the last valid (unmasked) value along `axis` (the backward
+  #   counterpart of {#first}).
+  #   @param axis [Integer, Array<Integer>, nil] reduce axis / axes; `nil`
+  #     reduces the whole array to a scalar.
+  #   @param keep_axis [Boolean] keep the reduced axis as a size-1 axis.
+  #   @return [Object, CArray] a scalar for a full reduce (UNDEF if no valid
+  #     cell), otherwise a reduced CArray.
+  def last(axis: nil, keep_axis: false); end
+
+  # @overload invert_mask
+  #   Flips the mask state of every element of `self` in place
+  #   (masked ↔ not masked). Mutates `self`.
+  #   @return [self]
+  def invert_mask; end
+
+  # @overload inherit_mask(*others)
+  #   Sets the mask of `self` to the logical OR of the current mask
+  #   of `self` and the masks of each array in `others`. Mutates
+  #   `self`.
+  #   @param others [Array<CArray>] arrays whose mask states are
+  #     OR-ed into `self`. Non-CArray arguments are ignored.
+  #   @return [self]
+  def inherit_mask(*others); end
+
+  # @overload inherit_mask_replace(*others)
+  #   Sets the mask of `self` to the logical OR of the masks of the
+  #   arrays in `others` only (the current mask of `self` is
+  #   discarded, in contrast to {#inherit_mask}). Mutates `self`.
+  #   @param others [Array<CArray>] arrays whose mask states form the
+  #     new mask of `self`.
+  #   @return [self]
+  def inherit_mask_replace(*others); end
+
+  # @overload count_masked
+  #   Returns the total number of masked elements in `self`.
+  #   @return [Integer]
+  # @overload count_masked(axis:)
+  #   Returns the per-slice count of masked elements along the given
+  #   axis or axes. The result is an int64 CArray with `axis` removed
+  #   from `shape`.
+  #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
+  #   @return [CArray] int64 CArray.
+  def count_masked(*, **); end
+
+  # @overload count_not_masked
+  #   Returns the total number of not-masked elements in `self`.
+  #   @return [Integer]
+  # @overload count_not_masked(axis:)
+  #   Returns the per-slice count of not-masked elements along the
+  #   given axis or axes. The result is an int64 CArray with `axis`
+  #   removed from `shape`.
+  #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
+  #   @return [CArray] int64 CArray.
+  def count_not_masked(*, **); end
+
+  # @!endgroup
+
+  # @!group Masking
+
+  # @overload mask_eq(v)
+  #   Returns a copy of `self` with every element equal to `v` masked.
+  #   In-place equivalent: `ca[:eq, v] = UNDEF`.
+  #
+  #   Replaces the removed `maskout(v)` from 2.x.
+  #   @param v [Object] value to mask. Cast to `self.data_type`.
+  #   @return [CArray]
+  def mask_eq(v); end
+
+  # @overload mask_invalid
+  #   Returns a copy of `self` with every NaN or Inf element masked.
+  #   For integer or boolean arrays this is a plain copy (no element
+  #   is invalid by `is_finite.not` semantics).
+  #   In-place equivalent: `ca[:is_invalid] = UNDEF`.
+  #   @return [CArray]
+  def mask_invalid; end
+
+  # @overload mask_where(key, *args)
+  #   Returns a copy of `self` with elements matching the given indexer
+  #   predicate masked. Mirrors the indexer key set:
+  #
+  #   ```ruby
+  #   ca.mask_where(:lt, v)      # same as: copy then ca[:lt, v] = UNDEF
+  #   ca.mask_where(:is_invalid) # same as: copy then ca[:is_invalid] = UNDEF
+  #   ca.mask_where(bool_array)  # same as: copy then ca[bool_array] = UNDEF
+  #   ```
+  #
+  #   At least one argument is required. For in-place mutation use the
+  #   indexer idiom directly: `ca[key, *args] = UNDEF`.
+  #   @param key [Symbol, CArray] indexer key or boolean condition array.
+  #   @param args [Array] additional arguments required by the predicate.
+  #   @return [CArray]
+  def mask_where(*args); end
+
+  # @!endgroup
+
+  class << self
+    # @!group Masking
+
+    # @overload guard_undef(*values, fill_value: UNDEF)
+    #   Returns `fill_value` immediately if any element of `values` is
+    #   `UNDEF`; otherwise yields all `values` to the block and returns
+    #   the block's result.
+    #
+    #   ```ruby
+    #   CArray.guard_undef(a, b) { |x, y| x / y }    # UNDEF if a or b masked
+    #   CArray.guard_undef(v, fill_value: 0.0) { |x| Math.sqrt(x) }
+    #   ```
+    #
+    #   @param values [Array<Object>] scalar values to test.
+    #   @param fill_value [Object] value returned on short-circuit.
+    #     Defaults to `UNDEF`.
+    #   @yieldparam values [Array<Object>] the non-UNDEF values.
+    #   @yieldreturn [Object] computation result.
+    #   @return [Object]
+    def guard_undef(*values, fill_value: UNDEF); end
+
+    # @!endgroup
+  end
+end

data/yard-stubs/carray_math.rb

@@ -0,0 +1,132 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for the elementwise arithmetic generated by ext/mkkernel.rb --
+# the division and modulo binops and the rounding monops.  These
+# generated kernels carry no C docstring, so the documentation lives
+# here.  See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Elementwise math
+
+  # @overload /(other)
+  #   Returns the element-wise quotient of `self` and `other`.
+  #
+  #   Integer division floors toward negative infinity, so that
+  #   `(a / b) * b + a % b == a` holds for every combination of signs
+  #   -- the same convention as Ruby's `Integer#/`. Float and complex
+  #   division is true division, as Ruby's `Float#/` is, so that
+  #   identity is an integer one. Boolean arrays participate as their
+  #   0/1 storage. Masked elements stay masked, and a masked cell is
+  #   never divided.
+  #   @param other [CArray, Numeric] divisor, broadcast to `self.shape`.
+  #   @return [CArray] result of the promoted `data_type` of the two
+  #     operands.
+  #   @raise [ZeroDivisionError] when an integer divisor is `0`. Float
+  #     division returns `Infinity` or `NaN` instead.
+  #   @example
+  #     CA_INT32([-7, -1, 7]) / 3      # => [ -3, -1, 2 ]
+  #     CA_DOUBLE([-7.0]) / 3.0        # => [ -2.3333333333333335 ]
+  def /(other); end
+
+  # @overload div(other)
+  #   Alias of {#/}.
+  #   @param other [CArray, Numeric] divisor.
+  #   @return [CArray]
+  def div(other); end
+
+  # @overload div!(other)
+  #   Divides `self` by `other` in place, keeping `self`'s `data_type`.
+  #   @param other [CArray, Numeric] divisor.
+  #   @return [self]
+  def div!(other); end
+
+  # @overload %(other)
+  #   Returns the element-wise remainder of `self` divided by `other`,
+  #   carrying the sign of the divisor.
+  #
+  #   This is the floored modulo, the pair of the floored `/` above and
+  #   the same convention as Ruby's `%`: `-7 % 3` is `2`, and `7 % -3`
+  #   is `-2`. A float remainder of zero takes the divisor's sign, so
+  #   the rule holds without exception. For the truncated form that C
+  #   gives -- the sign of the dividend -- use {#fmod}. Complex arrays
+  #   have no modulo. Masked elements stay masked.
+  #   @param other [CArray, Numeric] divisor, broadcast to `self.shape`.
+  #   @return [CArray] result of the promoted `data_type` of the two
+  #     operands.
+  #   @raise [ZeroDivisionError] when an integer divisor is `0`. A float
+  #     divisor of `0.0` yields `NaN`.
+  #   @raise [CArray::DataTypeError] for a complex array.
+  #   @example
+  #     CA_INT32([-7, -1, 7]) % 3      # => [ 2, 2, 1 ]
+  #     CA_INT32([7]) % -3             # => [ -2 ]
+  #     CA_DOUBLE([-0.4]) % 1.0        # => [ 0.6 ]
+  def %(other); end
+
+  # @overload mod(other)
+  #   Alias of {#%}.
+  #   @param other [CArray, Numeric] divisor.
+  #   @return [CArray]
+  def mod(other); end
+
+  # @overload mod!(other)
+  #   Replaces `self` with the remainder in place, keeping `self`'s
+  #   `data_type`.
+  #   @param other [CArray, Numeric] divisor.
+  #   @return [self]
+  def mod!(other); end
+
+  # @overload fmod(other)
+  #   Returns the element-wise truncated remainder of `self` divided by
+  #   `other`, carrying the sign of the dividend.
+  #
+  #   This is C's `fmod` and `%`: the quotient is truncated toward zero
+  #   rather than floored, so `fmod(-7, 3)` is `-1` where `-7 % 3` is
+  #   `2`. Integer arrays are accepted as well as floats. Complex
+  #   arrays have no remainder. An `:object` array delegates to each
+  #   element's `#remainder`, so an Integer element yields an Integer.
+  #   Masked elements stay masked.
+  #   @param other [CArray, Numeric] divisor, broadcast to `self.shape`.
+  #   @return [CArray] result of the promoted `data_type` of the two
+  #     operands.
+  #   @raise [ZeroDivisionError] when an integer divisor is `0`. A float
+  #     divisor of `0.0` yields `NaN`.
+  #   @raise [CArray::DataTypeError] for a complex array.
+  #   @example
+  #     CA_INT32([-7, -1, 7]).fmod(3)  # => [ -1, -1, 1 ]
+  #     CA_DOUBLE([-0.4]).fmod(1.0)    # => [ -0.4 ]
+  def fmod(other); end
+
+  # @overload fmod!(other)
+  #   Replaces `self` with the truncated remainder in place, keeping
+  #   `self`'s `data_type`.
+  #   @param other [CArray, Numeric] divisor.
+  #   @return [self]
+  def fmod!(other); end
+
+  # @overload round
+  #   Returns a new array with each element rounded to the nearest
+  #   integer value, half rounded away from zero (`2.5` -> `3.0`,
+  #   `-2.5` -> `-3.0`).  The result keeps `self`'s `data_type`.
+  #
+  #   Integer arrays are returned unchanged.  For a `:float64` /
+  #   `:float32` array the value stays floating-point (e.g. `1.4` ->
+  #   `1.0`); a `NaN` element is passed through as `NaN`, and `-0.0`
+  #   keeps its sign.  Masked elements stay masked.  An `:object`
+  #   array delegates to each element's `#round`.
+  #   @return [CArray] same `data_type` as `self`.
+  def round; end
+
+  # @overload frac
+  #   Returns a new array of the fractional part of each element:
+  #   `self - self.truncated_toward_zero`, so the result keeps the
+  #   sign of the input (`1.25` -> `0.25`, `-1.25` -> `-0.25`).  The
+  #   result keeps `self`'s `data_type`.
+  #
+  #   Integer arrays yield all zeros.  For a floating-point array a
+  #   `NaN` element is passed through as `NaN`, and `±0.0` keeps its
+  #   sign.  Masked elements stay masked.  An `:object` array
+  #   delegates to each element's `#frac`.
+  #   @return [CArray] same `data_type` as `self`.
+  def frac; end
+
+  # @!endgroup
+end

data/yard-stubs/carray_mathfunc.rb

@@ -0,0 +1,45 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for the CAMath module functions defined in
+# ext/carray_mathfunc.c.  Most CAMath entries (atan2 / hypot / expm1
+# / log1p / copysign / logaddexp / nextafter / fmod / min / max) live
+# in lib/carray/math.rb and are documented at the source.  This file
+# covers only the C-defined module functions.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+# Namespace for math module functions that operate on CArray (and
+# auto-wrappable scalar) inputs.
+module CAMath
+  module_function
+
+  # @overload spherical_to_xyz(r, theta, phi)
+  #   Returns three CArrays `[x, y, z]` of cartesian coordinates
+  #   converted from spherical coordinates.  All inputs are coerced
+  #   to `:float64`; outputs are `:float64`.
+  #
+  #   `theta` is the polar angle from the `+z` axis in radians;
+  #   `phi` is the azimuthal angle in the `xy` plane in radians.
+  #   @param r [CArray, Numeric] radial distance.
+  #   @param theta [CArray, Numeric] polar angle (radians).
+  #   @param phi [CArray, Numeric] azimuthal angle (radians).
+  #   @return [Array<CArray>] `[x, y, z]`.
+  def spherical_to_xyz(r, theta, phi); end
+
+  # @overload xyz_to_spherical(x, y, z)
+  #   Returns three CArrays `[r, theta, phi]` of spherical
+  #   coordinates converted from cartesian coordinates.  All inputs
+  #   are coerced to `:float64`; outputs are `:float64`.
+  #   @param x [CArray, Numeric]
+  #   @param y [CArray, Numeric]
+  #   @param z [CArray, Numeric]
+  #   @return [Array<CArray>] `[r, theta, phi]`.
+  #   @raise [RuntimeError] when the build lacks `atan2`.
+  def xyz_to_spherical(x, y, z); end
+
+  # @overload lgamma(x)
+  #   Returns a `:float64` CArray of `log(|Γ(x)|)` for each element of
+  #   `x`.  `x` is coerced to `:float64`.
+  #   @param x [CArray, Numeric]
+  #   @return [CArray]
+  #   @raise [RuntimeError] when the build lacks `lgamma`.
+  def lgamma(x); end
+end

data/yard-stubs/carray_median_percentile.rb

@@ -0,0 +1,89 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for methods defined in ext/carray_median_percentile.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  # @!group Statistics
+
+  # @overload median(axis: nil, min_count: 0, fill_value: nil, keep_axis: false)
+  #   Returns the median of `self` along `axis` (or over all elements
+  #   when `axis` is `nil`).
+  #
+  #   Numeric arrays return a `Float`; `CA_OBJECT` arrays return the
+  #   result of Ruby `+` / `/` on the stored objects. Fixlen arrays
+  #   raise, since no numeric midpoint is defined.
+  #
+  #   Masked cells are excluded. Per-axis, each fiber uses only its own
+  #   present values; a fully masked fiber reduces to `UNDEF`. If the
+  #   count of not-masked cells (per fiber, or over all elements in the
+  #   flat form) is below `min_count`, that cell is `fill_value` (or
+  #   `UNDEF` when `fill_value` is `nil`).
+  #
+  #   With `keep_axis: true`, the reduced axis is retained with
+  #   length 1 rather than dropped.
+  #   @param axis [Integer, nil]
+  #   @param min_count [Integer] minimum not-masked count required.
+  #   @param fill_value [Object, nil] replacement when the not-masked
+  #     count is below `min_count`.
+  #   @param keep_axis [Boolean]
+  #   @return [Float, CArray, Object]
+  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @raise [ArgumentError] on negative `min_count`.
+  def median(*); end
+
+  # @overload percentile(*p, axis: nil, min_count: 0, fill_value: nil,
+  #                      method: :linear, keep_axis: false)
+  #   Returns percentile values at each `p` (each in `[0, 100]`)
+  #   along `axis` or over all elements.
+  #
+  #   `p` may be given as individual positional arguments, a single
+  #   `Array<Numeric>`, or a single 1-D `CArray`. When the effective
+  #   `p` count (after flattening) is 1, the result is unwrapped:
+  #   flat form returns a `Float`, per-axis form returns a `CArray`.
+  #   With 2 or more `p` values the result is an `Array` whose length
+  #   matches the number of requested `p` values.
+  #
+  #   `method` picks the interpolation rule between adjacent order
+  #   statistics:
+  #
+  #   - `:linear` (default) — linear interpolation.
+  #   - `:lower` — floor to the smaller neighbor.
+  #   - `:higher` — ceil to the larger neighbor.
+  #   - `:nearest` — round-half-to-even to the nearer neighbor.
+  #   - `:midpoint` — arithmetic mean of the two neighbors.
+  #
+  #   Numeric arrays produce `Float` results; `CA_OBJECT` arrays
+  #   apply Ruby `+` / `/` / `*` on the stored objects. Fixlen
+  #   arrays raise.
+  #
+  #   Masking, `min_count`, `fill_value`, and `keep_axis` follow the
+  #   same rules as {#median}.
+  #   @param p [Numeric, Array<Numeric>, CArray] percentile targets in
+  #     `[0, 100]`.
+  #   @param axis [Integer, nil]
+  #   @param min_count [Integer]
+  #   @param fill_value [Object, nil]
+  #   @param method [Symbol] one of `:linear`, `:lower`, `:higher`,
+  #     `:nearest`, `:midpoint`.
+  #   @param keep_axis [Boolean]
+  #   @return [Float, CArray, Object, Array<Float>, Array<CArray>, Array<Object>]
+  #   @raise [CArray::DataTypeError] for fixlen data_type.
+  #   @raise [ArgumentError] on empty `p` list, `p` outside `[0, 100]`,
+  #     empty axis, unknown `method`, or invalid option combinations.
+  def percentile(*); end
+
+  # @overload quantile(axis: nil, keep_axis: false)
+  #   Returns the five quartile percentiles
+  #   `[p0, p25, p50, p75, p100]` — shorthand for
+  #   `percentile(0, 25, 50, 75, 100, axis: axis, keep_axis: keep_axis)`.
+  #   Accepts no positional arguments. Flat form returns
+  #   `Array<Float>` of length 5; per-axis form returns `Array<CArray>`
+  #   of length 5, each CArray reduced along `axis`.
+  #   @param axis [Integer, nil]
+  #   @param keep_axis [Boolean]
+  #   @return [Array<Float>, Array<CArray>]
+  #   @raise [ArgumentError] on any positional argument.
+  def quantile(*); end
+
+  # @!endgroup
+end

data/yard-stubs/carray_memory_view.rb

@@ -0,0 +1,163 @@
+# DOCUMENTATION ONLY — DO NOT REQUIRE.
+# Stubs for singleton methods defined in ext/carray_memory_view.c.
+# See yard-stubs/README.md and yard-stubs/STYLE.md.
+
+class CArray
+  class << self
+    # @!group MemoryView interop
+
+    # @overload memory_view_available?(obj)
+    #   Returns `true` if `obj` exposes the Ruby `rb_memory_view`
+    #   protocol and a view can be acquired from it. Lightweight probe
+    #   used to gate {.from_memory_view} / {.wrap_memory_view} calls.
+    #
+    #   Returning `true` does not guarantee acquisition will succeed —
+    #   a producer may still refuse a particular flag combination at
+    #   acquisition time.
+    #   @param obj [Object] any object (typically a foreign array such
+    #     as `Numo::NArray`, `Arrow::Array`, a `bytearray`, or a
+    #     CArray).
+    #   @return [Boolean]
+    #   @example
+    #     CArray.memory_view_available?(CArray.int32(3))      # => true
+    #     CArray.memory_view_available?("plain string")        # => false
+    def memory_view_available?(obj); end
+
+    # @overload memory_view_reject_reason(obj)
+    #   Returns a String explaining why CArray's MemoryView producer
+    #   refuses to export `obj`, or `nil` if no problem is detected.
+    #
+    #   Diagnostic only; useful when {.memory_view_available?} returns
+    #   `false` on a CArray and the generic "memory view not available"
+    #   error does not say which link in the parent chain caused the
+    #   reject. Consumers that need to debug an alias-chain reject
+    #   (mask propagation, non-contiguous strided view, etc.) call this
+    #   to print a human-readable reason.
+    #   @param obj [Object]
+    #   @return [String, nil] reason text, or `nil` when acquisition
+    #     would succeed.
+    def memory_view_reject_reason(obj); end
+
+    # @overload from_memory_view(src, data_type: nil, mask: nil)
+    #   Returns a new `CArray` that owns an independent copy of `src`'s
+    #   buffer. Accepts both contiguous and strided producers; strided
+    #   sources are gathered into a freshly allocated row-major
+    #   buffer.
+    #
+    #   For typeless producers (format `nil`, e.g. byte blobs from
+    #   `IO#read`), `data_type:` is required and the byte buffer is
+    #   reinterpreted as that data type with `ndim = 1`. For typed
+    #   producers `data_type:` is optional; when given it must match
+    #   the producer's format.
+    #
+    #   `mask:` accepts a paired buffer-protocol source whose shape
+    #   matches `src` and whose item size is 1 (PEP 3118 `?` / `B` /
+    #   `b`). The mask bytes are copied into the canonical
+    #   `CA_BOOLEAN` mask slot with non-zero coerced to `1`. The copy
+    #   is independent of both buffers after the call.
+    #   @param src [Object] any MemoryView producer.
+    #   @param data_type [Symbol, Integer, Class, nil] target data
+    #     type. Required for typeless producers; optional (must match
+    #     producer format) for typed ones.
+    #   @param mask [Object, nil] optional paired mask MemoryView
+    #     source. Must match `src.shape` and use a 1-byte/element
+    #     format.
+    #   @return [CArray] independent copy; not a `CAWrap`.
+    #   @raise [ArgumentError] if `src` is not a MemoryView producer,
+    #     if `data_type:` is missing for a typeless source, if
+    #     `data_type:` conflicts with the producer's format, or if
+    #     the supplied `mask:` fails shape / data type / contiguity
+    #     validation.
+    #   @example Copy from a strided source
+    #     a = CArray.int32(4, 3).seq
+    #     b = CArray.from_memory_view(a.transpose)
+    #     b.shape    # => [3, 4]
+    #     b.equal?(a)  # => false
+    #   @example Copy paired (data, mask) — independent of source
+    #     data = CArray.uint8(3) { |i| i }
+    #     mask = CArray.boolean(3) { |i| i.zero? ? 1 : 0 }
+    #     c = CArray.from_memory_view(data, mask: mask)
+    #     c.has_mask?   # => true
+    #     data[0] = 99  # source change does not reach c
+    def from_memory_view(src, data_type: nil, mask: nil); end
+
+    # @overload wrap_memory_view(src, data_type: nil, mask: nil)
+    #   Returns a `CAWrap` (or `CAStride` for strided producers) that
+    #   borrows `src`'s buffer zero-copy. Writes through the wrap
+    #   reach the source buffer; external changes to the source are
+    #   visible through the wrap.
+    #
+    #   The borrowed view is kept alive for the lifetime of the
+    #   returned object via internal ivars; the source is released
+    #   when the wrap is garbage-collected.
+    #
+    #   Contiguous typed producers return a `CAWrap`. Strided typed
+    #   producers return a `CAStride` layered on an inner `CAWrap` of
+    #   the producer's first byte, preserving the full stride pattern
+    #   (including negative strides where the producer offers them).
+    #   Typeless producers (format `nil`) require `data_type:` and are
+    #   reinterpreted with `ndim = 1`.
+    #
+    #   `mask:` accepts a paired buffer-protocol source whose shape
+    #   matches `src` and whose item size is 1 (PEP 3118 `?` / `B` /
+    #   `b`). The mask buffer is borrowed; writes to either side
+    #   propagate, and the mask MemoryView is released when the wrap
+    #   is collected. In this release, `mask:` requires a row-major
+    #   contiguous data source and a row-major contiguous mask
+    #   buffer.
+    #
+    #   The receiver picks the class of the result. Called on `CArray`
+    #   it builds a `CAWrap`; called on a subclass of `CAWrap` it
+    #   builds that subclass, so a gem bridging a foreign buffer can
+    #   name where the array came from without writing a C extension.
+    #   Any other receiver raises `TypeError`, and a strided producer
+    #   raises `ArgumentError` when a subclass was asked for, since the
+    #   result would be a `CAStride` rather than the named class.
+    #
+    #   The class marks the provenance of the returned object only. A
+    #   view derived from it is a `CABlock` or a `CAStride` like any
+    #   other — a slice of a borrowed image is no longer that image —
+    #   so do not build an API that expects the class to survive view
+    #   algebra. For semantic identity that does survive it, see
+    #   {file:docs/topics/CAFace.md CAFace}.
+    #   @param src [Object] any MemoryView producer.
+    #   @param data_type [Symbol, Integer, Class, nil] target data
+    #     type, same rules as {.from_memory_view}.
+    #   @param mask [Object, nil] optional paired mask MemoryView
+    #     source.
+    #   @return [CAWrap, CAStride] zero-copy borrowed view of `src`.
+    #     A `CAStride` is returned when `src` is strided (and `mask:`
+    #     is not given); otherwise a `CAWrap`, or the subclass of
+    #     `CAWrap` the method was called on.
+    #   @raise [TypeError] if the receiver is neither `CArray` nor a
+    #     subclass of `CAWrap`.
+    #   @raise [ArgumentError] if `src` is not a MemoryView producer,
+    #     if `data_type:` is missing for a typeless source, if
+    #     `data_type:` conflicts with the producer's format, or if
+    #     the supplied `mask:` fails validation (shape / ndim /
+    #     data type / item_size / contiguity). Also raises when `mask:`
+    #     is combined with a strided data source — that combination
+    #     is not supported in this release.
+    #   @example Zero-copy write propagation
+    #     a = CArray.int32(4).seq
+    #     w = CArray.wrap_memory_view(a)
+    #     w[0] = 999
+    #     a[0]   # => 999
+    #   @example Paired masked wrap
+    #     data = CArray.uint8(3) { |i| i + 10 }
+    #     mask = CArray.boolean(3) { 0 }
+    #     w = CArray.wrap_memory_view(data, mask: mask)
+    #     w[1] = UNDEF      # writes the source mask buffer
+    #     mask[1]           # => 1
+    #   @example Naming where a borrowed buffer came from
+    #     class VipsPixels < CAWrap
+    #       def image ; instance_variable_get(:@vips_image) ; end
+    #     end
+    #     v = VipsPixels.wrap_memory_view(bmv)
+    #     v.class            # => VipsPixels
+    #     v[0..1, nil].class # => CABlock  (the class does not descend)
+    def wrap_memory_view(src, data_type: nil, mask: nil); end
+
+    # @!endgroup
+  end
+end