carray 3.0.4 → 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.4"
-#define CA_VERSION_CODE 30004
+#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 4
-#define CA_VERSION_DATE "2026/10/19"
+#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?
 #
@@ -33,14 +34,17 @@
 #    parent's cells, so the parent's attributes do not describe them.
 #    `a.lazy` itself (CALazyMarker) is a view of `a` and walks through,
 #    and so does a lazy type conversion (the cast lane `promote_list`
-#    and `wrap_readonly` build), for the reason `to_type` carries them.
+#    and `wrap_readonly` build), for the reason `to_type` carries them,
+#    and `swap_bytes`: like `refer`, `bitarray` and `bitfield`, a view
+#    that reads the same cells another way carries them.
 #    A view of a Face shows the attributes of the Face it was taken
 #    from (the walk goes to that Face, which the view's own parent
 #    chain skips).
 #    A view of several arrays (CAStack / CAMeld, so `stack`, `meld` and
 #    `montage`) shows, below its own @attr, the keys every one of its
 #    arrays shows with the same value; a key they disagree on, or one
-#    some of them lack, is not shown.
+#    some of them lack, is not shown.  An array with no cells is left out
+#    of that count, unless all of them are empty.
 #
 #  Stored values are frozen copies, nested Arrays and Hashes included, so
 #  an attribute changes only through set_attr / set_attrs: a value read
@@ -58,7 +62,9 @@
 #  `categorize`, a CAFrame `cast` / `parse_to_time` / `to_time`) carries
 #  them.  Arithmetic and reductions do not -- the result is a different
 #  quantity -- including those that pick a value (`first`, `last`, `min`,
-#  `max`, `unique`).  A CAFrame index built from a key column's values
+#  `max`, `unique`) and the element-wise ones that keep the unit (`abs`,
+#  `round`, `clip`): an attribute does not say which operations leave it
+#  true, so none carries it.  Set it on the result again.  A CAFrame index built from a key column's values
 #  (group and pivot) shows the key column's attributes.
 
 class CArray
@@ -157,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.
@@ -235,7 +250,12 @@ class CArray
   end
 
   # The attributes every array in `list` shows with the same value.
+  # An array with no cells holds no values for the attributes to describe,
+  # so it has no say (unless every one is empty), as CAFrame leaves a frame
+  # with no rows out of a meld.
   def self.attrs_shared_by (list)
+    with_cells = list.reject { |a| a.elements == 0 }
+    list = with_cells unless with_cells.empty?
     first, *rest = list.map(&:attrs)
     return {} if first.nil?
     first.select { |k, v| rest.all? { |h| h.key?(k) && h[k] == v } }
@@ -243,7 +263,10 @@ class CArray
   private_class_method :attrs_shared_by
 
   def attr_computing_view? (ca)
-    return ca.__op_id__ < CAMonOp::CAST_BASE if ca.is_a?(CAMonOp)
+    if ca.is_a?(CAMonOp)
+      op = ca.__op_id__
+      return op < CAMonOp::CAST_BASE && op != CAMonOp::OP_BYTE_SWAP
+    end
     ca.is_a?(CABinOp) || ca.is_a?(CATriOp) ||
       ca.is_a?(CAMonCmp) || ca.is_a?(CABinCmp)
   end
@@ -304,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

@@ -117,13 +117,15 @@ class CArray
   end
 
   # @overload drop_axis
-  #   Returns a view of `self` with every size-1 axis dropped.
+  #   Returns a view of `self` with every size-1 axis dropped.  When every
+  #   axis has size 1, one axis of size 1 is kept.
   #   @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
       return ( ndim != newdim.size ) ? reshape(*newdim) : self[]
     end
   end
@@ -189,7 +191,13 @@ class CArray
   #   @param src [CArray] source array.
   #   @return [self]
   #   @raise [ArgumentError] when `offset.length != self.ndim`.
+  #   @raise [FrozenError] when `self` is frozen.
   def paste (offset, src)
