carray 3.0.0 → 3.0.1

data/lib/carray/construct.rb

@@ -35,6 +35,7 @@ class CArray
   # CArray whose elements are `boolean`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Boolean.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Boolean
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -47,6 +48,7 @@ class CArray
   # CArray whose elements are `uint8`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::UInt8.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class UInt8
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -59,6 +61,7 @@ class CArray
   # CArray whose elements are `uint16`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::UInt16.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class UInt16
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -71,6 +74,7 @@ class CArray
   # CArray whose elements are `uint32`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::UInt32.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class UInt32
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -83,6 +87,7 @@ class CArray
   # CArray whose elements are `uint64`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::UInt64.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class UInt64
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -95,6 +100,7 @@ class CArray
   # CArray whose elements are `int8`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Int8.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Int8
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -107,6 +113,7 @@ class CArray
   # CArray whose elements are `int16`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Int16.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Int16
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -119,6 +126,7 @@ class CArray
   # CArray whose elements are `int32`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Int32.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Int32
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -131,6 +139,7 @@ class CArray
   # CArray whose elements are `int64`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Int64.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Int64
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -143,6 +152,7 @@ class CArray
   # CArray whose elements are `float32`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Float32.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Float32
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -153,11 +163,13 @@ class CArray
   end
 
   # Numo-compatible alias of {Float32}.
+  # @private
   SFloat = Float32
 
   # CArray whose elements are `float64`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Float64.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Float64
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -168,11 +180,13 @@ class CArray
   end
 
   # Numo-compatible alias of {Float64}.
+  # @private
   DFloat = Float64
 
   # CArray whose elements are `complex64`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Complex64.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Complex64
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -183,11 +197,13 @@ class CArray
   end
 
   # Numo-compatible alias of {Complex64}.
+  # @private
   SComplex = Complex64
 
   # CArray whose elements are `complex128`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Complex128.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Complex128
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -198,11 +214,13 @@ class CArray
   end
 
   # Numo-compatible alias of {Complex128}.
+  # @private
   DComplex = Complex128
 
   # CArray whose elements are `object`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Object.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Object
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -213,11 +231,13 @@ class CArray
   end
 
   # Numo-compatible alias of {Object}.
+  # @private
   RObject = Object
 
   # CArray whose elements are `fixlen`.  Naming the element type as a
   # class lets a constructor be spelled `CArray::Fixlen.new(...)`; see
   # {DataTypeNewConstructor} for what that form adds.
+  # @private
   class Fixlen
     extend DataTypeNewConstructor
     extend DataTypeExtension
@@ -232,6 +252,7 @@ end
 class CArray
   extend DataTypeExtension
   # @!visibility private
+  # @private
   TypeSymbol = nil
   # @!visibility private
   DataType   = nil

data/lib/carray/core_extensions.rb

@@ -10,6 +10,8 @@
 #    - Postfix math on Float/Integer/Rational (sqrt, exp, log, sin, ...)
 #      enabling scalar/CArray polymorphism: the same expression
 #      `(0.0415*(t-218.8)).tanh` works whether t is a Float or a CArray.
+#    - The same postfix math on Complex, so an expression written for a
+#      complex CArray still reads for a single cell taken out of it.
 #    - Angle normalisation on Numeric (deg_360 / deg_180 / rad_2pi / rad_pi).
 #    - Comparison helpers on Numeric (#eq / #ne) for symmetric usage:
 #      `5.eq(ca)` dispatches to `ca.eq(5)`.
@@ -36,9 +38,9 @@ class CArray
   # `using CArray::CoreExtensions`.
   #
   # It provides postfix math on scalars (so `(0.0415*(t-218.8)).tanh` reads
-  # the same whether `t` is a Float or a CArray), angle normalisation, and
-  # comparison helpers.  Being a refinement, it is lexically scoped: nothing
-  # changes for code that does not opt in.
+  # the same whether `t` is a Float, a Complex or a CArray), angle
+  # normalisation, and comparison helpers.  Being a refinement, it is
+  # lexically scoped: nothing changes for code that does not opt in.
   module CoreExtensions
 
     # @!visibility private
@@ -51,7 +53,11 @@ class CArray
     [Float, Integer, Rational].each do |klass|
       refine(klass) do
         MATH_METHODS.each do |m|
