carray 3.0.4 → 3.0.5

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.4"
-#define CA_VERSION_CODE 30004
+#define CA_VERSION "3.0.5"
+#define CA_VERSION_CODE 30005
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 4
-#define CA_VERSION_DATE "2026/10/19"
+#define CA_VERSION_TEENY 5
+#define CA_VERSION_DATE "2026/10/20"

data/lib/carray/attribute.rb

@@ -33,14 +33,17 @@
 #    parent's cells, so the parent's attributes do not describe them.
 #    `a.lazy` itself (CALazyMarker) is a view of `a` and walks through,
 #    and so does a lazy type conversion (the cast lane `promote_list`
-#    and `wrap_readonly` build), for the reason `to_type` carries them.
+#    and `wrap_readonly` build), for the reason `to_type` carries them,
+#    and `swap_bytes`: like `refer`, `bitarray` and `bitfield`, a view
+#    that reads the same cells another way carries them.
 #    A view of a Face shows the attributes of the Face it was taken
 #    from (the walk goes to that Face, which the view's own parent
 #    chain skips).
 #    A view of several arrays (CAStack / CAMeld, so `stack`, `meld` and
 #    `montage`) shows, below its own @attr, the keys every one of its
 #    arrays shows with the same value; a key they disagree on, or one
-#    some of them lack, is not shown.
+#    some of them lack, is not shown.  An array with no cells is left out
+#    of that count, unless all of them are empty.
 #
 #  Stored values are frozen copies, nested Arrays and Hashes included, so
 #  an attribute changes only through set_attr / set_attrs: a value read
@@ -58,7 +61,9 @@
 #  `categorize`, a CAFrame `cast` / `parse_to_time` / `to_time`) carries
 #  them.  Arithmetic and reductions do not -- the result is a different
 #  quantity -- including those that pick a value (`first`, `last`, `min`,
-#  `max`, `unique`).  A CAFrame index built from a key column's values
+#  `max`, `unique`) and the element-wise ones that keep the unit (`abs`,
+#  `round`, `clip`): an attribute does not say which operations leave it
+#  true, so none carries it.  Set it on the result again.  A CAFrame index built from a key column's values
 #  (group and pivot) shows the key column's attributes.
 
 class CArray
@@ -235,7 +240,12 @@ class CArray
   end
 
   # The attributes every array in `list` shows with the same value.
+  # An array with no cells holds no values for the attributes to describe,
+  # so it has no say (unless every one is empty), as CAFrame leaves a frame
+  # with no rows out of a meld.
   def self.attrs_shared_by (list)
+    with_cells = list.reject { |a| a.elements == 0 }
+    list = with_cells unless with_cells.empty?
     first, *rest = list.map(&:attrs)
     return {} if first.nil?
     first.select { |k, v| rest.all? { |h| h.key?(k) && h[k] == v } }
@@ -243,7 +253,10 @@ class CArray
   private_class_method :attrs_shared_by
 
   def attr_computing_view? (ca)
-    return ca.__op_id__ < CAMonOp::CAST_BASE if ca.is_a?(CAMonOp)
+    if ca.is_a?(CAMonOp)
+      op = ca.__op_id__
+      return op < CAMonOp::CAST_BASE && op != CAMonOp::OP_BYTE_SWAP
+    end
     ca.is_a?(CABinOp) || ca.is_a?(CATriOp) ||
       ca.is_a?(CAMonCmp) || ca.is_a?(CABinCmp)
   end

data/lib/carray/basics.rb

@@ -117,13 +117,15 @@ class CArray
   end
 
   # @overload drop_axis
-  #   Returns a view of `self` with every size-1 axis dropped.
+  #   Returns a view of `self` with every size-1 axis dropped.  When every
+  #   axis has size 1, one axis of size 1 is kept.
   #   @return [CArray] view with reduced `ndim`.
   def drop_axis
     if ndim == 1
       return self[]
     else
       newdim = shape.reject{|x| x == 1 }
+      newdim = [1] if newdim.empty?     # every axis has size 1: keep one
       return ( ndim != newdim.size ) ? reshape(*newdim) : self[]
     end
   end