+    # The write goes through a window view, which is not frozen itself:
+    # refuse a frozen self here, as a write into it directly is refused.
+    if frozen?
+      raise FrozenError.new("can't modify frozen #{self.class}: #{inspect}", receiver: self)
+    end
     raise ArgumentError, "offset length must equal ndim" if offset.length != ndim
     # A zero-length source covers no cell, so there is nothing to write --
     # and the empty range it would ask for is not a window CAWindow can
@@ -310,8 +318,7 @@ class CArray
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #
-  #   Either bound may be `nil` for a one-sided clip; that side
-  #   dispatches to the `pmax` / `pmin` binop kernels. When
+  #   Either bound may be `nil` for a one-sided clip. When
   #   `fill_value` (or `lfill` / `ufill`) is given, out-of-range
   #   cells are replaced by the fill instead of clamped -- pass
   #   `UNDEF` to mask that end. `fill_value` is sugar for symmetric
@@ -320,6 +327,8 @@ class CArray
   #
   #   `min` may not exceed `max` (in any cell, when a bound is an
   #   array); equal bounds give every unmasked cell that value.
+  #   A NaN cell of `self` stays NaN, one-sided or two-sided (unlike
+  #   `pmax` / `pmin`, which answer the other operand for it).
   #   A NaN in a bound array leaves that cell unbounded on that side,
   #   as `nil` does for the whole side.  A bound is never UNDEF or
   #   masked: a missing bound is not read as either, so fill it first.
@@ -373,19 +382,30 @@ class CArray
 
     if lfill.nil? && ufill.nil?
       return clamp_between(min, max) if !min.nil? && !max.nil?
-      return pmax(min) if max.nil?
-      return pmin(max)
+      return clamp_below(min) if max.nil?
+      return clamp_above(max)
     end
 
     # A side without a fill still clamps.
     out = self.copy
-    out = out.pmax(min) if !min.nil? && lfill.nil?
-    out = out.pmin(max) if !max.nil? && ufill.nil?
+    out = out.clamp_below(min) if !min.nil? && lfill.nil?
+    out = out.clamp_above(max) if !max.nil? && ufill.nil?
     out[self.lt(min)] = lfill unless min.nil? || lfill.nil?
     out[self.gt(max)] = ufill unless max.nil? || ufill.nil?
     out
   end
 
+  # A one-sided clip of a float array passes a NaN cell through, as the
+  # two-sided one does: the open side is a NaN bound, which leaves it
+  # unbounded.  pmax / pmin would answer the bound for a NaN cell.
+  protected def clamp_below (min)
+    float? ? clamp_between(min, Float::NAN) : pmax(min)
+  end
+
+  protected def clamp_above (max)
+    float? ? clamp_between(Float::NAN, max) : pmin(max)
+  end
+
   # `contains` was retired in favour of {#is_in} (value-hash membership).
   # `a.contains(v1, v2)` -> `a.is_in([v1, v2])`;
   # `a.contains(v1, v2, axis: k)` -> `a.is_in([v1, v2]).any(axis: k)`.

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

@@ -299,7 +299,7 @@ class CACategorical < CAObject
   #   `codes[i] = x` raises; use `codes.copy` for a mutable copy.
   #   @return [CArray]
   def codes
-    parent
+    face_storage
   end
 
   # Face hook: carry the vocabulary across lifted views (slice / reshape / …).
@@ -328,10 +328,17 @@ class CACategorical < CAObject
   # Face hook: decode a per-cell code into its category label, through the one
   # decode every code-to-label path shares (see #label_at).
   def storage_to_element(raw)
-    code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(parent.data_type)) : raw
+    code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(face_storage.data_type)) : raw
     label_at(code)
   end
 
+  # Face hook: a value written into a cell (a fill_value of shift and
+  # window) is a label, and the cell holds its code.
+  # @raise [ArgumentError] if the value is not one of the labels.
+  def element_to_storage (value)
+    code_for_fill(value)
+  end
+
   # ---- category-space operations (by label, not code) -------------------
   #
   # The element value of a categorical IS its category, so these specialise
