carray 3.0.5 → 3.0.6

data/ext/ruby_carray.c

@@ -14,6 +14,7 @@
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "carray_internal.h"
 #include "carray_build_flags.h"
 #include "version.h"
 
@@ -313,7 +314,7 @@ Init_carray_ext (void)
   Init_carray_sort();               /* sort / sort_copy / sort_addr / axis2addr */
   Init_carray_count();
   Init_carray_kernels();            /* mkkernel-generated: reductions + maps */
-  Init_carray_round();              /* round(ndigits); after the generated round */
+  Init_carray_round();              /* round(ndigits) / round!(ndigits) */
 
   Init_carray_utils();
 
@@ -394,5 +395,7 @@ Init_carray_ext (void)
   Init_carray_slab();
 
   Init_carray_address_basis();
+
+  ca_obj_num_builtin = ca_obj_num;
 }
 

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.5"
-#define CA_VERSION_CODE 30005
+#define CA_VERSION "3.0.6"
+#define CA_VERSION_CODE 30006
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 5
-#define CA_VERSION_DATE "2026/10/20"
+#define CA_VERSION_TEENY 6
+#define CA_VERSION_DATE "2026/10/28"

data/lib/carray/attribute.rb

@@ -6,6 +6,7 @@
 #    ca.set_attr(:unit, "m/s")  # => setter; writes to self's @attr
 #    ca.set_attrs(other.attrs)  # => sets every key of a Hash at once
 #    ca.attrs                   # => frozen shallow clone of the full Hash
+#    ca.attrs_symkey            # => the same, with Symbol keys (nested too)
 #    ca.has_attr?               # => any attribute present?
 #    ca.has_attr?(:unit)        # => specific key present?
 #
@@ -162,6 +163,15 @@ class CArray
     (merged || {}).freeze
   end
 
+  # @overload attrs_symkey
+  #   Returns {#attrs} with its keys as Symbols, frozen.  The keys of
+  #   Hashes nested in the values, inside Arrays too, become Symbols
+  #   as well.
+  #   @return [Hash{Symbol => Object}]
+  def attrs_symkey
+    return CArray.__send__(:attr_symbolize_keys, self.attrs)
+  end
+
   # @overload has_attr?
   #   Returns whether `self` (or any parent view) has any attribute
   #   set.
@@ -317,6 +327,20 @@ class CArray
       v
     end
   end
-  private_class_method :attr_normalize_key, :attr_validate_value, :attr_coerce_value
+  # A stored value with the keys of every Hash in it as Symbols, frozen
+  # as the stored value is.
+  def self.attr_symbolize_keys (v)
+    case v
+    when Array then v.map { |e| attr_symbolize_keys(e) }.freeze
+    when Hash
+      v.each_with_object({}) do |(k, vv), h|
+        h[k.to_sym] = attr_symbolize_keys(vv)
+      end.freeze
+    else
+      v
+    end
+  end
+  private_class_method :attr_normalize_key, :attr_validate_value, :attr_coerce_value,
+                       :attr_symbolize_keys
 
 end

data/lib/carray/autoload_carray.rb

@@ -32,12 +32,12 @@ class CArray
   autoload_method "marshal_load",        serialize_rb
 end
 
-# A view, a wrap and a scalar are marshalled through _dump / self._load,
+# A view, a mask, a wrap and a scalar are marshalled through _dump / self._load,
 # which return a new array: with marshal_dump Marshal records the class and
 # loads into an empty instance of it, which the plain array the payload
 # holds cannot become.  A record array keeps marshal_dump, under which it
 # already round-trips with its class.
-[CAView, CAWrap, CScalar].each do |klass|
+[CAView, CAWrap, CScalar, CArrayMask, CAObjectMask].each do |klass|
   klass.class_eval do
     undef_method :marshal_dump
     autoload_method "_dump",               "carray/serialize"
