carray 2.0.0 → 3.0.0

data/lib/carray/core_extensions.rb

@@ -0,0 +1,240 @@
+# ----------------------------------------------------------------------------
+#
+#  carray/core_extensions.rb
+#
+#  Refinement that restores the carray-flavoured monkey patches on
+#  Float / Integer / Rational / Numeric / TrueClass / FalseClass
+#  for files that opt in with `using CArray::CoreExtensions`.
+#
+#  Provides:
+#    - 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.
+#    - 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)`.
+#    - Symmetric bitwise operators on Integer / TrueClass / FalseClass
+#      so that `5 | bool_ca`, `0xff & flag_ca`, `1 << position_ca` work
+#      without writing CA_INT(5) on the left.
+#
+#  None of these are loaded by default `require "carray"`. Each file
+#  that wants any of them must opt in:
+#
+#      using CArray::CoreExtensions
+#
+#  Refinements are lexically scoped to the file (or class/module body)
+#  where `using` is written. Methods defined in that scope resolve
+#  the refined methods at call time regardless of who is calling.
+#
+#  This file is auto-loaded on first reference to CArray::CoreExtensions.
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+  # Refinement carrying the carray-flavoured additions to Float / Integer /
+  # Rational / Numeric / TrueClass / FalseClass, for files that opt in with
+  # `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.
+  module CoreExtensions
+
+    # @!visibility private
+    MATH_METHODS = %i[
+      sqrt exp log log10
+      sin cos tan sinh cosh tanh
+      asin acos atan asinh acosh atanh
+    ].freeze
+
+    [Float, Integer, Rational].each do |klass|
+      refine(klass) do
+        MATH_METHODS.each do |m|
+          define_method(m) { Math.send(m, self) }
+        end
+        def rad
+          self.to_f * Math::PI / 180.0
+        end
+        def deg
+          self.to_f * 180.0 / Math::PI
+        end
+        def distance(other)
+          (self.to_f - other.to_f).abs
+        end
+        # 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.
+        # Math.expm1 / Math.log1p don't exist in stdlib; hand-roll.
+        def expm1
+          Math.exp(self) - 1.0
+        end
+        def log1p
+          Math.log(1.0 + self)
+        end
+        def rsqrt
+          1.0 / Math.sqrt(self)
+        end
+        def square
+          self * self
+        end
+        def signbit
+          self.negative?
+        end
+      end
+    end
+
+    refine Numeric do
+      def deg_360
+        a = self.to_f
+        fa = a / 360.0
+        if a >= 0
+          (fa - fa.floor) * 360.0
+        else
+          (fa - fa.ceil + 1) * 360.0
+        end
+      end
+
+      def deg_180
+        a = self.to_f
+        fa = (a + 180.0) / 360.0
+        b = if a >= 0
+              (fa - fa.floor) * 360.0 - 180.0
+            else
+              (fa - fa.ceil) * 360.0 - 180.0
+            end
+        b += 360.0 if b <= -180.0
+        b
+      end
+
+      def rad_2pi
+        a = self.to_f
+        two_pi = 2 * Math::PI
+        fa = a / two_pi
+        if a >= 0
+          (fa - fa.floor) * two_pi
+        else
+          (fa - fa.ceil + 1) * two_pi
+        end
+      end
+
+      def rad_pi
+        a = self.to_f
+        two_pi = 2 * Math::PI
+        fa = (a + Math::PI) / two_pi
+        b = if a >= 0
+              (fa - fa.floor) * two_pi - Math::PI
+            else
+              (fa - fa.ceil) * two_pi - Math::PI
+            end
+        b += two_pi if b <= -Math::PI
+        b
+      end
+
+      def eq(other)
+        if CArray === other
+          other.eq(self)
+        else
+          self == other
+        end
+      end
+
+      def ne(other)
+        if CArray === other
+          other.ne(self)
+        else
+          self != other
+        end
+      end
+    end
+
+    refine Integer do
+      def |(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_or(self)
+          else
+            l, r = other.coerce(self)
+            l | r
+          end
+        else
+          super
+        end
+      end
+
+      def &(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_and(self)
+          else
+            l, r = other.coerce(self)
+            l & r
+          end
+        else
+          super
+        end
+      end
+
+      def ^(other)
+        if CArray === other
+          if other.boolean?
+            other.bit_xor(self)
+          else
+            l, r = other.coerce(self)
+            l ^ r
+          end
+        else
+          super
+        end
+      end
+
+      def <<(other)
+        if CArray === other
+          l, r = other.coerce(self)
+          l << r
+        else
+          super
+        end
+      end
+
+      def >>(other)
+        if CArray === other
+          l, r = other.coerce(self)
+          l >> r
+        else
+          super
+        end
+      end
+    end
+
+    [TrueClass, FalseClass].each do |klass|
+      refine(klass) do
+        def |(other)
+          if CArray === other && other.boolean?
+            other.bit_or(self)
+          else
+            super
+          end
+        end
+
+        def &(other)
+          if CArray === other && other.boolean?
+            other.bit_and(self)
+          else
+            super
+          end
+        end
+
+        def ^(other)
+          if CArray === other && other.boolean?
+            other.bit_xor(self)
+          else
+            super
+          end
+        end
+      end
+    end
+
+  end # module CoreExtensions
+end # class CArray

data/lib/carray/data_type_extension.rb

@@ -0,0 +1,233 @@
+#  Numo / NumPy-style factory class methods, gathered here as a
+#  best-effort soft compatibility layer.
+#
+#  Rationale (the apology this file owes the rest of carray):
+#
+#  carray's native idiom for building arrays is the typed
+#  constructor (CArray.float64(3, 3) { 0 }, CA_INT([1, 2, 3]), and
+#  friends).  The methods below -- zeros / ones / eye / identity /
+#  linspace / arange / full / meshgrid -- duplicate that
+#  functionality with NumPy / Numo-flavoured names.  They exist
+#  for one specific reason: when a user is porting a NumPy or Numo
+#  example program over to carray, the first thing they hit is
+#  the array-creation entry point, and "I have to learn a whole
+#  different API just to call zeros" is the worst place to lose
+#  someone.  Having these helpers means a paste from
+#
+#     np.zeros((3, 3))            -> CArray.zeros([3, 3])
+#     np.full((3, 3), 7)          -> CArray.full([3, 3], 7)
+#     np.linspace(0.0, 1.0, 5)    -> CArray.linspace(0.0, 1.0, 5)
+#     Numo::DFloat.zeros(3, 3)    -> CArray::Float64.zeros(3, 3)
+#
+#  works with minimal rewriting.  Both the splat-shape carray-ish
+#  form (CArray.zeros(3, 3)) and the array-shape NumPy-ish form
+#  (CArray.zeros([3, 3])) are accepted by the shape-taking
+#  factories.
+#
+#  The methods land on CArray itself and on every typed class
+#  (CArray::Int32, CArray::Float64, etc.) via the
+#  DataTypeExtension module declared (empty) in
+#  lib/carray/construct.rb.  Required AFTER construct.rb in
+#  lib/carray.rb so the module exists -- the extends in construct
+#  see this file's method additions transparently.
+#
+#  meshgrid was previously in this file; it is now in
+#  lib/carray/methods/meshgrid.rb (autoloaded on first call).
+#
+#  These helpers are not the "main" carray API.  When writing new
+#  carray-flavoured code, prefer the typed constructors.  Use
+#  these when porting external code or when a NumPy / Numo
+#  spelling reads more naturally to the audience.
+
+class CArray
+
+  module DataTypeExtension
+
+    def guess_data_type_from_values (*values)
+      if values.all? {|v| v == true || v == false }
+        CA_BOOLEAN
+      elsif values.all? { |v| v.is_a?(Integer) }
+        CA_INT64
+      elsif values.all? { |v| v.is_a?(Float) }
+        CA_FLOAT64
+      elsif values.all? { |v| v.is_a?(Complex) }
+        CA_CMPLX128
+      else
+        CA_OBJECT
+      end
+    end
+
+    private :guess_data_type_from_values
+
+    # Normalize a shape argument list: accept both
+    #
+    #   foo(3, 4)     # splat (carray-style)
+    #   foo([3, 4])   # Array (NumPy-style: foo((3, 4)))
+    #
+    # so users can paste NumPy / Numo example code with minimal
+    # rewriting.
+    def normalize_shape (args)
+      if args.size == 1 && args.first.is_a?(Array)
+        args.first
+      else
+        args
+      end
+    end
+
+    private :normalize_shape
+
+    # @overload zeros(*shape)
+    #   Returns a new CArray of the given shape filled with zeros.
+    #   Shape accepts both splat Integers and a single Array. When
+    #   called on a typed class the `data_type` is taken from the
+    #   class; otherwise it defaults to `CA_FLOAT64`.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>] shape
+    #     of the result.
+    #   @return [CArray]
+    def zeros (*args)
+      CArray.new(self::DataType || CA_FLOAT64, normalize_shape(args)).zero
+    end
+
+    # @overload ones(*shape)
+    #   Returns a new CArray of the given shape filled with ones.
+    #   Same shape and `data_type` rules as {#zeros}.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>]
+    #   @return [CArray]
+    def ones (*args)
+      CArray.new(self::DataType || CA_FLOAT64, normalize_shape(args)).one
+    end
+
+    # @overload eye(n, m = n, k = 0)
+    #   Returns a 2-D CArray with ones on the `k`-th diagonal and
+    #   zeros elsewhere.
+    #   @param n [Integer] number of rows.
+    #   @param m [Integer] number of columns; defaults to `n`.
+    #   @param k [Integer] diagonal offset (positive above the main
+    #     diagonal, negative below).
+    #   @return [CArray] shape `(n, m)`.
+    def eye (n, m = nil, k = 0)
+      m ||= n
+      mat = CArray.new(self::DataType || CA_FLOAT64, [n, m])
+      if k >= 0
+        count = [n, m - k].min
+        start = k
+      else
+        count = [n + k, m].min
+        start = (-k) * m
+      end
+      if count > 0
+        mat[[start, count, m+1]] = 1
+      end
+      mat
+    end
+
+    # @overload identity(n)
+    #   Returns the `n` by `n` identity matrix.
+    #   @param n [Integer] matrix size.
+    #   @return [CArray] shape `(n, n)`.
+    def identity (n)
+      mat = CArray.new(self::DataType || CA_FLOAT64, [n, n])
+      mat[[nil,n+1]] = 1
+      mat
+    end
+
+    # @overload linspace(x1, x2, n = 100)
+    #   Returns a 1-D CArray of `n` values evenly spaced from `x1`
+    #   to `x2` inclusive, matching NumPy's `linspace`. For an integer
+    #   target `data_type`, values are computed in float64 with the
+    #   linspace step `(x2 - x1) / (n - 1)`, then floored to the target
+    #   type — the rule `np.linspace(x1, x2, n, dtype=int)` uses (round
+    #   toward -infinity, not toward zero). Both endpoints are hit
+    #   exactly for integer output when `x1` and `x2` are
+    #   integer-valued.
+    #
+    #   Called on `CArray` itself (module method) integer inputs promote
+    #   to `CA_FLOAT64` and the result is a float array. Called via an
+    #   integer subclass (`CArray::Int32.linspace(...)`), the result is
+    #   an integer array with floor semantics.
+    #
+    #   @param x1 [Numeric] first value.
+    #   @param x2 [Numeric] last value.
+    #   @param n [Integer] number of samples.
+    #   @return [CArray]
+    def linspace (x1, x2, n = 100)
+      data_type = self::DataType
+      unless data_type
+        guess = guess_data_type_from_values(x1, x2)
+        guess = CA_FLOAT64 if guess == CA_INT64
+        data_type = guess
+      end
+      #  span is float-only ("N evenly-spaced integers" is ambiguous —
+      #  see basics.rb).  Route non-float targets through a float64
+      #  span, then floor + cast; this matches np.linspace(dtype=int)
+      #  bit for bit (floor rounds toward -infinity so negative
+      #  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
+      float_out.floor.to_type(data_type)
+    end
+
+    # @overload arange(stop)
+    #   Returns a 1-D CArray with values `0, 1, ..., stop - 1`.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @return [CArray]
+    # @overload arange(start, stop)
+    #   Returns `start, start + 1, ..., stop - 1`.
+    #   @param start [Numeric] inclusive lower bound.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @return [CArray]
+    # @overload arange(start, stop, step)
+    #   Returns values from `start` to `stop` (exclusive) stepping
+    #   by `step`.
+    #   @param start [Numeric] inclusive lower bound.
+    #   @param stop [Numeric] exclusive upper bound.
+    #   @param step [Numeric] spacing.
+    #   @return [CArray]
+    def arange (*args)
+      case args.size
+      when 3
+        start, stop, step = *args
+      when 2
+        start, stop = *args
+        step = 1
+      when 1
+        start = 0
+        stop, = *args
+        step = 1
+      end
+      data_type = self::DataType
+      data_type ||= guess_data_type_from_values(start, stop, step)
+      CArray.send(:__cast__, data_type, start..stop-step, step)
+    end
+
+    # @overload full(shape, fill_value)
+    #   Returns a new CArray of the given shape filled with
+    #   `fill_value`. `shape` accepts an Integer or an Array of
+    #   Integers. The `data_type` is inferred from `fill_value`
+    #   when the receiver is not a typed class.
+    #   @param shape [Integer, Array<Integer>]
+    #   @param fill_value [Object] value used to fill the array.
+    #   @return [CArray]
+    def full (shape, fill_value)
+      data_type = self::DataType
+      data_type ||= guess_data_type_from_values(fill_value)
+      shape = [shape] unless shape.is_a?(Array)
+      CArray.new(data_type, shape).fill(fill_value)
+    end
+
+    # @overload empty(*shape)
+    #   Returns a new CArray of the given shape whose contents are
+    #   **uninitialised**. The caller must overwrite the array
+    #   before reading from it. `CA_OBJECT` silently falls back to
+    #   a zero-VALUE init required for GC safety.
+    #   @param shape [Array<Integer>, Array<Array<Integer>>]
+    #   @return [CArray]
+    def empty (*args)
+      CArray.__alloc_uninit__(self::DataType || CA_FLOAT64,
+                              normalize_shape(args))
+    end
+
+  end
+
+end
+

data/lib/carray/fixlen_string.rb

@@ -0,0 +1,95 @@
+# ----------------------------------------------------------------------------
+#
+#  CAFixlenString high-level construction surface.
+#
+#  CAFixlenString itself (the string interpretation of CA_FIXLEN storage) lives
+#  in ext/ca_obj_string.c.  This file provides the ergonomic builder that packs
+#  Ruby Strings into a fixed-width CA_FIXLEN entity and wraps it via
+#  CAFixlenString.wrap.
+#
+# ----------------------------------------------------------------------------
+
+class CArray
+
+  # Build a CAFixlenString (fixed-width String array over CA_FIXLEN storage).
+  #
+  #   CArray.fixlen_string(["ab", "cde"], bytes: 4)   # explicit slot width
+  #   CArray.fixlen_string(["ab", "cde"])             # width = max bytesize
+  #   CArray.fixlen_string([a, nil, b], bytes: 8)     # nil → masked element
+  #
+  # The bounded slot width is the storage seam CAFixlenString exposes.
+  # `truncate:` controls what happens when
+  # a value exceeds `bytes` (only reachable when `bytes` is given explicitly;
+  # the auto width can never overflow):
+  #
+  #   :error   (default) raise ArgumentError on overflow — loud data loss
+  #   :silent  let the native fixlen store keep the leading `bytes` bytes
+  #
+  # The overflow policy lives at this construction surface, not at per-cell
+  # `fix[i] = v` (which always truncates silently via the native fixlen store).
+  # A CArray source is normalised through a String Face
+  # ({CArray.string_face_of}): a raw CA_FIXLEN of matching width wraps
+  # 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 truncate [Symbol] `:error` or `:silent`.
+  #   @return [CAFixlenString]
+  # @overload fixlen_string(ca, bytes: nil, truncate: :error)
+  #   @param ca [CArray] a String Face, CA_OBJECT, or raw CA_FIXLEN array.
+  #   @return [CAFixlenString]
+  #   @raise [CArray::DataTypeError] if `ca` is numeric / boolean.
+  # @overload fixlen_string(n, bytes: nil, truncate: :error) { |i| ... }
+  #   @param n [Integer] element count.
+  #   @param bytes [Integer, nil] slot width; defaults to the max bytesize.
+  #   @param truncate [Symbol] `:error` or `:silent`.
+  #   @return [CAFixlenString]
+  def self.fixlen_string (arg, bytes: nil, truncate: :error, &block)
+    if arg.is_a?(CArray)
+      return string_face_of(arg).to_fixlen_string(bytes: bytes, truncate: truncate)
+    end
+    unless [:error, :silent].include?(truncate)
+      raise ArgumentError, "truncate: must be :error or :silent (got #{truncate.inspect})"
+    end
+    if block
+      n = Integer(arg)
+      if block.arity == 0
+        v = block.call
+        values = Array.new(n) { v }
+      else
+        values = Array.new(n) { |i| block.call(i) }
+      end
+    else
+      values = arg.to_a
+    end
+
+    width = bytes || values.compact.map { |s| s.to_s.bytesize }.max || 1
+    width = 1 if width < 1
+
+    if truncate == :error
+      values.each_with_index do |s, i|
+        next if s.nil?
+        b = s.to_s.bytesize
+        if b > width
+          raise ArgumentError,
+                "CArray.fixlen_string: value at #{i} is #{b} bytes, exceeds slot width #{width} " \
+                "(use truncate: :silent to keep the leading bytes)"
+        end
+      end
+    end
+
+    entity = CArray.new(CA_FIXLEN, [values.size], :bytes => width)
+    values.each_with_index do |s, i|
+      entity[i] = s.nil? ? UNDEF : s.to_s
+    end
+    CAFixlenString.wrap(entity)
+  end
+
+end
+
+# Mutable fixed-width String Face: L1 ops + in-place variants.  In-place
+# transforms re-store through the native fixlen path (silent truncate).
+class CAFixlenString
+  include CArray::StringOperationMixin
+  include CArray::StringOperationMixin::Mutable
+end

data/lib/carray/frame/concat.rb

@@ -0,0 +1,132 @@
+# CAFrame row concatenation (memo §5, spine = addressing + gather).
+#
+# Two entry points, mirroring the CArray-level taxonomy:
+#
+#   +CAFrame.meld+         view frame,  strict same-dtype 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
+#
+# Both are class methods (symmetric N-ary; no frame is privileged), like
+# +CArray.meld+ / +CArray.concatenate+, not instance verbs.
+
+class CAFrame
+  # Weld frames along the row axis, view-style.  Each output column is
+  # +CArray.meld+ of that column across the input frames, so the result
+  # is a view frame that shares storage with the inputs (chain composability
+  # 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
+  # {CAFrame.concatenate}.
+  #
+  # Column matching is by name (output order follows the first frame);
+  # every frame must carry the same column-name set.  N-D columns carry
+  # their trailing dimensions along; masks are preserved.
+  #
+  # The index is welded too when every frame has one (their +axis_name+
+  # must agree); if none do, the result has no index; a mix raises.
+  # Column-set mismatch raises — a union-with-UNDEF mode is a possible
+  # future opt-in, kept out here to stay explicit (memo §4.2).
+  #
+  #   CAFrame.meld(jan, feb, mar)      # view over three months
+  #   CAFrame.meld([jan, feb, mar])    # an Array is accepted too
+  def self.meld(*frames)
+    frames = frames.flatten
+    check_concat_inputs(frames, verb: "meld")
+    first = frames.first
+    names = first.variable_names
+    check_column_sets(frames, names, verb: "meld")
+    cols = {}
+    names.each do |name|
+      cols[name] = CArray.meld(frames.map { |f| f[name] }, axis: 0)
+    end
+    new(cols, axis_name: first.axis_name, index: meld_index(frames))
+  end
+
+  # 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
+  # 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
+  # per column, chain composability preserved) use {CAFrame.meld}.
+  #
+  # Column matching, index handling, and column-set / index-mix rules
+  # match {CAFrame.meld}.
+  #
+  #   CAFrame.concatenate(jan, feb, mar)     # eager, independent result
+  #   CAFrame.concatenate([jan, feb, mar])   # an Array is accepted too
+  def self.concatenate(*frames)
+    frames = frames.flatten
+    check_concat_inputs(frames, verb: "concatenate")
+    first = frames.first
+    names = first.variable_names
+    check_column_sets(frames, names, verb: "concatenate")
+    cols = {}
+    names.each do |name|
+      cols[name] = CArray.concatenate(frames.map { |f| f[name] })
+    end
+    new(cols, axis_name: first.axis_name, index: concatenate_index(frames))
+  end
+
+  # ---- shared validators -------------------------------------------------
+
+  def self.check_concat_inputs(frames, verb:)
+    raise ArgumentError, "#{verb} requires at least one frame" if frames.empty?
+    unless frames.all? { |f| f.is_a?(CAFrame) }
+      raise ArgumentError, "#{verb} expects CAFrame arguments"
+    end
+  end
+  private_class_method :check_concat_inputs
+
+  def self.check_column_sets(frames, names, verb:)
+    expected = names.sort
+    frames.each_with_index do |f, i|
+      next if i.zero?
+      if f.variable_names.sort != expected
+        raise ArgumentError,
+              "#{verb}: frame #{i} has columns #{f.variable_names.inspect}, " \
+              "expected the same set as #{names.inspect}"
+      end
+    end
+  end
+  private_class_method :check_column_sets
+
+  # ---- index helpers -----------------------------------------------------
+
+  # Index welded via CArray.meld (view).  Every frame must agree: all
+  # indexed (axis names must match) or none.
+  def self.meld_index(frames)
+    indexes, axis = index_pieces(frames, verb: "meld")
+    return nil unless indexes
+    axis   # unused; kept for symmetry
+    CArray.meld(indexes, axis: 0)
+  end
+  private_class_method :meld_index
+
+  # Index concatenated eagerly via CArray.concatenate.
+  def self.concatenate_index(frames)
+    indexes, _axis = index_pieces(frames, verb: "concatenate")
+    return nil unless indexes
+    CArray.concatenate(indexes)
+  end
+  private_class_method :concatenate_index
+
+  def self.index_pieces(frames, verb:)
+    indexes = frames.map(&:index)
+    return nil if indexes.none?
+    unless indexes.all?
+      raise ArgumentError, "#{verb}: some frames have an index and others do not"
+    end
+    axis_names = frames.map(&:axis_name).uniq
+    unless axis_names.size == 1
+      raise ArgumentError,
+            "#{verb}: indexed frames have different axis names #{axis_names.inspect}"
+    end
+    [indexes, axis_names.first]
+  end
+  private_class_method :index_pieces
+end