@@ -189,7 +191,13 @@ class CArray
   #   @param src [CArray] source array.
   #   @return [self]
   #   @raise [ArgumentError] when `offset.length != self.ndim`.
+  #   @raise [FrozenError] when `self` is frozen.
   def paste (offset, src)
+    # The write goes through a window view, which is not frozen itself:
+    # refuse a frozen self here, as a write into it directly is refused.
+    if frozen?
+      raise FrozenError.new("can't modify frozen #{self.class}: #{inspect}", receiver: self)
+    end
     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
@@ -310,8 +318,7 @@ class CArray
   # @overload clip(min, max = nil, fill_value = nil, lfill: nil, ufill: nil)
   #   Returns `self` with every element clamped to `[min, max]`.
   #
-  #   Either bound may be `nil` for a one-sided clip; that side
-  #   dispatches to the `pmax` / `pmin` binop kernels. When
+  #   Either bound may be `nil` for a one-sided clip. When
   #   `fill_value` (or `lfill` / `ufill`) is given, out-of-range
   #   cells are replaced by the fill instead of clamped -- pass
   #   `UNDEF` to mask that end. `fill_value` is sugar for symmetric
@@ -320,6 +327,8 @@ class CArray
   #
   #   `min` may not exceed `max` (in any cell, when a bound is an
   #   array); equal bounds give every unmasked cell that value.
+  #   A NaN cell of `self` stays NaN, one-sided or two-sided (unlike
+  #   `pmax` / `pmin`, which answer the other operand for it).
   #   A NaN in a bound array leaves that cell unbounded on that side,
   #   as `nil` does for the whole side.  A bound is never UNDEF or
   #   masked: a missing bound is not read as either, so fill it first.
@@ -373,19 +382,30 @@ class CArray
 
     if lfill.nil? && ufill.nil?
       return clamp_between(min, max) if !min.nil? && !max.nil?
-      return pmax(min) if max.nil?
-      return pmin(max)
+      return clamp_below(min) if max.nil?
+      return clamp_above(max)
     end
 
     # A side without a fill still clamps.
     out = self.copy
-    out = out.pmax(min) if !min.nil? && lfill.nil?
-    out = out.pmin(max) if !max.nil? && ufill.nil?
+    out = out.clamp_below(min) if !min.nil? && lfill.nil?
+    out = out.clamp_above(max) if !max.nil? && ufill.nil?
     out[self.lt(min)] = lfill unless min.nil? || lfill.nil?
     out[self.gt(max)] = ufill unless max.nil? || ufill.nil?
     out
   end
 
+  # A one-sided clip of a float array passes a NaN cell through, as the
+  # two-sided one does: the open side is a NaN bound, which leaves it
+  # unbounded.  pmax / pmin would answer the bound for a NaN cell.
+  protected def clamp_below (min)
+    float? ? clamp_between(min, Float::NAN) : pmax(min)
+  end
+
+  protected def clamp_above (max)
+    float? ? clamp_between(Float::NAN, max) : pmin(max)
+  end
+
   # `contains` was retired in favour of {#is_in} (value-hash membership).
   # `a.contains(v1, v2)` -> `a.is_in([v1, v2])`;
   # `a.contains(v1, v2, axis: k)` -> `a.is_in([v1, v2]).any(axis: k)`.

data/lib/carray/categorical.rb

@@ -299,7 +299,7 @@ class CACategorical < CAObject
   #   `codes[i] = x` raises; use `codes.copy` for a mutable copy.
   #   @return [CArray]
   def codes
-    parent
+    face_storage
   end
 
   # Face hook: carry the vocabulary across lifted views (slice / reshape / …).
@@ -328,10 +328,17 @@ class CACategorical < CAObject
   # Face hook: decode a per-cell code into its category label, through the one
   # decode every code-to-label path shares (see #label_at).
   def storage_to_element(raw)
-    code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(parent.data_type)) : raw
+    code = raw.is_a?(String) ? raw.unpack1(UNPACK_FORMAT.fetch(face_storage.data_type)) : raw
     label_at(code)
   end
 