@@ -137,7 +137,7 @@ autoload :CAUnion,  "carray/struct"
 # ---- CAFrame (DataFrame over CArray columns) -------------------------------
 #
 # The frame is only reached through the CAFrame constant (CAFrame.new /
-# .from_csv / subclassing) or GroupedFrame (obtained from CAFrame#group_by,
+# .read_csv / subclassing) or GroupedFrame (obtained from CAFrame#group_by,
 # by which point CAFrame is already loaded). Both constants live in the same
 # require bundle (carray/frame.rb), so autoloading either loads the whole
 # frame. Nothing in the eager core references them, so it loads on first use.

data/lib/carray/autoload_method_extension.rb

@@ -31,9 +31,11 @@ module AutoloadMethodExtension
 
   private
 
-  def autoload_define (target, name, library, original_spec)
-    library       = Ractor.make_shareable(library.to_s.dup)
-    original_spec = Ractor.make_shareable(original_spec.to_s.dup)
+  def autoload_define (target, name, library_given, spec_given)
+    # The stub reads these two, so they are never assigned again: Ruby 4.0
+    # refuses to make a Proc shareable when a variable it reads may be.
+    library       = Ractor.make_shareable(library_given.to_s.dup)
+    original_spec = Ractor.make_shareable(spec_given.to_s.dup)
     # Shareable, so the stub answers in any Ractor.  Only the main Ractor
     # loads the library: Ractors that require at the same time can deadlock
     # (Ruby 3.4), so another Ractor is told what to load there instead.

data/lib/carray/axis_group.rb

@@ -409,7 +409,7 @@ class CAGroupIterator
     # except for a band folded into the count, which has no route but the
     # engine.
     def core_counts? (kw)
-      return false if CArray.__fast_paths_enabled__
+      return false if CArray.__fast_paths_enabled__(:axis_group_count_kernel)
       has_group, fused = AxisGroup.parse_axis(kw[:axis])
       has_group && fused.empty?
     end
@@ -494,8 +494,8 @@ class CAGroupIterator
   # Weighted mean = Sum(v*w) / Sum(w), both over the combined present-set. The
   # `value*0 + weights` denominator carries the same value|weight mask, so its
   # group-sum is Sum(w) over exactly the cells value*weight used. An empty group
-  # (no present pair) is UNDEF (matching CArray#wmean); a present group whose
-  # weights sum to zero yields NaN/Inf (core's 0/0).
+  # (no present pair) and a group whose weights sum to zero are UNDEF, as
+  # CArray#wmean leaves both.
   def wmean (weights, **kw)
     has_group, = AxisGroup.parse_axis(kw[:axis])
     return value.wmean(weights, **kw) unless has_group
@@ -508,7 +508,7 @@ class CAGroupIterator
     # No present pair is UNDEF (an empty group), set on the denominator so
     # the division never meets an empty group's 0 / 0.
     den  = den.copy
-    den[cnt.eq(0)] = UNDEF
+    den[cnt.eq(0).or(den.eq(0))] = UNDEF
     # min_count: counts the present pairs, as the core wmean does.
     pairs = regroup(prod, spec)
     pairs.finish_reduction(:wmean, kw, num / den)
@@ -863,7 +863,7 @@ class CAGroupIterator
   # pass. With the fast paths off it goes through the band loop instead,
   # which then has one position.
   def whole_block? (bslots)
-    bslots.empty? && CArray.__fast_paths_enabled__
+    bslots.empty? && CArray.__fast_paths_enabled__(:axis_group_whole_block)
   end
 
   # Iterate the band positions of a band-preserving grouping. For each band
@@ -923,9 +923,15 @@ class CAGroupIterator
   # paths off (a development build run with CARRAY_GENERAL_PATH set) each
   # group is reduced by the core instead -- except a band folded into the
   # statistic (+fused+), which has no route but the kernel.
