carray 3.0.0 → 3.0.2

data/ext/ruby_carray.c

@@ -2,7 +2,7 @@
 
   Single entry point Init_carray_ext: declares the CArray class
   hierarchy + exception class + CA module, populates top-level
-  constants (CA_RANK_MAX / CA_NIL / CA_* data_type Symbols / alignment
+  constants (CA_RANK_MAX / CA_* data_type Symbols / alignment
   values), then drives the per-module Init_* sequence in load order.
 
   CAREFUL: the Init_* call order below carries real ordering
@@ -14,6 +14,7 @@
 ---------------------------------------------------------------------------- */
 
 #include "carray.h"
+#include "carray_build_flags.h"
 #include "version.h"
 
 #ifdef HAVE_RB_ARITHMETIC_SEQUENCE_EXTRACT
@@ -26,7 +27,7 @@ VALUE rb_cCAIterator;
 VALUE rb_eCADataTypeError;
 VALUE rb_mCA;
 
-VALUE CA_NIL;
+VALUE CA_UNSPECIFIED;
 
 void Init_carray_core ();
 void Init_carray_undef ();
@@ -81,7 +82,6 @@ void Init_ca_obj_stack ();   /* multi-parent outer-axis stack */
 void Init_ca_obj_meld ();    /* multi-parent ragged concat along existing axis */
 void Init_ca_obj_transpose ();
 void Init_ca_obj_repeat ();
-void Init_ca_obj_unbound_repeat ();
 void Init_ca_obj_reduce ();
 void Init_ca_obj_field ();
 void Init_ca_obj_fake ();
@@ -107,7 +107,7 @@ void Init_ca_obj_moncmp ();  /* CAMonCmp + lazy elementwise predicate dispatch *
 
 /* Init_carray_iterator retired; CAIterator is a form-only base defined inline
    in Init_carray_ext (accessors in lib/carray/iterator.rb).  The 2.0 C engines
-   (dimension / window / block iterators) live at samples/caiterator/. */
+   (dimension / window / block iterators) were retired in 3.0. */
 
 void Init_carray_mathfunc ();
 
@@ -121,6 +121,13 @@ void Init_ca_kernel_iterator ();
 
 void Init_carray_slab ();
 
+void Init_carray_address_basis (); /* CArray::AddressBasis: pointer + byte
+                                      strides lent for the length of a block,
+                                      for code that addresses cells itself.
+                                      A runtime facility at the ca_attach
+                                      layer, not a user surface; see
+                                      guides/devel/21_address_basis.md */
+
 void
 Init_carray_ext (void)
 {
@@ -142,7 +149,7 @@ Init_carray_ext (void)
   rb_cCScalar    = rb_define_class("CScalar",   rb_cCArray);
   rb_cCAView  = rb_define_class("CAView", rb_cCArray);
   /* CAREFUL: CAStride must exist before its subclasses (CARefer /
-     CABlock / CAField / CARepeat / CAUnboundRepeat / CATranspose /
+     CABlock / CAField / CARepeat / CATranspose /
      CAFarray) are defined or registered.  See devel/CAStride.md. */
   rb_cCAStride   = rb_define_class("CAStride",  rb_cCAView);
   rb_cCARefer    = rb_define_class("CARefer",   rb_cCAStride);
@@ -151,10 +158,6 @@ Init_carray_ext (void)
   rb_cCASelect   = rb_define_class("CASelect",  rb_cCAView);
   rb_cCAObject   = rb_define_class("CAObject",  rb_cCAView);
   rb_cCARepeat   = rb_define_class("CARepeat",  rb_cCAStride);
-  /* CAUnboundRepeat: a CAStride with stride-0 axes on each `*` position
-     and sized (matching parent) on each nil position. */
-  rb_cCAUnboundRepeat  = rb_define_class("CAUnboundRepeat",  rb_cCAStride);
-
   rb_cCArrayMask     = rb_define_class("CArrayMask",    rb_cCArray);
   rb_cCAStrideMask   = rb_define_class("CAStrideMask",  rb_cCAStride);
   rb_cCAReferMask    = rb_define_class("CAReferMask",   rb_cCARefer);
@@ -162,7 +165,6 @@ Init_carray_ext (void)
   rb_cCAFieldMask    = rb_define_class("CAFieldMask",   rb_cCAField);
   rb_cCASelectMask   = rb_define_class("CASelectMask",  rb_cCASelect);
   rb_cCARepeatMask   = rb_define_class("CARepeatMask",  rb_cCARepeat);
-  rb_cCAUnboundRepeatMask  = rb_define_class("CAUnboundRepeatMask",  rb_cCAUnboundRepeat);
 
   /* -- Exception class -- */
 
@@ -175,6 +177,10 @@ Init_carray_ext (void)
 
   /* -- version -- */
 
+  /* The flags this build's arithmetic was compiled with.  Anything that
+     computes what these kernels compute, somewhere other than in them, has
+     to be built the same way to arrive at the same answer. */
+  rb_define_const(rb_cCArray, "BUILD_FLAGS",  rb_str_new2(CA_BUILD_FLAGS));
   rb_define_const(rb_cCArray, "VERSION",       rb_str_new2(CA_VERSION));
   rb_define_const(rb_cCArray, "VERSION_CODE",  INT2NUM(CA_VERSION_CODE));
   rb_define_const(rb_cCArray, "VERSION_MAJOR", INT2NUM(CA_VERSION_MAJOR));
@@ -184,8 +190,14 @@ Init_carray_ext (void)
 
   /* -- system -- */
   rb_define_const(rb_cObject, "CA_RANK_MAX", INT2NUM(CA_RANK_MAX));
-  CA_NIL = rb_funcall(rb_cObject, rb_intern("new"), 0);
-  rb_define_const(rb_cObject, "CA_NIL", CA_NIL);
+  /* Sentinel meaning "the caller did not give this argument".  It is
+     distinct from nil because nil is itself a legal fill value (a
+     CA_OBJECT array can be filled with nil), so nil cannot mark
+     absence.  C code only ever compares against it; the value is never
+     read and must never be passed in from Ruby.  The constant exists to
+     anchor the object against the GC. */
+  CA_UNSPECIFIED = rb_funcall(rb_cObject, rb_intern("new"), 0);
+  rb_define_const(rb_cCArray, "UNSPECIFIED", CA_UNSPECIFIED);
 
 #ifdef HAVE_COMPLEX_H
   /* @private */
@@ -305,7 +317,7 @@ Init_carray_ext (void)
   Init_ca_obj_refer();
   Init_ca_obj_stride();       /* CAREFUL: must precede CAStride subclasses
                                  (farray / block / transpose / repeat /
-                                 unbound_repeat / field). */
+                                 field). */
   Init_ca_obj_farray();
   Init_ca_obj_block();
   Init_ca_obj_select();
@@ -320,7 +332,6 @@ Init_carray_ext (void)
   Init_ca_obj_meld();
   Init_ca_obj_transpose();
   Init_ca_obj_repeat();
-  Init_ca_obj_unbound_repeat();
   Init_ca_obj_reduce();
   Init_ca_obj_field();
   Init_ca_obj_fake();
@@ -351,9 +362,7 @@ Init_carray_ext (void)
   /* CAIterator is the form-only base of the 3.0 iterator family; its shared
      accessors are plain Ruby attr_readers (lib/carray/iterator.rb).  The C
      reduction iterators subclass it and carray_access.c constructs
-     CASlabIterator by name, so the class object must exist here.  The retired
-     2.0 dispatch engines (dimension / window / block C iterators + the
-     kernel_at_addr base) are preserved at samples/caiterator/. */
+     CASlabIterator by name, so the class object must exist here. */
   rb_cCAIterator = rb_define_class("CAIterator", rb_cObject);
 
   Init_ca_group_iter();    /* devel/MEMO_AXIS_GROUP.md — axis-group [] surface
@@ -371,5 +380,7 @@ Init_carray_ext (void)
   Init_ca_kernel_iterator();
 
   Init_carray_slab();
+
+  Init_carray_address_basis();
 }
 

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.0"
-#define CA_VERSION_CODE 300
+#define CA_VERSION "3.0.2"
+#define CA_VERSION_CODE 302
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 0
-#define CA_VERSION_DATE "2026/08/25"
+#define CA_VERSION_TEENY 2
+#define CA_VERSION_DATE "2026/09/24"

data/lib/carray/autoload_carray.rb

@@ -30,8 +30,9 @@
 
 class CArray
   inspect_rb = "carray/inspect"
-  autoload_method "inspect",     inspect_rb
-  autoload_method "source_code", inspect_rb
+  autoload_method "inspect",      inspect_rb
+  autoload_method "inspect_full", inspect_rb
+  autoload_method "source_code",  inspect_rb
 end
 
 # ---- Serializer / Marshal / dump / load ------------------------------------
@@ -42,7 +43,6 @@ class CArray
   autoload_method "self.save",           serialize_rb
   autoload_method "self.load",           serialize_rb
   autoload_method "self.dump",           serialize_rb
-  autoload_method "self.load_from_file", serialize_rb
   autoload_method "marshal_dump",        serialize_rb
   autoload_method "marshal_load",        serialize_rb
 end
@@ -62,6 +62,24 @@ class CArray
   autoload :TableMethods, "carray/table"
 end
 
+# ---- Fusion (reading a lazy expression as a plan) --------------------------
+#
+# Nothing in the core asks for a plan -- CArray can always walk the view --
+# so this loads only when something that compiles one asks.
+
+class CArray
+  autoload :Fusion, "carray/fusion"
+end
+
+# ---- Reading a block as an expression (CArray.fuse) -------------------------
+#
+# Only `fuse` needs this, and only when it is called, so the parser it uses
+# is not loaded by `require "carray"`.
+
+class CArray
+  autoload :FuseSource, "carray/fuse_source"
+end
+
 # ---- Iterators (class / slab) ----------------------------------------------
 
 autoload :CASlabIterator,   "carray/slab_iterator"
@@ -172,6 +190,7 @@ end
 # (2) Single-feature method files under carray/methods/
 # ============================================================================
 
+
 class CArray
   # composition family (eager ragged list -> one array)
   autoload_method "self.concatenate", "carray/methods/composition"
@@ -182,11 +201,13 @@ class CArray
   autoload_method "self.meshgrid",  "carray/methods/meshgrid"
 
   autoload_method "bincount",       "carray/methods/bincount"
+  autoload_method "repeat",         "carray/methods/repeat"
   autoload_method "self.broadcast", "carray/methods/broadcast"
   autoload_method "gather_nd",      "carray/methods/gather_nd"
   autoload_method "put_nd",         "carray/methods/gather_nd"
   autoload_method "mask_duplicates", "carray/methods/mask_duplicates"
   autoload_method "unique",          "carray/methods/unique"
+  autoload_method "factorize",       "carray/methods/factorize"
   autoload_method "is_in",           "carray/methods/is_in"
   autoload_method "intersection",    "carray/methods/is_in"
   autoload_method "difference",      "carray/methods/is_in"

data/lib/carray/autoload_method_extension.rb

@@ -15,6 +15,7 @@
 # monkey patching is avoided -- only classes that explicitly `extend
 # AutoloadMethodExtension` gain the method.
 
+# @private
 module AutoloadMethodExtension
   # @!visibility private
   def autoload_method (method, library)
@@ -31,14 +32,26 @@ module AutoloadMethodExtension
   private
 
   def autoload_define (target, name, library, original_spec)
-    target.send(:define_method, name) do |*args, **kwargs, &block|
+    stub = nil
+    target.define_method(name) do |*args, **kwargs, &block|
       begin
         require library
       rescue LoadError
         raise "error in autoloading '#{library}' hooked by method " \
               "'#{original_spec}', check gem installation."
       end
+      # The require is supposed to have replaced this stub with the real
+      # definition. If it has not, the method does not exist anywhere, and
+      # forwarding would land straight back here and keep doing so until the
+      # stack gave out -- naming neither the method nor the library. Say
+      # which, once.
+      if target.instance_method(name) == stub
+        raise NoMethodError,
+              "'#{original_spec}' is registered for autoload from " \
+              "'#{library}', but that library defines no such method"
+      end
       send(name, *args, **kwargs, &block)
     end
+    stub = target.instance_method(name)
   end
 end

data/lib/carray/axis_group.rb

@@ -308,7 +308,72 @@ end
 # / min / max / variance / stddev / variancep / stddevp / count /
 # count_not_masked / all / any) bind in C to one driver; the rest of the common
 # iterator surface that composes cheaply from those is added here.
+# CAGroupIterator subclasses CAIterator, but the class itself is created in
+# C, so the reopening below carries no superclass for YARD to read.
+# @!parse class CAGroupIterator < CAIterator; end
 class CAGroupIterator
+  # The shape one value per piece comes back in: a group slot contributes its
+  # category count, a band slot its length, in slot order. The base declares
+  # these and every other member answers them; this one inherited the readers
+  # without anything ever setting the ivars, so it answered nil -- which the
+  # base's own rule calls out as the one thing a member must not do ("a clean
+  # NotImplementedError, never a wrong answer").
+  def shape
+    spec.slot_meta.map { |m| m[:kind] == :group ? m[:k] : m[:len] }
+  end
+  alias dim shape
+
+  def ndim
+    spec.nslots
+  end
+
+  # The C dispatcher every reduction shares takes keywords only, so the
+  # value-equality and masked forms the base declares -- count(v), count(UNDEF)
+  # -- arrived as "wrong number of arguments", which reads as a method that
+  # does not take one rather than one whose engine has no such fold. Both are
+  # composed here instead, out of folds the engine does have.
+  alias __count_present__ count
+
+  # @overload count
+  #   Per-group count of present (non-masked) cells.
+  # @overload count(UNDEF)
+  #   Per-group count of masked cells, as {#count_masked}.
+  # @overload count(v)
+  #   Per-group count of cells equal to `v`.
+  #   @return [CArray]
+  def count (*args, **kw)
+    return __count_present__(**kw) if args.empty?
+    if args.size > 1
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..1)"
+    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
+  end
+
+  alias __all_folded__ all
+  alias __any_folded__ any
+
+  # @overload all
+  #   Per-group `all` over a boolean payload.
+  #   @return [CArray]
+  def all (**kw)
+    boolean_payload!(:all)
+    __all_folded__(**kw)
+  end
+
+  # @overload any
+  #   Per-group `any` over a boolean payload.
+  #   @return [CArray]
+  def any (**kw)
+    boolean_payload!(:any)
+    __any_folded__(**kw)
+  end
+
   # Per-group classified cell count (mask-independent) = count on the
   # mask-stripped value, so every classified cell is counted regardless of the
   # value mask (unlike count / count_not_masked, which count present cells).
@@ -401,8 +466,8 @@ class CAGroupIterator
   end
 
   # @overload cummax(axis: :group)
-  #   Per-group inclusive running maximum, source-shaped, in the source dtype
-  #   (extrema do not grow magnitude, so the dtype is preserved). The first
+  #   Per-group inclusive running maximum, source-shaped, in the source data type
+  #   (extrema do not grow magnitude, so the data type is preserved). The first
   #   member of a group emits its own value. Without :group delegates to value
   #   cummax.
   #   @return [CArray]
@@ -411,7 +476,7 @@ class CAGroupIterator
   end
 
   # @overload cummin(axis: :group)
-  #   Per-group inclusive running minimum, source-shaped, in the source dtype.
+  #   Per-group inclusive running minimum, source-shaped, in the source data type.
   #   Without :group delegates to value cummin.
   #   @return [CArray]
   def cummin (**kw)
@@ -549,6 +614,18 @@ class CAGroupIterator
   # (the shape a length-K result reshapes to). This is the classification the C
   # scatter kernel computes on the fly, materialised once so the order
   # statistics / iterate / sort_addr can hold each group's members together.
+  # Whether a payload folds with all / any is the core's call, not this
+  # engine's. The engine counts any non-zero numeric cell as true, which made
+  # the group the one member of the family that answered where CArray#all and
+  # every sibling refuse -- so `data.all` and `data[g].all(axis: :group)` on
+  # the same float array disagreed about whether the question was even
+  # 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)
+    nil
+  end
+
   def composite_layout
     gslots = spec.slot_meta.select { |m| m[:kind] == :group }
     bslots = spec.slot_meta.select { |m| m[:kind] == :band }
@@ -612,7 +689,7 @@ class CAGroupIterator
       unless value.respond_to?(op)
         raise NotImplementedError, "axis_group scan: value has no ##{op}"
       end
-      return value.send(op)
+      return value.public_send(op)
     end
     unless fused.empty?
       raise ArgumentError,
@@ -630,7 +707,7 @@ class CAGroupIterator
   # operation, and remains a follow-up.
   def order_stat (op, args, kw)
     has_group, fused = AxisGroup.parse_axis(kw[:axis])
-    return value.send(op, *args) unless has_group
+    return value.public_send(op, *args) unless has_group
     unless fused.empty?
       raise NotImplementedError,
             "axis_group: folding a band into an order statistic (axis: [:group, k]) " \
@@ -651,13 +728,13 @@ class CAGroupIterator
     ccat, kdims, gslots, bslots, gaxes = composite_layout
     nout = (op == :quantile) ? 5 : 1
     if bslots.empty?
-      res = value.group_by_category(ccat).send(op, *args)
+      res = value.group_by_category(ccat).public_send(op, *args)
       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) }
     each_band_block(ccat, gslots, bslots, gaxes) do |_vi, out_idx, _co, gi|
-      result = gi.send(op, *args)
+      result = gi.public_send(op, *args)
       if nout == 1
         outs[0][*out_idx] = result.reshape(*kdims)
       else

data/lib/carray/basics.rb

@@ -30,27 +30,26 @@ class CArray
   #   shift as other axes are inserted (e.g. `insert_axis(0, 1, 2)`
   #   puts one axis before each of the first three source axes).
   #
-  #   Each inserted axis takes one of three forms, chosen by its
-  #   `repeat` value: `1` (or `nil`) for a plain size-1 axis, an
-  #   Integer `N > 1` for a read-only bound repeat view, or `:*` for
-  #   an unbound repeat that binds on assignment. `repeat` is either
-  #   a single value applied to every inserted axis, or an Array
-  #   giving one value per position.
+  #   Each inserted axis takes one of two forms, chosen by its
+  #   `repeat` value: `1` (or `nil`) for a plain size-1 axis, or an
+  #   Integer `N > 1` for a read-only bound repeat view. `repeat` is
+  #   either a single value applied to every inserted axis, or an
+  #   Array giving one value per position.
   #
-  #   The everyday way to add an axis is the `:_` / `:*` indexer
-  #   when the shape is known at the call site; `insert_axis` is for
-  #   library code that builds the axis list programmatically.
+  #   The everyday way to add an axis is the `:_` indexer when the
+  #   shape is known at the call site; `insert_axis` is for library
+  #   code that builds the axis list programmatically.
   #
   #   @param positions [Array<Integer>] source-frame positions of the
   #     new axes.
-  #   @param repeat [Integer, Symbol, Array, nil] repeat spec applied
-  #     to each inserted axis.
+  #   @param repeat [Integer, Array, nil] repeat spec applied to each
+  #     inserted axis.
   #   @return [CArray] view with the new axes inserted.
   #   @example
   #     a = CArray.int32(3, 4).seq
   #     a.insert_axis(0)                       # shape (1, 3, 4)
   #     a.insert_axis(1, repeat: 5)            # shape (3, 5, 4)
-  #     a.insert_axis(0, 1, repeat: [:*, 3])   # mixed unbound + bound
+  #     a.insert_axis(0, 1, repeat: [1, 3])    # size-1 then bound
   def insert_axis (*positions, repeat: nil)
     flat = positions.flatten
     if flat.empty?
@@ -81,57 +80,31 @@ class CArray
         Array.new(flat.length, repeat)
       end
 
-    # Validate each value.  A positive Integer or :* only; nil is not a
-    # valid per-axis repeat.
-    reps.each do |r|
-      case r
-      when Integer
-        raise ArgumentError, "insert_axis: repeat count must be >= 1" if r < 1
-      when :*
-        # ok
-      else
-        raise ArgumentError,
-          "insert_axis: repeat must be a positive Integer or :*, got #{r.inspect}"
-      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}"
     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 is only used to drive the
-    # output-shaped view constructors (broadcast_to / unbound_repeat); the
-    # actual insertion always goes through the source-frame primitive below.
-    order = (0...flat.length).sort_by { |i| [gaps[i], i] }
-    final = {}
-    order.each_with_index { |i, k| final[i] = gaps[i] + k }
-
-    unbound_args  = order.select { |i| reps[i] == :* }
-    concrete_args = order.reject { |i| reps[i] == :* }   # in output order
-
-    # Stage 1: insert the concrete (size-1 / bound) axes by their source
-    # gaps, then grow the bound ones with broadcast_to.
-    inter = self
-    unless concrete_args.empty?
-      inter = __insert_axis_size1__(*concrete_args.map { |i| gaps[i] })
-      if concrete_args.any? { |i| reps[i].is_a?(Integer) && reps[i] > 1 }
-        shp = inter.shape
-        concrete_args.each do |i|
-          r = reps[i]
-          next unless r.is_a?(Integer) && r > 1
-          # intermediate position = final position minus unbound axes before it
-          shp[final[i] - unbound_args.count { |u| final[u] < final[i] }] = r
-        end
-        inter = inter.broadcast_to(*shp)
-      end
-    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 }
 
-    return inter if unbound_args.empty?
+  inter = __insert_axis_size1__(*order.map { |i| gaps[i] })
+  return inter unless order.any? { |i| reps[i] > 1 }
 
-    # Stage 2: add the unbound axes over the final ndim (`:*` at unbound
-    # positions, nil consumes one stage-1 axis in order).
-    pattern = Array.new(ndim + flat.length, nil)
-    unbound_args.each { |i| pattern[final[i]] = :* }
-    inter.unbound_repeat(*pattern)
-  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.
@@ -186,6 +159,10 @@ class CArray
   #   @raise [ArgumentError] when `offset.length != self.ndim`.
   def paste (offset, src)
     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
+    # build.  This is what lets concatenate / mosaic take an empty piece.
+    return self if src.elements.zero?
     ranges = offset.each_with_index.map { |o, i| o...(o + src.shape[i]) }
     self.window(*ranges)[] = src
     self
@@ -246,6 +223,33 @@ class CArray
 
   alias cmp <=>
 
+  # @!group Elementwise math
+
+  # Returns `[quotient, remainder]` element-wise.
+  #
+  # The quotient is floored toward -inf, so `q * other + r == self` holds
+  # for every sign combination -- the pair Ruby's `Integer#divmod` and
+  # `Float#divmod` return.  For integers that is `self / other` unchanged;
+  # for floats `/` is true division, so the quotient is floored here.
+  #
+  # @param other [CArray, Numeric] divisor.
+  # @return [Array<CArray>] the floored quotient and the remainder.
+  # @raise [ArgumentError] for complex arrays, which have no ordering to
+  #   floor toward.
+  # @example
+  #   CA_INT32([-7]).divmod(3)     # => [-3, 2]
+  #   CA_DOUBLE([-7.0]).divmod(3.0) # => [-3.0, 2.0]
+  def divmod(other)
+    if complex?
+      raise ArgumentError, "divmod is not defined for complex arrays"
+    end
+    q = self / other
+    q = q.floor unless q.integer?
+    [q, self % other]
+  end
+
+  # @!endgroup
+
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #

data/lib/carray/bincount_nd.rb

@@ -68,16 +68,16 @@ class CArray
   # use `CArray#histogram`.
   class BincountND
 
-    # @overload initialize(lengths:, fiber_shape: [], weights_dtype: nil)
+    # @overload initialize(lengths:, fiber_shape: [], weights_data_type: nil)
     #   Allocates a new N-D discrete bincount accumulator.
     #   @param lengths [Array<Integer>] per-dimension label ranges;
     #     each must be `>= 1`.
     #   @param fiber_shape [Array<Integer>] shape of the leading
     #     axes.
-    #   @param weights_dtype [Symbol, nil] `data_type` for weighted
+    #   @param weights_data_type [Symbol, nil] `data_type` for weighted
     #     accumulators; `nil` for pure counts (int64).
     #   @return [BincountND]
-    def initialize (lengths:, fiber_shape: [], weights_dtype: nil)
+    def initialize (lengths:, fiber_shape: [], weights_data_type: nil)
       @lengths = lengths.map(&:to_i)
       raise ArgumentError, "lengths must be a non-empty list" if @lengths.empty?
       @lengths.each_with_index do |l, k|
@@ -85,11 +85,11 @@ class CArray
       end
       @m = @lengths.size
       @fiber_shape = fiber_shape.map(&:to_i).freeze
-      @weighted = !weights_dtype.nil?
-      @counts_dtype = @weighted ? weights_dtype : :int64
+      @weighted = !weights_data_type.nil?
+      @counts_data_type = @weighted ? weights_data_type : :int64
       ext_dims = @lengths.map { |l| l + 1 }       # +1: upper overflow cell
       ext_shape = @fiber_shape + ext_dims
-      @full_counts = CArray.public_send(@counts_dtype, *ext_shape).fill(0)
+      @full_counts = CArray.public_send(@counts_data_type, *ext_shape).fill(0)
       @sample_axis  = nil
       @channel_axis = nil
     end
@@ -209,7 +209,7 @@ class CArray
 
       if weights
         raise ArgumentError, "weights given but accumulator is unweighted" unless @weighted
-        weights = CArray.wrap_readonly(weights, @counts_dtype)
+        weights = CArray.wrap_readonly(weights, @counts_data_type)
         expected_w_shape = chunk.shape.dup
         expected_w_shape.delete_at(channel_ax)
         unless weights.shape == expected_w_shape
@@ -297,7 +297,7 @@ class CArray
       result = self.class.send(:new,
                                lengths: @lengths,
                                fiber_shape: @fiber_shape,
-                               weights_dtype: @weighted ? @counts_dtype : nil)
+                               weights_data_type: @weighted ? @counts_data_type : nil)
       rf = result.instance_variable_get(:@full_counts)
       rf[] = @full_counts + other.full_counts
       result.instance_variable_set(:@sample_axis, @sample_axis)
@@ -344,14 +344,14 @@ class CArray
     [sample_ax, channel_ax].sort.reverse.each { |p| fiber_shape.delete_at(p) }
 
     # Weighted counts are float64-only (the FLAT bincount coerces weights to the
-    # counts dtype and the FIBER kernel requires float64 weights/counts), so the
-    # dtype is fixed here rather than derived from the weights' own dtype.
-    weights_dtype = (:float64 if weights)
+    # counts data type and the FIBER kernel requires float64 weights/counts), so
+    # the type is fixed here rather than derived from the weights' own type.
+    weights_data_type = (:float64 if weights)
 
     h = BincountND.send(:new,
                         lengths: lengths,
                         fiber_shape: fiber_shape,
-                        weights_dtype: weights_dtype)
+                        weights_data_type: weights_data_type)
     h.add(self, axis: axis, weights: weights)
     h
   end