carray 3.0.3 → 3.0.4

data/lib/carray/categorical_iterator.rb

@@ -63,11 +63,13 @@ require "carray"
 require "carray/segment_iterator"
 
 # A CAIterator over the categories of a CACategorical.  It is a
-# CASegmentIterator over a category-sorted copy of the value: construction
-# gathers the value through the categorical's cached grouping plan, so each
-# category is one contiguous segment, and every reduction without `axis:` is
-# the segment reduction over that copy (one value per category, in {#labels}
-# order).  This class adds the construction, the labels, and the per-fiber
+# CASegmentIterator over a category-sorted copy of the value: the value is
+# gathered through the categorical's cached grouping plan, so each category
+# is one contiguous segment, and every reduction without `axis:` is the
+# segment reduction over that copy (one value per category, in {#labels}
+# order). With few categories and a numeric value, the count / sum / min /
+# max are read from the values by code instead, and the copy is gathered
+# only for the reductions that need it.  This class adds the construction, the labels, and the per-fiber
 # form (`axis:`), which classifies each fiber along an axis and keeps the
 # other axes.
 class CACategoricalIterator < CASegmentIterator
@@ -106,10 +108,9 @@ class CACategoricalIterator < CASegmentIterator
       nvalid    = counts.sum
       @offsets  = cat.reduceat_index                # cached segment STARTS (int64[k])
       @bounds   = CArray.segment_offsets(lengths: @elements)  # every boundary (int64[k+1])
-      # Group-major source indices = the valid prefix of the cached sort_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.
-      @perm     = nvalid > 0 ? cat.sort_addr[0...nvalid] : CArray.int64(0)
+      # The group-major source indices (#perm) are taken from the cached
+      # sort_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
       # and materialise (the reduceat kernels read the grouped buffer's raw ptr,
@@ -118,9 +119,21 @@ class CACategoricalIterator < CASegmentIterator
       # rebuilt per column. With no classified cell (empty / all-excluded) there
       # is nothing to gather — an empty index into an empty source is out of
       # range — so build the empty grouped buffer directly.
-      @grouped  = nvalid > 0 ? value.reshape(value.elements)[@perm].copy
-                             : CArray.new(value.data_type, [0], bytes: value.bytes)
-      @empty    = CArray.new(grouped.data_type, [0], bytes: grouped.bytes)
+      #
+      # With few categories, a numeric value is instead copied as it lies:
+      # the count / sum / min / max read it in one pass by code (scattering
+      # into one slot per category beats gathering every cell first while
+      # the slots stay in cache), and the grouped copy is gathered from it
+      # only when a reduction needs the categories contiguous. Either way
+      # the iterator holds the values as they were when it was built.
+      flat = value.reshape(value.elements)
+      if @k <= SCATTER_CATEGORIES_MAX && kernel_reads?(value.data_type)
+        @as_built = flat.copy
+        @empty    = @as_built[0...0]
+      else
+        @grouped  = nvalid > 0 ? flat[perm].copy : flat[0...0].copy
+        @empty    = @grouped[0...0]       # an empty category is the values' own kind
+      end
     else
       # Shape mismatch: only per-fiber axis: dispatch could still work.  With a
       # 1-D value there is no fiber structure to broadcast into, so a mismatch
@@ -148,6 +161,10 @@ class CACategoricalIterator < CASegmentIterator
     self
   end
 
+  # The most categories for which the count / sum / min / max are read by
+  # scattering the values by code rather than through the grouped copy.
+  SCATTER_CATEGORIES_MAX = 4096
+
   # @overload labels
   #   Returns the category vocabulary the results are aligned to.
   #   @return [Array]
@@ -299,7 +316,13 @@ 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.
+  # 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.
   def perm
+    if @nvalid && ! @perm
+      @perm = @nvalid > 0 ? @cat.sort_addr[0...@nvalid] : CArray.int64(0)
+    end
     @perm
   end
 
@@ -307,6 +330,34 @@ class CACategoricalIterator < CASegmentIterator
     @codes
   end
 
