carray 3.0.2 → 3.0.3

data/lib/carray/lazy.rb

@@ -133,6 +133,10 @@ class CArray
   __abs_eager_um__ = instance_method(:__abs_eager__)
   define_method(:abs) do
     if __lazy_view__?
+      # A boolean has no absolute value to change type for, as eager says.
+      raise CArray::DataTypeError,
+            "data_type-changing monop not implemented for input data_type " \
+            "#{CArray.data_type_code(CA_BOOLEAN)}" if boolean?
       abs_i_node = CAMonOp.__build__(self, CAMonOp::OP_ABS_I)
       if complex?
         # float_dt is a Symbol; convert via data_type_code so the cast
@@ -206,7 +210,11 @@ class CArray
   define_method(:imag) do
     if __lazy_view__?
       imag_i_node = CAMonOp.__build__(self, CAMonOp::OP_IMAG_I)
-      if complex?
+      if boolean?
+        # imag_i reads a boolean as int64; the eager imag stays boolean.
+        CAMonOp.__build__(imag_i_node,
+                          CAMonOp::CAST_BASE + CArray.data_type_code(CA_BOOLEAN))
+      elsif complex?
         float_dt = (data_type == CA_CMPLX64) ? CA_FLOAT32 : CA_FLOAT64
         # float_dt is a Symbol; convert via data_type_code for kernel
         # op_id arithmetic.
@@ -235,8 +243,7 @@ class CArray
   #
   # Both paths keep the operand's float / complex width (f32 → f32,
   # cmplx64 → f32), and both send integers to f64 since pi does not fit
-  # an integer slot.  That agrees with the general lazy-substrate rule
-  # "scalar keeps operand's precision" (see ca_lazy_wrap_scalar header).
+  # an integer slot.
   # ---------------------------------------------------------------------------
 
   # @private
@@ -244,8 +251,11 @@ class CArray
   __arg_eager_um__ = instance_method(:__arg_eager__)
   define_method(:arg) do
     if __lazy_view__?
+      raise CArray::DataTypeError,
+            "data_type-changing monop not implemented for input data_type " \
+            "#{CArray.data_type_code(CA_BOOLEAN)}" if boolean?
       parent = self
-      if integer? || boolean?
+      if integer?
         parent = CAMonOp.__build__(parent,
                                    CAMonOp::CAST_BASE +
                                    CArray.data_type_code(CA_FLOAT64))
@@ -326,6 +336,10 @@ class CArray
     end
   end
 
+  # The shift count of an Integer is brought into the array's type before
+  # either form sees it (see CArray::IntegerShiftCount).
+  prepend IntegerShiftCount
+
   # Binop word aliases (`add` -> `+`, `mul` -> `*`, `bit_and` -> `&`, …) were
   # installed by rb_define_alias at Init time (see MkKernel.alias_binop in
   # ext/carray_kernels_*.c) BEFORE the redefinitions above.  The C alias
@@ -529,23 +543,48 @@ class CArray
     end
   end
 
+  # A lazy receiver takes the scalar the eager coerce makes, and stays
+  # lazy itself: the builder promotes the pair as the eager operator does.
   # @!visibility private
   alias_method :__coerce_eager__, :coerce
   coerce_um = instance_method(:__coerce_eager__)
   define_method(:coerce) do |other|
-    if __lazy_view__?
-      dt_name = data_type_name
-      if CScalar.respond_to?(dt_name)
-        s = CScalar.public_send(dt_name)
-        s[0] = other
-        [s, self]
-      else
-        coerce_um.bind_call(self, other)
-      end
-    else
-      coerce_um.bind_call(self, other)
+    begin
+      scalar, receiver = coerce_um.bind_call(self, other)
+    rescue RangeError => e
+      raise unless other.is_a?(Integer)
+      return [OutOfRangeInteger.new(other, self, e), self]
     end
+    __lazy_view__? ? [scalar, self] : [scalar, receiver]
   end
+
+  # An Integer the array's type cannot hold, on the left of an operator.
+  # A comparison is answered from the array's side, where it compares by
+  # value; any other operator refuses the Integer as the array would.
+  class OutOfRangeInteger
+    def initialize (value, array, error)
+      @value, @array, @error = value, array, error
+    end
+
+    def <  (other) = flip(other, :>)
+    def <= (other) = flip(other, :>=)
+    def >  (other) = flip(other, :<)
+    def >= (other) = flip(other, :<=)
+
+    def method_missing (*)
+      raise @error
+    end
+
+    def respond_to_missing? (*) = false
+
+    private
+
+    def flip (other, op)
+      raise @error unless other.equal?(@array)
+      @array.send(op, @value)
+    end
+  end
+  private_constant :OutOfRangeInteger
 end
 
 # ---------------------------------------------------------------------------
