carray 3.0.2 → 3.0.4

data/lib/carray/methods/nunique.rb

@@ -12,7 +12,9 @@ class CArray
   #   whole array and returns an Integer. With `axis: k` it counts per
   #   fiber along axis `k`, returning a reduced `CA_INT64` CArray
   #   (shape = self.shape with axis `k` removed; `keep_axis: true` keeps
-  #   it as a length-1 axis). The shape rule matches other per-axis
+  #   it as a length-1 axis). An Array of axes counts over all of them
+  #   together, one count per remaining position; naming every axis
+  #   returns an Integer. The shape rule matches other per-axis
   #   reductions such as `sum(axis:)`.
   #
   #   The distinct count has identity 0: an empty array, an all-masked
@@ -25,12 +27,12 @@ class CArray
   #   distinctness follows Ruby `eql?` / `hash` (which, unlike numeric,
   #   does not collapse distinct NaN objects).
   #
-  #   @param axis [Integer, nil] axis to count along; `nil` counts over
-  #     the whole array.
+  #   @param axis [Integer, Array<Integer>, nil] axis or axes to count
+  #     over; `nil` counts over the whole array.
   #   @param keep_axis [Boolean] when `axis` is given, keep the reduced
   #     axis as a length-1 axis instead of dropping it.
-  #   @return [Integer, CArray] Integer for `axis: nil`, otherwise a
-  #     reduced `CA_INT64` CArray.
+  #   @return [Integer, CArray] Integer for `axis: nil` or every axis,
+  #     otherwise a reduced `CA_INT64` CArray.
   # @overload nunique(along: k)
   #   Returns how many distinct **sub-arrays** `self` holds, comparing
   #   whole sub-arrays rather than cells: `along: k` names the axis
@@ -60,7 +62,10 @@ class CArray
       # then read the single reduced cell as an Integer.
       flatten.send(:__nunique__, 0, false)[0]
     else
-      __nunique__(normalize_axis(axis, "nunique"), keep_axis)
+      axes = Array(axis).map { |a| normalize_axis(a, "nunique") }
+      counts = __nunique__(axes, keep_axis)
+      # naming every axis reduces to one count, an Integer as sum(axis:) gives
+      (axes.size == ndim && ! keep_axis) ? counts[0] : counts
     end
   end
 

data/lib/carray/methods/repeat.rb

@@ -76,26 +76,7 @@ class CArray
       end
 
     source = along ? self : (ndim > 1 ? flatten : self)
-    source[*gather_args(repeat_index(counts), along)]
-  end
-
-  #  The source index of every position in the result: element i appears
-  #  at the `counts[i]` positions starting at the exclusive prefix sum.
-  #
-  #  Marking those starts with +1 and running a cumulative sum turns the
-  #  marks back into indices, and does the right thing with a zero
-  #  count for free -- two elements then share a start, that position
-  #  carries 2, and the sum steps over the one that was asked for zero
-  #  times.
-  private def repeat_index (counts)
-    total = counts.sum.to_i
-    return CArray.int64(0) if total.zero?
-    starts = counts.cumsum.int64 - counts
-    marks  = CArray.int64(total)
-    #  A trailing zero count starts one past the end; it marks nothing,
-    #  which is what a zero count means.
-    marks.scatter_add!(starts[starts.lt(total)], 1)
-    marks.cumsum.int64 - 1
+    source[*gather_args(CArray.segment_index(lengths: counts), along)]
   end
 
   #  One index argument per axis: the gathered index on the axis being

data/lib/carray/methods/resize.rb

@@ -4,8 +4,8 @@ class CArray
   #   Returns `self` resized to `newdim`. The original data is
   #   placed at offset 0 (positive size) or right-aligned (negative
   #   size); the new area outside the original region is filled
-  #   with `fill_value`, or -- for fixlen storage -- left as zero
-  #   bytes. Pass `UNDEF` to mask the new area.
+  #   with `fill_value`, or left as zero storage when it is not given
+  #   (0 for a numeric array). Pass `UNDEF` to mask the new area.
   #
   #   Each entry of `newdim` is: `nil` to keep the current
   #   `shape[i]`, a positive Integer for a new size with the
@@ -13,15 +13,19 @@ class CArray
   #   `d` for a new size `|d|` with the original right-aligned.
   #
   #   Works on Face arrays (CARecord / CATime / ...) and
