carray 3.0.1 → 3.0.3

data/yard-stubs/carray_lazy.rb

@@ -17,7 +17,216 @@ class CArray
   #   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]
+  #
+  #   A Face (`CATime`, `CACategorical`, a string array, ...) returns
+  #   `self`: a lazy tree computes on storage and would drop what the
+  #   Face means, so operations on a Face stay eager.
+  #   @return [CALazyMarker, CArray] the marker, or `self` for a Face
   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
+

data/yard-stubs/carray_loop.rb

@@ -53,7 +53,10 @@ class CArray
 
   # @overload map!
   #   Replaces each element of `self` with the block's return value.
-  #   Mutates `self`.
+  #   Mutates `self`.  When the block raises or breaks part way, or
+  #   returns a value that cannot be stored, the cells already replaced
+  #   stay replaced -- through a view as well, which writes them back to
+  #   its parent.  The same holds for every `map_*!` below.
   #   @yieldparam elem [Object]
   #   @yieldreturn [Object] new value for the cell.
   #   @return [self]

data/yard-stubs/carray_mask.rb

@@ -74,7 +74,8 @@ class CArray
   #   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`.
+  #     masked position, converted as a store into `self` converts it.
+  #     `UNDEF` leaves the masked cells masked.
   #   @return [self]
   # @overload unmask(method:, axis: nil)
   #   Fills masked cells in place from neighbouring valid cells along
@@ -106,7 +107,8 @@ class CArray
   #
   #   Replaces the removed `unmask_copy(fill)` from 2.x.
   #   @param fill_value [Object] value to substitute at masked
-  #     positions. Cast to `self.data_type`.
+  #     positions, converted as a store into `self` converts it.
+  #     `UNDEF` leaves them masked (the copy keeps the mask).
   #   @return [CArray]
   # @overload strip_mask(method:, axis: nil)
   #   Returns a new array with masked cells filled from neighbouring
@@ -151,6 +153,8 @@ class CArray
   #   Flips the mask state of every element of `self` in place
   #   (masked ↔ not masked). Mutates `self`.
   #   @return [self]
+  #   @raise [FrozenError] if `self` is frozen or a view of a frozen array.
+  #   @raise [RuntimeError] if `self` is read-only (a lazy expression, for one).
   def invert_mask; end
 
   # @overload inherit_mask(*others)
@@ -174,23 +178,43 @@ class CArray
   # @overload count_masked
   #   Returns the total number of masked elements in `self`.
   #   @return [Integer]
-  # @overload count_masked(axis:)
+  # @overload count_masked(axis:, keep_axis: false, min_count: nil, fill_value: nil)
   #   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`.
+  #   from `shape` (kept as length 1 with `keep_axis: true`). Naming
+  #   every axis without `keep_axis:` returns an Integer, as the form
+  #   without `axis:` does. The answer is the same whether or not
+  #   `self` has a mask.
   #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
-  #   @return [CArray] int64 CArray.
+  #   @param keep_axis [Boolean] keep the reduced axes as length 1.
+  #   @param min_count [Integer, nil] cells with fewer than this many
+  #     elements are UNDEF.  A count of the mask reads every element,
+  #     masked or not, so this compares with the slice size.
+  #   @param fill_value [Object, nil] value written into UNDEF cells.
+  #   @return [CArray, Integer]
+  #   @raise [ArgumentError] if an axis is out of range, repeated, or
+  #     the axis list is empty.
   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`.
+  # @overload count_not_masked(axis:, keep_axis: false, min_count: nil, fill_value: nil)
+  #   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` (kept as length 1 with `keep_axis: true`). Naming
+  #   every axis without `keep_axis:` returns an Integer, as the form
+  #   without `axis:` does. The answer is the same whether or not
+  #   `self` has a mask.
   #   @param axis [Integer, Array<Integer>] axis or axes to reduce.
-  #   @return [CArray] int64 CArray.
+  #   @param keep_axis [Boolean] keep the reduced axes as length 1.
+  #   @param min_count [Integer, nil] cells with fewer than this many
+  #     elements are UNDEF.  A count of the mask reads every element,
+  #     masked or not, so this compares with the slice size.
+  #   @param fill_value [Object, nil] value written into UNDEF cells.
+  #   @return [CArray, Integer]
+  #   @raise [ArgumentError] if an axis is out of range, repeated, or
+  #     the axis list is empty.
   def count_not_masked(*, **); end
 
   # @!endgroup