@@ -618,14 +657,6 @@ class CAMonOp
     to_ca.to_a
   end
 
-  # @overload sort(*args, **kwargs)
-  #   Materialises `self` into a copy and returns
-  #   `entity.sort(*args, **kwargs)`.
-  #   @return [CArray]
-  def sort(*args, **kwargs)
-    copy.sort(*args, **kwargs)
-  end
-
   # --- MemoryView export → TypeError + .copy recommendation -----------
 
   # bulk-memory-view / Numo / Apache Arrow consumers go through the MV
@@ -714,13 +745,6 @@ class CABinOp
     to_ca.to_a
   end
 
-  # @overload sort(*args, **kwargs)
-  #   Materialises `self` and sorts the resulting entity.
-  #   @return [CArray]
-  def sort(*args, **kwargs)
-    to_ca.sort(*args, **kwargs)
-  end
-
   # @overload to_memory_view
   #   Not supported for lazy binops.
   #   @raise [TypeError] always.

data/lib/carray/mask_gap_fill.rb

@@ -46,15 +46,10 @@ class CArray
         raise ArgumentError,
               "unmask: pass either a constant fill value or method:, not both"
       end
-      held = __gap_fill__(method, axis)
-      # Copy the filled values in place.  A Face writes through its storage: a
-      # bulk store into its surface would try to cast the storage values to the
-      # surface type (int64 ticks to fixlen, for a time array).
-      if face?
-        parent.value[] = held.parent.value
-      else
-        value[] = held.value
-      end
+      held = __gap_fill__(method, axis, "unmask")
+      # Copy the filled values in place (a Face takes a Face of its own kind
+      # as it is).
+      value[] = held.value
       if held.has_mask?
         self.mask = held.mask              # residual leading/trailing mask
       else
@@ -71,7 +66,7 @@ class CArray
         raise ArgumentError,
               "strip_mask: pass either a constant fill value or method:, not both"
       end
-      return __gap_fill__(method, axis)
+      return __gap_fill__(method, axis, "strip_mask")
     end
     if fill.equal?(MASK_FILL_UNSET)
       raise ArgumentError, "strip_mask: a fill value is required (or method:)"
@@ -85,7 +80,8 @@ class CArray
   # unfillable cells stay masked; a fully filled result carries no mask
   # (hold allocates the output mask only when a leading run goes UNDEF;
   # :linear masks only the exterior via mask_invalid).
-  def __gap_fill__ (method, axis)
+  def __gap_fill__ (method, axis, name)
+    axis = normalize_axis(axis, name) unless axis.nil?
     case method
     when :forward, :ffill
       __hold_axis__(axis, false)
@@ -100,8 +96,8 @@ class CArray
     end
   end
 
-  # Forward (backward = false) or backward (true) hold along `axis`
-  # (axis nil = flatten).  Backward reuses the forward primitive on the
+  # Forward (backward = false) or backward (true) hold along `axis`, already
+  # normalised by __gap_fill__ (axis nil = flatten).  Backward reuses the forward primitive on the
   # reversed view; flatten flattens, holds axis 0, reshapes back.
   def __hold_axis__ (axis, backward)
     if axis.nil?
@@ -111,11 +107,10 @@ class CArray
       held = held.reverse if backward
       held.reshape(*shape)
     else
-      ax = axis < 0 ? axis + ndim : axis
       if backward
-        flip(ax).send(:__hold__, ax).flip(ax)
+        flip(axis).send(:__hold__, axis).flip(axis)
       else
-        send(:__hold__, ax)
+        send(:__hold__, axis)
       end
     end
   end
@@ -123,11 +118,18 @@ class CArray
   # Linear-by-index gap fill: interpolate each masked cell from the two
   # bracketing valid cells, x = cell index along the axis.  Cells outside the
   # valid range (leading/trailing) stay masked.  A Face goes through its own
-  # linear_fetch, which keeps its unit and rounds to its grid; whether that
-  # means anything is the Face's call (an ORDERABLE numeric one answers, the
-  # rest raise from there), so this gate only asks that it be one.
+  # linear_fetch, which keeps its unit and rounds to its grid.  Defining one
+  # is how a Face says it interpolates: without it, the core linear_fetch
+  # reads the Face's storage and fails from inside.
   def __gap_fill_linear__ (axis)
