carray 3.0.3 → 3.0.4

data/lib/carray/mask_gap_fill.rb

@@ -15,7 +15,7 @@
 # `strip_mask(:na)`).  Passing both raises ArgumentError.
 #
 # Design / rationale: devel/PROPOSAL_UNMASK_FILL_METHOD.md.  The forward
-# hold is the C primitive #__hold__; backward = flip -> forward -> flip,
+# hold is the C primitive #hold_forward; backward = flip -> forward -> flip,
 # flatten = flatten -> hold -> reshape, and :linear composes
 # linear_section / linear_fetch.  User-facing YARD docs live in
 # yard-stubs/carray_mask.rb.
@@ -29,50 +29,50 @@
 
 class CArray
 
-  # Preserve the C constant-fill primitives under private names so the
-  # Ruby wrappers can delegate the non-method path unchanged.
-  alias __unmask_const__ unmask
-  alias __strip_mask_const__ strip_mask
-  private :__unmask_const__, :__strip_mask_const__
-
   # Sentinel for "no positional fill value given" (distinct from any real
   # fill value, including nil / false / a Symbol).
   MASK_FILL_UNSET = ::Object.new
+  Ractor.make_shareable(MASK_FILL_UNSET)
   private_constant :MASK_FILL_UNSET
 
-  def unmask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
-    if method
-      unless fill.equal?(MASK_FILL_UNSET)
-        raise ArgumentError,
-              "unmask: pass either a constant fill value or method:, not both"
-      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
-        __unmask_const__                   # fully filled: drop the mask
+  # unmask / strip_mask with method:, in front of the C constant-fill
+  # primitives, which they reach with super.
+  module GapFill
+    def unmask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
+      if method
+        unless fill.equal?(MASK_FILL_UNSET)
+          raise ArgumentError,
+                "unmask: pass either a constant fill value or method:, not both"
+        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
+          super()                   # fully filled: drop the mask
+        end
+        return self
       end
-      return self
+      fill.equal?(MASK_FILL_UNSET) ? super() : super(fill)
     end
-    fill.equal?(MASK_FILL_UNSET) ? __unmask_const__ : __unmask_const__(fill)
-  end
 
-  def strip_mask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
-    if method
-      unless fill.equal?(MASK_FILL_UNSET)
-        raise ArgumentError,
-              "strip_mask: pass either a constant fill value or method:, not both"
+    def strip_mask (fill = MASK_FILL_UNSET, method: nil, axis: nil)
+      if method
+        unless fill.equal?(MASK_FILL_UNSET)
+          raise ArgumentError,
+                "strip_mask: pass either a constant fill value or method:, not both"
+        end
+        return carry_attrs(gap_fill(method, axis, "strip_mask"))
       end
-      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:)"
+      if fill.equal?(MASK_FILL_UNSET)
+        raise ArgumentError, "strip_mask: a fill value is required (or method:)"
+      end
+      carry_attrs(super(fill))
     end
-    __strip_mask_const__(fill)
   end
+  prepend GapFill
 
   private
 
@@ -80,15 +80,15 @@ 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, name)
+  def gap_fill (method, axis, name)
     axis = normalize_axis(axis, name) unless axis.nil?
     case method
     when :forward, :ffill
-      __hold_axis__(axis, false)
+      hold_along_axis(axis, false)
     when :backward, :bfill
-      __hold_axis__(axis, true)
+      hold_along_axis(axis, true)
     when :linear
-      __gap_fill_linear__(axis)
+      gap_fill_linear(axis)
     else
       raise ArgumentError,
             "unmask/strip_mask: unknown method: #{method.inspect} " \
@@ -97,20 +97,20 @@ class CArray
   end
 
   # Forward (backward = false) or backward (true) hold along `axis`, already
-  # normalised by __gap_fill__ (axis nil = flatten).  Backward reuses the forward primitive on the
+  # 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)
+  def hold_along_axis (axis, backward)
     if axis.nil?
       flat = flatten
       flat = flat.reverse if backward
-      held = flat.send(:__hold__, 0)
+      held = flat.send(:hold_forward, 0)
       held = held.reverse if backward
       held.reshape(*shape)
     else
       if backward
-        flip(axis).send(:__hold__, axis).flip(axis)
+        flip(axis).send(:hold_forward, axis).flip(axis)
       else
-        send(:__hold__, axis)
+        send(:hold_forward, axis)
       end
     end
   end