-  #   plain fixlen: the resize is done on the storage layout
-  #   (preserving bytes) and re-wrapped as the same Face.
+  #   plain fixlen: the result is the same Face, and `fill_value` is a
+  #   value of it (a Time for a time array).
   #
   #   @param newdim [Array<Integer, nil>] new shape spec, one entry
   #     per axis.
-  #   @param fill_value [Object] value for the extended area.
+  #   @param fill_value [Object] value for the extended area (zero
+  #     storage when not given).
   #   @return [CArray] resized copy.
-  def resize (*newdim, fill_value: 0)
-    raise "ndim mismatch" if newdim.size != ndim
+  NO_FILL_VALUE = ::Object.new.freeze
+  private_constant :NO_FILL_VALUE
+
+  def resize (*newdim, fill_value: NO_FILL_VALUE)
+    raise ArgumentError, "ndim mismatch" if newdim.size != ndim
     offset = Array.new(ndim, 0)
     newdim = newdim.each_with_index.map do |d, i|
       case d
@@ -32,24 +36,18 @@ class CArray
         offset[i] = size - shape[i] if d < 0
         size
       else
-        raise "invalid dimension size"
+        raise ArgumentError, "invalid dimension size"
       end
     end
-    face_parent = self.face? ? self : nil
-    src = self
-    src = src.parent while src.face?
-    dt    = src.data_type
-    bytes = (dt == :fixlen) ? src.bytes : nil
-    out = CArray.new(dt, newdim, bytes: bytes)
-    # Fill the new area: numeric storage takes fill_value as-is; fixlen
-    # storage cannot hold a numeric 0, so leave zero bytes and honor only
-    # UNDEF (mask) or an explicit String fill.
-    if dt != :fixlen || fill_value.equal?(UNDEF) || fill_value.is_a?(String)
-      out[] = fill_value
-    end
-    out.mask.paste(offset, src.false) if out.has_mask?
-    out.paste(offset, src)
-    out = out.face_lift(face_parent) if face_parent
+    # The original cells are copied as storage, so a read-only Face (a
+    # const string, a categorical) resizes too.  The new area starts as zero
+    # storage; a given fill_value is written as a value of the array, which a
+    # read-only Face refuses.
+    out = blank_like(newdim)
+    out_storage = out.__send__(:face_storage)
+    out[] = fill_value unless fill_value.equal?(NO_FILL_VALUE)
+    out_storage.mask.paste(offset, self.false) if out_storage.has_mask?
+    out_storage.paste(offset, face_storage)
     out
   end
 

data/lib/carray/methods/snap.rb

@@ -66,8 +66,11 @@ class CArray
   #   the sample, `:ceil` at or above), and delegates to
   #   `locate_nearest_addr(direction:)`.
   #
-  #   `list` must be a 1-D ascending numeric CArray (or convertible via
-  #   `CArray.wrap_readonly`). Out-of-range and NaN handling follows the
+  #   `list` must be a 1-D ascending numeric CArray, or a Ruby Array /
+  #   Range.  An Array grid takes `self`'s data_type, except that a Float
+  #   in it makes an integer array's grid float64 (so `0.5` is not
+  #   truncated); an Integer that does not fit `self`'s type raises
+  #   `RangeError`.  Out-of-range and NaN handling follows the
   #   same pattern as `bin_to`, but with an additional `:clamp`
   #   sentinel that snaps out-of-range cells to the nearest list end.
   #
@@ -95,19 +98,21 @@ class CArray
   #     shape as `self`.
   #   @raise [ArgumentError] when `list` is not 1-D or is empty, or
   #     `direction` is not one of the accepted symbols.
+  #   @raise [RangeError] when an Integer in an Array `list` does not
+  #     fit `self`'s data_type.
   #   @example
   #     temp.snap_to([270.0, 280.0, 290.0, 300.0])                   # clamp OOB
   #     temp.snap_to(grid, lfill: nil, ufill: nil)                   # mask OOB
   #     rain.snap_to([0.0, 1.0, 5.0, 20.0], direction: :floor)       # list value at or below
   def snap_to(list, lfill: :clamp, ufill: :clamp, direction: :round)