-          define_method(m) { Math.send(m, self) }
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{m}
+              Math.#{m}(self)
+            end
+          RUBY
         end
         def rad
           self.to_f * Math::PI / 180.0
@@ -65,7 +71,7 @@ class CArray
         # M.1 (PyTorch alignment) scalar polymorphism additions.
         # `trunc` is left to Ruby's built-in semantics (Float#truncate
         # returns Integer when arg=0) — its CArray counterpart preserves
-        # dtype, so scalar-side use should call .to_f.trunc explicitly.
+        # data type, so scalar-side use should call .to_f.trunc explicitly.
         # Math.expm1 / Math.log1p don't exist in stdlib; hand-roll.
         def expm1
           Math.exp(self) - 1.0
@@ -85,6 +91,57 @@ class CArray
       end
     end
 
+    # The subset of MATH_METHODS that CArray's complex kernels implement,
+    # plus the two elementwise helpers that also accept complex input.
+    #
+    # Absent, because a complex CArray raises CArray::DataTypeError for
+    # them: log10 (C99 has no clog10) and expm1 / log1p (no complex form
+    # in C99 either).  Leaving them undefined on Complex keeps the scalar
+    # side failing wherever the array side fails.  rad / deg / distance /
+    # signbit are absent for the same reason from the other direction:
+    # they go through #to_f, which Complex does not have.
+    #
+    # @!visibility private
+    COMPLEX_MATH_METHODS = %i[
+      sqrt exp log
+      sin cos tan sinh cosh tanh
+      asin acos atan asinh acosh atanh
+      square rsqrt
+    ].freeze
+
+    # Complex is not handled the way Float / Integer / Rational are.
+    # Math.tanh(Complex(1,2)) raises RangeError -- of the stdlib Math
+    # methods only Math.sqrt accepts a Complex -- so the complex forms
+    # need their own implementation.
+    #
+    # Each one runs the value through a one-element cmplx128 CScalar, so
+    # the answer comes from the very kernel the array form would have
+    # used.  That is the point: the branch cuts of csqrt / clog / casin /
+    # cacosh / catanh, and the sign of a zero on either side of them, are
+    # whatever the platform's C99 complex.h says they are, and they are
+    # not the same everywhere.  On this machine, for instance,
+    # catanh(-1+0i) yields -Infinity+(pi/4)i where C99 Annex G describes
+    # -Infinity+0i.  A hand-written Complex implementation would have to
+    # reproduce each such quirk to agree with the array form, and would
+    # stop agreeing on the next platform; delegating agrees by
+    # construction on all of them.  The cost is one CScalar per call
+    # (~0.4 microseconds), which is the right trade for a scalar
+    # convenience whose whole purpose is to read the same as the array.
+    #
+    # `square` is delegated rather than written as `self * self`: Ruby's
+    # Complex multiplication and C's `double _Complex` multiplication part
+    # ways on infinities (Complex(1, Inf) squared gives -Inf+Inf*i in Ruby
+    # and -Inf+NaN*i in C).
+    refine Complex do
+      COMPLEX_MATH_METHODS.each do |m|
+        module_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{m}
+            CA_CMPLX128(self).#{m}[0]
+          end
+        RUBY
+      end
+    end
+
     refine Numeric do
       def deg_360
         a = self.to_f

data/lib/carray/data_type_extension.rb

@@ -194,10 +194,27 @@ class CArray
         start = 0
         stop, = *args
         step = 1
+      else
+        raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1..3)"
       end
+      raise ArgumentError, "step must not be 0" if step == 0
       data_type = self::DataType
       data_type ||= guess_data_type_from_values(start, stop, step)
-      CArray.send(:__cast__, data_type, start..stop-step, step)
+      #  Element count comes from the arguments as given, not from the
+      #  target data type: CArray::Int32.arange(0, 1, 0.25) counts four
+      #  elements from the float step and truncates them on store.
+      #  Integer arguments count exactly (divmod) so that a step dividing
+      #  the span evenly does not gain a spurious element through float
+      #  rounding.
+      span = stop - start
+      if span.is_a?(Integer) && step.is_a?(Integer)
+        q, r = span.divmod(step)
+        n = r.zero? ? q : q + 1
+      else
+        n = (span.to_f / step).ceil
+      end
+      n = 0 if n < 0
+      CArray.new(data_type, [n]).seq(start, step)
     end
 
     # @overload full(shape, fill_value)

data/lib/carray/frame/concat.rb