+  #
+  # With no band axis the core groups the whole value in one pass, which is
+  # faster than the kernel for every group size (1M cells on an M2 Max: 7.5
+  # to 12.5 ms against 15 ms), so the kernel is taken only with a band.
   def kernel_reads_value? (fused = [])
     return false if value.face? || ! (value.integer? || value.float?)
-    CArray.__fast_paths_enabled__ || ! fused.empty?
+    return true unless fused.empty?
+    return false if spec.slot_meta.none? { |m| m[:kind] == :band }
+    CArray.__fast_paths_enabled__(:axis_group_reduce_kernel)
   end
 
   # Whether the scan kernel gives the core's answer: it reads an integer,
@@ -933,7 +939,7 @@ class CAGroupIterator
   # float64 (an object in object), cummax / cummin in the payload's data type
   # and cumcount in int64 -- not the core's answer for a boolean's running sum.
   def kernel_scans? (op)
-    return false unless CArray.__fast_paths_enabled__
+    return false unless CArray.__fast_paths_enabled__(:axis_group_scan_kernel)
     return false if value.face? || value.complex?
     return true if value.object? || op == :cumcount
     core = CAIterator.core_probe(value).public_send(op).data_type

data/lib/carray/basics.rb

@@ -122,7 +122,7 @@ class CArray
   #   @return [CArray] view with reduced `ndim`.
   def drop_axis
     if ndim == 1
-      return self[]
+      return scalar? ? self : self[]
     else
       newdim = shape.reject{|x| x == 1 }
       newdim = [1] if newdim.empty?     # every axis has size 1: keep one

data/lib/carray/block_iterator.rb

@@ -74,6 +74,14 @@ class CABlockIterator < CAIterator
             "blocks: expected #{source.ndim} tile sizes (one per axis), " \
             "got #{blocks.size}"
     end
+    # Each tile is read through a view with one axis per tile position and
+    # one per cell in the tile, twice the source's rank.
+    if 2 * source.ndim > CA_RANK_MAX
+      raise ArgumentError,
+            "blocks: a rank #{source.ndim} array would need #{2 * source.ndim} " \
+            "axes for its tiles, beyond the limit of #{CA_RANK_MAX}; " \
+            "blocks works up to rank #{CA_RANK_MAX / 2}"
+    end
 
     @sndim   = source.ndim
     offsets  = Array.new(@sndim, 0)
@@ -93,7 +101,9 @@ class CABlockIterator < CAIterator
     # Absorb a leading offset with a zero-copy pre-slice, so the tile geometry
     # below always starts at index 0.
     @source =
-      if offsets.all?(&:zero?)
+      if source.scalar?
+        source.flatten        # a CScalar takes no index; its one-cell view does
+      elsif offsets.all?(&:zero?)
         source
       else
         source[*offsets.map { |o| o..-1 }]
@@ -517,7 +527,7 @@ class CABlockIterator < CAIterator
       sview = saddr[*strip_ranges].block_view(*tiles)
       grid  = (0...@sndim).map { |i| vview.shape[i] }
       cells = tiles.inject(1) { |p, t| p * t }
-      order = vview.copy.reshape(*(grid + [cells])).sort_addr(axis: @sndim)
+      order = vview.copy.reshape(*(grid + [cells])).sort_index(axis: @sndim)
       src_sorted = sview.reshape(*(grid + [cells])).take_along_axis(order, axis: @sndim)
       out[*strip_ranges].block_view(*tiles)[] = src_sorted.reshape(*(grid + tiles))
     end
@@ -817,7 +827,7 @@ class CABlockIterator < CAIterator
   # A padded entity whose interior holds the source and whose partial-edge
   # margin is masked (UNDEF), sized to exactly cover the ceil tile grid.  When
   # the source already divides evenly this is the source itself (no copy), so
-  # the tiles alias it.  Memoised; feeds the iterate escape hatches.
+  # the tiles alias it.  Kept for one call; feeds the iterate escape hatches.
   def padded_source
     @padded_source ||= begin
       pshape = @sndim.times.map { |i| @shape[i] * @sizes[i] }