@@ -121,9 +121,9 @@ class CArray
   # 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)
+  def gap_fill_linear (axis)
     if face?
-      unless __interpolable__
+      unless interpolable?
         raise ArgumentError,
               "unmask/strip_mask(method: :linear): #{self.class} does not " \
               "interpolate (it defines no linear_fetch of its own); " \
@@ -135,15 +135,15 @@ class CArray
             "required (got #{data_type_name})"
     end
     if axis.nil?
-      return __linear_fiber__(flatten).reshape(*shape)
+      return linear_fill_fiber(flatten).reshape(*shape)
     end
     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|
-      out[*key] = __linear_fiber__(self[*key])
+    each_fiber_key(ax) do |key|
+      out[*key] = linear_fill_fiber(self[*key])
     end
     out
   end
@@ -151,13 +151,13 @@ class CArray
   # 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?
+  private def interpolable?
+    face? ? self.class.instance_method(:linear_fetch).owner != CArray : numeric?   # type-label: asks what the Face can do, names nothing
   end
 
   # 1-D linear-by-index fill of a single (possibly masked) fiber.
-  def __linear_fiber__ (vec)
-    vec.send(:__linear_fill_along__, CArray.float64(vec.elements) { |i| i.to_f })
+  def linear_fill_fiber (vec)
+    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
@@ -169,7 +169,7 @@ class CArray
   # 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)
+  def linear_fill_along (x)
     present = is_not_masked
     # Fewer than two valid points -> nothing to interpolate between; leave
     # every masked cell masked.
@@ -180,7 +180,13 @@ class CArray
       # lands on its own grid.
       return self[present].linear_fetch(addr)
     end
-    interp = value.float64[present].linear_fetch(addr)
+    v = value[present]
+    # A complex value interpolates its real and imaginary parts.
+    interp = v.complex? ? v.linear_fetch(addr) : v.float64.linear_fetch(addr)
+    # An integer array takes the nearest integer, half away from zero (as a
+    # time Face lands on its own grid), rounded before the store would cut
+    # the fraction off.
+    interp = interp.round if integer?
     # Built from the values alone, so a fully filled result carries no mask.
     out      = value.copy
     masked   = is_masked
@@ -194,7 +200,7 @@ class CArray
   # Yield an index key (Array with `nil` at `axis`, integers elsewhere)
   # for every fiber along `axis`.  `self[*key]` is that fiber as a masked
   # 1-D view.
-  def __each_fiber_key__ (axis)
+  def each_fiber_key (axis)
     outer = shape
     outer_dims = outer.each_index.reject { |k| k == axis }.map { |k| outer[k] }
     idx = Array.new(outer_dims.size, 0)
@@ -210,7 +216,7 @@ class CArray
       end
     end
   end
-  private :__hold_axis__, :__gap_fill_linear__, :__linear_fiber__,
-          :__each_fiber_key__
+  private :hold_along_axis, :gap_fill_linear, :linear_fill_fiber,
+          :each_fiber_key
 
 end

data/lib/carray/meld_reduce.rb

@@ -16,7 +16,7 @@
 #
 # Fast path activates when:
 #   - axis kwarg is a single Integer (or absent for flat reduce)
-#   - no mask on CAMeld or any parent (skipna needs per-cell dispatch;
+#   - no mask on CAMeld or any parent (skipping masked cells needs per-cell dispatch;
 #     the decompose would not see correct mask propagation across parents)
 #   - no non-:axis kwargs (min_count / fill_value / keep_axis / etc. punt
 #     to super; those change finalisation semantics)
@@ -66,9 +66,9 @@ class CAMeld
       total_count = parents.map(&:elements).inject(:+)
       total_sum / total_count.to_f
     elsif meld_axis_normalized?(axis)
-      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
       total_sum = parents.map { |p| p.sum(axis: axis) }.inject(:+)
-      total_count = parents.map { |p| p.dim[meld_axis] }.inject(:+)
+      total_count = parents.map { |p| p.shape[meld_axis] }.inject(:+)
       total_sum / total_count.to_f
     else
       non_meld_axis_decompose(:mean, axis)
@@ -88,8 +88,8 @@ class CAMeld
       return super if parents.all? { |p| p.elements == 0 }
       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 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.shape[meld_axis] == 0 }
       CArray.stack(nonempty.map { |p| p.min(axis: axis) }).min(axis: 0)
     else
       non_meld_axis_decompose(:min, axis)