+  # With few categories the grouped copy is gathered from the values as
+  # built, the first time a reduction asks for it.
+  def grouped
+    if @as_built && ! @grouped
+      @grouped = @nvalid > 0 ? @as_built[perm].copy : @as_built[0...0].copy
+    end
+    super
+  end
+
+  def kernel_reads? (data_type = (@as_built || grouped).data_type)
+    super(data_type)
+  end
+
+  # With few categories the count / sum / min / max come from one pass over
+  # the values as built, each cell added to the slot of its code; a cell
+  # whose value or code is masked, or whose code names no category, is in
+  # no slot, as it is in no segment of the grouped copy.
+  def moments
+    return @moments if defined?(@moments)
+    return super unless @as_built && kernel_reads?
+    counts = CArray.int64(@k)
+    sums   = CArray.float64(@k)
+    mins   = CArray.new(@as_built.data_type, [@k])
+    maxs   = CArray.new(@as_built.data_type, [@k])
+    @as_built.__send__(:__fiber_scatter_moments__, @codes, 0, @k, counts, sums, mins, maxs)
+    @moments = { count: counts, sum: sums, min: mins, max: maxs }
+  end
+
   # Axis-aware count of present cells. Counting how many cells fall in a
   # group does not look at what is in them. An integer or float payload goes
   # through the fused moments kernel, which counts in the same pass that
@@ -315,7 +366,7 @@ class CACategoricalIterator < CASegmentIterator
   # counted from the codes and the value's mask, one group at a time.
   def axis_counts (axis, op)
     h = @value
-    return axis_moments(axis, op)[:count] if h.integer? || h.float?
+    return axis_moments(axis, op)[:count] if kernel_reads?(h.data_type)
     axis = checked_axis(axis, op)
     full_c  = resolve_axis_codes(@cat.codes, h.shape, axis)
     band    = h.shape.dup; band.delete_at(axis)
@@ -349,7 +400,7 @@ class CACategoricalIterator < CASegmentIterator
   # this one thing was the odd choice; a caller who wants a fused kernel's
   # four answers shares them by keeping the result.
   def axis_moments (axis, op)
-    return axis_moments_by_core(axis, op) unless MONOID_TYPES.include?(@value.data_type)
+    return axis_moments_by_core(axis, op) unless kernel_reads?(@value.data_type)
     h = @value
     axis = checked_axis(axis, op)
     band = h.shape.dup; band.delete_at(axis)
@@ -382,6 +433,7 @@ class CACategoricalIterator < CASegmentIterator
   # kernel had all four from one.
   BAND_ONLY_KEYS = { sum: [:sum], mean: [:sum, :count], min: [:min],
                      max: [:max], minmax: [:min, :max] }.freeze
+  Ractor.make_shareable(BAND_ONLY_KEYS)
   private_constant :BAND_ONLY_KEYS
 
   def band_only_moments (h, axis, band, op)
@@ -419,7 +471,7 @@ class CACategoricalIterator < CASegmentIterator
   # Axis-aware mean: sums / counts (float64); empty group cells (count=0) MASKED.
   # Matches flat #mean per fiber.
   def axis_mean (axis)
-    return axis_by_core(axis, :mean) unless MONOID_TYPES.include?(@value.data_type)
+    return axis_by_core(axis, :mean) unless kernel_reads?(@value.data_type)
     m   = axis_moments(axis, :mean)
     cnt = m[:count]
     out = m[:sum] / cnt.float64      # count 0 -> NaN
@@ -448,14 +500,13 @@ class CACategoricalIterator < CASegmentIterator
     slot_idx  = [nil] + [nil] * band.size    # placeholder; c fills slot 0
     codes_bad = full_c.has_mask? ? full_c.is_masked : nil
     @k.times do |c|
