carray 3.0.5 → 3.0.6

data/lib/carray/window_iterator.rb

@@ -106,6 +106,14 @@ class CAWindowIterator < CAIterator
             "windows: expected #{@source.ndim} ranges (one per axis), " \
             "got #{@ranges.size}"
     end
+    # Each window is read through a view with one axis per anchor and one
+    # per cell in the window, twice the source's rank.
+    if 2 * @source.ndim > CA_RANK_MAX
+      raise ArgumentError,
+            "windows: a rank #{@source.ndim} array would need #{2 * @source.ndim} " \
+            "axes for its windows, beyond the limit of #{CA_RANK_MAX}; " \
+            "windows works up to rank #{CA_RANK_MAX / 2}"
+    end
     @ranges = @ranges.each_with_index.map { |r, k| window_offsets(r, k) }
 
     @sndim  = @source.ndim
@@ -151,14 +159,15 @@ class CAWindowIterator < CAIterator
 
   # ---- padded entity + sliding_windows view -----------------------------
   #
-  # The engine: pad the source once (:skip -> UNDEF, :nearest -> edge, :constant
+  # The engine: pad the source (:skip -> UNDEF, :nearest -> edge, :constant
   # -> value; :truncate does not pad), then take a sliding_windows view.  Both
-  # are memoised: every named reduction reuses the one pad + one view.
+  # are kept for one call, so the helpers a reduction runs share one pad and
+  # one view, and the next call pads the source as it is then.
 
   # @overload sliding_view
   #   Returns the sliding_windows view feeding the reductions.  For :truncate
   #   this is the source's own view (zero-copy); otherwise it is the view over
-  #   the padded entity.
+  #   a padded copy made from the source as it is at this call.
   #   @return [CArray]
   def sliding_view
     @sliding_view ||= @shape.include?(0) ? no_windows : anchored_buffer.sliding_windows(*@widths)
@@ -553,7 +562,7 @@ class CAWindowIterator < CAIterator
   # Runs the fold by offset, or returns nil when this window is not one it can
   # answer for -- in which case the caller delegates as before.
   def fold_by_offset (op, min_count, fill_value = nil)
-    return nil unless CArray.__fast_paths_enabled__
+    return nil unless CArray.__fast_paths_enabled__(:window_fold_by_offset)
     need = CArray.__present_cells_needed_per_result_cell__(op, min_count, 0)
     return nil unless op == :mean || OFFSET_FOLD.key?(op)
     # The elementwise kernels act on a Face's storage; its reductions are its own.
@@ -1150,6 +1159,9 @@ class CAWindowIterator < CAIterator
       yield idx
     end
   end
+
+  read_source_per_call :@sliding_view, :@padded_entity, :@neutral_value,
+                       :@offset_fold_base, :@window_cell_counts
 end
 
 

data/yard-stubs/ca_obj_array.rb

@@ -244,7 +244,8 @@ class CScalar
   # @!group Construction
 
   # @overload initialize(data_type)
-  #   Allocates a CScalar (0-D CArray) of the given `data_type`.
+  #   Allocates a CScalar of the given `data_type`: one cell on one axis
+  #   (`ndim` 1, `shape` `[1]`).
   #   @param data_type [Symbol, Integer, Class, String]
   #   @return [self]
   # @overload initialize(data_type, bytes:)
@@ -269,6 +270,30 @@ class CScalar
 
   # @!endgroup
 
+  # @!group Indexing and slicing
+
+  # @overload []
+  # @overload [](0)
+  #   Reads the scalar's value.  A CScalar is one cell and takes no index:
+  #   `s[]` and `s[0]` both name that cell, and any other index (another
+  #   integer, a range, `nil`, an index array, a symbol) is refused.  A view
+  #   of the scalar, such as `s.refer(s.data_type, [1])`, takes the usual
+  #   indexes.
+  #   @return [Object] the value, or `UNDEF` if it is masked.
+  #   @raise [ArgumentError] when any other index is given.
+  def [](*index); end
+
+  # @overload []=(value)
+  # @overload []=(0, value)
+  #   Writes the scalar's value.  `s[] = v` and `s[0] = v` both write it;
+  #   any other index is refused.
+  #   @param value [Object] the value, or `UNDEF` to mask the cell.
+  #   @return [Object] value
+  #   @raise [ArgumentError] when any other index is given.
+  def []=(*index_and_value); end
+
+  # @!endgroup
+
   class << self
     # @!group Construction (typed shorthands)
 