-    ref = list.is_a?(CArray) ? list : CArray.wrap_readonly(list, self.data_type)
+    ref = list.is_a?(CArray) ? list : snap_list(list)
     raise ArgumentError, "snap_to: list must be 1-D" unless ref.ndim == 1
     n = ref.elements
     raise ArgumentError, "snap_to: list must have at least one value" if n < 1
 
     if n == 1
       # Degenerate: every finite cell snaps to the only value.
-      out = CArray.new(ref.data_type, shape).fill(ref[0])
+      out = CArray.new(ref.data_type, shape, bytes: ref.bytes).fill(ref[0])
       out.mask = self.mask.to_ca if self.has_mask?
       if self.float?
         inv = self.is_invalid
@@ -118,17 +123,16 @@ class CArray
       return out
     end
 
-    # `locate_nearest_addr` (via `linear_section`) accepts a 1-D `val` only;
-    # flatten multi-D input and reshape the result back to preserve the
-    # element-wise semantic on any shape.
+    # Multi-D input is snapped as its flattened cells and given its shape
+    # back.
     if ndim > 1
       return reshape(-1).snap_to(ref, lfill: lfill, ufill: ufill,
                                  direction: direction).reshape(*shape)
     end
 
-    # locate_nearest_addr returns int64 indices; OOB (below / above / NaN)
-    # cells come back masked. We split OOB into below / above with
-    # explicit comparisons so the two sides can be filled independently.
+    # locate_nearest_addr returns int64 indices; whether a cell outside the
+    # list gets one depends on the direction, so the two sides are split with
+    # explicit comparisons and filled here independently of it.
     idx = self.locate_nearest_addr(ref, direction: direction)
     out = ref.project(idx)
 
@@ -137,13 +141,13 @@ class CArray
 
     case lfill
     when :clamp then out[below] = ref[0]
-    when nil    then # leave masked (locate_nearest_addr already masked OOB)
+    when nil    then out[below] = UNDEF
     else             out[below] = lfill
     end
 
     case ufill
     when :clamp then out[above] = ref[-1]
-    when nil    then # leave masked
+    when nil    then out[above] = UNDEF
     else             out[above] = ufill
     end
 
@@ -158,4 +162,22 @@ class CArray
     out
   end
 
+  private
+
+  # A Ruby Array grid in the type a search query would get: a Float in it
+  # makes an integer array's grid float64 (so 0.5 is not truncated to 0),
+  # otherwise the grid takes self's type, and an Integer that does not fit
+  # it is refused rather than wrapped.
+  def snap_list(list)
+    vals = list.to_a
+    type = data_type
+    type = CA_FLOAT64 if (integer? || data_type == CA_BOOLEAN) && vals.any? { |v| v.is_a?(Float) }
+    ref = CArray.wrap_readonly(vals, type)
+    if ref.integer?
+      bad = vals.zip(ref.to_a).find { |v, w| v != w }
+      raise RangeError, "snap_to: #{bad[0].inspect} is out of range for #{ref.data_type_name}" if bad
+    end
+    ref
+  end
+
 end

data/lib/carray/methods/unique.rb

@@ -26,10 +26,13 @@ class CArray
   #   For `CA_OBJECT` / `CA_FIXLEN` distinctness follows Ruby
   #   `eql?` / `hash`; note that Ruby does not collapse distinct NaN
   #   objects, so a `CA_OBJECT` array of Float NaN is not collapsed
-  #   (unlike the numeric path).
+  #   (unlike the numeric path). Complex values follow the float rules
+  #   in each component; the values come back with -0.0 written as 0.0
+  #   and every NaN as one NaN.
   #
   #   @param sort [Boolean] when true, return the distinct values
-  #     sorted ascending instead of in first-appearance order.
+  #     sorted ascending instead of in first-appearance order. A complex
+  #     array has no order and raises {CArray::DataTypeError}.
   #   A time array (`CATime` / `CATimedelta`) answers with its own type on
   #   its own unit: the distinct values are values, so the array comes back
   #   as itself rather than as raw storage ticks.
@@ -80,6 +83,12 @@ class CArray
     # collapsed and -0.0 / +0.0 normalized; object keys on rb_hash + rb_eql and
     # fixlen on a byte-hash + memcmp, both reproducing Ruby Hash distinctness.
     # Masked cells are skipped in the kernel.