-      h_local = h.copy
       # Boolean of cells that DO belong to group c (with codes present).  On
       # any masked codes cell the codes.eq(c) result carries UNDEF, which
       # naturally reads as "not in group c" for our exclusion purpose.
       in_c = full_c.eq(c)
       exclude = in_c.not
       exclude = exclude | codes_bad if codes_bad
-      h_local[exclude] = UNDEF
+      h_local = h.mask_where(exclude)
       slice = h_local.__send__(op, axis: axis)   # band shape, mask carries n<contract
       slot_idx[0] = c
       out[*slot_idx] = slice
@@ -472,16 +523,21 @@ class CACategoricalIterator < CASegmentIterator
   # taken by index; otherwise its cells are kept by masking the rest of a copy.
   # A read-only Face's answers (a const string's records index a pool of
   # their own) cannot be put together, so they are collected as the surface
-  # values they are, as the flat form does.
+  # values they are, as the flat form does.  Over a 1-D value each group
+  # reduces to one cell, kept as a 1-element array so the answers stack.
   def axis_by_core (axis, op, *args)
     h    = @value
     axis = checked_axis(axis, op)
+    flat = (h.ndim == 1)
     groups  = (0...[@k, 1].max).map { |c| group_cells(h, axis, c, @k.zero?) }
-    answers = groups.map { |g| g.__send__(op, *args, axis: axis) }
+    answers = groups.map do |g|
+      flat ? g.__send__(op, *args, axis: axis, keep_axis: true)
+           : g.__send__(op, *args, axis: axis)
+    end
     if answers.first.face? && answers.first.read_only?
       answers = answers.map { |a| CArray.object(*a.shape) { a.to_a } }
     end
-    out = CArray.stack(answers, axis: 0).copy
+    out = flat ? CArray.concatenate(answers) : CArray.stack(answers, axis: 0).copy
     @k.zero? ? out[0...0, *([nil] * (out.ndim - 1))].copy : out
   end
 
@@ -493,7 +549,9 @@ class CACategoricalIterator < CASegmentIterator
 
   def group_cells (h, axis, c, none)
     codes = @cat.codes
-    if codes.shape == [h.shape[axis]]
+    # 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__
       sel = none ? CArray.boolean(codes.elements) { false } : codes.eq(c)
       sel = sel.strip_mask(false) if sel.has_mask?
       idx = [nil] * h.ndim
@@ -503,9 +561,8 @@ class CACategoricalIterator < CASegmentIterator
       full_c  = resolve_axis_codes(codes, h.shape, axis)
       exclude = none ? CArray.boolean(*h.shape) { true } : full_c.eq(c).not
       exclude = exclude | full_c.is_masked if full_c.has_mask?
-      local = h.copy
-      local[exclude] = UNDEF
-      local
+      # a copy with the rest masked, which a read-only Face also gives
+      h.mask_where(exclude)
     end
   end
   private :axis_by_core, :axis_moments_by_core, :group_cells
@@ -524,13 +581,43 @@ class CACategoricalIterator < CASegmentIterator
     if kernel_scans?(op, answer)
       bundle = @k > 0 ? [@cat.codes, @k, [axis]]
                       : [CArray.int64(h.shape[axis]).fill(-1), 1, [axis]]
-      return h.__axis_group_scan__([axis], [bundle], op)
+      return h.__scan_by_axis_groups__([axis], [bundle], op)
     end
     each_group_along(axis, ->(shape) { blank_like(answer, shape) }) do |g|
       g.public_send(op, axis: axis)
     end
   end
 
