carray 3.0.2 → 3.0.3

data/ext/ruby_carray.c

@@ -44,6 +44,7 @@ void Init_carray_access ();
 void Init_carray_index_classifier ();
 void Init_carray_element ();
 void Init_carray_scatter ();     /* scatter_*! family */
+void Init_carray_segment ();     /* segment lengths / offsets / index */
 void Init_ca_axis_group ();      /* devel/MEMO_AXIS_GROUP.md — axis-group reduction kernel */
 void Init_ca_group_iter ();      /* devel/MEMO_AXIS_GROUP.md — axis-group [] surface */
 void Init_carray_bincount ();    /* bincount dedicated kernel */
@@ -89,6 +90,8 @@ void Init_ca_obj_byte_swap ();
 void Init_ca_face ();            /* CAFace abstract base; must precede CATime / CATimedelta / CARecord / CAConstString */
 void Init_ca_source ();          /* CASource abstract base; concrete sources live in C extensions */
 void Init_ca_obj_time ();  /* first numeric Face */
+void Init_carray_time_text ();
+void Init_caframe_csv_reader ();
 void Init_ca_obj_timedelta ();   /* CATime sibling */
 void Init_ca_obj_record ();      /* composite Face for CAStruct backing */
 void Init_ca_obj_const_string ();/* read-only variable-length string Face */
@@ -169,7 +172,7 @@ Init_carray_ext (void)
   /* -- Exception class -- */
 
   rb_eCADataTypeError =
-    rb_define_class_under(rb_cCArray, "DataTypeError", rb_eStandardError);
+    rb_define_class_under(rb_cCArray, "DataTypeError", rb_eTypeError);
 
   /* -- CA module -- namespace for misc utilities related to CArray */
 
@@ -286,6 +289,7 @@ Init_carray_ext (void)
   Init_carray_index_classifier();
   Init_carray_element();
   Init_carray_scatter();
+  Init_carray_segment();
   Init_ca_axis_group();    /* devel/MEMO_AXIS_GROUP.md — axis-group reduction kernel */
   Init_carray_bincount();
   Init_carray_factorize();
@@ -343,6 +347,8 @@ Init_carray_ext (void)
                                  (datetime / timedelta / record /
                                  const_string). */
   Init_ca_obj_time();
+  Init_carray_time_text();
+  Init_caframe_csv_reader();
   Init_ca_obj_timedelta();
   Init_ca_obj_record();
   Init_ca_obj_const_string();

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.2"
-#define CA_VERSION_CODE 302
+#define CA_VERSION "3.0.3"
+#define CA_VERSION_CODE 30003
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 2
-#define CA_VERSION_DATE "2026/09/24"
+#define CA_VERSION_TEENY 3
+#define CA_VERSION_DATE "2026/10/13"

data/ext/version.rb

@@ -21,8 +21,10 @@ def carray_version
 
   ca_version2 = format("%i.%i.%i", 
                        ca_version_major, ca_version_minor, ca_version_teeny)
-  ca_version_code2 = 
-            100 * ca_version_major + 10*ca_version_minor + ca_version_teeny
+  # Two decimal digits for each of minor and teeny, so 3.0.10 (30010)
+  # comes after 3.0.9 (30009) and before 3.1.0 (30100).
+  ca_version_code2 =
+            10000 * ca_version_major + 100 * ca_version_minor + ca_version_teeny
 
   # Allow pre-release suffix like "3.0.0.dev" / "3.0.0.alpha1" while still
   # validating the numeric MAJOR.MINOR.TEENY prefix.

data/lib/carray/attribute.rb

@@ -4,6 +4,7 @@
 #  Surface:
 #    ca.attr(:unit)             # => getter; nil if absent
 #    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.has_attr?               # => any attribute present?
 #    ca.has_attr?(:unit)        # => specific key present?
@@ -27,6 +28,14 @@
 #    `attrs` returns the effective merged Hash (deeper writes
 #    override shallower ones), frozen.
 #    Setter side always writes to self's @attr.
