carray 3.0.3 → 3.0.4

data/ext/ruby_carray.c

@@ -38,6 +38,7 @@ void Init_carray_attribute ();
 void Init_carray_loop ();
 void Init_carray_mask ();
 void Init_carray_hold ();
+void Init_carray_key_windows ();
 void Init_carray_mask_fast_paths ();  /* patches generated bit-op tables;
                                          must run AFTER Init_ca_op_ipower */
 void Init_carray_access ();
@@ -60,6 +61,7 @@ void Init_carray_median_percentile ();  /* median / percentile / quantile */
 void Init_carray_sort ();         /* sort / sort_copy / sort_addr / axis2addr */
 void Init_carray_count ();
 void Init_carray_kernels ();      /* mkkernel-generated: reductions + maps */
+void Init_carray_round ();
 void Init_carray_utils ();
 void Init_carray_generate ();
 void Init_carray_copy ();
@@ -183,13 +185,13 @@ Init_carray_ext (void)
   /* The flags this build's arithmetic was compiled with.  Anything that
      computes what these kernels compute, somewhere other than in them, has
      to be built the same way to arrive at the same answer. */
-  rb_define_const(rb_cCArray, "BUILD_FLAGS",  rb_str_new2(CA_BUILD_FLAGS));
-  rb_define_const(rb_cCArray, "VERSION",       rb_str_new2(CA_VERSION));
+  rb_define_const(rb_cCArray, "BUILD_FLAGS",  rb_obj_freeze(rb_str_new2(CA_BUILD_FLAGS)));
+  rb_define_const(rb_cCArray, "VERSION",       rb_obj_freeze(rb_str_new2(CA_VERSION)));
   rb_define_const(rb_cCArray, "VERSION_CODE",  INT2NUM(CA_VERSION_CODE));
   rb_define_const(rb_cCArray, "VERSION_MAJOR", INT2NUM(CA_VERSION_MAJOR));
   rb_define_const(rb_cCArray, "VERSION_MINOR", INT2NUM(CA_VERSION_MINOR));
   rb_define_const(rb_cCArray, "VERSION_TEENY", INT2NUM(CA_VERSION_TEENY));
-  rb_define_const(rb_cCArray, "VERSION_DATE",  rb_str_new2(CA_VERSION_DATE));
+  rb_define_const(rb_cCArray, "VERSION_DATE",  rb_obj_freeze(rb_str_new2(CA_VERSION_DATE)));
 
   /* -- system -- */
   rb_define_const(rb_cObject, "CA_RANK_MAX", INT2NUM(CA_RANK_MAX));
@@ -199,8 +201,10 @@ Init_carray_ext (void)
      absence.  C code only ever compares against it; the value is never
      read and must never be passed in from Ruby.  The constant exists to
      anchor the object against the GC. */
-  CA_UNSPECIFIED = rb_funcall(rb_cObject, rb_intern("new"), 0);
+  CA_UNSPECIFIED = rb_obj_freeze(rb_funcall(rb_cObject, rb_intern("new"), 0));
   rb_define_const(rb_cCArray, "UNSPECIFIED", CA_UNSPECIFIED);
+  /* Compared by identity in C, so it must not move. */
+  rb_gc_register_mark_object(CA_UNSPECIFIED);
 
 #ifdef HAVE_COMPLEX_H
   /* @private */
@@ -284,6 +288,7 @@ Init_carray_ext (void)
   Init_carray_undef();
   Init_carray_mask();
   Init_carray_hold();
+  Init_carray_key_windows();
   Init_carray_loop();
   Init_carray_access();
   Init_carray_index_classifier();
@@ -308,6 +313,7 @@ Init_carray_ext (void)
   Init_carray_sort();               /* sort / sort_copy / sort_addr / axis2addr */
   Init_carray_count();
   Init_carray_kernels();            /* mkkernel-generated: reductions + maps */
+  Init_carray_round();              /* round(ndigits); after the generated round */
 
   Init_carray_utils();
 

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.3"
-#define CA_VERSION_CODE 30003
+#define CA_VERSION "3.0.4"
+#define CA_VERSION_CODE 30004
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 3
-#define CA_VERSION_DATE "2026/10/13"
+#define CA_VERSION_TEENY 4
+#define CA_VERSION_DATE "2026/10/19"

data/lib/carray/attribute.rb

@@ -31,11 +31,35 @@
 #    The walk stops at a lazy operation view (CAMonOp / CABinOp /
 #    CATriOp / CAMonCmp / CABinCmp): its cells are computed, not the
 #    parent's cells, so the parent's attributes do not describe them.