@@ -2,7 +2,7 @@
 #
 # Two entry points, mirroring the CArray-level taxonomy:
 #
-#   +CAFrame.meld+         view frame,  strict same-dtype per column,
+#   +CAFrame.meld+         view frame,  strict same data type per column,
 #                          each column is a CAMeld view over the inputs
 #   +CAFrame.concatenate+  eager frame, auto-casts per column,
 #                          each column is a materialised entity
@@ -48,10 +48,10 @@ class CAFrame
 
   # Concatenate frames along the row axis, eagerly.  Each output column is
   # +CArray.concatenate+ of that column across the input frames, so per-column
-  # dtypes auto-promote to a common type.  The result is a fresh, independent
+  # data types auto-promote to a common type.  The result is a fresh, independent
   # frame — writes to it do not propagate back to the input frames.
   #
-  # For a view frame that shares storage with the inputs (strict same dtype
+  # For a view frame that shares storage with the inputs (strict same data type
   # per column, chain composability preserved) use {CAFrame.meld}.
   #
   # Column matching, index handling, and column-set / index-mix rules

data/lib/carray/frame/convert.rb

@@ -31,7 +31,7 @@ class CAFrame
   #
   # Only same-shape scalar (1-D) columns qualify. An N-D column has no single
   # matrix form and raises — escape it per column with +df["name"]+. A mixed
-  # dtype set is promoted to a common type (+result_type+, §12-F) through
+  # data type set is promoted to a common type (+result_type+, §12-F) through
   # lazy cast lanes, so the promotion costs no buffer either.
   #
   # +writable: true+ demands a result whose writes reach this frame's own

data/lib/carray/frame/frame.rb

@@ -436,13 +436,6 @@ class CAFrame
     h
   end
 
-  # @return [String]
-  def inspect
-    parts = @columns.map { |k, v| "#{k}:#{v.data_type}#{v.ndim > 1 ? v.shape[1..].inspect : ''}" }
-    idx = @index ? " index=#{@axis_name.inspect}" : ""
-    "#<CAFrame nrow=#{@nrow} vars=[#{parts.join(', ')}]#{idx}>"
-  end
-
   private def rebuild(cols)
     CAFrame.new(cols, axis_name: @axis_name, index: @index)
   end
@@ -511,7 +504,7 @@ class CAFrame
   end
 
   # df[sel] = other : replace the selected contiguous span with other's rows
-  # (any length). Columns are concatenated head + other + tail, so dtypes
+  # (any length). Columns are concatenated head + other + tail, so data types
   # promote and the row count shifts by other.nrow - span.
   private def splice_rows(selector, other)
     lo, hi = contiguous_span(selector)
@@ -536,9 +529,9 @@ 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; dtype mismatch
+        else CArray.meld(pieces, axis: 0)         # CAMeld view; data type mismatch
         end                                        # across pieces raises.
-                                                   # For dtype conversion, cast
+                                                   # For data type conversion, cast
                                                    # the incoming +other+'s
                                                    # column beforehand — silent
                                                    # promotion in a splice would
@@ -566,7 +559,7 @@ class CAFrame
     case pieces.size
     when 0 then @index[CArray.int32(0)]
     when 1 then pieces.first
-    else CArray.meld(pieces, axis: 0)   # index dtype must match across frames
+    else CArray.meld(pieces, axis: 0)   # index data type must match across frames
     end
   end
 

data/lib/carray/frame/io.rb

@@ -62,8 +62,8 @@ class CAFrame
   # is a view into it (§3.6).
   # Write the frame as CSV. CSV is a flat table of scalar cells, so this is the
   # text form of the same all-scalar subset +to_ca+ requires (§11.9): every
-  # column must be 1-D. Unlike +to_ca+ it does not promote to a common dtype --
-  # each column is formatted to text independently, so mixed dtypes (numbers,
+  # column must be 1-D. Unlike +to_ca+ it does not promote to a common data type --
+  # each column is formatted to text independently, so mixed data types (numbers,
   # strings, datetime / categorical Faces) sit side by side. An N-D column has
   # no flat CSV cell and raises; export it per column, or use +to_records+ +
   # JSON for the structured shape (memo §11.9, the N-D escape).
@@ -115,6 +115,163 @@ class CAFrame
     end
   end
 