+#    The walk stops at a lazy operation view (CAMonOp / CABinOp /
+#    CATriOp / CAMonCmp / CABinCmp): its cells are computed, not the
+#    parent's cells, so the parent's attributes do not describe them.
+#    `a.lazy` itself (CALazyMarker) is a view of `a` and walks through.
+#
+#  Copies: `copy` and `to_type` give the new array the attributes the
+#  source shows, as its own Hash.  Arithmetic and reductions do not
+#  carry them -- the result is a different quantity.
 
 class CArray
 
@@ -61,6 +70,30 @@ class CArray
     (@attr ||= {})[attr_normalize_key(key)] = attr_coerce_value(value)
   end
 
+  # @overload set_attrs(hash)
+  #   Sets every key of `hash` on `self`, as {#set_attr} does one key.
+  #   Keys already on `self` and not in `hash` are kept. Every value is
+  #   validated before any is written, so a rejected value leaves `self`
+  #   unchanged. `b.set_attrs(a.attrs)` gives `b` the attributes `a`
+  #   shows.
+  #   @param hash [Hash{Symbol, String => Object}] attributes to set.
+  #   @return [CArray] self.
+  #   @raise [TypeError] when a key or a value is not accepted.
+  def set_attrs (hash)
+    unless hash.is_a?(Hash)
+      raise TypeError, "set_attrs takes a Hash (got #{hash.class})"
+    end
+    entries = hash.map do |key, value|
+      attr_validate_value(value)
+      [attr_normalize_key(key), attr_coerce_value(value)]
+    end
+    unless entries.empty?
+      h = (@attr ||= {})
+      entries.each { |k, v| h[k] = v }
+    end
+    self
+  end
+
   # @overload attrs
   #   Returns a frozen shallow Hash of all attributes visible on
   #   `self`, merged along the parent chain (deeper writes shadow
@@ -114,6 +147,7 @@ class CArray
         h = ca.instance_variable_get(:@attr)
         yield(h) if h
       end
+      return nil if attr_computing_view?(ca)
       parent = ca.respond_to?(:parent) ? ca.parent : nil
       return nil if parent.nil? || parent.equal?(ca)
       ca = parent
@@ -121,6 +155,11 @@ class CArray
     nil
   end
 
+  def attr_computing_view? (ca)
+    ca.is_a?(CAMonOp) || ca.is_a?(CABinOp) || ca.is_a?(CATriOp) ||
+      ca.is_a?(CAMonCmp) || ca.is_a?(CABinCmp)
+  end
+
   def attr_normalize_key (key)
     case key
     when String then key

data/lib/carray/autoload_carray.rb

@@ -47,6 +47,23 @@ class CArray
   autoload_method "marshal_load",        serialize_rb
 end
 
+# A view, 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|
+  klass.class_eval do
+    undef_method :marshal_dump
+    autoload_method "_dump",               "carray/serialize"
+    autoload_method "self._load",          "carray/serialize"
+  end
+end
+
+class CARecord
+  autoload_method "marshal_dump",        "carray/serialize"
+end
+
 # ---- Arrow tensor IPC (interop) --------------------------------------------
 
 class CArray
@@ -126,10 +143,12 @@ class CArray
   categorical_iterator_rb = "carray/categorical_iterator"
   autoload_method "group_by_category", categorical_iterator_rb
   autoload_method "group_by_run", categorical_iterator_rb
+  autoload_method "segments", "carray/segment_iterator"
 end
 
 autoload :CACategorical,          "carray/categorical"
 autoload :CACategoricalIterator,  "carray/categorical_iterator"
+autoload :CASegmentIterator,      "carray/segment_iterator"
 autoload :AxisGroup,              "carray/axis_group"
 autoload :GroupLabels,            "carray/axis_group"
 

data/lib/carray/autoload_method_extension.rb

@@ -53,5 +53,11 @@ module AutoloadMethodExtension
       send(name, *args, **kwargs, &block)
     end
     stub = target.instance_method(name)