data/yard-stubs/carray_cast.rb

@@ -202,10 +202,13 @@ class CArray
   # -- as_type: reinterpreting view (no copy) ---------------------------
 
   # @overload as_type(data_type, bytes: nil)
-  #   Returns a {CAFake} view of `self` reinterpreted as `data_type`
-  #   (with `bytes:` for `:fixlen`). Reads and writes cast on the fly
-  #   through the shared parent storage; no copy is made. For an eager
-  #   copy use `arr.as_type(...).to_ca` or {#to_type}.
+  #   Returns a view of `self` reinterpreted as `data_type` (with
+  #   `bytes:` for `:fixlen`): a {CAMonOp} for a numeric type, a {CAFake}
+  #   otherwise. Reads and writes cast on the fly through the shared
+  #   parent storage; no copy is made. The view is a new array also when
+  #   `data_type` is `self`'s own, so an attribute set on it or a freeze
+  #   of it does not reach `self`. For an eager copy use
+  #   `arr.as_type(...).copy` or {#to_type}.
   #
   #   Note: for an `:object` source the on-the-fly cast to a numeric type
   #   uses the lenient path and does NOT mask parse failures — a
@@ -225,7 +228,7 @@ class CArray
   #   @param data_type [Symbol, Integer, Class, String] target element type.
   #   @param bytes [Integer, nil] element width in bytes, required for
   #     `:fixlen`.
-  #   @return [CAFake]
+  #   @return [CAMonOp, CAFake]
   #   @raise [TypeError] when `self` is a Face and the request would read its
   #     storage under another type.
   #   @raise [FloatDomainError] when a NaN cell that is not masked is read

data/yard-stubs/carray_conversion.rb

@@ -81,10 +81,16 @@ class CArray
   #   `String` of the exact size, or any object responding to
   #   `read(n, buf = nil)`. Into a boolean array, a non-zero byte is
   #   read as 1 (true).
+  #   From an IO into an array that owns its memory, the bytes are written
+  #   as they are read, so that no second copy of the data is held; when the
+  #   IO runs out before the array is full, what the array holds afterwards
+  #   is not defined (the part read so far may already be in it).  Into a
+  #   view the whole data is read first and nothing is written on a short
+  #   read.
   #   @param io [String, IO, #read]
   #   @return [self]
-  #   @raise [RuntimeError] on a short read.
-  #   @raise [ArgumentError] when a String source is not the array's size.
+  #   @raise [ArgumentError] on a short read, and when a String source is
+  #     not the array's size.
   #   @raise [CArray::DataTypeError] if `self.data_type` is
   #     `:object`.
   def load_binary(io); end

data/yard-stubs/carray_mask.rb

@@ -26,7 +26,20 @@ class CArray
   #   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.
+  #   This is a method for peeking at the internal state of an array, and
+  #   nothing more. What a masked cell holds is not defined: a computation
+  #   leaves there whatever it happens to. Use it on the spot, as in
+  #   `a.value.copy`, `a.value[nil, 1].copy` or `a.value[nil, 1] = 2`; do
+  #   not keep the view to carry around (`b = a.value`,
+  #   `b = a.value[nil, 1]`), do not compute with it, and do not mix it
+  #   with other arrays (as an operand, or as a part of {CArray.stack} or
+  #   {CArray.meld}). To take the mask off, use {#unmask} or
+  #   {#strip_mask} and give the masked cells a value.
+  #
+  #   A library that handles the mask itself may use `value` on the spot
+  #   to hand the stored cells on together with {#mask}, as long as it
+  #   reads nothing from the masked ones.
+  #
   #   Nothing in a value array is masked, so `unmask` on it does nothing,
   #   while a write that would mask a cell (`UNDEF`, `mask=`,
   #   `invert_mask`) raises TypeError.