-    unless numeric? || face?
+    if face?
+      unless __interpolable__
+        raise ArgumentError,
+              "unmask/strip_mask(method: :linear): #{self.class} does not " \
+              "interpolate (it defines no linear_fetch of its own); " \
+              "use method: :forward or :backward"
+      end
+    elsif ! numeric?
       raise ArgumentError,
             "unmask/strip_mask(method: :linear): numeric or time data_type " \
             "required (got #{data_type_name})"
@@ -135,46 +137,58 @@ class CArray
     if axis.nil?
       return __linear_fiber__(flatten).reshape(*shape)
     end
-    ax = axis < 0 ? axis + ndim : axis
-    if ax < 0 || ax >= ndim
-      raise ArgumentError, "axis #{axis} out of range for ndim #{ndim}"
-    end
-    # A Face assembles in storage space -- its linear_fetch has already rounded
-    # to the grid, so there is nothing left to hold in float64.  A numeric
-    # array assembles in float64 and casts back once at the end.
-    out  = face? ? template : float64.copy
-    sink = face? ? out.parent : out
+    ax = axis
+    # A fiber comes back in self's own type (a Face's linear_fetch has already
+    # rounded to its grid), so the result assembles in that type and the
+    # present cells are never carried through float64.
+    out = face? ? template : value.copy
     __each_fiber_key__(ax) do |key|
-      fiber = __linear_fiber__(self[*key])
-      sink[*key] = face? ? fiber.parent : fiber
+      out[*key] = __linear_fiber__(self[*key])
     end
-    face? ? out : out.to_type(data_type)
+    out
   end
 
-  # 1-D linear-by-index fill of a single (possibly masked) fiber.  Present
-  # cells reproduce exactly; interior masked cells interpolate; exterior
-  # masked cells become UNDEF (linear_section returns NaN out of range,
-  # mask_invalid marks it).  Returns the same kind as `vec`: a Face fiber
-  # comes back as that Face, on its own unit.
+  # Whether linear interpolation can fill this array: a numeric array, or a
+  # Face that defines a linear_fetch of its own -- which is how a Face says it
+  # interpolates (the core linear_fetch would read its storage).
+  private def __interpolable__
+    face? ? self.class.instance_method(:linear_fetch).owner != CArray : numeric?
+  end
+
+  # 1-D linear-by-index fill of a single (possibly masked) fiber.
   def __linear_fiber__ (vec)
-    n = vec.elements
-    present = vec.is_not_masked
+    vec.send(:__linear_fill_along__, CArray.float64(vec.elements) { |i| i.to_f })
+  end
+
+  # Fill the masked cells of this 1-D array by linear interpolation against
+  # the coordinate `x` (same length, ascending over the present cells).
+  # The one rule both the core (x = cell position) and CAFrame (x = index)
+  # use: present cells come back exactly as they are, in this array's own
+  # type; a masked cell inside the span of the present ones takes the
+  # interpolated value; one outside it stays masked.  Outside is where
+  # linear_section answers NaN -- a property of x, not of the values, so a
+  # NaN or Inf stored in a present cell is left alone.  A Face goes through
+  # its own linear_fetch, which keeps its unit and rounds to its grid.
+  def __linear_fill_along__ (x)
+    present = is_not_masked
     # Fewer than two valid points -> nothing to interpolate between; leave
-    # every masked cell masked (the copy carries vec's mask).
-    if present.count(true) < 2
-      return vec.face? ? vec.copy : vec.float64.copy
-    end
-    pos  = CArray.float64(n) { |i| i.to_f }
-    addr = pos[present].linear_section(pos)   # valid positions -> monotonic grid
-    if vec.face?
+    # every masked cell masked.
+    return copy if present.count(true) < 2
+    addr = x[present].linear_section(x)       # valid positions -> monotonic grid
+    if face?
       # The Face's linear_fetch already masks the exterior (out of range) and
-      # lands on its own grid, so it needs no cast and no mask_invalid.
-      return vec[present].linear_fetch(addr)
+      # lands on its own grid.
+      return self[present].linear_fetch(addr)
     end