+    # The library replaces the stub with a plain `def`, which `ruby -w`
+    # reports as a redefinition.  Replacing is what the stub is for, so mark
+    # it as aliased: Ruby does not warn when the old definition has an alias.
+    tmp = :"__autoload_stub_#{name}__"
+    target.send(:alias_method, tmp, name)
+    target.send(:remove_method, tmp)
   end
 end

data/lib/carray/axis_group.rb

@@ -213,6 +213,57 @@ class AxisGroup
     end
   end
 
+  # The keywords a group reduction takes besides axis:.  Checked before the
+  # work, so an unknown keyword is refused rather than dropped.
+  REDUCE_KEYWORDS = [:axis, :min_count, :fill_value].freeze
+
+  # all / any take axis: only, as the core ones do.
+  LOGICAL_REDUCE_KEYWORDS = [:axis].freeze
+
+  def self.__check_reduce_keywords__ (op, kw)
+    allowed = [:all, :any].include?(op.to_sym) ? LOGICAL_REDUCE_KEYWORDS : REDUCE_KEYWORDS
+    unknown = kw.keys - allowed
+    unless unknown.empty?
+      raise ArgumentError,
+            "#{op}: unknown keyword#{unknown.size > 1 ? "s" : ""}: " +
+            unknown.map(&:inspect).join(", ")
+    end
+    CArray.__min_count_need__(op, kw[:min_count], 0)
+    nil
+  end
+
+  # A boolean array carrying value's mask: what a count reads, for a value
+  # whose payload the group kernel cannot read.
+  def self.__count_stand_in__ (value)
+    return value if value.boolean? || value.integer? || value.float?
+    stand_in = CArray.boolean(*value.shape)
+    stand_in.mask = value.mask if value.has_mask?
+    stand_in
+  end
+
+  # A count of the mask reads every cell of the group, as the core's does.
+  MASK_COUNTS = [:count, :count_not_masked, :count_masked].freeze
+
+  # min_count: masks a group with fewer contributing cells (present cells,
+  # or every cell for a count of the mask); fill_value: then fills the masked
+  # cells -- as a core reduction does with each.
+  def self.__finish_reduction__ (iter, op, kw, result)
+    need = CArray.__min_count_need__(op, kw[:min_count], 0)
+    if need > 0
+      counts = if MASK_COUNTS.include?(op.to_sym)
+                 iter.elements(axis: kw[:axis])
+               else
+                 iter.count_not_masked(axis: kw[:axis])
+               end
+      if result.is_a?(CArray)
+        result[counts.lt(need)] = UNDEF
+      elsif counts < need
+        result = UNDEF
+      end
+    end
+    CArray.__reduce_fill__(result, kw[:fill_value])
+  end
+
   # Parse an axis: spec into [has_group, fused_band_slot_positions].
   def self.parse_axis (axis)
     has_group = false
@@ -348,11 +399,9 @@ class CAGroupIterator
     end
     v = args.first
     return count_masked(**kw) if v.equal?(UNDEF)
-    # a masked cell equals nothing, and eq marks it UNDEF; drop that to false
-    # so it is simply not counted
-    hit = value.eq(v)
-    hit = hit.strip_mask(false) if hit.has_mask?
-    self.class.__build__(hit.int64, spec).sum(**kw).int64
+    # eq leaves a masked cell UNDEF, so the sum leaves it out and its
+    # min_count: counts the present cells, as the core count(v) does
+    self.class.__build__(value.eq(v).int64, spec).sum(**kw).int64
   end
 
   alias __all_folded__ all
@@ -383,7 +432,30 @@ class CAGroupIterator
 
   # Per-group count of value-masked cells = elements - count_not_masked.
   def count_masked (**kw)