-#    `a.lazy` itself (CALazyMarker) is a view of `a` and walks through.
+#    `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.
+#    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.
 #
-#  Copies: `copy` and `to_type` give the new array the attributes the
-#  source shows, as its own Hash.  Arithmetic and reductions do not
-#  carry them -- the result is a different quantity.
+#  Stored values are frozen copies, nested Arrays and Hashes included, so
+#  an attribute changes only through set_attr / set_attrs: a value read
+#  back cannot be changed in place, and a copy that shares it with its
+#  source cannot change the source.  A frozen array takes no new
+#  attribute.
+#
+#  A mask array (`a.mask`) holds no attributes: set_attr / set_attrs raise.
+#
+#  Copies: `dup` and `clone` give the new array its own Hash of the
+#  receiver's own attributes.  `copy` and `to_type` give the new array the attributes the
+#  source shows, as its own Hash; `concatenate`, `mosaic` and `tabulate`
+#  give it the keys every piece shows with the same value, as the views
+#  do.  A conversion to another type or representation (`to_type`,
+#  `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
+#  (group and pivot) shows the key column's attributes.
 
 class CArray
 
@@ -63,9 +87,15 @@ class CArray
   #   store.
   #   @param key [Symbol, String] attribute key.
   #   @param value [Object] JSON-compatible value.
-  #   @return [Object] the coerced stored value.
+  #   The value is stored as a frozen copy (nested Arrays and Hashes
+  #   too).
+  #   @return [Object] the stored value.
   #   @raise [TypeError] when `key` or `value` is not accepted.
+  #   @raise [ArgumentError] when `value` nests more than 32 levels.
+  #   @raise [FrozenError] when `self` is frozen.
+  #   @raise [TypeError] when `self` is a mask array.
   def set_attr (key, value)
+    attr_check_writable
     attr_validate_value(value)
     (@attr ||= {})[attr_normalize_key(key)] = attr_coerce_value(value)
   end
@@ -79,7 +109,11 @@ class CArray
   #   @param hash [Hash{Symbol, String => Object}] attributes to set.
   #   @return [CArray] self.
   #   @raise [TypeError] when a key or a value is not accepted.
+  #   @raise [ArgumentError] when a value nests more than 32 levels.
+  #   @raise [FrozenError] when `self` is frozen.
+  #   @raise [TypeError] when `self` is a mask array.
   def set_attrs (hash)
+    attr_check_writable
     unless hash.is_a?(Hash)
       raise TypeError, "set_attrs takes a Hash (got #{hash.class})"
     end
@@ -94,8 +128,23 @@ class CArray
     self
   end
 
+  # @overload delete_attr(key)
+  #   Removes attribute `key` from `self` (not from any parent) and
+  #   returns its value, or `nil` when `self` has no such key. A key a
+  #   view shows from its parent stays visible after this, as `set_attr`
+  #   writes to `self` only.
+  #   @param key [Symbol, String] attribute key.
+  #   @return [Object, nil] the removed value.
+  #   @raise [FrozenError] when `self` is frozen.
+  def delete_attr (key)
+    k = attr_normalize_key(key)
+    return nil unless instance_variable_defined?(:@attr) && @attr
+    attr_check_not_frozen
+    @attr.delete(k)
+  end
+
   # @overload attrs
-  #   Returns a frozen shallow Hash of all attributes visible on
+  #   Returns a frozen Hash of all attributes visible on
   #   `self`, merged along the parent chain (deeper writes shadow
   #   shallower ones on a per-key basis).
   #   @return [Hash{String => Object}]
@@ -135,32 +184,85 @@ class CArray
   private
 
   # Yield each non-nil @attr Hash along the parent chain (self first).
-  # Bounded to MAX_CHAIN_DEPTH for paranoia against unexpected cycles;
-  # real CArray view chains rarely exceed a handful of levels.
-  MAX_CHAIN_DEPTH = 64
-  private_constant :MAX_CHAIN_DEPTH
-
+  # The chain has no fixed bound; an array seen twice ends the walk.
   def attr_each_chain
     ca = self
-    MAX_CHAIN_DEPTH.times do
+    seen = nil
+    loop do
       if ca.instance_variable_defined?(:@attr)
         h = ca.instance_variable_get(:@attr)
         yield(h) if h
       end
       return nil if attr_computing_view?(ca)