+    if sort && complex?
+      raise CArray::DataTypeError,
+            "unique(sort: true): a #{data_type_name} value has no order " \
+            "(complex numbers are not ordered); unique without sort: gives " \
+            "the values in first-appearance order"
+    end
     levels = __unique_flat__
     sort ? levels.sort : levels
   end

data/lib/carray/methods/value_counts.rb

@@ -52,17 +52,10 @@ class CArray
       [ values[CArray.int64(order.size) { |i| order[i] }],
         counts[CArray.int64(order.size) { |i| order[i] }] ]
     when :value
-      # Ascending value; NaN (numeric) or non-comparable last. Build the
-      # permutation with an explicit NaN-last key so float NaN doesn't blow up
-      # the Ruby sort, then gather both arrays through it.
-      v = values.to_a
-      order = (0...v.size).sort_by do |i|
-        x = v[i]
-        nan = x.is_a?(Float) && x.nan?
-        [nan ? 1 : 0, nan ? 0 : x, i]
-      end
-      [ values[CArray.int64(order.size) { |i| order[i] }],
-        counts[CArray.int64(order.size) { |i| order[i] }] ]
+      # Ascending value in the order sort uses (NaN after every number),
+      # then gather both arrays through it.
+      order = values.sort_index
+      [values[order], counts[order]]
     else
       [values, counts]
     end

data/lib/carray/record_order.rb