@@ -845,6 +855,8 @@ class CABlockIterator < CAIterator
     def lag (*args, **keywords) = @source.__send__(:carry_attrs, super)
     def strip_mask (**keywords) = @source.__send__(:carry_attrs, super)
   end)
+
+  read_source_per_call :@padded_source, :@tile_grid_view
 end
 
 
@@ -857,6 +869,8 @@ class CArray
   #   first for "valid" tiling.
   #   @param blocks [Array<Integer, Range>] per-axis tile sizes (or ranges).
   #   @return [CABlockIterator]
+  #   @raise [ArgumentError] when `self` has a rank above `CA_RANK_MAX / 2`
+  #     (8): the tiles are read through a view of twice the rank.
   def blocks (*blocks)
     CABlockIterator.new(self, *blocks)
   end

data/lib/carray/categorical.rb

@@ -415,8 +415,8 @@ class CACategorical < CAObject
   # Memoised: the codes are read-only (immutable storage), so the counts are a
   # pure function of the categorical and stay valid for its lifetime. The same
   # cached array backs {#reduceat_index} and {#group_addr}, so a wide aggregate
-  # over the same categorical pays the count once. (Do not mutate the returned
-  # array — it is shared; take `.copy` for a scratch buffer.) A derived-view /
+  # over the same categorical pays the count once. The returned array is shared,
+  # so it is frozen; take `.copy` for a scratch buffer. A derived-view /
   # composite categorical caches too: read-only rides from the codes as a flag,
   # not a Ruby freeze, so the object stays non-frozen and the memo ivar sticks.
   # @overload category_sizes
@@ -429,8 +429,7 @@ class CACategorical < CAObject
     bc  = codes.bincount
     out = CArray.new(bc.data_type, [@labels.size], bytes: bc.bytes)   # new zero-fills
     out[0...bc.elements] = bc if bc.elements > 0
-    @category_sizes = out
-    out
+    @category_sizes = out.freeze
   end
 
   # Back-compatible alias; {#category_sizes} is the canonical name (a histogram
@@ -635,7 +634,7 @@ class CACategorical < CAObject
   # Memoised (see the grouping-plan note above): the counting sort is the
   # dominant grouping cost, so it is computed once and shared by every payload
   # column and by CACategoricalIterator, and kept for the categorical's
-  # lifetime (an int64 per cell). Do not mutate the returned array.
+  # lifetime (an int64 per cell). The returned array is shared, so it is frozen.
   # @overload group_addr
   #   Returns a length-{#elements} integer CArray of flat storage
   #   addresses that order the cells by category (excluded cells last).
@@ -645,8 +644,7 @@ class CACategorical < CAObject
     out = codes.reshape(elements).__send__(:addresses_by_category,
                                            reduceat_index.copy, @labels.size,
                                            category_sizes.sum)
-    @group_addr = out
-    out
+    @group_addr = out.freeze
   end
 
   # Segment start offsets into the category-contiguous layout produced by
@@ -663,7 +661,7 @@ class CACategorical < CAObject
     return @reduceat_index if @reduceat_index
     # Every boundary but the last; the copy makes it an entity the
     # reduceat kernels can read directly.
-    @reduceat_index = CArray.segment_offsets(lengths: category_sizes)[0...-1].copy
+    @reduceat_index = CArray.segment_offsets(lengths: category_sizes)[0...-1].copy.freeze
   end
 
   # @overload categorize(labels: nil, sort_labels: false)

data/lib/carray/categorical_iterator.rb

@@ -295,7 +295,7 @@ class CACategoricalIterator < CASegmentIterator
   #   @overload wmean(weights, axis:)
   #     Per-fiber per-category weighted mean along `axis`.  Same weights-shape
   #     contract as {#wsum} (weights.shape == source.shape).  Empty cell → MASKED;