-      parent = ca.respond_to?(:parent) ? ca.parent : nil
-      return nil if parent.nil? || parent.equal?(ca)
+      if ca.is_a?(CAStack) || ca.is_a?(CAMeld)
+        shared = CArray.__send__(:attrs_shared_by, ca.parents)
+        yield(shared) unless shared.empty?
+        return nil
+      end
+      parent = ca.is_a?(CArray) ? ca.__send__(:attribute_parent) : nil
+      return nil if parent.nil?
+      seen ||= {}.compare_by_identity
+      return nil if seen.key?(parent)
+      seen[ca] = true
       ca = parent
     end
-    nil
   end
 
+  def attr_check_not_frozen
+    raise FrozenError.new("can't modify frozen #{self.class}: attributes", receiver: self) if frozen?
+  end
+
+  def attr_check_writable
+    attr_check_not_frozen
+    raise TypeError, "a mask array holds no attributes" if mask_array?
+  end
+
+  # Give `out`, a new array holding self's values in another type or
+  # representation, the attributes self shows; returns `out`.  A view of
+  # self that already shows them is left alone.
+  def carry_attrs (out)
+    return out if out.equal?(self)
+    shown = attrs
+    out.set_attrs(shown) unless shown.empty? || out.attrs == shown
+    out
+  end
+
+  # Remove what `out`, a new array a reduction made, holds of self's
+  # attributes; returns `out`.
+  def drop_carried_attrs (out)
+    out.remove_instance_variable(:@attr) if out.instance_variable_defined?(:@attr)
+    out
+  end
+
+  # The attributes every array in `list` shows with the same value.
+  def self.attrs_shared_by (list)
+    first, *rest = list.map(&:attrs)
+    return {} if first.nil?
+    first.select { |k, v| rest.all? { |h| h.key?(k) && h[k] == v } }
+  end
+  private_class_method :attrs_shared_by
+
   def attr_computing_view? (ca)
-    ca.is_a?(CAMonOp) || ca.is_a?(CABinOp) || ca.is_a?(CATriOp) ||
+    return ca.__op_id__ < CAMonOp::CAST_BASE if ca.is_a?(CAMonOp)
+    ca.is_a?(CABinOp) || ca.is_a?(CATriOp) ||
       ca.is_a?(CAMonCmp) || ca.is_a?(CABinCmp)
   end
 
   def attr_normalize_key (key)
+    CArray.__send__(:attr_normalize_key, key)
+  end
+
+  def attr_validate_value (v)
+    CArray.__send__(:attr_validate_value, v)
+  end
+
+  def attr_coerce_value (v)
+    CArray.__send__(:attr_coerce_value, v)
+  end
+
+  # The key and value rules, as class methods so that CAFrame's attributes
+  # follow the same ones.
+  def self.attr_normalize_key (key)
     case key
     when String then key
     when Symbol then key.to_s
@@ -169,7 +271,7 @@ class CArray
     end
   end
 
-  def attr_validate_value (v, depth = 0)
+  def self.attr_validate_value (v, depth = 0)
     raise ArgumentError, "attribute value nests too deep" if depth > 32
     case v
     when String, Integer, Float, true, false, nil, Symbol
@@ -189,17 +291,19 @@ class CArray
     end
   end
 
-  def attr_coerce_value (v)
+  def self.attr_coerce_value (v)
     case v
-    when Symbol then v.to_s
-    when Array  then v.map { |e| attr_coerce_value(e) }
+    when Symbol then v.to_s.freeze
+    when String then v.frozen? ? v : v.dup.freeze
+    when Array  then v.map { |e| attr_coerce_value(e) }.freeze
     when Hash
       v.each_with_object({}) do |(k, vv), h|
-        h[k.is_a?(Symbol) ? k.to_s : k] = attr_coerce_value(vv)
-      end
+        h[(k.is_a?(Symbol) ? k.to_s : k.dup).freeze] = attr_coerce_value(vv)
+      end.freeze
     else
       v
     end
   end
+  private_class_method :attr_normalize_key, :attr_validate_value, :attr_coerce_value
 
 end

data/lib/carray/autoload_carray.rb

@@ -6,7 +6,7 @@
 #  after autoload_method_extension is installed.  Split by intent:
 #
 #    (1) Top-level feature files under carray/ — constant class + entry
-#        methods (Serializer, TableMethods, iterators, aggregation
+#        methods (Serializer, iterators, aggregation
 #        accumulators, categorical / axis-group).
 #    (2) Single-feature method files under carray/methods/ — each first
 #        call requires its file, whose definitions overwrite the stubs
@@ -20,21 +20,6 @@
 # (1) Top-level feature files
 # ============================================================================
 