@@ -389,7 +396,14 @@ class CACategorical < CAObject
   #   (0 for an unknown label).
   #   @param label [Object] category to count.
   #   @return [Integer]
-  def count(label)
+  # @overload count
+  #   Returns the number of cells in some category (not masked), as
+  #   {CArray#count} with no value does.
+  #   @return [Integer]
+  def count(*args)
+    return count_not_masked if args.empty?
+    raise ArgumentError, "count: wrong number of arguments (given #{args.size}, expected 0..1)" if args.size > 1
+    label = args[0]
     code = @labels.index(label)
     code ? codes.count(code) : 0
   end
@@ -400,9 +414,9 @@ 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 {#sort_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 /
+  # cached array backs {#reduceat_index} and {#group_addr}, so a wide aggregate
+  # 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
@@ -415,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
@@ -543,7 +556,7 @@ class CACategorical < CAObject
   # The code a fill value stands for: UNDEF stays UNDEF, a label is its code.
   def code_for_fill (value)
     return UNDEF if UNDEF.equal?(value)
-    code = labels.index(value)
+    code = label_position(value)
     raise ArgumentError, "#{value.inspect} is not one of the labels #{labels.inspect}" unless code
     code
   end
@@ -583,27 +596,27 @@ class CACategorical < CAObject
   # two accessors are the building blocks for that other engine — lay the data
   # out as category-contiguous blocks, then select per block.
   #
-  # The grouping plan — sort_addr (the counting sort, the dominant cost) plus
+  # The grouping plan — group_addr (the counting sort, the dominant cost) plus
   # reduceat_index and category_sizes — depends only on the codes, which are
   # read-only. It is therefore memoised (a pure function of the categorical): the
   # first grouping access builds it and every later one reuses it. This is what
   # lets a wide aggregate (many payload columns over one classifier) or a
   # CACategoricalIterator run the counting sort once, not once per column /
   # iterator. Only the plan is cached; the payload-dependent grouped copy
-  # (value.reshape(n)[sort_addr]) is rebuilt per column (it varies with value).
+  # (value.reshape(n)[group_addr]) is rebuilt per column (it varies with value).
 
-  # Force-build (and cache) the whole grouping plan up front — sort_addr,
+  # Force-build (and cache) the whole grouping plan up front — group_addr,
   # reduceat_index, category_sizes — for prepare-ahead use before a batch of
   # groupings. Lazy building already covers correctness; this is the explicit
   # "pay the counting sort now" handle (e.g. right after `df.group_by(col)`).
   # Returns self so it chains.
   # @overload build_grouping
-  #   Eagerly builds and caches the grouping plan (sort_addr / reduceat_index
+  #   Eagerly builds and caches the grouping plan (group_addr / reduceat_index
   #   / category_sizes). Optional — the plan is built lazily on first grouping
   #   access — but useful to pay the counting sort once ahead of a batch.
   #   @return [self]
   def build_grouping
-    sort_addr        # pulls category_sizes; reduceat_index shares category_sizes
+    group_addr       # pulls category_sizes; reduceat_index shares category_sizes
     reduceat_index
     self
   end
@@ -617,26 +630,25 @@ class CACategorical < CAObject
   # order. The first {#category_sizes}.sum addresses are exactly the classified
   # cells in category order — CACategoricalIterator's permutation. For an N-D
   # categorical the addresses are into the raveled storage, so
-  # `value.reshape(elements)[cat.sort_addr]` produces the contiguous blocks.
+  # `value.reshape(elements)[cat.group_addr]` produces the contiguous blocks.
   # 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.
-  # @overload sort_addr
+  # 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).
   #   @return [CArray]
-  def sort_addr
-    return @sort_addr if @sort_addr
+  def group_addr
+    return @group_addr if @group_addr
     out = codes.reshape(elements).__send__(:addresses_by_category,
                                            reduceat_index.copy, @labels.size,
                                            category_sizes.sum)
-    @sort_addr = out
-    out
+    @group_addr = out.freeze
   end
 
   # Segment start offsets into the category-contiguous layout produced by
-  # {#sort_addr}: reduceat_index[c] is where category c's block begins, so
+  # {#group_addr}: reduceat_index[c] is where category c's block begins, so
   # block c spans `reduceat_index[c] ... reduceat_index[c] + category_sizes[c]`.
   # Empty categories repeat the following start (a zero-width block). Length k,
   # aligned to #labels; pair with {#category_sizes} for the block lengths. On
@@ -649,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

@@ -15,7 +15,7 @@
 #      grp.median   # order statistics share the same surface
 #      grp.stddev
 #
-#  This is the consumer of the sort_addr / reduceat_index foundation on
+#  This is the consumer of the group_addr / reduceat_index foundation on
 #  CACategorical.  Order statistics (median / percentile / quantile) cannot be
 #  scattered — they need every value of a group held together — so the values
 #  are materialized into contiguous blocks once, and every reduction (monoid or
@@ -82,7 +82,7 @@ class CACategoricalIterator < CASegmentIterator
   # once and shared by every payload column and iterator — see
   # CACategorical's grouping-plan note). The plan gives the segment STARTS
   # (reduceat_index) and the group-major permutation (perm[slot] = source index
-  # at that grouped slot, = the valid prefix of sort_addr); gathering value
+  # at that grouped slot, = the valid prefix of group_addr); gathering value
   # through perm is the only per-column work. Excluded cells (masked or
   # out-of-vocabulary code) are absent from perm, so they never join a group;
   # the value mask rides the gather into the grouped copy.
@@ -109,7 +109,7 @@ class CACategoricalIterator < CASegmentIterator
       @offsets  = cat.reduceat_index                # cached segment STARTS (int64[k])
       @bounds   = CArray.segment_offsets(lengths: @elements)  # every boundary (int64[k+1])
       # The group-major source indices (#perm) are taken from the cached
-      # sort_addr when first asked for.
+      # group_addr when first asked for.
       @nvalid   = nvalid
       @codes    = cat.codes.reshape(cat.elements)   # flat codes view (map re-walk / weights)
       # Gather value into category-contiguous order via the cached permutation
@@ -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]
@@ -316,12 +316,12 @@ class CACategoricalIterator < CASegmentIterator
 
   # Both are built with the grouping plan, and only on the flat path; the
   # per-fiber form has neither and must not build a segment's.