+  # Face hook: a value written into a cell (a fill_value of shift and
+  # window) is a label, and the cell holds its code.
+  # @raise [ArgumentError] if the value is not one of the labels.
+  def element_to_storage (value)
+    code_for_fill(value)
+  end
+
   # ---- category-space operations (by label, not code) -------------------
   #
   # The element value of a categorical IS its category, so these specialise
@@ -389,7 +396,14 @@ class CACategorical < CAObject
   #   (0 for an unknown label).
   #   @param label [Object] category to count.
   #   @return [Integer]
-  def count(label)
+  # @overload count
+  #   Returns the number of cells in some category (not masked), as
+  #   {CArray#count} with no value does.
+  #   @return [Integer]
+  def count(*args)
+    return count_not_masked if args.empty?
+    raise ArgumentError, "count: wrong number of arguments (given #{args.size}, expected 0..1)" if args.size > 1
+    label = args[0]
     code = @labels.index(label)
     code ? codes.count(code) : 0
   end
@@ -400,7 +414,7 @@ class CACategorical < CAObject
   #
   # Memoised: the codes are read-only (immutable storage), so the counts are a
   # pure function of the categorical and stay valid for its lifetime. The same
-  # cached array backs {#reduceat_index} and {#sort_addr}, so a wide aggregate
+  # cached array backs {#reduceat_index} and {#group_addr}, so a wide aggregate
   # over the same categorical pays the count once. (Do not mutate the returned
   # array — it is shared; take `.copy` for a scratch buffer.) A derived-view /
   # composite categorical caches too: read-only rides from the codes as a flag,
@@ -543,7 +557,7 @@ class CACategorical < CAObject
   # The code a fill value stands for: UNDEF stays UNDEF, a label is its code.
   def code_for_fill (value)
     return UNDEF if UNDEF.equal?(value)
-    code = labels.index(value)
+    code = label_position(value)
     raise ArgumentError, "#{value.inspect} is not one of the labels #{labels.inspect}" unless code
     code
   end
@@ -583,27 +597,27 @@ class CACategorical < CAObject
   # two accessors are the building blocks for that other engine — lay the data
   # out as category-contiguous blocks, then select per block.
   #
-  # The grouping plan — sort_addr (the counting sort, the dominant cost) plus
+  # The grouping plan — group_addr (the counting sort, the dominant cost) plus
   # reduceat_index and category_sizes — depends only on the codes, which are
   # read-only. It is therefore memoised (a pure function of the categorical): the
   # first grouping access builds it and every later one reuses it. This is what
   # lets a wide aggregate (many payload columns over one classifier) or a
   # CACategoricalIterator run the counting sort once, not once per column /
   # iterator. Only the plan is cached; the payload-dependent grouped copy
-  # (value.reshape(n)[sort_addr]) is rebuilt per column (it varies with value).
+  # (value.reshape(n)[group_addr]) is rebuilt per column (it varies with value).
 
-  # Force-build (and cache) the whole grouping plan up front — sort_addr,
+  # Force-build (and cache) the whole grouping plan up front — group_addr,
   # reduceat_index, category_sizes — for prepare-ahead use before a batch of
   # groupings. Lazy building already covers correctness; this is the explicit
   # "pay the counting sort now" handle (e.g. right after `df.group_by(col)`).
   # Returns self so it chains.
   # @overload build_grouping
-  #   Eagerly builds and caches the grouping plan (sort_addr / reduceat_index
+  #   Eagerly builds and caches the grouping plan (group_addr / reduceat_index
   #   / category_sizes). Optional — the plan is built lazily on first grouping
   #   access — but useful to pay the counting sort once ahead of a batch.
   #   @return [self]
   def build_grouping
-    sort_addr        # pulls category_sizes; reduceat_index shares category_sizes
+    group_addr       # pulls category_sizes; reduceat_index shares category_sizes
     reduceat_index
     self
   end
@@ -617,26 +631,26 @@ class CACategorical < CAObject
   # order. The first {#category_sizes}.sum addresses are exactly the classified
   # cells in category order — CACategoricalIterator's permutation. For an N-D
   # categorical the addresses are into the raveled storage, so