-  #     a present cell whose weights sum to zero → NaN (0/0 core contract).
+  #     a present cell whose weights sum to zero → UNDEF, as CArray#wmean.
   #     @param weights [CArray]
   #     @param axis [Integer]
   #     @return [CArray]
@@ -551,7 +551,7 @@ class CACategoricalIterator < CASegmentIterator
     codes = @cat.codes
     # Classified along the axis, a group is taken by index; the general way,
     # masking the rest of a copy, gives the same cells.
-    if codes.shape == [h.shape[axis]] && CArray.__fast_paths_enabled__
+    if codes.shape == [h.shape[axis]] && CArray.__fast_paths_enabled__(:categorical_group_by_index)
       sel = none ? CArray.boolean(codes.elements) { false } : codes.eq(c)
       sel = sel.strip_mask(false) if sel.has_mask?
       idx = [nil] * h.ndim

data/lib/carray/complex.rb

@@ -74,7 +74,7 @@ class CArray
              when CA_CMPLX128 then field(0, CA_FLOAT64)
              end
            else
-             self[]
+             scalar? ? self : self[]
            end
     frozen? ? view : (@__real__ = view)
   end
@@ -100,7 +100,7 @@ class CArray
     end
     if not complex?
       zero = template { 0 }
-      zero[is_masked] = UNDEF if has_mask?
+      zero.inherit_mask(self) if has_mask?
       return zero
     end
     return @__imag__ if part_of_self?(@__imag__)

data/lib/carray/conditional.rb

@@ -219,8 +219,9 @@ class CArray
             "conditional: cond must be a boolean CArray with same shape as self"
     end
 
-    x_then = self[cond]
-    x_else = self[cond.not]
+    src    = scalar? ? flatten : self   # a CScalar takes no index
+    x_then = src[cond]
+    x_else = src[cond.not]
     y_then = then_fn.call(x_then)
     y_else = else_fn.call(x_else)
     text = !data_type && CArray.send(:selection_text?, [y_then, y_else])

data/lib/carray/frame/column_verbs.rb

@@ -3,22 +3,32 @@
 class CAFrame
 
   # The one rule of a frame-wide verb over the frame's columns -- the group
-  # reductions and transforms, the windowed reductions -- kept in one place
-  # so that every verb answers in the same shape:
+  # reductions and transforms, the windowed reductions, and the frame's own
+  # reductions and running values -- kept in one place: which columns a verb
+  # computes, and what a named column without the operation does.
   #
-  # - given names, the CArray (one) or the Array of them (several), as
-  #   +df[...]+ returns columns; a named column whose type has no such
-  #   operation is refused with CArray::DataTypeError, as the core refuses
-  #   it, since it was asked for;
+  # - given names, those columns, as the CArray (one) or a Hash of name to
+  #   result (several); a named column whose type has no such operation is
+  #   refused with CArray::DataTypeError, as the core refuses it, since it
+  #   was asked for;
   # - given none, every column whose type has it, the key columns left out,
-  #   as a Hash of name to result that the caller makes a frame of.
+  #   as a Hash of name to result.
+  #
+  # The caller decides the shape of the answer from these: a verb whose
+  # answers lie on the frame's rows (a transform, a window at the rows,
+  # +keep_rows:+) hands one named column back as it is, as +df[name]+
+  # returns it, and several as a frame on the frame's rows, while a verb
+  # with one row per group, per point or for the whole frame makes a frame
+  # of them, labelled by its rows.
   #
   # Whether a type has the operation is asked of the core on two copies of
   # the column's first row (two blank cells of its kind when it has no
   # rows), so the answer is about the type and not the data: a refusal
   # there means the operation does not apply, while an error in the verb