+  # #lag along an axis (case A): each group's positions along the axis, every
+  # other axis kept, lagged along it, so a lag never reaches another group.
+  def axis_lag (n, axis)
+    axis = checked_axis(axis, :lag)
+    classified_along!(:lag, axis)
+    each_group_along(axis, ->(shape) { blank_like(@value, shape) }) do |g|
+      g.lag(n, axis: axis)
+    end
+  end
+
+  # #strip_mask(method:) along an axis (case A): each group's positions along
+  # the axis filled along it, fiber by fiber.
+  def axis_hold (method, axis)
+    axis = checked_axis(axis, :strip_mask)
+    classified_along!(:strip_mask, axis)
+    each_group_along(axis, ->(shape) { blank_like(@value, shape) }) do |g|
+      g.strip_mask(method: method, axis: axis)
+    end
+  end
+
+  # #order along an axis (case A): each group's positions along the axis
+  # ranked along it, fiber by fiber.
+  def axis_order (axis, **kw)
+    axis = checked_axis(axis, :order)
+    classified_along!(:order, axis)
+    each_group_along(axis, ->(shape) { CArray.int64(*shape) }) do |g|
+      g.order(axis: axis, **kw)
+    end
+  end
+
   # #map along an axis (case A): the block receives each group's positions
   # along the axis, every other axis kept, and its answer goes back to them.
   def axis_map (axis, data_type, &block)
@@ -566,7 +653,7 @@ class CACategoricalIterator < CASegmentIterator
           "positions along axis #{axis} (shape [#{n}]); got shape " \
           "#{@cat.codes.shape.inspect}"
   end
-  private :axis_scan, :axis_map, :each_group_along, :classified_along!
+  private :axis_scan, :axis_lag, :axis_order, :axis_hold, :axis_map, :each_group_along, :classified_along!
 
   # Axis-aware wsum + wmean fused (single kernel call, both outputs).  Returns
   # [wsum_ca, wmean_ca].  Weights must match source shape exactly (explicit
@@ -582,6 +669,7 @@ class CACategoricalIterator < CASegmentIterator
             "must equal source.shape #{h.shape.inspect}. Wrap 1-D / band-shape " \
             "weights via `.broadcast_to(*source.shape)` before passing."
     end
+    return weighted_by_core(weights, axis) unless kernel_reads?(h.data_type)
     codes_h_shape = resolve_axis_codes(@cat.codes, h.shape, axis)
     weights_f64   = weights.data_type == CA_FLOAT64 ? weights : weights.float64
     band          = h.shape.dup; band.delete_at(axis)
@@ -592,10 +680,25 @@ class CACategoricalIterator < CASegmentIterator
     [ws_out, wm_out]
   end
 
+  # wsum and wmean of each group by the core: the group's cells of the value
+  # and of the weights, each other cell masked, reduced along the axis.
+  def weighted_by_core (weights, axis)
+    h = @value
+    %i[wsum wmean].map do |op|
+      answers = (0...[@k, 1].max).map do |c|
+        group_cells(h, axis, c, @k.zero?)
+          .public_send(op, group_cells(weights, axis, c, @k.zero?), axis: axis)
+      end
+      out = CArray.stack(answers, axis: 0).copy
+      @k.zero? ? out[0...0, *([nil] * (out.ndim - 1))].copy : out
+    end
+  end
+  private :weighted_by_core
+
   # Axis-aware prod: dedicated kernel (identity 1.0, separate from moments to
   # avoid conflating with sum's zero-identity memset).
   def axis_prod (axis)
-    return axis_by_core(axis, :prod) unless MONOID_TYPES.include?(@value.data_type)
+    return axis_by_core(axis, :prod) unless kernel_reads?(@value.data_type)
     h = @value
     axis = checked_axis(axis, :prod)
     codes_h_shape = resolve_axis_codes(@cat.codes, h.shape, axis)

data/lib/carray/complex.rb

@@ -1,7 +1,7 @@
 # Complex-component accessors (real / real= / imag / imag= / real? /
-# is_real).  Loaded eagerly BEFORE carray/lazy.rb, because lazy.rb does
-# `alias_method :__real_eager__, :real` (and the imag equivalent) at load
-# time -- these defs must exist by then.
+# is_real).  Loaded eagerly BEFORE carray/lazy.rb, because lazy.rb takes
+# `instance_method(:real)` (and the imag equivalent) at load time -- these
+# defs must exist by then.
 
 class CArray
 