-  # `value.reshape(elements)[cat.sort_addr]` produces the contiguous blocks.
+  # `value.reshape(elements)[cat.group_addr]` produces the contiguous blocks.
   # Memoised (see the grouping-plan note above): the counting sort is the
   # dominant grouping cost, so it is computed once and shared by every payload
   # column and by CACategoricalIterator, and kept for the categorical's
   # lifetime (an int64 per cell). Do not mutate the returned array.
-  # @overload sort_addr
+  # @overload group_addr
   #   Returns a length-{#elements} integer CArray of flat storage
   #   addresses that order the cells by category (excluded cells last).
   #   @return [CArray]
-  def sort_addr
-    return @sort_addr if @sort_addr
+  def group_addr
+    return @group_addr if @group_addr
     out = codes.reshape(elements).__send__(:addresses_by_category,
                                            reduceat_index.copy, @labels.size,
                                            category_sizes.sum)
-    @sort_addr = out
+    @group_addr = out
     out
   end
 
   # Segment start offsets into the category-contiguous layout produced by
-  # {#sort_addr}: reduceat_index[c] is where category c's block begins, so
+  # {#group_addr}: reduceat_index[c] is where category c's block begins, so
   # block c spans `reduceat_index[c] ... reduceat_index[c] + category_sizes[c]`.
   # Empty categories repeat the following start (a zero-width block). Length k,
   # aligned to #labels; pair with {#category_sizes} for the block lengths. On

data/lib/carray/categorical_iterator.rb

@@ -15,7 +15,7 @@
 #      grp.median   # order statistics share the same surface
 #      grp.stddev
 #
-#  This is the consumer of the sort_addr / reduceat_index foundation on
+#  This is the consumer of the group_addr / reduceat_index foundation on
 #  CACategorical.  Order statistics (median / percentile / quantile) cannot be
 #  scattered — they need every value of a group held together — so the values
 #  are materialized into contiguous blocks once, and every reduction (monoid or
@@ -82,7 +82,7 @@ class CACategoricalIterator < CASegmentIterator
   # once and shared by every payload column and iterator — see
   # CACategorical's grouping-plan note). The plan gives the segment STARTS
   # (reduceat_index) and the group-major permutation (perm[slot] = source index
-  # at that grouped slot, = the valid prefix of sort_addr); gathering value
+  # at that grouped slot, = the valid prefix of group_addr); gathering value
   # through perm is the only per-column work. Excluded cells (masked or
   # out-of-vocabulary code) are absent from perm, so they never join a group;
   # the value mask rides the gather into the grouped copy.
@@ -109,7 +109,7 @@ class CACategoricalIterator < CASegmentIterator
       @offsets  = cat.reduceat_index                # cached segment STARTS (int64[k])
       @bounds   = CArray.segment_offsets(lengths: @elements)  # every boundary (int64[k+1])
       # The group-major source indices (#perm) are taken from the cached
-      # sort_addr when first asked for.
+      # group_addr when first asked for.
       @nvalid   = nvalid
       @codes    = cat.codes.reshape(cat.elements)   # flat codes view (map re-walk / weights)
       # Gather value into category-contiguous order via the cached permutation
@@ -316,12 +316,12 @@ class CACategoricalIterator < CASegmentIterator
 
   # Both are built with the grouping plan, and only on the flat path; the
   # per-fiber form has neither and must not build a segment's.
-  # Group-major source indices = the valid prefix of the cached sort_addr.
+  # Group-major source indices = the valid prefix of the cached group_addr.
   # With no classified cell the prefix is empty (and slicing a length-0
-  # sort_addr would be out of range), so take the empty permutation directly.
+  # group_addr would be out of range), so take the empty permutation directly.
   def perm
     if @nvalid && ! @perm
-      @perm = @nvalid > 0 ? @cat.sort_addr[0...@nvalid] : CArray.int64(0)
+      @perm = @nvalid > 0 ? @cat.group_addr[0...@nvalid] : CArray.int64(0)
     end
     @perm
   end

data/lib/carray/const_string.rb

@@ -92,6 +92,16 @@ class CAConstString
   # override the L1 generics where present.
   include CArray::StringOperationMixin
 