@@ -0,0 +1,208 @@
+# ----------------------------------------------------------------------------
+#
+#  carray/record_order.rb
+#
+#  The order of a CARecord: the members its struct names in `order_by:`,
+#  compared in that order.
+#
+#  A record's storage is its bytes, and comparing bytes is no order of the
+#  values in them (a little-endian float, a signed integer).  So the
+#  ordering members do not run on the storage: they run on one int64 array,
+#  each record's rank among the others by the declared members, and the
+#  values they return are gathered from the record array by the positions
+#  that array gives.  A struct that declares no order has none, and these
+#  raise.
+#
+# ----------------------------------------------------------------------------
+
+class CARecord
+
+  # @overload sort(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns a sorted {CARecord} view, ordered by the struct's
+  #   `order_by:` members.  With no `axis:` the array is flattened first.
+  #   @return [CARecord]
+  #   @raise [ArgumentError] when the struct declares no `order_by:`.
+  def sort (*args, **kw)
+    addr = record_rank.sort_addr(*args, **kw)
+    kw[:axis].nil? ? self[addr.flatten] : self[addr]
+  end
+
+  # @overload sort_copy(axis: nil, kind: :quick, masked_position: :last)
+  #   @return [CARecord] an owned sorted copy.
+  def sort_copy (*args, **kw)
+    sort(*args, **kw).copy
+  end
+
+  # @!method sort_addr(axis: nil, kind: :quick, masked_position: :last)
+  #   @return [CArray] the view-flat addresses of a sort by the declared order.
+  # @!method sort_index(axis: nil, kind: :quick, masked_position: :last)
+  #   @return [CArray] the per-fiber indices of a sort by the declared order.
+  # @!method rank_index(axis: nil)
+  #   @return [CArray] each record's rank by the declared order.
+  # @!method order(axis: nil, descending: false, method: :ordinal, kind: :quick)
+  #   @return [CArray] each record's rank by the declared order.
+  # @!method min_index(axis: nil)
+  #   @return [Integer, CArray] where the smallest record sits.
+  # @!method max_index(axis: nil)
+  #   @return [Integer, CArray] where the largest record sits.
+  # @!method partition_index(kth, axis: nil)
+  #   @return [CArray] the indices that partition about the `kth` record.
+  [:sort_addr, :sort_index, :rank_index, :order,
+   :min_index, :max_index, :partition_index].each do |op|
+    define_method(op, &Ractor.make_shareable(proc { |*args, **kw| record_rank.public_send(op, *args, **kw) }))
+  end
+
+  # @overload min(axis: nil, keep_axis: false)
+  #   Returns the smallest record by the declared order, skipping masked
+  #   records; UNDEF when every record is masked.  With `axis:` a
+  #   {CARecord} of the smallest along that axis.
+  #   @return [CAStruct, CARecord]
+  def min (axis: nil, keep_axis: false)
+    record_extreme(:min_index, axis, keep_axis)
+  end
+
+  # @overload max(axis: nil, keep_axis: false)
+  #   The largest record; see {#min}.
+  #   @return [CAStruct, CARecord]
+  def max (axis: nil, keep_axis: false)
+    record_extreme(:max_index, axis, keep_axis)
+  end
+
+  # @overload minmax(axis: nil, keep_axis: false)
+  #   @return [Array] `[min, max]`.
+  def minmax (axis: nil, keep_axis: false)
+    [min(axis: axis, keep_axis: keep_axis), max(axis: axis, keep_axis: keep_axis)]
+  end
+
+  # @overload partition_copy(kth, axis: nil)
+  #   @return [CARecord] partitioned about the `kth` record in the declared
+  #     order.  With no `axis:` the array is flattened first.
+  def partition_copy (kth, axis: nil)
+    if axis.nil?
+      flat = flatten
+      return flat[flat.send(:record_rank).partition_index(kth)].copy
+    end
+    take_along_axis(record_rank.partition_index(kth, axis: axis), axis: axis).copy
+  end
+
+  # @!method lt(other)
+  #   Compares by the declared order.  `other` is a record of the same
+  #   struct, or a {CARecord} of them.
+  #   @return [CArray] boolean.
+  # @!method le(other)
+  # @!method gt(other)
+  # @!method ge(other)
+  [:lt, :le, :gt, :ge].each do |op|
+    define_method(op, &Ractor.make_shareable(proc do |other|
+      mine, theirs = record_rank_with(other)
+      mine.public_send(op, theirs)
+    end))
+  end
+
+  alias <  lt
+  alias <= le
+  alias >  gt
+  alias >= ge
+
+  private
+
+  # The struct's order_by: members, or a refusal naming where to declare it.
+  def record_order_by
+    data_class.order_by or
+      raise ArgumentError,
+            "#{data_class.inspect} declares no order; pass order_by: to " \
+            "CArray.struct to name the members records are ordered by"
+  end
+
+  # Each record's dense rank by the declared members, shaped like self.
+  # Each member is ranked on its own (a numeric member by value, NaN last;
+  # a fixlen member by its bytes), and the ranks are folded in member order.
+  # Ranking again after each fold keeps every value below the record count.
+  def record_rank
+    record_rank_of(self).reshape(*shape)
+  end
+
+  def record_rank_of (records)
+    rank = nil
+    record_order_by.each do |key|
+      r = records[key].flatten.order(method: :dense)
+      if rank.nil?
+        rank = r
+      else
+        top  = r.max
+        span = top.equal?(UNDEF) ? 1 : top + 1
+        rank = (rank * span + r).order(method: :dense)
+      end
+    end
+    rank
+  end
+
+  # Ranks of self and `other` in one ordering, so they can be compared.
+  def record_rank_with (other)
+    case other
+    when CARecord
+      unless other.data_class.equal?(data_class)
+        raise ArgumentError,
+              "can not compare a record of #{data_class.inspect} " \
+              "with one of #{other.data_class.inspect}"
+      end
+      theirs = other.flatten
+    when data_class
+      theirs = CARecord.new(data_class, 1)
+      theirs[0] = other
+    else
+      raise ArgumentError,
+            "can not compare a record of #{data_class.inspect} with #{other.class}"
+    end
+    n    = elements
+    both = record_rank_of(CArray.concatenate([flatten, theirs]))
+    mine = both[0...n].reshape(*shape)
+    rest = both[n..-1]
+    [mine, other.is_a?(CARecord) ? rest.reshape(*other.shape) : rest[0]]
+  end
+
+  # The record at each min_index / max_index, gathered from self.
+  def record_extreme (index_op, axis, keep_axis)
+    rank = record_rank
+    if axis.nil?
+      i = rank.flatten.public_send(index_op)
+      return i.equal?(UNDEF) ? UNDEF : flatten[i]
+    end
+    name = index_op.to_s.sub("_index", "")
+    if axis.is_a?(Array)
+      axes = axis.map { |k| normalize_axis(k, name) }.uniq
+      return record_extreme(index_op, axes[0], keep_axis) if axes.size == 1
+      return record_extreme_over(index_op, axes, keep_axis)
+    end
+    axis = normalize_axis(axis, name)
+    idx   = rank.public_send(index_op, axis: axis)
+    empty = idx.is_masked
+    picked_shape = shape.dup
+    picked_shape[axis] = 1
+    out = take_along_axis(idx.strip_mask(0).reshape(*picked_shape), axis: axis).copy
+    if empty.any
+      out[empty.reshape(*picked_shape)] = UNDEF
+    end
+    return out if keep_axis
+    out.reshape(*(shape[0...axis] + shape[axis + 1..-1]))
+  end
+
+  # Over several axes: the reduced axes are moved last and merged into one.
+  def record_extreme_over (index_op, axes, keep_axis)
+    keep = (0...ndim).to_a - axes
+    kept_shape = shape.values_at(*keep)
+    if keep.empty?
+      r = record_extreme(index_op, nil, false)
+      return r unless keep_axis
+      out = flatten[0..0].copy
+      out[0] = r
+      return out.reshape(*([1] * ndim))
+    end
+    merged = transpose(*(keep + axes))
+               .reshape(*kept_shape, shape.values_at(*axes).inject(:*))
+    out = merged.send(:record_extreme, index_op, keep.size, false)
+    return out unless keep_axis
+    out.reshape(*shape.each_with_index.map { |n, k| axes.include?(k) ? 1 : n })
+  end
+
+end