-    elements(**kw) - count_not_masked(**kw)
+    has_group, = AxisGroup.parse_axis(kw[:axis])
+    return value.count_masked(**kw) unless has_group
+    AxisGroup.__check_reduce_keywords__(:count_masked, kw)
+    plain = { axis: kw[:axis] }
+    AxisGroup.__finish_reduction__(self, :count_masked, kw,
+                                   elements(**plain) - count_not_masked(**plain))
+  end
+
+  # The scatter kernel reads an integer or float payload, and answers there
+  # as the core does. Any other payload -- boolean, complex, object, a Face --
+  # is reduced group by group by the core, through the composite categorical,
+  # so the data type, the Face and a refusal are the core's: a boolean's sum
+  # is uint64, a time column's minimum a time, its sum refused.
+  [:sum, :accumulate, :prod, :mean, :min, :max,
+   :variance, :stddev, :variancep, :stddevp].each do |op|
+    alias_method :"__#{op}_by_kernel__", op
+    define_method(op) do |**kw|
+      has_group, = AxisGroup.parse_axis(kw[:axis])
+      if ! has_group || kernel_reads_value?
+        __send__(:"__#{op}_by_kernel__", **kw)
+      else
+        reduce_by_core(op, kw)
+      end
+    end
   end
 
   # Per-group [min, max] pair (matching CArray#minmax).
@@ -427,13 +499,21 @@ class CAGroupIterator
   # (no present pair) is UNDEF (matching CArray#wmean); a present group whose
   # weights sum to zero yields NaN/Inf (core's 0/0).
   def wmean (weights, **kw)
+    has_group, = AxisGroup.parse_axis(kw[:axis])
+    return value.wmean(weights, **kw) unless has_group
+    AxisGroup.__check_reduce_keywords__(:wmean, kw)
+    plain = { axis: kw[:axis] }
     prod = value * weights
-    num  = self.class.__build__(prod, spec).sum(**kw)
-    den  = self.class.__build__(value * 0 + weights, spec).sum(**kw)
-    cnt  = self.class.__build__(prod, spec).count_not_masked(**kw)
-    out  = num / den
-    out[cnt.eq(0)] = UNDEF          # no present pair -> masked (empty group)
-    out
+    num  = self.class.__build__(prod, spec).sum(**plain)
+    den  = self.class.__build__(value * 0 + weights, spec).sum(**plain)
+    cnt  = self.class.__build__(prod, spec).count_not_masked(**plain)
+    # 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
+    # min_count: counts the present pairs, as the core wmean does.
+    pairs = self.class.__build__(prod, spec)
+    AxisGroup.__finish_reduction__(pairs, :wmean, kw, num / den)
   end
 
   # ---- segment scan: within-group running statistics ---------------------
@@ -569,12 +649,13 @@ class CAGroupIterator
     raise LocalJumpError, "no block given (yield)" unless block
     ccat, _kd, gslots, bslots, gaxes = composite_layout
     return value.group_by_category(ccat).map(data_type: data_type, &block) if bslots.empty?
-    dt  = data_type || value.data_type
-    out = CArray.new(dt, value.shape)
+    out = nil
     each_band_block(ccat, gslots, bslots, gaxes) do |val_idx, _oi, _co, gi|
-      out[*val_idx] = gi.map(data_type: dt, &block)
+      result = gi.map(data_type: data_type, &block)
+      out ||= blank_of(result, value.shape)
+      out[*val_idx] = result
     end
-    out
+    out || (data_type ? CArray.new(data_type, value.shape) : blank_of(value, value.shape))
   end
 
   # @overload reduce { |members| ... }
@@ -622,7 +703,7 @@ class CAGroupIterator
   # askable. Asking a one-cell array of the same data type lets the core's own
   # refusal through, unworded by us.
   def boolean_payload! (op)
-    CArray.new(value.data_type, [1]).public_send(op)
+    CArray.new(value.data_type, [1], bytes: value.bytes).public_send(op)
     nil
   end
 
@@ -696,10 +777,71 @@ class CAGroupIterator
             "axis_group scan: folding a band into a scan (axis: [:group, k]) " \
             "is not supported; a scan preserves the source shape"
     end
+    return scan_by_core(op) unless kernel_scans?(op)
     group_axes, bundles, = spec.reduce_plan([])
     value.__axis_group_scan__(group_axes, bundles, op)
   end
 