+  # Face hook: a value written into a cell (a fill_value of shift and
+  # window).  A cell is a byte range of the shared buffer, which has no room
+  # for a String it does not hold, so only UNDEF can be written.
+  # @raise [ArgumentError] for any value but UNDEF.
+  def element_to_storage (value)
+    raise ArgumentError,
+          "a CAConstString can't hold a new String (its strings share one " \
+          "buffer); use UNDEF, or to_string first"
+  end
+
   # ---- ordering family ---------------------------------------------------
   #
   # A storage cell is a `(start, end)` byte range into the shared buffer, so

data/lib/carray/data_type_extension.rb

@@ -164,8 +164,15 @@ class CArray
       #  midpoints go the same way as numpy's integer linspace).
       float_out = CArray.new(CA_FLOAT64, [n]).span(x1.to_f..x2.to_f)
       return float_out if data_type == CA_FLOAT64
+      # to_type masks a cell the type cannot hold; linspace refuses it
+      # instead, as arange does.
       # coerce: the type the caller asked for
-      float_out.floor.to_type(data_type)
+      out = float_out.floor.to_type(data_type)
+      if out.any_masked?
+        raise RangeError,
+              "linspace: #{x1.inspect}..#{x2.inspect} is out of range for #{out.data_type_name}"
+      end
+      out
     end
 
     # @overload arange(stop)

data/lib/carray/fixlen_string.rb

@@ -32,9 +32,11 @@ class CArray
   # zero-copy, other string-bearing arrays materialise, numeric is rejected.
   # @overload fixlen_string(values, bytes: nil, truncate: :error)
   #   @param values [Array<String, nil>] source values.
-  #   @param bytes [Integer, nil] slot width; defaults to the max bytesize.
+  #   @param bytes [Integer, nil] slot width, 1 or more; defaults to the
+  #     max bytesize (1 when every string is empty).
   #   @param truncate [Symbol] `:error` or `:silent`.
   #   @return [CAFixlenString]
+  #   @raise [ArgumentError] when `bytes` is given below 1.
   # @overload fixlen_string(ca, bytes: nil, truncate: :error)
   #   @param ca [CArray] a String Face, CA_OBJECT, or raw CA_FIXLEN array.
   #   @return [CAFixlenString]
@@ -63,8 +65,11 @@ class CArray
       values = arg.to_a
     end
 
+    unless bytes.nil? || (bytes.is_a?(Integer) && bytes >= 1)
+      raise ArgumentError, "CArray.fixlen_string: invalid bytes: #{bytes.inspect} (a cell needs bytes: of 1 or more)"
+    end
     width = bytes || values.compact.map { |s| s.to_s.bytesize }.max || 1
-    width = 1 if width < 1
+    width = 1 if width < 1   # every string empty: the narrowest cell
 
     if truncate == :error
       values.each_with_index do |s, i|
@@ -98,4 +103,38 @@ class CAFixlenString
 
   include CArray::StringOperationMixin
   include CArray::StringOperationMixin::Mutable
+
+  # ---- order family beyond the fixlen kernels --------------------------
+  #
+  # min / max / sort run on the cells' bytes.  The members those kernels do
+  # not cover answer here: minmax as the pair of them, and the running
+  # extremes through the strings ({#to_string}), as CAString answers them,
+  # written back at this width.
+
+  # @return [Array(String, String), Array(CAFixlenString, CAFixlenString)]
+  #   `[min, max]`, with the keywords of {CArray#min} / {CArray#max}.
+  def minmax (*args, **kw)
+    [min(*args, **kw), max(*args, **kw)]
+  end
+
+  # @return [CAFixlenString] the running maximum, as {CArray#cummax}.
+  def cummax (*args, **kw)
+    to_string.cummax(*args, **kw).to_fixlen_string(bytes: bytes)
+  end
+
+  # @return [CAFixlenString] the running minimum, as {CArray#cummin}.
+  def cummin (*args, **kw)
+    to_string.cummin(*args, **kw).to_fixlen_string(bytes: bytes)
+  end
+
+  # A String has no distance, so there is no nearest one; refused in the
+  # words CAString uses.
+  def search_nearest (*args, **kw)
+    to_string.search_nearest(*args, **kw)
+  end
+
+  # @see #search_nearest
+  def search_nearest_addr (*args, **kw)
+    to_string.search_nearest_addr(*args, **kw)
+  end
 end