@@ -84,6 +97,12 @@ class CArray
   # that derives values from neighbouring valid cells (mask gap-fill).
   # The two are mutually exclusive: passing both raises `ArgumentError`.
   #
+  # On a view, the values are written through to the cells it views. A
+  # position with no cell behind it -- the place of a masked cell of an
+  # index array (`a[i]`), as a join with `view: :full` gives for an
+  # unmatched row -- takes no write and stays masked, without an error.
+  # `strip_mask` gives a new array, where every masked cell takes a value.
+  #
   # @overload unmask
   #   Clears the mask state of every element of `self`, leaving the
   #   stored data values untouched. Mutates `self`.

data/yard-stubs/carray_math.rb

@@ -231,6 +231,13 @@ class CArray
   #   integer base with a negative integer exponent truncates toward
   #   zero rather than producing a fraction (`2 ** -1` is `0`). Cast to
   #   a float `data_type` first when a fractional power is wanted.
+  #   A float or complex array raised to an Integer is computed by
+  #   repeated multiplication rather than by `pow`.  Its rounding error
+  #   grows roughly in proportion to the exponent (tens of ulps at 100,
+  #   hundreds of thousands at a million), where `Float#**` and the same
+  #   exponent given as a Float are within an ulp or so; give the exponent
+  #   as a Float when a large one needs full precision.  The exponent can
+  #   be any Integer that fits 64 bits.
   #   Masked elements stay masked.
   #   @param other [CArray, Numeric] exponent, broadcast to `self.shape`.
   #   @return [CArray] result of the promoted `data_type` of the two
@@ -949,13 +956,15 @@ class CArray
   # @overload &(other)
   #   Returns the element-wise conjunction of `self` and `other`: a
   #   bitwise `AND` on integer arrays, a logical `AND` on boolean ones.
+  #   **On boolean arrays it is three-valued (Kleene); {#and} is the
+  #   two-valued form.** The two give different answers where one side
+  #   is masked.
   #
-  #   On boolean arrays the masked elements follow three-valued
-  #   (Kleene) logic rather than propagating blindly: an unknown
-  #   element `AND` `false` is `false`, because the answer does not
-  #   depend on the unknown. Only where the result genuinely depends on
-  #   a masked element is the result masked. {#and} is the two-valued
-  #   form that always propagates.
+  #   An unknown (masked) element `AND` `false` is `false`, because the
+  #   answer does not depend on the unknown; only where the result
+  #   genuinely depends on a masked element is the result masked. So
+  #   `(a & b).not` is `true` where `a` is `false`, whatever `b` is,
+  #   while `a.and(b).not` stays masked where `b` is.
   #   @param other [CArray, Integer, true, false] the other operand,
   #     broadcast to `self.shape`.
   #   @return [CArray] `:boolean` for boolean operands, otherwise the
@@ -972,8 +981,9 @@ class CArray
   # @overload |(other)
   #   Returns the element-wise disjunction of `self` and `other`: a
   #   bitwise `OR` on integer arrays, a logical `OR` on boolean ones.
-  #   Boolean operands follow Kleene logic as in {#&}, so an unknown
-  #   element `OR` `true` is `true`.
+  #   **On boolean arrays it is three-valued (Kleene) as {#&} is; {#or}
+  #   is the two-valued form.** An unknown element `OR` `true` is
+  #   `true`.
   #   @param other [CArray, Integer, true, false] the other operand,
   #     broadcast to `self.shape`.
   #   @return [CArray] `:boolean` for boolean operands, otherwise the
@@ -1055,13 +1065,16 @@ class CArray
   def not; end
 
   # @overload and(other)
-  #   Returns the two-valued logical `AND` of two boolean arrays.
+  #   Returns the logical `AND` of two boolean arrays, **two-valued: a
+  #   masked element on either side makes the result masked**, even
+  #   where the other side alone would settle the answer. {#&} is the
+  #   three-valued form, and the two differ exactly there: `false & U`
+  #   is `false`, `false.and(U)` is `U`.
   #