data/lib/carray/rng.rb

@@ -29,6 +29,7 @@ class CArray
       :xoshiro256pp => File.expand_path("../../ext/ca_rng_xoshiro256pp.h",
                                         __dir__),
     }.freeze
+    Ractor.make_shareable(SOURCE_FILES)
 
     # The C each generator is, as text.
     #
@@ -50,6 +51,7 @@ class CArray
     SOURCE = SOURCE_FILES.transform_values { |path|
       File.read(path, :encoding => "UTF-8")
     }.freeze
+    Ractor.make_shareable(SOURCE)
 
     # What every generator's text needs beside it, and what none of them
     # owns: turning uniforms into a normal is the same arithmetic whichever
@@ -80,6 +82,7 @@ class CArray
         :bits    => "ca_xoshiro256pp_next",
       }.freeze,
     }.freeze
+    Ractor.make_shareable(DRAW_FUNCTIONS)
 
   end
 

data/lib/carray/runtime.rb

@@ -5,13 +5,32 @@
 
 class CArray
 
+  # A fast path answers by a different algorithm what a general path also
+  # answers.  A development build defines this in C, false when run with
+  # CARRAY_GENERAL_PATH=1 so the test suite takes the general paths (see
+  # ext/carray_internal.h); a release build has no switch.
+  unless respond_to?(:__fast_paths_enabled__)
+    def self.__fast_paths_enabled__ # :nodoc:
+      true
+    end
+  end
+
+  # True when a development build runs with CARRAY_GENERAL_PATH=2: the
+  # kernel iterator then delivers every source through the view's own
+  # transfer.  A release build has no switch.
+  unless respond_to?(:__iter_by_transfer_only__)
+    def self.__iter_by_transfer_only__ # :nodoc:
+      false
+    end
+  end
+
   # String fallback for the global cast functions CA_INT32(data) etc.  The C
   # dispatcher (ext/carray_cast.c) handles every other input class in C and
   # delegates only String here, because the whitespace / `,` / `;` /
   # `_`->UNDEF parser is far more natural (and maintainable) in Ruby.
   # +type+ arrives as the data_type Symbol.  Required: without it
   # +CA_INT32("1 2 3")+ and friends raise.
-  def self.__cast_string__ (type, v) # :nodoc:
+  def self.cast_string (type, v)
     if type == CA_OBJECT
       return CScalar.new(CA_OBJECT) { v }
     elsif type == CA_BOOLEAN
@@ -30,7 +49,7 @@ class CArray
       return CArray.new(type, CArray.guess_array_shape(v)).tap { |a| a[] = v }
     end
   end
-  private_class_method :__cast_string__
+  private_class_method :cast_string
 
   # CA_OBJECT escape for the weighted-sum kernel (mkkernel object_escape:).
   # The C dispatcher (carray_kernels.c rb_ca_wsum_ki) intercepts CA_OBJECT