@@ -40,9 +40,9 @@ class CArray
   # Architecturally:
   #   - lib/carray/lazy.rb's `real`/`imag` overrides dispatch to CAMonOp
   #     when self is a lazy view, and fall through to the defs here for eager
-  #     parents (via `alias_method :__real_eager__, :real` at load time).
+  #     parents (via `instance_method(:real)` taken at load time).
   #     This file MUST be required before carray/lazy.rb (see carray.rb), and
-  #     removing these defs would break that alias and the lazy.rb load.
+  #     removing these defs would break the lazy.rb load.
   #
   #   - ext/ca_obj_stride.c recognises `CAField .real/.imag over complex`
   #     as a first-class byte-mismatched reinterpret pattern.  Architectural

data/lib/carray/conditional.rb

@@ -28,13 +28,18 @@ class CArray
   #   The result's data type is the common type of the two branches; a
   #   branch given as `UNDEF` masks its cells and leaves the type to the
   #   other branch (`cond.then_else(a, UNDEF)` has `a`'s data type).
+  #   String branches make the result a {CAString}
+  #   (`cond.then_else("yes", "no")`, also with `UNDEF` for one of them).
+  #   A Symbol branch, or a String beside a value of another kind, makes
+  #   the result an object array.
   #   When `self` or a branch is a lazy view, the result is a lazy view
   #   (read-only) that joins the expression around it; `copy` makes an
   #   array of it.  An object result is always computed at once.
   #   @param x [CArray, Numeric, Object] true-branch value(s).
   #   @param y [CArray, Numeric, Object] false-branch value(s).
-  #   @return [CArray] new array with the same shape as `self`, or a
-  #     lazy view (CATriOp) when an operand is lazy.
+  #   @return [CArray] new array with the same shape as `self` (a
+  #     {CAString} for String branches), or a lazy view (CATriOp) when an
+  #     operand is lazy.
   #   @raise [ArgumentError] when `self` is not a boolean CArray, or when
   #     an array branch's shape does not pair with `self`'s as an
   #     operator's operands would (equal, or size-1 axes of the same ndim;
@@ -52,15 +57,10 @@ class CArray
     face = [x, y].find { |v| v.is_a?(CArray) && !v.scalar? && v.face? }
     if face
       refuse_branch_shape(x, y) if reshaped
+      refuse_branch_mix(x, y, face)
       return face_then_else(x, y, face)
     end
-    # Promote data_type from both branches via CArray.result_type, which
-    # lets a scalar branch take the type of an array branch as an operator
-    # does (cond.then_else(0, int32_array) is int32).  UNDEF is a missing
-    # value, not a value of some type: a branch that is UNDEF leaves the
-    # type to the other.
-    typed = [x, y].reject { |v| v.equal?(UNDEF) }
-    dt = typed.empty? ? CA_OBJECT : CArray.result_type(*typed)
+    dt = CArray.send(:selection_type, [x, y])
     return lazy_then_else(x, y, dt) if lazy_then_else?(x, y, dt)
     # A branch shaped unlike the condition goes through the lazy select,
     # which pairs the shapes by the operator rule (equal, or size-1 axes
@@ -84,7 +84,7 @@ class CArray
     if self.has_mask?
       result[self.is_masked] = UNDEF
     end
-    result
+    CArray.send(:selection_text?, [x, y]) ? CAString.wrap(result) : result
   end
 
   # A lazy receiver or branch makes the selection a lazy node (CATriOp
@@ -93,7 +93,7 @@ class CArray
   # a CScalar of it, UNDEF a masked one.
   private def lazy_then_else? (x, y, dt)
     return false if scalar? || dt == CA_OBJECT || dt == CA_FIXLEN
-    [self, x, y].any? { |v| v.is_a?(CArray) && v.__lazy_view__? }
+    [self, x, y].any? { |v| v.is_a?(CArray) && v.lazy_view? }
   end
 
   # The types the lazy select cannot carry keep the strict form: a full
@@ -104,6 +104,22 @@ class CArray
           "then_else: branch shape #{bad.shape.inspect} does not match the condition's #{shape.inspect}"
   end
 