-# ---- Inspection (#inspect / #source_code) ----------------------------------
-#
-# CArray::Inspector (:nodoc:) and #inspect / #source_code live in carray/inspect.rb.
-# #inspect is an implicit method (p / pp / irb / error interpolation), so the
-# stub loads the file the first time any CArray is displayed. Nothing in the
-# eager core references it at load time; #desc is private (code-internal) and
-# Inspector is internal, so only the two public methods need stubs.
-
-class CArray
-  inspect_rb = "carray/inspect"
-  autoload_method "inspect",      inspect_rb
-  autoload_method "inspect_full", inspect_rb
-  autoload_method "source_code",  inspect_rb
-end
-
 # ---- Serializer / Marshal / dump / load ------------------------------------
 
 class CArray
@@ -64,21 +49,6 @@ class CARecord
   autoload_method "marshal_dump",        "carray/serialize"
 end
 
-# ---- Arrow tensor IPC (interop) --------------------------------------------
-
-class CArray
-  arrow_tensor_rb = "carray/arrow_tensor"
-  autoload :ArrowTensor, arrow_tensor_rb
-  autoload_method "self.load_arrow_tensor", arrow_tensor_rb
-  autoload_method "save_arrow_tensor",      arrow_tensor_rb
-end
-
-# ---- Table (row-major dispatch helper) -------------------------------------
-
-class CArray
-  autoload :TableMethods, "carray/table"
-end
-
 # ---- Fusion (reading a lazy expression as a plan) --------------------------
 #
 # Nothing in the core asks for a plan -- CArray can always walk the view --
@@ -101,6 +71,7 @@ end
 
 autoload :CASlabIterator,   "carray/slab_iterator"
 autoload :CAWindowIterator, "carray/window_iterator"
+autoload :CAKeyWindowIterator, "carray/key_windows"
 autoload :CABlockIterator,  "carray/block_iterator"
 
 class CArray
@@ -174,6 +145,10 @@ autoload :CAUnion,  "carray/struct"
 autoload :CAFrame,      "carray/frame"
 autoload :GroupedFrame, "carray/frame"
 
+class CArray
+  autoload_method "to_frame", "carray/frame"
+end
+
 class CArray
   struct_rb = "carray/struct"
   autoload_method "self.struct", struct_rb
@@ -231,10 +206,12 @@ class CArray
   autoload_method "intersection",    "carray/methods/is_in"
   autoload_method "difference",      "carray/methods/is_in"
   autoload_method "union",           "carray/methods/is_in"
+  autoload_method "is_between",      "carray/methods/is_between"
   autoload_method "self.align_addr",         "carray/methods/align_addr"
   autoload_method "self.align_nearest_addr", "carray/methods/align_addr"
   autoload_method "value_counts",    "carray/methods/value_counts"
   autoload_method "nunique",         "carray/methods/nunique"
+  autoload_method "lag",             "carray/methods/lag"
   autoload_method "is_mode",         "carray/methods/mode"
   autoload_method "mode",            "carray/methods/mode"
   autoload_method "snap",           "carray/methods/snap"

data/lib/carray/autoload_method_extension.rb

@@ -32,8 +32,18 @@ module AutoloadMethodExtension
   private
 
   def autoload_define (target, name, library, original_spec)
-    stub = nil
-    target.define_method(name) do |*args, **kwargs, &block|
+    library       = Ractor.make_shareable(library.to_s.dup)
+    original_spec = Ractor.make_shareable(original_spec.to_s.dup)
+    # Shareable, so the stub answers in any Ractor.  Only the main Ractor
+    # loads the library: Ractors that require at the same time can deadlock
+    # (Ruby 3.4), so another Ractor is told what to load there instead.
+    target.define_method(name, &Ractor.make_shareable(proc do |*args, **kwargs, &block|
+      unless Ractor.current == Ractor.main
+        raise Ractor::IsolationError,
+              "'#{original_spec}' is loaded on first use from '#{library}'; " \
+              "require it in the main Ractor before other Ractors use it"
+      end
+      stub_location = target.instance_method(name).source_location
       begin
         require library
       rescue LoadError
@@ -45,14 +55,13 @@ module AutoloadMethodExtension
       # forwarding would land straight back here and keep doing so until the
       # stack gave out -- naming neither the method nor the library. Say
       # which, once.
-      if target.instance_method(name) == stub
+      if target.instance_method(name).source_location == stub_location
         raise NoMethodError,
               "'#{original_spec}' is registered for autoload from " \
               "'#{library}', but that library defines no such method"
       end
       send(name, *args, **kwargs, &block)
-    end
-    stub = target.instance_method(name)
+    end))
     # The library replaces the stub with a plain `def`, which `ruby -w`
     # reports as a redefinition.  Replacing is what the stub is for, so mark
     # it as aliased: Ruby does not warn when the old definition has an alias.