-    vval = vec.value.float64[present]         # valid values
-    # Mark the out-of-range NaN before casting back: for an integer data_type
-    # the cast turns NaN into 0, and mask_invalid then has nothing left to find.
-    vval.linear_fetch(addr).mask_invalid.to_type(vec.data_type)
+    interp = value.float64[present].linear_fetch(addr)
+    # Built from the values alone, so a fully filled result carries no mask.
+    out      = value.copy
+    masked   = is_masked
+    fill     = masked & addr.is_finite
+    exterior = masked & fill.not
+    out[fill] = interp[fill] if fill.any
+    out[exterior] = UNDEF if exterior.any
+    out
   end
 
   # Yield an index key (Array with `nil` at `axis`, integers elsewhere)

data/lib/carray/math.rb

@@ -3,23 +3,30 @@ module CAMath
   module_function
 
   # Module-function front-ends for binop math methods registered on
-  # CArray by mkkernel. The first argument is auto-wrapped to CArray
-  # via `CArray.wrap_readonly`, so `CAMath.hypot(3, arr)` continues to
-  # work. Integer input is unsupported at the kernel layer -- the
-  # caller must cast to float64 explicitly (e.g.
-  # `arr.as_float64.hypot(...)`).
+  # CArray by mkkernel.  A CArray first argument answers through its own
+  # method, in its own data_type; any other first argument, and an
+  # integer CArray for a function defined only on floats, is taken as
+  # float64, so `CAMath.hypot(3, arr)` works.
 
   # @overload expm1(x)
-  #   Returns `exp(x) - 1` element-wise as float64.
+  #   Returns `exp(x) - 1` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#expm1}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def expm1(x);  CArray.wrap_readonly(x, :float64).expm1;  end
+  def expm1(x)
+    x.is_a?(CArray) ? x.expm1 : CArray.wrap_readonly(x, :float64).expm1
+  end
 
   # @overload log1p(x)
-  #   Returns `log(1 + x)` element-wise as float64.
+  #   Returns `log(1 + x)` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#log1p}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def log1p(x);  CArray.wrap_readonly(x, :float64).log1p;  end
+  def log1p(x)
+    x.is_a?(CArray) ? x.log1p : CArray.wrap_readonly(x, :float64).log1p
+  end
 
   # @overload atan2(y, x)
   #   Returns the element-wise arc tangent of `y / x` with quadrant
@@ -27,21 +34,21 @@ module CAMath
   #   @param y [CArray, Numeric] numerator.
   #   @param x [CArray, Numeric] denominator.
   #   @return [CArray]
-  def atan2(y, x);     CArray.wrap_readonly(y, :float64).atan2(x);     end
+  def atan2(y, x); float_operand(y).atan2(x); end
 
   # @overload hypot(x, y)
   #   Returns the element-wise Euclidean distance `sqrt(x^2 + y^2)`.
   #   @param x [CArray, Numeric] first leg.
   #   @param y [CArray, Numeric] second leg.
   #   @return [CArray]
-  def hypot(x, y);     CArray.wrap_readonly(x, :float64).hypot(y);     end
+  def hypot(x, y); float_operand(x).hypot(y); end
 
   # @overload copysign(x, y)
   #   Returns `|x|` with the sign of `y`, element-wise.
   #   @param x [CArray, Numeric] magnitude source.
   #   @param y [CArray, Numeric] sign source.
   #   @return [CArray]
-  def copysign(x, y);  CArray.wrap_readonly(x, :float64).copysign(y);  end
+  def copysign(x, y); float_operand(x).copysign(y); end
 
   # @overload logaddexp(x, y)
   #   Returns `log(exp(x) + exp(y))` computed to avoid overflow,
@@ -49,7 +56,7 @@ module CAMath
   #   @param x [CArray, Numeric] first log-space value.
   #   @param y [CArray, Numeric] second log-space value.
   #   @return [CArray]
-  def logaddexp(x, y); CArray.wrap_readonly(x, :float64).logaddexp(y); end
+  def logaddexp(x, y); float_operand(x).logaddexp(y); end
 
   # @overload nextafter(x, y)
   #   Returns the next representable float from `x` toward `y`,
@@ -57,21 +64,27 @@ module CAMath
   #   @param x [CArray, Numeric] starting value.
   #   @param y [CArray, Numeric] direction target.
   #   @return [CArray]
-  def nextafter(x, y); CArray.wrap_readonly(x, :float64).nextafter(y); end
+  def nextafter(x, y); float_operand(x).nextafter(y); end
 
   # @overload fmod(x, y)
   #   Returns the C-style `fmod(x, y)` element-wise (sign follows `x`).
   #   @param x [CArray, Numeric] dividend.
   #   @param y [CArray, Numeric] divisor.
   #   @return [CArray]