+  # Whether the scatter kernels read this payload: an integer or a float,
+  # not a Face. They answer there in the core's data types.
+  def kernel_reads_value?
+    ! value.face? && (value.integer? || value.float?)
+  end
+
+  # Whether the scan kernel gives the core's answer: it reads an integer,
+  # float, boolean or object payload (not a complex, not a Face), and answers cumsum / cumprod in
+  # 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 if value.face? || value.complex?
+    return true if value.object? || op == :cumcount
+    core = CArray.new(value.data_type, [1], bytes: value.bytes).public_send(op).data_type
+    kernel = [:cumsum, :cumprod].include?(op) ? CA_FLOAT64 : value.data_type
+    core == kernel
+  end
+
+  # A scan the kernel does not answer as the core does: each group block is
+  # grouped through the composite categorical, whose scans are the core's.
+  def scan_by_core (op)
+    ccat, _kd, gslots, bslots, gaxes = composite_layout
+    return value.group_by_category(ccat).public_send(op) if bslots.empty?
+    out = nil
+    each_band_block(ccat, gslots, bslots, gaxes) do |val_idx, _oi, _co, gi|
+      result = gi.public_send(op)
+      out ||= blank_of(result, value.shape)
+      out[*val_idx] = result
+    end
+    out || blank_of(value, value.shape)
+  end
+
+  # A reduction of a payload the scatter kernel does not read, group by
+  # group through the composite categorical. Folding a band into the
+  # statistic needs the kernel.
+  def reduce_by_core (op, kw)
+    _, fused = AxisGroup.parse_axis(kw[:axis])
+    unless fused.empty?
+      raise ArgumentError,
+            "axis_group #{op}: folding a band into the statistic " \
+            "(axis: [:group, k]) is not supported for a #{value.class} of " \
+            "data type #{value.data_type_name}"
+    end
+    AxisGroup.__check_reduce_keywords__(op, kw)
+    AxisGroup.__finish_reduction__(self, op, kw, composite_order(op, []))
+  end
+
+  # An array of +shape+ of the same kind as +model+ -- its data type, or its
+  # Face -- with every cell UNDEF. A read-only Face cannot be written cell by
+  # cell, so its values are held in an object array.
+  def blank_of (model, shape)
+    out = if model.face? && model.read_only?
+            CArray.new(CA_OBJECT, shape)
+          else
+            model.__send__(:__blank_like__, shape)
+          end
+    out[] = UNDEF
+    out
+  end
+
   # Dispatch an order statistic (median / percentile / quantile). No :group ->
   # plain value reduction; :group -> per-group order statistics via the composite
   # materialize. Folding a band into an order statistic (axis: [:group, k])
@@ -707,13 +849,19 @@ class CAGroupIterator
   # operation, and remains a follow-up.
   def order_stat (op, args, kw)
     has_group, fused = AxisGroup.parse_axis(kw[:axis])
-    return value.public_send(op, *args) unless has_group
+    return value.public_send(op, *args, **kw) unless has_group
     unless fused.empty?
       raise NotImplementedError,
             "axis_group: folding a band into an order statistic (axis: [:group, k]) " \
             "is not supported; order statistics gather every member of a group"
     end
-    composite_order(op, args)
+    AxisGroup.__check_reduce_keywords__(op, kw)
+    res = composite_order(op, args)
+    if op == :quantile
+      res.map { |r| AxisGroup.__finish_reduction__(self, op, kw, r) }
+    else
+      AxisGroup.__finish_reduction__(self, op, kw, res)
+    end
   end
 
   # Per-group order statistic over the composite grouping. A flat grouping (no
@@ -732,15 +880,15 @@ class CAGroupIterator
       return nout == 1 ? res.reshape(*kdims) : res.map { |r| r.reshape(*kdims) }
     end
     out_shape = spec.slot_meta.map { |m| m[:kind] == :group ? m[:k] : m[:len] }
-    outs = Array.new(nout) { CArray.float64(*out_shape) }
+    outs = nil
     each_band_block(ccat, gslots, bslots, gaxes) do |_vi, out_idx, _co, gi|