+  # Render the frame as an aligned text table for reading:
+  #
+  #   puts df.to_table
+  #
+  #   time        temp  station
+  #   ----------  ----  -------
+  #   2026-01-01   1.5  Tokyo
+  #   2026-01-02     _  Osaka
+  #
+  # This is the display counterpart of +to_csv+ and shares none of its
+  # constraints: it is text meant to be looked at, not read back. Numeric
+  # columns are right-aligned, everything else left-aligned; a masked cell
+  # shows as +_+, the same marker CArray's own inspect uses. An N-D column
+  # (which +to_csv+ rejects, having no flat cell) shows each row's slice as
+  # an Array literal.
+  #
+  # Float cells are rounded to +precision+ decimal places for display only
+  # (default 6); +precision: nil+ prints them at full precision, which is
+  # faithful but lets one long value set the column width.
+  #
+  # Long frames are truncated in the middle: +rows+ caps how many rows are
+  # printed (default 20, split evenly around an ellipsis row), and
+  # +rows: nil+ prints every row. +index: false+ drops the index column.
+  def to_table(rows: 20, index: true, precision: 6)
+    head = rows && (rows + 1) / 2
+    render_table(head: head, tail: rows && rows - head,
+                 index: index, precision: precision, footer: true)
+  end
+
+  # +to_s+ is the whole frame, +inspect+ the middle-elided one -- so +puts df+
+  # dumps everything and +p df+ stays a screenful. +inspect+ leads with the
+  # same summary line it always had (nrow, variable data types, index), so the
+  # table under it needs no row-count footer.
+  def to_s
+    to_table(rows: nil)
+  end
+
+  # The summary line (nrow, variable data types, index) followed by the
+  # middle-elided table.
+  # @return [String]
+  def inspect
+    parts = @columns.map { |k, v| "#{k}:#{v.data_type}#{v.ndim > 1 ? v.shape[1..].inspect : ''}" }
+    idx = @index ? " index=#{@axis_name.inspect}" : ""
+    head = "#<CAFrame nrow=#{@nrow} vars=[#{parts.join(', ')}]#{idx}>"
+    return head if @columns.empty?
+    head + "\n" + render_table(head: 8, tail: 2, index: true, precision: 6,
+                               footer: false)
+  end
+
+  private def render_table(head:, tail:, index:, precision:, footer:)
+    names   = []
+    columns = []
+    aligns  = []
+
+    if index && @index
+      names   << @axis_name
+      columns << @index
+      aligns  << (@index.numeric? ? :right : :left)
+    end
+    @columns.each do |name, col|
+      names   << name
+      columns << col
+      aligns  << (col.ndim == 1 && col.numeric? ? :right : :left)
+    end
+    return "" if names.empty?
+
+    positions = table_row_positions(head, tail)
+    body = positions.map do |i|
+      if i.nil?
+        Array.new(columns.size, ":") # vertical ellipsis for the elided middle
+      else
+        columns.map { |col| format_table_cell(col, i, precision) }
+      end
+    end
+
+    widths = names.each_with_index.map do |name, j|
+      [display_width(name), *body.map { |cells| display_width(cells[j]) }].max
+    end
+
+    out = +""
+    out << table_row(names, widths, aligns) << "\n"
+    out << table_row(widths.map { |w| "-" * w }, widths, aligns) << "\n"
+    body.each { |cells| out << table_row(cells, widths, aligns) << "\n" }
+    if footer && positions.size - positions.count(nil) < @nrow
+      out << "(#{plural(@nrow, 'row')}, #{plural(@columns.size, 'variable')})\n"
+    end
+    out
+  end
+
+  # Row indices to print, with nil marking the elided middle. A nil head means
+  # no cap; a frame that already fits in head + tail is listed whole.
+  private def table_row_positions(head, tail)
+    return (0...@nrow).to_a if head.nil? || @nrow <= head + tail
+    (0...head).to_a + [nil] + ((@nrow - tail)...@nrow).to_a
+  end
+
+  private def table_row(cells, widths, aligns)
+    line = cells.each_with_index.map do |text, j|
+      pad = " " * (widths[j] - display_width(text))
+      aligns[j] == :right ? pad + text : text + pad
+    end.join("  ")
+    line.rstrip
+  end
+
+  # Column widths are counted in terminal cells, not characters: a CJK
+  # ideograph, kana, or full-width form occupies two cells, so counting
+  # characters would leave every column holding such a name ragged. The
+  # ranges below are the East Asian Wide / Fullwidth blocks; a combining
+  # mark takes no cell of its own.
+  WIDE_CHAR_RANGES = [
+    0x1100..0x115F, 0x2E80..0x303E, 0x3041..0x33FF, 0x3400..0x4DBF,
+    0x4E00..0x9FFF, 0xA000..0xA4CF, 0xA960..0xA97F, 0xAC00..0xD7A3,
+    0xF900..0xFAFF, 0xFE10..0xFE19, 0xFE30..0xFE6F, 0xFF00..0xFF60,
+    0xFFE0..0xFFE6, 0x1F300..0x1F64F, 0x1F900..0x1F9FF, 0x20000..0x3FFFD,
+  ].freeze
+  private_constant :WIDE_CHAR_RANGES
+
+  COMBINING_RANGES = [0x0300..0x036F, 0x1AB0..0x1AFF, 0x20D0..0x20F0].freeze
+  private_constant :COMBINING_RANGES
+
+  private def display_width(text)
+    text.each_char.sum do |ch|
+      cp = ch.ord
+      if COMBINING_RANGES.any? { |r| r.cover?(cp) }
+        0
+      elsif WIDE_CHAR_RANGES.any? { |r| r.cover?(cp) }
+        2
+      else
+        1
+      end
+    end
+  end
+
+  private def plural(n, noun)
+    "#{n} #{noun}#{n == 1 ? '' : 's'}"
+  end
+
+  private def format_table_cell(col, i, precision)
+    e = elem_at(col, i)
+    if UNDEF.equal?(e) || e.nil?
+      "_"
+    elsif e.is_a?(Float) && precision
+      # Display rounding only: a full-precision float (141.67833333333334)
+      # sets the column width for every other row and makes the table hard
+      # to read. precision: nil prints the value as Ruby renders it.
+      e.round(precision).to_s
+    elsif e.is_a?(CArray)
+      e.to_a.inspect
+    elsif e.is_a?(String)
+      e
+    elsif e.respond_to?(:iso8601)
+      e.iso8601
+    else
+      e.to_s
+    end
+  end
+
   private def format_csv_column(col)
     col.to_a.map do |e|
       if UNDEF.equal?(e) || e.nil?