-  def fmod(x, y);      CArray.wrap_readonly(x, :float64).fmod(y);      end
+  def fmod(x, y);      (x.is_a?(CArray) ? x : CArray.wrap_readonly(x, :float64)).fmod(y); end
+
+  # A float or complex CArray as it is; anything else as float64.
+  def float_operand(x)
+    x.is_a?(CArray) && (x.float? || x.complex?) ? x : CArray.wrap_readonly(x, :float64)
+  end
+  private_class_method :float_operand
 
   # @overload min(*argv)
   #   Returns the element-wise minimum of the given CArray and other
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running min.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def min (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -80,7 +93,7 @@ module CAMath
         out.pmin!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end
@@ -90,7 +103,7 @@ module CAMath
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running max.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def max (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -99,7 +112,7 @@ module CAMath
         out.pmax!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end

data/lib/carray/meld_reduce.rb

@@ -36,7 +36,7 @@ class CAMeld
 
   def sum(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       parents.map(&:sum).inject(:+)
     elsif meld_axis_normalized?(axis)
@@ -52,7 +52,10 @@ class CAMeld
   # @return [CArray, Numeric]
   def mean(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The combine divides in Float; an object array's mean stays exact
+    # (Rational, Integer division) on the core path.
+    return super if object?
+    axis = meld_fast_path_axis(kw)
     # `mean` has no identity: an empty set of contributors has no defined
     # mean (0/0 = NaN).  Punt to super, which returns UNDEF: a reduction
     # with no contributors yields the identity where one exists and UNDEF
@@ -78,12 +81,12 @@ class CAMeld
   # @return [CArray, Numeric]
   def min(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     # `min` has no identity — empty parent list / all-empty parents punt to
     # super for UNDEF.
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:min).min
+      meld_combine_flat(:min)
     elsif meld_axis_normalized?(axis)
       return super if parents.all? { |p| p.dim[meld_axis] == 0 }
       nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
@@ -99,10 +102,10 @@ class CAMeld
   # @return [CArray, Numeric]
   def max(*args, **kw)
     return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    axis = meld_fast_path_axis(kw)
     if axis.nil?
       return super if parents.all? { |p| p.elements == 0 }
-      parents.reject { |p| p.elements == 0 }.map(&:max).max
+      meld_combine_flat(:max)
     elsif meld_axis_normalized?(axis)
       return super if parents.all? { |p| p.dim[meld_axis] == 0 }
       nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
@@ -168,6 +171,9 @@ class CAMeld
   # more elaborate (min_count / fill_value / keep_axis / multi-axis /
   # mask propagation) punts to super.
   def meld_reduce_fast_path_ok?(kw)
+    return false unless CArray.__fast_paths_enabled__
+    # The mask of a meld is a meld built in C, with no parents list.
+    return false unless parents
     return false unless (kw.keys - [:axis]).empty?
     axis = kw[:axis]
     unless axis.nil?
@@ -177,9 +183,30 @@ class CAMeld
     end
     return false if has_mask?
     parents.each { |p| return false if p.has_mask? }
+    # A meld of Face arrays keeps its parents in their Face; the per-parent
+    # calls would reach the Face's own reductions, which answer in the Face's
+    # terms (or refuse), not in storage.
+    parents.each { |p| return false if p.face? }
     true
   end
 
+  # The axis a fast path reduces along.  A 1-D meld has only the meld axis,
+  # and reducing it is reducing the whole array: the answer is a scalar, as
+  # for the flat call.
+  def meld_fast_path_axis(kw)
+    ndim == 1 ? nil : kw[:axis]
+  end
+
+  # The per-parent answers of a whole-array min / max, combined by core's
+  # own min / max so NaN loses the way it loses inside one parent (Ruby's
+  # Array#min would raise on it).
+  def meld_combine_flat(op)
+    vals = parents.reject { |p| p.elements == 0 }.map(&op)
+    part = CArray.new(data_type, [vals.size])
+    vals.each_with_index { |v, i| part[i] = v }
+    part.public_send(op)
+  end
+
   # Non-meld-axis decompose: each parent reduces the same axis independently,
   # then the K per-parent results are concatenated back along the meld axis.
   # Materialised to entity (`.copy`) to match CArray#reduce entity semantics.
@@ -198,7 +225,13 @@ class CAMeld
 
   def variance_family(args, kw, sample:, sqrt:)
     return yield unless args.empty? && meld_reduce_fast_path_ok?(kw)
-    axis = kw[:axis]
+    # The merge works in Float; an object array's variance stays exact
+    # (Rational, BigDecimal) on the core path.
+    return yield if object?
+    # The merge squares the difference of means, which for complex values is
+    # not |δ|²; the core path computes the variance of a complex array.
+    return yield if complex?
+    axis = meld_fast_path_axis(kw)
     # Empty-parent / short-parent handling — Welford needs n >= 2 per parent
     # to recover m2 from p.variance for sample, n >= 1 for variancep (n=1
     # gives m2=0, fine).  Any parent below its threshold punts to super,

data/lib/carray/methods/align_addr.rb

@@ -85,8 +85,10 @@ class CArray
   #     b_on_grid = b_data.project(ib)
   #
   #   `direction:` (`:round` / `:floor` / `:ceil`) and `tolerance:` are
-  #   forwarded to {#locate_nearest_addr}: out-of-range grid points, and points
-  #   whose nearest value is farther than `tolerance`, come back masked.
+  #   forwarded to {#locate_nearest_addr}: grid points with no match in the
+  #   direction (before an array's first value under `:floor`, after its last
+  #   under `:ceil`), and points whose match is farther than `tolerance`, come
+  #   back masked.
   #
   #   @param arrays [Array<CArray>] one or more arrays (Array / Range coerced
   #     via `to_ca`).
@@ -94,8 +96,10 @@ class CArray
   #     `nil` uses the first array verbatim.
   #   @param direction [:round, :floor, :ceil] rounding rule for the nearest
   #     match.
-  #   @param tolerance [Numeric, nil] maximum accepted distance; farther grid
-  #     points are masked. `nil` disables the check.
+  #   @param tolerance [Numeric, String, CATimedelta::Element, nil] maximum
+  #     accepted distance; farther grid points are masked. For time keys it
+  #     is a duration (`"10 minutes"` or a CATimedelta value), as in
+  #     {#locate_nearest_addr}. `nil` disables the check.
   #   @return [Array<CArray>] `[common, idx_0, idx_1, ...]`.
   #   @raise [ArgumentError] when no array is given (or `direction` is invalid,
   #     raised by {#locate_nearest_addr}).

data/lib/carray/methods/bincount.rb

@@ -38,7 +38,7 @@ class CArray
 
     if elements.zero?
       if weights
-        out = CArray.new(weights.data_type, [length])
+        out = CArray.new(weights.data_type, [length], bytes: weights.bytes)
       else
         out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
         out = CArray.new(out_type, [length])
@@ -54,7 +54,7 @@ class CArray
       # Every cell is masked: no labels to count, same result as an empty
       # input (all-zero output of the requested minimum length).
       if weights
-        out = CArray.new(weights.data_type, [length])
+        out = CArray.new(weights.data_type, [length], bytes: weights.bytes)
       else
         out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
         out = CArray.new(out_type, [length])

data/lib/carray/methods/bit_string.rb

@@ -58,9 +58,12 @@ class CArray
   #   multiple of 8) are zero-filled. The byte order matches the packed-bit
   #   convention used by Apache Arrow validity bitmaps and PEP 3118 `?` /
   #   `_Bool` at the bit level.
+  #   A masked cell has no bit to pack, so a receiver with masked cells is
+  #   refused; pack the mask separately with {#validity_bits}.
   #   @return [CArray] uint8 CArray of shape `[ceil(n / 8)]`.
-  #   @raise [ArgumentError] when the receiver is not 1-D or its
-  #     `data_type` is not one of `CA_BOOLEAN` / `CA_UINT8` / `CA_INT8`.
+  #   @raise [ArgumentError] when the receiver is not 1-D, its `data_type`
+  #     is not one of `CA_BOOLEAN` / `CA_UINT8` / `CA_INT8`, or it has
+  #     masked cells.
   def pack_bits
     unless data_type == CA_BOOLEAN || data_type == CA_UINT8 || data_type == CA_INT8
       raise ArgumentError,
@@ -71,7 +74,15 @@ class CArray
     n_bytes = (n + 7) / 8
     packed = CArray.uint8(n_bytes) { 0 }
     return packed if n == 0
-    packed.bitarray.reshape(-1)[0..n-1] = self
+    source = self
+    if has_mask?
+      if count_masked > 0
+        raise ArgumentError,
+          "pack_bits: masked cells have no bit to pack; pack the mask with validity_bits"
+      end
+      source = value
+    end
+    packed.bitarray.reshape(-1)[0..n-1] = source
     packed
   end