-      result = gi.public_send(op, *args)
-      if nout == 1
-        outs[0][*out_idx] = result.reshape(*kdims)
-      else
-        result.each_with_index { |r, q| outs[q][*out_idx] = r.reshape(*kdims) }
-      end
+      results = gi.public_send(op, *args)
+      results = [results] unless results.is_a?(Array)    # quantile answers five
+      # each output takes the kind the categorical answered in
+      outs ||= results.map { |r| blank_of(r, out_shape) }
+      results.each_with_index { |r, q| outs[q][*out_idx] = r.reshape(*kdims) }
     end
+    outs ||= Array.new(nout) { blank_of(value, out_shape) }
     nout == 1 ? outs[0] : outs
   end
 

data/lib/carray/basics.rb

@@ -80,31 +80,31 @@ class CArray
         Array.new(flat.length, repeat)
       end
 
-  # Validate each value.  A positive Integer only; nil is not a valid
-  # per-axis repeat.
-  reps.each do |r|
-    unless r.is_a?(Integer)
-      raise ArgumentError,
-        "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+    # Validate each value.  A positive Integer only; nil is not a valid
+    # per-axis repeat.
+    reps.each do |r|
+      unless r.is_a?(Integer)
+        raise ArgumentError,
+          "insert_axis: repeat must be a positive Integer, got #{r.inspect}"
+      end
+      raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
     end
-    raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
-  end
 
-  # Final output layout: stable order by (gap, argument index) keeps
-  # same-gap axes in argument order; the k-th inserted axis lands at output
-  # position gap + k.  This output position only drives broadcast_to; the
-  # insertion itself always goes through the source-frame primitive.
-  order = (0...flat.length).sort_by { |i| [gaps[i], i] }
-  final = {}
-  order.each_with_index { |i, k| final[i] = gaps[i] + k }
+    # Final output layout: stable order by (gap, argument index) keeps
+    # same-gap axes in argument order; the k-th inserted axis lands at output
+    # position gap + k.  This output position only drives broadcast_to; the
+    # insertion itself always goes through the source-frame primitive.
+    order = (0...flat.length).sort_by { |i| [gaps[i], i] }
+    final = {}
+    order.each_with_index { |i, k| final[i] = gaps[i] + k }
 
-  inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
-  return inter unless order.any? { |i| reps[i] > 1 }
+    inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
+    return inter unless order.any? { |i| reps[i] > 1 }
 
-  shp = inter.shape
-  order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
-  inter.broadcast_to(*shp)
-end
+    shp = inter.shape
+    order.each { |i| shp[final[i]] = reps[i] if reps[i] > 1 }
+    inter.broadcast_to(*shp)
+  end
 
   # @overload drop_axis
   #   Returns a view of `self` with every size-1 axis dropped.
@@ -142,6 +142,28 @@ end
     return template(:boolean) { 1 }
   end
 
+  # A Face is clipped in its own terms: its comparisons decide which cells are
+  # out of range (a time array reads its bounds as times, a record array
+  # orders by its declared members, a Face that cannot be ordered refuses),
+  # and its store writes the bound or the fill value into them.
+  private def __face_clip__ (min, max, fill_value, lfill, ufill)
+    lfill = fill_value if lfill.nil?
+    ufill = fill_value if ufill.nil?
+    out = copy
+    out[self < min] = lfill.nil? ? min : lfill unless min.nil?
+    out[self > max] = ufill.nil? ? max : ufill unless max.nil?
+    out
+  end
+
+  # An array of +shape+ of the same kind as self: its data type and cell
+  # width, or its Face over a zero storage.  Nothing is written into it, so
+  # it can be built for a read-only Face too.
+  private def __blank_like__ (shape)
+    storage = __face_storage__
+    out = CArray.new(storage.data_type, shape, bytes: storage.bytes)
+    face? ? out.face_lift(self) : out
+  end
+
   # Sub-region copy (paste / crop), the old C `ca_paste` / `ca_clip` pair.
   # `clip` is reserved for value clamping (clamp to a min/max range), so
   # the read-out side is `crop`.  Kept together as a pair (crop is rare, but paste is reached