+  # An array branch beside a Face branch must be a Face of the same kind
+  # (the same obj_type, so a CARecord subclass and a CARecord of one data
+  # class pair, as their store takes): the Face decides what a cell means,
+  # so a plain array would be read as its storage (an integer as a time's
+  # ticks) and the result would take the class of whichever branch came
+  # second.  A scalar branch is a value and goes through the Face's store.
+  private def refuse_branch_mix (x, y, face)
+    arrays = [x, y].select { |v| v.is_a?(CArray) && !v.scalar? }
+    return if arrays.all? { |v| v.face? && v.obj_type == face.obj_type }
+    hint = face.is_a?(CAString) ?
+      " (CArray.string(a) makes a CAString of an object array of Strings)" : ""
+    raise ArgumentError,
+          "then_else: cannot mix Face and non-Face arrays, or arrays of " \
+          "different Face classes; convert them first to one Face class or to no Face" + hint
+  end
+
   private def lazy_then_else (x, y, dt)
     branch = lambda do |v|
       next v if v.is_a?(CArray) && !v.scalar?
@@ -178,7 +194,9 @@ class CArray
   #   Scalar returns from a callable (e.g. `->(v) { 0 }`) broadcast
   #   to the subset shape. The result `data_type` is the promotion
   #   of the two subset results via `CArray.result_type`, or
-  #   `data_type` when given. Masked cells in `cond` propagate to
+  #   `data_type` when given. A String result is a value (not the name
+  #   of a data type); when both callables give Strings or {CAString}s
+  #   the result is a {CAString}. Masked cells in `cond` propagate to
   #   `UNDEF` in the result.
   #
   #   @param cond [CArray] boolean selector; same shape as `self`.
@@ -205,18 +223,19 @@ class CArray
     x_else = self[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])
 
     # A callable that returns a scalar (e.g. `->(v) { 0 }`) broadcasts
     # to the subset shape; wrap it here so the scatter step below sees a
     # same-length CArray.
     unless y_then.is_a?(CArray)
-      y_then = CArray.new(data_type || CArray.result_type(y_then), x_then.shape).fill(y_then)
+      y_then = CArray.new(data_type || CArray.send(:selection_type, [y_then]), x_then.shape).fill(y_then)
     end
     unless y_else.is_a?(CArray)
-      y_else = CArray.new(data_type || CArray.result_type(y_else), x_else.shape).fill(y_else)
+      y_else = CArray.new(data_type || CArray.send(:selection_type, [y_else]), x_else.shape).fill(y_else)
     end
 
-    dt  = data_type || CArray.result_type(y_then, y_else)
+    dt  = data_type || CArray.send(:selection_type, [y_then, y_else])
     out = CArray.new(dt, self.shape)
     out[cond]     = y_then
     out[cond.not] = y_else
@@ -225,7 +244,7 @@ class CArray
     # positions, so both scatters leave the cell untouched — an explicit
     # fix-up is required.
     out[cond.is_masked] = UNDEF if cond.has_mask?
-    out
+    text ? CAString.wrap(out) : out
   end
 
   # @overload select(condlist, choicelist, default: 0, data_type: nil)
@@ -238,7 +257,9 @@ class CArray
   #   Each `choicelist[k]` is either a same-shape CArray or a scalar
   #   broadcast to every cell. The result `data_type` is the promotion
   #   of every choice plus `default` via `CArray.result_type`, or
-  #   `data_type` when given.
+  #   `data_type` when given. A String choice is a value (not the name of
+  #   a data type); when every choice and `default` is a String or a
+  #   {CAString}, the result is a {CAString}.
   #
   #   @param condlist [Array<CArray>] boolean selectors.
   #   @param choicelist [Array<CArray, Numeric, Object>] values, one
@@ -274,7 +295,7 @@ class CArray
     end
     shape = first.shape
 
