carray 3.0.2 → 3.0.4

data/ext/ruby_carray.c

@@ -38,12 +38,14 @@ 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 ();
 void Init_carray_index_classifier ();
 void Init_carray_element ();
 void Init_carray_scatter ();     /* scatter_*! family */
+void Init_carray_segment ();     /* segment lengths / offsets / index */
 void Init_ca_axis_group ();      /* devel/MEMO_AXIS_GROUP.md — axis-group reduction kernel */
 void Init_ca_group_iter ();      /* devel/MEMO_AXIS_GROUP.md — axis-group [] surface */
 void Init_carray_bincount ();    /* bincount dedicated kernel */
@@ -59,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 ();
@@ -89,6 +92,8 @@ void Init_ca_obj_byte_swap ();
 void Init_ca_face ();            /* CAFace abstract base; must precede CATime / CATimedelta / CARecord / CAConstString */
 void Init_ca_source ();          /* CASource abstract base; concrete sources live in C extensions */
 void Init_ca_obj_time ();  /* first numeric Face */
+void Init_carray_time_text ();
+void Init_caframe_csv_reader ();
 void Init_ca_obj_timedelta ();   /* CATime sibling */
 void Init_ca_obj_record ();      /* composite Face for CAStruct backing */
 void Init_ca_obj_const_string ();/* read-only variable-length string Face */
@@ -169,7 +174,7 @@ Init_carray_ext (void)
   /* -- Exception class -- */
 
   rb_eCADataTypeError =
-    rb_define_class_under(rb_cCArray, "DataTypeError", rb_eStandardError);
+    rb_define_class_under(rb_cCArray, "DataTypeError", rb_eTypeError);
 
   /* -- CA module -- namespace for misc utilities related to CArray */
 
@@ -180,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));
@@ -196,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 */
@@ -281,11 +288,13 @@ 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();
   Init_carray_element();
   Init_carray_scatter();
+  Init_carray_segment();
   Init_ca_axis_group();    /* devel/MEMO_AXIS_GROUP.md — axis-group reduction kernel */
   Init_carray_bincount();
   Init_carray_factorize();
@@ -304,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();
 
@@ -343,6 +353,8 @@ Init_carray_ext (void)
                                  (datetime / timedelta / record /
                                  const_string). */
   Init_ca_obj_time();
+  Init_carray_time_text();
+  Init_caframe_csv_reader();
   Init_ca_obj_timedelta();
   Init_ca_obj_record();
   Init_ca_obj_const_string();

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.2"
-#define CA_VERSION_CODE 302
+#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 2
-#define CA_VERSION_DATE "2026/09/24"
+#define CA_VERSION_TEENY 4
+#define CA_VERSION_DATE "2026/10/19"

data/ext/version.rb

@@ -21,8 +21,10 @@ def carray_version
 
   ca_version2 = format("%i.%i.%i", 
                        ca_version_major, ca_version_minor, ca_version_teeny)
-  ca_version_code2 = 
-            100 * ca_version_major + 10*ca_version_minor + ca_version_teeny
+  # Two decimal digits for each of minor and teeny, so 3.0.10 (30010)
+  # comes after 3.0.9 (30009) and before 3.1.0 (30100).
+  ca_version_code2 =
+            10000 * ca_version_major + 100 * ca_version_minor + ca_version_teeny
 
   # Allow pre-release suffix like "3.0.0.dev" / "3.0.0.alpha1" while still
   # validating the numeric MAJOR.MINOR.TEENY prefix.

data/lib/carray/attribute.rb

@@ -4,6 +4,7 @@
 #  Surface:
 #    ca.attr(:unit)             # => getter; nil if absent
 #    ca.set_attr(:unit, "m/s")  # => setter; writes to self's @attr
+#    ca.set_attrs(other.attrs)  # => sets every key of a Hash at once
 #    ca.attrs                   # => frozen shallow clone of the full Hash
 #    ca.has_attr?               # => any attribute present?
 #    ca.has_attr?(:unit)        # => specific key present?
@@ -27,6 +28,38 @@
 #    `attrs` returns the effective merged Hash (deeper writes
 #    override shallower ones), frozen.
 #    Setter side always writes to self's @attr.
+#    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,
+#    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.
+#
+#  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
 
@@ -54,15 +87,64 @@ 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
 
+  # @overload set_attrs(hash)
+  #   Sets every key of `hash` on `self`, as {#set_attr} does one key.
+  #   Keys already on `self` and not in `hash` are kept. Every value is
+  #   validated before any is written, so a rejected value leaves `self`
+  #   unchanged. `b.set_attrs(a.attrs)` gives `b` the attributes `a`
+  #   shows.
+  #   @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
+    entries = hash.map do |key, value|
+      attr_validate_value(value)
+      [attr_normalize_key(key), attr_coerce_value(value)]
+    end
+    unless entries.empty?
+      h = (@attr ||= {})
+      entries.each { |k, v| h[k] = v }
+    end
+    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}]
@@ -102,26 +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
-      parent = ca.respond_to?(:parent) ? ca.parent : nil
-      return nil if parent.nil? || parent.equal?(ca)
+      return nil if attr_computing_view?(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)
+    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
@@ -130,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
@@ -150,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
@@ -47,19 +32,21 @@ class CArray
   autoload_method "marshal_load",        serialize_rb
 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
+# A view, a wrap and a scalar are marshalled through _dump / self._load,
+# which return a new array: with marshal_dump Marshal records the class and
+# loads into an empty instance of it, which the plain array the payload
+# holds cannot become.  A record array keeps marshal_dump, under which it
+# already round-trips with its class.
+[CAView, CAWrap, CScalar].each do |klass|
+  klass.class_eval do
+    undef_method :marshal_dump
+    autoload_method "_dump",               "carray/serialize"
+    autoload_method "self._load",          "carray/serialize"
+  end
 end
 
-# ---- Table (row-major dispatch helper) -------------------------------------
-
-class CArray
-  autoload :TableMethods, "carray/table"
+class CARecord
+  autoload_method "marshal_dump",        "carray/serialize"
 end
 
 # ---- Fusion (reading a lazy expression as a plan) --------------------------
@@ -84,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
@@ -126,10 +114,12 @@ class CArray
   categorical_iterator_rb = "carray/categorical_iterator"
   autoload_method "group_by_category", categorical_iterator_rb
   autoload_method "group_by_run", categorical_iterator_rb
+  autoload_method "segments", "carray/segment_iterator"
 end
 
 autoload :CACategorical,          "carray/categorical"
 autoload :CACategoricalIterator,  "carray/categorical_iterator"
+autoload :CASegmentIterator,      "carray/segment_iterator"
 autoload :AxisGroup,              "carray/axis_group"
 autoload :GroupLabels,            "carray/axis_group"
 
@@ -155,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
@@ -212,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,13 +55,18 @@ 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.
+    tmp = :"__autoload_stub_#{name}__"
+    target.send(:alias_method, tmp, name)
+    target.send(:remove_method, tmp)
   end
 end