data/lib/carray/frame/sort.rb

@@ -13,7 +13,7 @@
 #
 # sort_addr is ascending, so a descending key is expressed by replacing it with
 # its dense descending rank (CArray#order(descending: true, method: :dense)):
-# this works for every dtype (unlike negation, which cannot reverse a string and
+# this works for every data type (unlike negation, which cannot reverse a string and
 # silently wraps an unsigned integer), and the *dense* rank keeps equal values
 # on one rank so ties fall through to later keys in a multi-key sort.
 # masked_position (CArray.sort_addr's kwarg) places masked key rows first or

data/lib/carray/frame/verbs.rb

@@ -143,11 +143,28 @@ class CAFrame
   # carry, so it raises rather than silently truncate. Make it the index with
   # +set_index+ afterward.
   #
+  # A +CATime::Grid+ carries the same (unit, epoch) pair as one value, so a
+  # netCDF +units+ attribute goes straight in. It also carries a phase the
+  # keyword form cannot: the keyword +epoch+ is read on the +unit+ grid, so
+  # an epoch off that grid ("days since 1980-01-01 12:00") loses its
+  # time-of-day, while a grid resolves the finer storage that holds it.
+  #
   #   df.to_time("time", unit: :h, epoch: "1990-01-01").set_index("time")
-  def to_time(name, unit: :s, epoch: nil)
+  #   df.to_time("time", CATime::Grid.parse("hours since 1990-01-01"))
+  #   df.to_time("time", CATime::Grid.parse("days since 1980-01-01 12:00"))
+  def to_time(name, grid = nil, unit: :s, epoch: nil)
     key = name.to_s
     col = @columns.fetch(key) { raise KeyError, "no column #{key.inspect}" }
     raw = integer_serial_column(col, key)
+    grid = unit if unit.is_a?(CATime::Grid)
+    if grid.is_a?(CATime::Grid)
+      @columns[key] = grid.at(raw)
+      return self
+    end
+    unless grid.nil?
+      raise ArgumentError,
+            "the positional argument must be a CATime::Grid (got #{grid.class})"
+    end
     if epoch
       raw = raw + CArray.time(epoch, unit: unit).ticks[0]
     end