-  # Group-major source indices = the valid prefix of the cached sort_addr.
+  # Group-major source indices = the valid prefix of the cached group_addr.
   # With no classified cell the prefix is empty (and slicing a length-0
-  # sort_addr would be out of range), so take the empty permutation directly.
+  # group_addr would be out of range), so take the empty permutation directly.
   def perm
     if @nvalid && ! @perm
-      @perm = @nvalid > 0 ? @cat.sort_addr[0...@nvalid] : CArray.int64(0)
+      @perm = @nvalid > 0 ? @cat.group_addr[0...@nvalid] : CArray.int64(0)
     end
     @perm
   end
@@ -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/const_string.rb

@@ -92,6 +92,16 @@ class CAConstString
   # override the L1 generics where present.
   include CArray::StringOperationMixin
 
+  # Face hook: a value written into a cell (a fill_value of shift and
+  # window).  A cell is a byte range of the shared buffer, which has no room
+  # for a String it does not hold, so only UNDEF can be written.
+  # @raise [ArgumentError] for any value but UNDEF.
+  def element_to_storage (value)
+    raise ArgumentError,
+          "a CAConstString can't hold a new String (its strings share one " \
+          "buffer); use UNDEF, or to_string first"
+  end
+
   # ---- ordering family ---------------------------------------------------
   #
   # A storage cell is a `(start, end)` byte range into the shared buffer, so