-    dt = data_type || CArray.result_type(*choicelist, default)
+    dt = data_type || selection_type(choicelist + [default])
     # `default` can be either a same-shape CArray (per-cell fallback) or a
     # scalar (broadcast to every cell).
     default_full = default.is_a?(CArray) && !default.scalar?
@@ -297,7 +318,35 @@ class CArray
       v = choicelist[k]
       out[c] = v.is_a?(CArray) ? v[c] : v
     end
+    if !data_type && selection_text?(choicelist + [default])
+      out = CAString.wrap(out)
+    end
     out
   end
 
+  # The data type a selection among `values` writes into: their common type,
+  # by the rule an operator promotes its operands by (a scalar takes the
+  # type of an array beside it).  UNDEF is a missing value, not a value of
+  # some type, so it leaves the type to the others.  A String or Symbol is a
+  # value, which CArray.result_type would read as the name of a data type
+  # ("int32"), so it makes the result object.
+  def self.selection_type (values)
+    typed = values.reject { |v| v.equal?(UNDEF) }
+    if typed.empty? || typed.any? { |v| v.is_a?(String) || v.is_a?(Symbol) }
+      CA_OBJECT
+    else
+      CArray.result_type(*typed)
+    end
+  end
+  private_class_method :selection_type
+
+  # Whether a selection among `values` gives text: every value that is not
+  # UNDEF is a String or a CAString, and there is at least one.  The result
+  # is then a CAString rather than an object array of Strings.
+  def self.selection_text? (values)
+    present = values.reject { |v| v.equal?(UNDEF) }
+    !present.empty? && present.all? { |v| v.is_a?(String) || v.is_a?(CAString) }
+  end
+  private_class_method :selection_text?
+
 end

data/lib/carray/const_string.rb

@@ -55,7 +55,7 @@ class CArray
   #   @return [CAConstString]
   def self.const_string (arg, encoding: Encoding::UTF_8, &block)
     if arg.is_a?(CArray)
-      return string_face_of(arg).to_const_string(encoding: encoding)
+      return string_face_of(arg, "CArray.const_string").to_const_string(encoding: encoding)
     end
     if block
       n = Integer(arg)
@@ -135,7 +135,7 @@ class CAConstString
   def sort_addr (*args, **kw)
     # The native scan has no notion of an incomparable sentinel, so a masked
     # column goes the same way a per-axis one does.
-    return __sort_addr_bytes__ if args.empty? && kw.empty? && ! has_mask?
+    return sort_addr_by_bytes if args.empty? && kw.empty? && ! has_mask?
     to_string.sort_addr(*args, **kw)
   end
 
@@ -143,6 +143,12 @@ class CAConstString
   #   Returns the per-fiber indices that index a sort by string order.
   #   @return [CArray] `:int64` indices.
   def sort_index (*args, **kw)
+    if args.empty? && kw.empty? && ! has_mask?
+      # With no axis the indices are those of the flattened array, which are
+      # its addresses.
+      addr = sort_addr_by_bytes
+      return ndim == 1 ? addr : addr.flatten.copy
+    end
     to_string.sort_index(*args, **kw)
   end
 
@@ -163,7 +169,7 @@ class CAConstString
   #   every cell is masked or the array is empty.
   #   @return [String, CAConstString]
   def min (*args, **kw)
-    return __min_bytes__ || UNDEF if args.empty? && kw.empty?
+    return min_string_by_bytes || UNDEF if args.empty? && kw.empty?
     const_string_lift(to_string.min(*args, **kw))
   end
 
@@ -171,7 +177,7 @@ class CAConstString
   #   Byte-largest counterpart of {#min}.
   #   @return [String, CAConstString]
   def max (*args, **kw)
-    return __max_bytes__ || UNDEF if args.empty? && kw.empty?
+    return max_string_by_bytes || UNDEF if args.empty? && kw.empty?
     const_string_lift(to_string.max(*args, **kw))
   end
 
@@ -319,6 +325,9 @@ class CAConstString
   # @overload categorize(labels: nil, sort_labels: false)
   #   @return [CACategorical] categories keyed on the strings.
   def categorize (labels: nil, sort_labels: false)