@@ -250,6 +272,31 @@ end
 
   # @!endgroup
 
+  # An Integer shift count on an integer array means what it means to
+  # Integer#<< and #>>: negative shifts the other way, and a count past the
+  # width shifts every bit out.  The kernels do that for a count of the
+  # array's own type; this brings a count the type cannot hold -- -1 for a
+  # uint8 array, 300 for an int8 one -- to one it can.
+  module IntegerShiftCount
+    UNSIGNED = [CA_UINT8, CA_UINT16, CA_UINT32, CA_UINT64].freeze
+
+    def << (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self >> -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+
+    def >> (other)
+      return super unless other.is_a?(Integer) && integer? && ! face?
+      w = bytes * 8
+      return self << -other if other < 0 && UNSIGNED.include?(data_type)
+      super(other.clamp(-w, w))
+    end
+  end
+  # Prepended by carray/lazy, after it has wrapped << and >>: prepended
+  # here, the method lazy aliases as the eager form would be this one.
+
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #
@@ -258,7 +305,12 @@ end
   #   `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
-  #   dual-fill; `lfill` / `ufill` override per side.
+  #   dual-fill; `lfill` / `ufill` override per side, and a side
+  #   given no fill is still clamped.
+  #
+  #   `min` may not exceed `max` (in any cell, when a bound is an
+  #   array); equal bounds give every unmasked cell that value.
+  #   A NaN bound bounds nothing.
   #
   #   Boundary is strict `[min, max]`: values equal to a bound
   #   remain unchanged in both the clamped and filled variants.
@@ -272,7 +324,8 @@ end
   #   @param lfill [Object, nil] override below-range fill.
   #   @param ufill [Object, nil] override above-range fill.
   #   @return [CArray] new CArray with clamped or filled values.
-  #   @raise [ArgumentError] when both `min` and `max` are `nil`.
+  #   @raise [ArgumentError] when both `min` and `max` are `nil`,
+  #     or when `min` exceeds `max`.
   #   @example
   #     a.clip(0, 10)                          # strict clamp
   #     a.clip(0, 10, -1)                      # both ends -> -1
@@ -281,6 +334,16 @@ end
     if min.nil? && max.nil?
       raise ArgumentError, "clip: at least one of (min, max) must be given"
     end
+    return __face_clip__(min, max, fill_value, lfill, ufill) if face?
+    if !min.nil? && !max.nil?
+      reversed = if min.is_a?(CArray) then min.gt(max).any
+                 elsif max.is_a?(CArray) then max.lt(min).any
+                 else min > max
+                 end
+      if reversed
+        raise ArgumentError, "clip: min must be less than or equal to max"
+      end
+    end
 
     # `fill_value` as a single argument is sugar applied to both ends; kwargs override.
     lfill = fill_value if lfill.nil?
@@ -292,9 +355,12 @@ end
       return pmin(max)
     end
 
+    # A side without a fill still clamps.
     out = self.copy
-    out[:lt, min] = lfill unless min.nil? || lfill.nil?
-    out[:gt, max] = ufill unless max.nil? || ufill.nil?
+    out = out.pmax(min) if !min.nil? && lfill.nil?
+    out = out.pmin(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
 

data/lib/carray/bincount_nd.rb

@@ -269,6 +269,12 @@ class CArray
           term = strides_ext[k] == 1 ? b : b * strides_ext[k]
           ravel = ravel.nil? ? term : ravel + term
         end
+        # A NaN weight drops its sample, as the fiber kernel and histogram
+        # do; bincount itself would add the NaN in.
+        if tweights && tweights.float?
+          nan = tweights.is_nan
+          tweights = tweights.mask_where(nan) if nan.any
+        end
         chunk_counts = ravel.bincount(weights: tweights, length: total_ext)
         @full_counts[] = @full_counts + chunk_counts.reshape(*@full_counts.shape)
       else