data/lib/carray/frame/column_verbs.rb

@@ -30,18 +30,19 @@ class CAFrame
           next if key_names.include?(name)
           col = @frame[name]
           next unless column_has?(col, verb, args, keywords)
-          cols[name] = yield(col)
+          cols[name] = yield(col, name)
         end
         return cols
       end
       results = names.map do |name|
-        col = @frame[@frame.__send__(:column_key, name, verb)]
+        key = @frame.__send__(:column_key, name, verb)
+        col = @frame[key]
         unless column_has?(col, verb, args, keywords)
           raise CArray::DataTypeError,
                 "#{verb}: column #{name.inspect} " \
                 "(#{CArray::Inspector.type_label(col)}) has no #{verb}"
         end
-        yield(col)
+        yield(col, key)
       end
       results.size == 1 ? results.first : results
     end

data/lib/carray/frame/concat.rb

@@ -20,9 +20,9 @@ class CAFrame
   # preserved: writes to the result flow back to whichever input frame owns
   # the target segment, and vice versa).
   #
-  # Per-column +data_type+ must match across frames (CArray.meld is a view
-  # constructor that refuses to auto-cast — silent promotion here would
-  # hide schema drift).  For an eager, auto-casting alternative use
+  # Per-column +data_type+ must match across frames: CArray.meld would bring
+  # the pieces to a common type, and in a frame that promotion would hide
+  # schema drift.  For an eager, auto-casting alternative use
   # {CAFrame.concatenate}.
   #
   # Column matching is by name (output order follows the first frame);
@@ -54,6 +54,7 @@ class CAFrame
     frames = frames_with_rows(frames)
     cols = {}
     names.each do |name|
+      check_same_column_type(frames.map { |f| f[name] }, name, verb: "meld")
       cols[name] = CArray.meld(frames.map { |f| f[name] }, axis: 0)
     end
     new(cols, axis_name: first.axis_name, index: meld_index(frames))
@@ -229,6 +230,19 @@ class CAFrame
   end
   private_class_method :check_trailing_shapes
 
+  # The pieces of one column have one data type (and one class, for a
+  # Face): a frame does not promote a column to make its pieces agree.
+  def self.check_same_column_type(pieces, name, verb:)
+    first = pieces.first
+    pieces.each_with_index do |c, i|
+      next if CArray::Inspector.type_label(c) == CArray::Inspector.type_label(first)
+      raise ArgumentError,
+            "#{verb}: column #{name.inspect} is #{CArray::Inspector.type_label(c)} in piece #{i}, " \
+            "#{CArray::Inspector.type_label(first)} in piece 0 (cast it first, or use concatenate)"
+    end
+  end
+  private_class_method :check_same_column_type
+
   # Two indexes hold the same rows when their values agree cell by cell; a
   # NaN label matches a NaN label, and a masked cell a masked cell.
   def self.same_index_values?(a, b)

data/lib/carray/frame/frame.rb

@@ -840,13 +840,12 @@ class CAFrame
         case pieces.size
         when 0 then col[CArray.int32(0), *tail]   # replaced every row with none
         when 1 then pieces.first
-        else CArray.meld(pieces, axis: 0)         # CAMeld view; data type mismatch
-        end                                        # across pieces raises.
-                                                   # For data type conversion, cast
-                                                   # the incoming +other+'s
-                                                   # column beforehand — silent
-                                                   # promotion in a splice would
-                                                   # hide schema drift.
+        else
+          # A splice does not promote the column (it would hide schema
+          # drift); cast the incoming column beforehand.
+          CAFrame.send(:check_same_column_type, pieces, name, verb: "splice")
+          CArray.meld(pieces, axis: 0)
+        end
       splice_keep_attrs(new_cols[name], col)
     end
     new_index = splice_index(other, lo, hi)