-  # itself is left to raise. An N-D column (each row a profile) is asked,
-  # and computed, along the rows.
+  # itself is left to raise. An object column is the exception: its type
+  # says nothing of what it holds, so one with no present value is left out
+  # of a verb run over every column. An N-D column (each row a profile) is
+  # asked, and computed, along the rows.
   module ColumnVerbs
 
     private
@@ -29,13 +39,17 @@ class CAFrame
         @frame.column_names.each do |name|
           next if key_names.include?(name)
           col = @frame[name]
+          next if valueless_object_column?(col, verb, args)
           next unless column_has?(col, verb, args, keywords)
           cols[name] = yield(col, name)
         end
         return cols
       end
-      results = names.map do |name|
-        key = @frame.__send__(:column_key, name, verb)
+      # A column named twice would be one result column twice over.
+      keys = CAFrame.__send__(:refuse_repeated_names,
+                              names.map { |name| @frame.__send__(:column_key, name, verb) }, verb)
+      results = keys.map do |key|
+        name = key
         col = @frame[key]
         unless column_has?(col, verb, args, keywords)
           raise CArray::DataTypeError,
@@ -44,7 +58,17 @@ class CAFrame
         end
         yield(col, key)
       end
-      results.size == 1 ? results.first : results
+      results.size == 1 ? results.first : keys.zip(results).to_h
+    end
+
+    # An object column with no present cell says nothing of what it holds,
+    # so a verb run over every column leaves it out, as select leaves it out
+    # of every kind; counting the present cells applies to any column.
+    def valueless_object_column? (col, verb, args)
+      return false if col.face? || col.data_type != CA_OBJECT
+      return false if %i[count_not_masked count_masked].include?(verb)
+      return false if verb == :count && args.empty?
+      col.count_not_masked == 0
     end
 
     # count with no value counts the present cells, which every type has;
@@ -54,10 +78,17 @@ class CAFrame
       verb = :count_not_masked if verb == :count && args.empty?
       # Two cells: one cell does not reach what combines two (a String's
       # median interpolates, its sum adds), and an empty column answers
-      # with the identity without asking the type at all.
+      # with the identity without asking the type at all. The row is the
+      # first that holds a present cell, so a masked first row does not
+      # answer with the identity for a column whose values have none.
       tail = [nil] * (col.ndim - 1)
+      row = 0
+      if col.has_mask? && col.elements > 0
+        present = col.is_not_masked.flatten.where
+        row = present[0] / (col.elements / col.shape[0]) if present.elements > 0
+      end
       probe = if col.shape[0] > 0
-                col[CA_INT64([0, 0]), *tail]
+                col[CA_INT64([row, row]), *tail]
               else
                 col.resize(2, *col.shape[1..])
               end

data/lib/carray/frame/convert.rb

@@ -26,6 +26,25 @@ class CAFrame
     each_row.map { |row| row.transform_values { |v| record_value(v) } }
   end
 
+  # The rows as an Array of Arrays, one value per column in column order --
+  # the table as plain Ruby data, for a library that takes rows (anything
+  # that calls +to_a+ on what it is given). A cell is what the column's own
+  # +to_a+ gives: a masked cell is +UNDEF+, a time column's cell its element,
+  # and an N-D column's cell an Array. The index is a row label, not a value,
+  # and is left out; +reset_index+ first to have it as the first column.
+  #
+  # Masked cells are not turned into anything: decide what they should be
+  # before handing the rows over, with +strip_mask+ or +drop_masked+.
+  #
+  #   df.drop_masked.to_a
+  #   df.strip_mask("temp" => Float::NAN).to_a
+  #
+  # @return [Array<Array>]
+  def to_a
+    return Array.new(@nrow) { [] } if @columns.empty?
+    return @columns.values.map(&:to_a).transpose
+  end
+
   # Hand the frame over as a CArray with the minimum work (memo §11.9): a
   # 2-D **view** of shape (nrow, ncol), one per column in column
   # order (§12-C). Nothing is materialised — the result is a +CAStack+ over