-  #   Where {#&} applies Kleene logic, this form propagates the mask
-  #   unconditionally: if either element is masked the result is
-  #   masked, even when the unmasked element alone would settle the
-  #   answer. Use it when an unknown operand should make the result
-  #   unknown regardless.
+  #   Use it when the answer should be given only where both inputs are
+  #   known -- the element-wise counterpart of keeping only complete
+  #   records -- and {#&} when an answer the known side settles should
+  #   stand.
   #   @param other [CArray, true, false] the other operand, broadcast
   #     to `self.shape`.
   #   @return [CArray] `:boolean`.
@@ -1070,8 +1083,10 @@ class CArray
   def and(other); end
 
   # @overload or(other)
-  #   Returns the two-valued logical `OR` of two boolean arrays,
-  #   propagating the mask unconditionally as {#and} does.
+  #   Returns the logical `OR` of two boolean arrays, **two-valued: a
+  #   masked element on either side makes the result masked**, as
+  #   {#and} does. {#|} is the three-valued form: `true | U` is `true`,
+  #   `true.or(U)` is `U`.
   #   @param other [CArray, true, false] the other operand.
   #   @return [CArray] `:boolean`.
   #   @raise [CArray::DataTypeError] for any `data_type` other than

data/yard-stubs/carray_memory_view.rb

@@ -102,6 +102,13 @@ class CArray
     #   returned object via internal ivars; the source is released
     #   when the wrap is garbage-collected.
     #
+    #   Views made from the wrap keep it reachable too, so the view is
+    #   given back only once all of them are collected. A producer that
+    #   locks while it is borrowed (`IO::Buffer` refuses `resize` and
+    #   `free`) stays locked until then; import with
+    #   {.from_memory_view} to hold no view at all. See
+    #   {file:docs/interop/MemoryView.md MemoryView} §9.
+    #
     #   Contiguous typed producers return a `CAWrap`. Strided typed
     #   producers return a `CAStride` over a byte `CAWrap` of the
     #   bytes its elements reach, preserving the full stride pattern

data/yard-stubs/carray_test.rb

@@ -36,8 +36,11 @@ class CArray
   # @overload ==(other)
   #   Returns `true` if `other` is a CArray with the same shape,
   #   `data_class`, `data_type`, mask state, and elementwise values as
-  #   `self`. NaN values compare unequal (IEEE semantics), so two
-  #   arrays with NaN at the same position are not `==`.
+  #   `self`. It asks whether the contents are the same, so a NaN equals
+  #   a NaN at the same position (whatever its payload, in a float, a
+  #   complex part or an object cell) and -0.0 equals 0.0: an array with
+  #   NaN is `==` to its copy. The IEEE comparison, where NaN equals
+  #   nothing, is {#eq}, cell by cell.
   #
   #   A Face (a time, string or categorical array) equals only a Face of
   #   its own class, and is compared by its values: two time arrays of
@@ -53,8 +56,8 @@ class CArray
   #   Returns `true` under Hash-invariant semantics: `data_class`,
   #   `data_type`, shape, and mask state must all match, and elements
   #   are compared bitwise (for numeric types) or via `Object#eql?`
-  #   (for `:object` arrays). Unlike `==`, `NaN.eql?(NaN)` holds, so
-  #   two mask-free arrays with NaN at the same positions are `eql?`.
+  #   (for `:object` arrays), so -0.0 and 0.0 differ and two NaNs are
+  #   `eql?` only with the same bits.
   #   Two Faces are `eql?` only when they are of the same class, share
   #   their state (a time array's unit, a categorical's labels) and hold
   #   the same storage.

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: carray
 version: !ruby/object:Gem::Version
-  version: 3.0.5
+  version: 3.0.6
 platform: ruby
 authors:
 - himotoyoshi
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: |2
       Ruby/CArray adds multi-dimensional numerical arrays to Ruby. Elements are held
       in a single flat memory block, so whole-array work -- element-wise arithmetic,
@@ -318,14 +332,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Multi-dimensional numerical array class for Ruby
 test_files: []