@@ -107,8 +107,8 @@ class CAMeld
       return super if parents.all? { |p| p.elements == 0 }
       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 }
+      return super if parents.all? { |p| p.shape[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.shape[meld_axis] == 0 }
       CArray.stack(nonempty.map { |p| p.max(axis: axis) }).max(axis: 0)
     else
       non_meld_axis_decompose(:max, axis)
@@ -163,7 +163,7 @@ class CAMeld
   private
 
   def meld_axis_normalized?(axis)
-    (axis < 0 ? axis + ndim : axis) == meld_axis
+    normalize_axis(axis) == meld_axis
   end
 
   # Fast path fires when: no mask anywhere, no non-:axis kwargs, and axis
@@ -177,9 +177,7 @@ class CAMeld
     return false unless (kw.keys - [:axis]).empty?
     axis = kw[:axis]
     unless axis.nil?
-      return false unless axis.is_a?(Integer)
-      norm = axis < 0 ? axis + ndim : axis
-      return false unless norm >= 0 && norm < ndim
+      return false unless axis.is_a?(Integer) && axis >= -ndim && axis < ndim   # axis-check: a gate only; super normalizes
     end
     return false if has_mask?
     parents.each { |p| return false if p.has_mask? }
@@ -218,7 +216,7 @@ class CAMeld
   # meld_axis branch and never reaches here.)
   def non_meld_axis_decompose(op, axis)
     parts = parents.map { |p| p.public_send(op, axis: axis) }
-    axis_norm = axis < 0 ? axis + ndim : axis
+    axis_norm = normalize_axis(axis)
     new_meld_axis = axis_norm < meld_axis ? meld_axis - 1 : meld_axis
     CArray.meld(parts, axis: new_meld_axis).copy
   end
@@ -241,7 +239,7 @@ class CAMeld
       return yield if parents.any? { |p| p.elements < min_n }
       finalize_scalar(welford_flat, sample, sqrt)
     elsif meld_axis_normalized?(axis)
-      return yield if parents.any? { |p| p.dim[meld_axis] < min_n }
+      return yield if parents.any? { |p| p.shape[meld_axis] < min_n }
       finalize_vector(welford_axis(axis), sample, sqrt)
     else
       # Non-meld-axis: each parent's variance/stddev is independent along
@@ -288,7 +286,7 @@ class CAMeld
     mean = nil
     m2 = nil
     parents.each do |p|
-      np = p.dim[meld_axis]
+      np = p.shape[meld_axis]
       mp = p.mean(axis: axis)
       # variance is undefined at n=1; for variancep with n=1, m2_p = 0 by
       # definition (variance_family already gated n >= min_n).

data/lib/carray/methods/bin.rb

@@ -18,6 +18,11 @@ class CArray
   #   that side. NaN / masked input cells are always masked in the
   #   output, independently of `lfill` / `ufill`.
   #
+  #   When `vmin == vmax` the range is one point: a value equal to it is
+  #   in bin 0 whatever `bins:` or `step` says, and a value below or above
+  #   it is out of range.  An array whose values are all the same is
+  #   binned this way by `bin(a.min, a.max, ...)`.
+  #
   #   Use `snap(step, offset:)` when the desired output is the snapped
   #   value; use `bin_to(edges)` when the edges are non-uniform.
   #
@@ -46,23 +51,21 @@ class CArray
     end
     raise ArgumentError, "bin: vmin > vmax" if vmin > vmax
 
-    n = bins || ((vmax - vmin).to_f / step).round
-    raise ArgumentError, "bin: n must be >= 1" if n < 1
-
+    unless bins.nil? || bins.is_a?(Integer)
+      raise TypeError, "bin: bins: must be an Integer (got #{bins.inspect})"
+    end
     if vmin == vmax
-      # Degenerate: zero interval → all cells fall on the single edge;
-      # with include_max: true they land in bin 0.
-      out = CArray.int64(*shape) { 0 }
-      out.mask = self.mask.to_ca if self.has_mask?
-      if self.float?
-        inv = self.is_invalid
-        if inv.count(true) > 0
-          out.mask = out.has_mask? ? (out.mask | inv) : inv
-        end
-      end
-      return out
+      # A range of one point: a value equal to it is in bin 0 whatever the
+      # count of bins (or the step), a value below or above it is out of
+      # range.
+      raise ArgumentError, "bin: n must be >= 1" if bins && bins < 1
+      return bin_to(CArray.float64(2) { vmin.to_f },
+                    lfill: lfill, ufill: ufill, include_max: true)
     end
 
+    n = bins || ((vmax - vmin).to_f / step).round
+    raise ArgumentError, "bin: n must be >= 1" if n < 1
+
     # Delegate to `bin_to` with generated uniform edges — same kernel
     # (`histbin_ki`) as `histogram`, so semantics are identical.
     edges = CArray.float64(n + 1).span(vmin..vmax)
@@ -99,8 +102,9 @@ class CArray
   #   @return [CArray] `CA_INT64` array with the same shape as `self`
   #     holding bin indices in `[0, N-1]` (or the fill values / mask
   #     for out-of-range and masked cells).
-  #   @raise [ArgumentError] when `edges` is not 1-D or has fewer
-  #     than 2 values.
+  #   @raise [ArgumentError] when `edges` is not 1-D, has fewer than 2
+  #     values, has a masked value or NaN, or decreases anywhere.  Equal
+  #     edges (a bin of zero width) and infinite ones are accepted.
   #   @example
   #     e = CA_FLOAT64([0, 1, 10, 100])
   #     v = CA_FLOAT64([0.5, 5.0, 50.0, -1.0, 200.0])
@@ -120,8 +124,12 @@ class CArray
     # under -> -1, in-range -> 0..N-1, over -> N.
     out = src.send(:histbin_ki, e, include_max) - 1
 
-    out[:eq, -1] = lfill.nil? ? UNDEF : lfill          # under
-    out[:eq, n]  = ufill.nil? ? UNDEF : ufill          # over
+    # Both sides are found before either is written, so a fill that equals
+    # the other side's index (lfill: n) is not taken for it.
+    under = out.eq(-1)
+    over  = out.eq(n)
+    out[under] = lfill.nil? ? UNDEF : lfill
+    out[over]  = ufill.nil? ? UNDEF : ufill
     out
   end
 

data/lib/carray/methods/bincount.rb

@@ -35,6 +35,22 @@ class CArray
       raise CArray::DataTypeError,
             "bincount requires an integer label array (got #{data_type_name})"
     end
+    unless length.is_a?(Integer)
+      raise TypeError, "bincount: length: must be an Integer (got #{length.inspect})"
+    end
+    if length < 0
+      raise ArgumentError, "bincount: length: must not be negative (got #{length})"
+    end
+    unless weights.nil?
+      unless weights.is_a?(CArray)
+        raise ArgumentError, "bincount: weights must be a CArray"
+      end
+      unless weights.integer? || weights.float?
+        raise CArray::DataTypeError,
+              "bincount: weights must be numeric (got " \
+              "#{CArray::Inspector.type_label(weights)})"
+      end
+    end
 
     if elements.zero?
       if weights

data/lib/carray/methods/bit_string.rb

@@ -69,7 +69,7 @@ class CArray
       raise ArgumentError,
         "pack_bits: expected CA_BOOLEAN / CA_UINT8 / CA_INT8 (got #{data_type_name})"
     end
-    raise ArgumentError, "pack_bits: 1-D CArray expected (got rank #{rank})" unless rank == 1
+    raise ArgumentError, "pack_bits: 1-D CArray expected (got ndim #{ndim})" unless ndim == 1
     n = elements
     n_bytes = (n + 7) / 8
     packed = CArray.uint8(n_bytes) { 0 }

data/lib/carray/methods/choose.rb

@@ -6,7 +6,8 @@ class CArray
   #
   #   Where `self == i`, the result takes `choices[i]` -- a scalar
   #   fills those cells, a CArray contributes its corresponding
-  #   cells. The result has the same shape as `self`.
+  #   cells. The result has the same shape as `self`. Where a label
+  #   is masked, the result is masked.
   #
   #   @param choices [Array<CArray, Object>] values indexed by the
   #     labels in `self`; each entry is either a same-shape CArray
@@ -15,7 +16,10 @@ class CArray
   #     When `nil` it is inferred: `CArray.result_type` of the CArray
   #     choices, or `CA_OBJECT` when every choice is a scalar.
   #   @return [CArray] new CArray with the shape of `self` holding
-  #     the chosen values.
+  #     the chosen values; a {CAString} when every choice is a String
+  #     or a {CAString} and `data_type` is not given.
+  #   @raise [IndexError] if a label that is not masked is negative or
+  #     not less than the number of choices.
   #   @example
   #     ref = CA_INT([[0, 1, 2], [1, 2, 0], [2, 0, 1]])
   #     a = CArray.int(3, 3).seq(1)
@@ -24,6 +28,14 @@ class CArray
   #     ref.choose([a, b, c])       # per-cell pick from a / b / c
   #     ref.choose(["a", "b", "c"]) # recode labels to values
   def choose (choices, data_type: nil)
+    outside = (self.lt(0) | self.ge(choices.size)).where
+    if outside.elements > 0
+      addr = outside[0]
+      raise IndexError,
+            "choose: label #{self[addr]} at address #{addr} is out of range " \
+            "for #{choices.size} choices"
+    end
+    text = !data_type && CArray.send(:selection_text?, choices)
     unless data_type
       ca = choices.select { |v| v.is_a?(CArray) }
       data_type = ca.empty? ? CA_OBJECT : CArray.result_type(*ca)
@@ -33,7 +45,8 @@ class CArray
       s = self.eq(i)
       out[s] = v.is_a?(CArray) ? v[s] : v
     end
-    out
+    out[self.is_masked] = UNDEF if has_mask?
+    text ? CAString.wrap(out) : out
   end
 
 end

data/lib/carray/methods/composition.rb

@@ -139,6 +139,7 @@ class CArray
   # per-piece dim sizes summed along each tile axis (= block-matrix
   # consistency required across rows / columns).
   def self.__ragged_paste (list, tdim, axis, data_type, name)
+    shared_attrs = attrs_shared_by(list)
     list = CArray.promote_list(list, data_type: data_type)
     # promote_list has already enforced homogeneity (= common data_type, and
     # for Face elements: same Face class + portable + state-compatible).  So,
@@ -150,7 +151,7 @@ class CArray
     # its cell width, and the result is as wide as its widest piece.
     face_parent = list[0].face? ? list.max_by(&:bytes) : nil
     if face_parent
-      list = list.map { |x| x.__send__(:__face_storage__) }
+      list = list.map { |x| x.__send__(:face_storage) }
     end
     data_type = list[0].data_type
     # Fixlen pieces of different widths join at the widest, so no cell is
@@ -223,6 +224,7 @@ class CArray
       obj.paste(idx, item)
     end
     obj = obj.face_lift(face_parent) if face_parent
+    obj.set_attrs(shared_attrs) unless shared_attrs.empty?
     obj
   end
   private_class_method :__ragged_paste

data/lib/carray/methods/gather_nd.rb

@@ -5,9 +5,9 @@
 #  Treats the trailing K axes of `indices.shape = (..., K)` as coordinate tuples
 #  and consumes the first K axes of params while carrying the remaining axes (= rest).
 #
-#  Implementation goes through a CAMapping view of the flattened array:
+#  Implementation goes through an index view (CAGrid) of the flattened array:
 #  `params.flatten[flat_addr]`.  Pure Ruby, no additional framework, composed
-#  entirely from existing indexers as in `take_along_axis`.  Since CAMapping is
+#  entirely from existing indexers as in `take_along_axis`.  Since the view is
 #  writable, write-through via `put_nd` uses last-write-wins semantics (= last
 #  value wins on duplicate indices, same contract as `put_along_axis`).  For
 #  accumulate semantics, route to the `scatter_*!` family instead.
@@ -63,7 +63,7 @@ class CArray
   def gather_nd (indices)
     flat_addr, outer, rest = gather_nd_flat_addr(indices, "gather_nd")
     out_shape = outer + rest
-    # flatten + 1-D fancy indexing -> CAMapping view -> materialise via .copy.
+    # flatten + 1-D fancy indexing -> CAGrid view -> materialise via .copy.
     # A masked coordinate reads as UNDEF: project carries the address mask.
     result = flat_addr.has_mask? ? flatten.project(flat_addr) : self.flatten[flat_addr].copy
     out_shape.empty? ? result : result.reshape(*out_shape)
@@ -91,10 +91,19 @@ class CArray
   #   @raise [ArgumentError] on the same conditions as {#gather_nd}.
   #   @raise [IndexError] when a coordinate is out of range on any axis.
   def put_nd (indices, values)
+    # The write goes through a flattened view, which carries a frozen
+    # array's read-only flag but not its frozenness; say what the array is.
+    raise FrozenError.new("can't modify frozen #{self.class}", receiver: self) if frozen?
     flat_addr, _outer, _rest = gather_nd_flat_addr(indices, "put_nd")
     if flat_addr.has_mask?
-      # A masked coordinate writes nothing: scatter_replace! skips it.
-      flatten.scatter_replace!(flat_addr, values)
+      # A masked coordinate writes nothing.  The values are laid out over
+      # the coordinates by the store itself, so they mean what they mean
+      # unmasked, and only the cells at unmasked coordinates are written.
+      flat = flatten
+      vals = flat.project(flat_addr)
+      vals[] = values
+      sel  = flat_addr.is_not_masked
+      flat[flat_addr[sel]] = vals[sel]
     else
       self.flatten[flat_addr] = values
     end

data/lib/carray/methods/insert_block.rb

@@ -43,13 +43,13 @@ class CArray
     # The original cells are copied as storage, so a read-only Face inserts
     # too; the block's value is written as a value of the array, which a
     # read-only Face refuses.
-    out = __blank_like__(newdim)
+    out = blank_like(newdim)
     if block_given?
       sel = CArray.boolean(*newdim) { true }
       sel[*grids] = false
       out[sel] = block.call
     end
-    out.__send__(:__face_storage__)[*grids] = __face_storage__
+    out.__send__(:face_storage)[*grids] = face_storage
     return out
   end
 

data/lib/carray/methods/is_between.rb

@@ -0,0 +1,59 @@
+class CArray
+
+  # @!group Elementwise math
+
+  # @overload is_between(lo, hi, exclude: nil)
+  # @overload is_between(range)
+  #   Returns a boolean CArray of the same shape as `self`, `true` at each
+  #   cell whose value lies between `lo` and `hi`.  Both bounds are included
+  #   unless `exclude:` names the one to leave out:
+  #
+  #     a.is_between(2, 4)                    # 2 <= a <= 4
+  #     a.is_between(2, 4, exclude: :upper)   # 2 <= a <  4
+  #     a.is_between(2, 4, exclude: :lower)   # 2 <  a <= 4
+  #     a.is_between(2, 4, exclude: :both)    # 2 <  a <  4
+  #
+  #   A Range says the same as the two bounds, its excluded end as
+  #   `exclude: :upper`: `a.is_between(2...4)`.  A bound given as `nil` (or
+  #   the open end of `..4` / `2..`) leaves that side unbounded.
+  #
+  #   It is the two comparisons joined by `&`, so it takes what they take --
+  #   a time array is bounded by Strings, `Time` or elements -- and answers as
+  #   they do: a masked cell is masked, and NaN is outside every interval.
+  #   Bounds the wrong way round (`lo > hi`) contain nothing.
+  #   @param lo [Object, nil] the lower bound.
+  #   @param hi [Object, nil] the upper bound.
+  #   @param exclude [nil, :lower, :upper, :both] the bounds left out.
+  #   @return [CArray] boolean, the shape of `self`.
+  #   @raise [ArgumentError] when neither bound is given, `exclude:` is not one
+  #     of the three, or a Range comes with a second bound or `exclude:`.
+  def is_between (*bounds, exclude: nil)
+    if bounds.size == 1 && bounds[0].is_a?(Range)
+      unless exclude.nil?
+        raise ArgumentError,
+              "is_between: a Range says which ends it includes; give two bounds to use exclude:"
+      end
+      range = bounds[0]
+      lo, hi = range.begin, range.end
+      exclude = :upper if range.exclude_end? && !hi.nil?
+    elsif bounds.size == 2
+      lo, hi = bounds
+    else
+      raise ArgumentError,
+            "is_between: give a lower and an upper bound, or a Range (got #{bounds.size} arguments)"
+    end
+    unless [nil, :lower, :upper, :both].include?(exclude)
+      raise ArgumentError,
+            "is_between: exclude: must be :lower, :upper or :both (got #{exclude.inspect})"
+    end
+    if lo.nil? && hi.nil?
+      raise ArgumentError, "is_between: give at least one bound"
+    end
+    lower = lo.nil? ? nil : (%i[lower both].include?(exclude) ? gt(lo) : ge(lo))
+    upper = hi.nil? ? nil : (%i[upper both].include?(exclude) ? lt(hi) : le(hi))
+    lower && upper ? lower & upper : (lower || upper)
+  end
+
+  # @!endgroup
+
+end