@@ -43,18 +62,18 @@ class CArray
   # scalar or a full-shape weight), matching CArray's explicit-broadcast rule.
   # +opts+ is the trailing options Hash (axis:/keep_axis:/min_count:/
   # fill_value:) forwarded verbatim by the C escape; it goes straight to +sum+.
-  def __wsum_object__ (weights, opts = {}) # :nodoc:
+  def wsum_object (weights, opts = {}) # :nodoc:
     (self * weights).sum(**opts)
   end
-  private :__wsum_object__
+  private :wsum_object
 
   # CA_OBJECT escape for the weighted-mean kernel.  Weighted mean is
   # +Σ(w*v) / Σw+ over the cells valid after mask overlay (a masked value OR a
   # masked weight drops the cell from BOTH sums).  The denominator is guarded:
   # an empty / all-masked slab or weights summing to zero yields UNDEF (the
   # object analogue of the numeric kernel's 0/0 -> NaN, since objects have no
-  # NaN).  Weight forms and +opts+ as in {#__wsum_object__}.
-  def __wmean_object__ (weights, opts = {}) # :nodoc:
+  # NaN).  Weight forms and +opts+ as in {#wsum_object}.
+  def wmean_object (weights, opts = {}) # :nodoc:
     axis      = opts[:axis]
     keep_axis = opts[:keep_axis]
     prod = self * weights
@@ -65,25 +84,54 @@ class CArray
     num = prod.sum(**nopt)
     den = wv.sum(axis: axis, keep_axis: keep_axis)
     result =
-      if axis
+      if den.is_a?(CArray)               # axis given, or keep_axis
         den = den.copy
         den[den.eq(0)] = UNDEF          # zero / empty denominator -> undetermined
         num / den                        # UNDEF propagates cell-wise
-      elsif den.equal?(UNDEF) || den == 0
-        UNDEF
+      elsif num.equal?(UNDEF) || den.equal?(UNDEF) || den == 0
+        UNDEF                            # min_count unmet leaves num UNDEF
       else
         num / den
       end
-    fill_value = opts[:fill_value]
-    return result if fill_value.nil?
-    if result.is_a?(CArray)
-      result[result.is_masked] = fill_value if result.has_mask?
-      result
-    else
-      result.equal?(UNDEF) ? fill_value : result
+    CArray.__fill_undefined_result_cells__(result, opts[:fill_value])
+  end
+  private :wmean_object
+
+  # Define on +mod+ one method per name in +names+, each a `def` that passes
+  # its own name and its arguments to the private method +to+:
+  #
+  #   CArray.send(:define_named_methods, self, [:sum, :min], :fold_reduction)
+  #   # def sum (...) = fold_reduction(:sum, ...)
+  #
+  # A method made by define_method carries no name in its frame, so an error
+  # raised inside it cannot name the method the user called; a `def` does.
+  # With +super_block+ the method passes its arguments as an Array and a Hash,
+  # and a block that calls the method it overrides with the arguments the
+  # block is given (`yield(*args, **kw)`).
+  #
+  # With +template+ (and no +to+) each method is written out from it, for a
+  # method on a path where a helper call would cost: __NAME__ is the name and
+  # __VALUE__ the value +names+ (a Hash) gives it, inspected.
+  NAMED_METHOD = /\A(?:[a-z_]\w*[?!]?|\+|-|\*\*?|\/|%|<=>|==|<=?|>=?|<<|>>|&|\||\^|~|[+-]@)\z/
+  def self.define_named_methods (mod, names, to = nil, super_block: false, template: nil)
+    loc = caller_locations(1, 1).first
+    names.each do |name, value|
+      unless name.to_s.match?(NAMED_METHOD)
+        raise ArgumentError, "define_named_methods: #{name.inspect} is not a method name"
+      end
+      src = if template
+              template.gsub("__NAME__", name.to_s).gsub("__VALUE__", value.inspect)
+            elsif super_block
+              "def #{name}(*args, **kw, &blk)\n" \
+              "  #{to}(:#{name}, args, kw) { |*a, **k| super(*a, **k, &blk) }\n" \
+              "end\n"
+            else
+              "def #{name}(...)\n  #{to}(:#{name}, ...)\nend\n"
+            end
+      mod.class_eval(src, loc.path, loc.lineno)
     end
   end
-  private :__wmean_object__
+  private_class_method :define_named_methods
 
 end