carray 3.0.2 → 3.0.4

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,10 +35,26 @@ 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
-        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 +70,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,20 +58,31 @@ 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,
         "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 }
     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
 

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

@@ -75,7 +75,8 @@ class CArray
   #   Use `CArray.meld` for the uniform-shape view-default counterpart.
   #
   #   @param list [Array<CArray>] pieces to concatenate.
-  #   @param axis [Integer] axis to concatenate along.
+  #   @param axis [Integer, nil] axis to concatenate along; `nil` is the
+  #     same as `0`.
   #   @param data_type [Symbol, Integer, nil] result `data_type`;
   #     inferred via `result_type` when `nil`.
   #   @return [CArray] fresh CArray with per-piece `axis` sizes summed.
@@ -83,7 +84,8 @@ class CArray
   #     inconsistent.
   def self.concatenate (list, axis: 0, data_type: nil)
     raise ArgumentError, "concatenate: list must not be empty" if list.empty?
-    __ragged_paste(list, [list.size], axis, data_type)
+    axis = 0 if axis.nil?
+    __ragged_paste(list, [list.size], axis, data_type, "concatenate")
   end
 
   # @overload concatenate(*others, axis: 0, data_type: nil)
@@ -128,7 +130,7 @@ class CArray
       raise ArgumentError,
             "mosaic: tdim product (#{expected}) must equal list size (#{list.size})"
     end
-    __ragged_paste(list, tdim, axis, data_type)
+    __ragged_paste(list, tdim, axis, data_type, "mosaic")
   end
 
   # Shared eager paste-loop helper (= ex-`combine` paste implementation,
@@ -136,7 +138,8 @@ class CArray
   # shape obtained by tiling `list` over `tdim` starting at `axis`, with
   # 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)
+  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,
@@ -144,12 +147,16 @@ class CArray
     # result with face_lift, rather than special-casing data_class / DATA_SIZE
     # here (= which only ever handled CARecord and silently corrupted plain
     # fixlen / numeric Faces by leaving bytes nil).
-    face_parent = list[0].face? ? list[0] : nil
+    # The Face is re-wrapped from the widest piece: a fixlen Face carries
+    # 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| s = x; s = s.parent while s.face?; s }
+      list = list.map { |x| x.__send__(:face_storage) }
     end
     data_type = list[0].data_type
-    bytes     = (data_type == :fixlen) ? list[0].bytes : nil
+    # Fixlen pieces of different widths join at the widest, so no cell is
+    # cut; each narrower piece is padded with NUL as it is pasted.
+    bytes     = (data_type == :fixlen) ? list.map(&:bytes).max : nil
     # promote_list guarantees a non-empty list of CArrays, so the reference
     # shape is simply the first element (a CScalar carries shape [1], so a
     # leading scalar is fine; the scalar-expansion pass below broadcasts it).
@@ -157,7 +164,7 @@ class CArray
     dim   = ref.shape
     ndim  = ref.ndim
     tndim = tdim.size
-    axis = CArray.normalize_axis(axis, ndim - tndim + 1, "concatenate/mosaic")
+    axis = CArray.normalize_axis(axis, ndim - tndim + 1, name)
 
     list = list.map do |x|
       if x.scalar?
@@ -190,7 +197,7 @@ class CArray
     block.each_with_index do |item, *tidx|
       unless item.ndim == ndim
         raise ArgumentError,
-              "concatenate/mosaic: piece at tile #{tidx.inspect} has ndim " \
+              "#{name}: piece at tile #{tidx.inspect} has ndim " \
               "#{item.ndim} (expected #{ndim})"
       end
       ndim.times do |d|
@@ -199,7 +206,7 @@ class CArray
         expected = on_tile ? tile_sizes[i][tidx[i]] : dim[d]
         unless item.shape[d] == expected
           raise ArgumentError,
-                "concatenate/mosaic: piece at tile #{tidx.inspect} has " \
+                "#{name}: piece at tile #{tidx.inspect} has " \
                 "#{on_tile ? 'tile' : 'non-tile'} axis #{d} size " \
                 "#{item.shape[d]} (expected #{expected}); pieces must agree " \
                 "on non-tile axes and be block-matrix consistent along tile axes"
@@ -217,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/factorize.rb

@@ -23,8 +23,8 @@ class CArray
   #   Distinctness is the family's hash-key judgement (see {#unique}):
   #   `==` for numeric with all NaN collapsed to one value and
   #   -0.0 / +0.0 the same value; `eql?` / `hash` for `CA_OBJECT` and
-  #   `CA_FIXLEN`. Complex is not a lane the factorizer takes and raises
-  #   {CArray::DataTypeError}.
+  #   `CA_FIXLEN`. Complex values compare by value, with NaN and -0.0
+  #   treated the same way in each component.
   #
   #   There is no `sort:` here, unlike {#unique} and {#value_counts}:
   #   the codes index the levels, so reordering the vocabulary would

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,8 +63,9 @@ 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.
-    result = self.flatten[flat_addr].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)
   end
 
@@ -90,8 +91,22 @@ 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")
-    self.flatten[flat_addr] = values
+    if flat_addr.has_mask?
+      # 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
     self
   end
 
@@ -150,6 +165,11 @@ class CArray
     flat_idx = (flat_idx_raw + dims) % dims
 
     base     = (flat_idx * strides).sum(axis: 1).int64.reshape(m)  # (M,)
+    # sum skips a masked coordinate, which would leave its row pointing at
+    # the wrong cell: a row with any masked coordinate has no address.
+    if flat_idx_raw.has_mask?
+      base[flat_idx_raw.is_masked.any(axis: 1)] = UNDEF
+    end
 
     flat_addr =
       if rest.empty?

data/lib/carray/methods/insert_block.rb

@@ -11,8 +11,8 @@ class CArray
   #   appends at the end) and a negative value counts from the end;
   #   `bsize[i]` must be non-negative. Inserted cells are filled by
   #   the block's return value, or left at the type's default when
-  #   no block is given. Preserves fixlen bytes and Face identity
-  #   (built on the storage layout, re-wrapped via `face_lift`).
+  #   no block is given. Preserves fixlen bytes and Face identity; the
+  #   block returns a value of the array (a Time for a time array).
   #   The `offset` array is not mutated.
   #
   #   @param offset [Array<Integer>] insertion offset per axis.
@@ -40,21 +40,16 @@ class CArray
       # offset == dim (append) leaves nothing on the upper side to shift.
       grids[i][offset[i]..-1].seq!(offset[i]+bsize[i]) if offset[i] < shape[i]
     end
-    # Build at the storage layout (preserving bytes for fixlen / Face),
-    # then re-wrap as the same Face.
-    face_parent = self.face? ? self : nil
-    src = self
-    src = src.parent while src.face?
-    dt    = src.data_type
-    bytes = (dt == :fixlen) ? src.bytes : nil
-    out = CArray.new(dt, newdim, bytes: bytes)
+    # 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)
     if block_given?
-      sel = out.true
-      sel[*grids] = 0
+      sel = CArray.boolean(*newdim) { true }
+      sel[*grids] = false
       out[sel] = block.call
     end
-    out[*grids] = src
-    out = out.face_lift(face_parent) if face_parent
+    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