+    # Discovery reads the bytes (a String per distinct value only); a given
+    # vocabulary is matched through the strings.
+    return super if labels.nil?
     to_string.categorize(labels: labels, sort_labels: sort_labels)
   end
 
@@ -340,7 +349,7 @@ class CAConstString
   # @!method ge(other)
   #   @return [CArray] boolean, true where self sorts after or equals `other`.
   [:ne, :lt, :le, :gt, :ge].each do |op|
-    define_method(op) { |other| to_string.public_send(op, string_operand(other)) }
+    define_method(op, &Ractor.make_shareable(proc { |other| to_string.public_send(op, string_operand(other)) }))
   end
 
   alias <  lt

data/lib/carray/construct.rb

@@ -287,7 +287,7 @@ class CArray
             "(its contents are left undefined); use CArray.new to fill."
     end
     if args.size == 2 and args[1].is_a?(Array)
-      return __empty__(*args, **options)
+      return empty_of_data_type(*args, **options)
     end
     unless options.empty?
       raise ArgumentError,
@@ -314,32 +314,36 @@ class CArray
       CArray.new(self::DataType, shape)
     end
 
-    # @overload from_memory_view(obj)
+    # @overload from_memory_view(obj, mask: nil)
     #   Returns a fresh CArray interpreted as this typed subclass's
     #   `data_type`, imported by copy from a MemoryView producer.
     #   Forwards to
-    #   `CArray.from_memory_view(obj, data_type: self::DataType)`; the
-    #   result is always 1-D (chain `.reshape` for higher rank).
+    #   `CArray.from_memory_view(obj, data_type: self::DataType)`.  A
+    #   typed producer keeps its shape and must agree with the type; a
+    #   typeless one is read as 1-D (chain `.reshape` for higher rank).
     #   @param obj [Object] MemoryView producer.
+    #   @param mask [Object, nil] MemoryView producer of the mask.
     #   @return [CArray]
-    def from_memory_view (obj)
-      CArray.from_memory_view(obj, data_type: self::DataType)
+    def from_memory_view (obj, mask: nil)
+      CArray.from_memory_view(obj, data_type: self::DataType, mask: mask)
     end
 
-    # @overload wrap_memory_view(obj)
+    # @overload wrap_memory_view(obj, mask: nil)
     #   Returns a zero-copy CAWrap over `obj`'s MemoryView interpreted
     #   as this typed subclass's `data_type`. Forwards to
-    #   `CArray.wrap_memory_view(obj, data_type: self::DataType)`; the
-    #   result is always 1-D (chain `.reshape` for higher rank).
+    #   `CArray.wrap_memory_view(obj, data_type: self::DataType)`.  A
+    #   typed producer keeps its shape and must agree with the type; a
+    #   typeless one is read as 1-D (chain `.reshape` for higher rank).
     #
     #   Here the receiver names the element type, not the class of the
     #   result: the call forwards with `CArray` as the receiver, so a
     #   `CAWrap` comes back. Choosing the class is the other reading of
     #   the receiver, and it lives on `CArray.wrap_memory_view` itself.
     #   @param obj [Object] MemoryView producer.
+    #   @param mask [Object, nil] MemoryView producer of the mask.
     #   @return [CAWrap]
-    def wrap_memory_view (obj)
-      CArray.wrap_memory_view(obj, data_type: self::DataType)
+    def wrap_memory_view (obj, mask: nil)
+      CArray.wrap_memory_view(obj, data_type: self::DataType, mask: mask)
     end
 
   end

data/lib/carray/data_type_extension.rb

@@ -164,6 +164,7 @@ class CArray
       #  midpoints go the same way as numpy's integer linspace).
       float_out = CArray.new(CA_FLOAT64, [n]).span(x1.to_f..x2.to_f)
       return float_out if data_type == CA_FLOAT64
+      # coerce: the type the caller asked for
       float_out.floor.to_type(data_type)
     end