carray 3.0.0 → 3.0.2

data/lib/carray/conditional.rb

@@ -81,7 +81,7 @@ class CArray
     result
   end
 
-  # @overload conditional(cond, then_fn, else_fn, dtype: nil)
+  # @overload conditional(cond, then_fn, else_fn, data_type: nil)
   #   Returns per-cell `then_fn.call(self[cond])` where `cond` is
   #   true and `else_fn.call(self[cond.not])` where it is false.
   #   The two callables are applied only to their own subset of
@@ -91,14 +91,14 @@ class CArray
   #   Scalar returns from a callable (e.g. `->(v) { 0 }`) broadcast
   #   to the subset shape. The result `data_type` is the promotion
   #   of the two subset results via `CArray.result_type`, or
-  #   `dtype` when given. Masked cells in `cond` propagate to
+  #   `data_type` when given. Masked cells in `cond` propagate to
   #   `UNDEF` in the result.
   #
   #   @param cond [CArray] boolean selector; same shape as `self`.
   #   @param then_fn [#call] callable applied to `self[cond]`.
   #   @param else_fn [#call] callable applied to `self[cond.not]`.
-  #   @param dtype [Symbol, Integer, nil] override for the result
-  #     `data_type`.
+  #   @param data_type [Symbol, Integer, nil] override for the result
+  #     data type.
   #   @return [CArray] new array with the same shape as `self`.
   #   @raise [ArgumentError] when `cond` is not a same-shape
   #     boolean CArray.
@@ -108,7 +108,7 @@ class CArray
   #                   ->(v) { v.log },        # domain-safe: only positive cells
   #                   ->(v) { -v })
   #     # => [2.0, 1.0, -0.0, 0.0, 0.6931..., 1.0986...]
-  def conditional (cond, then_fn, else_fn, dtype: nil)
+  def conditional (cond, then_fn, else_fn, data_type: nil)
     unless cond.is_a?(CArray) && cond.boolean? && cond.shape == self.shape
       raise ArgumentError,
             "conditional: cond must be a boolean CArray with same shape as self"
@@ -123,13 +123,13 @@ class CArray
     # to the subset shape; wrap it here so the scatter step below sees a
     # same-length CArray.
     unless y_then.is_a?(CArray)
-      y_then = CArray.new(dtype || CArray.result_type(y_then), x_then.shape).fill(y_then)
+      y_then = CArray.new(data_type || CArray.result_type(y_then), x_then.shape).fill(y_then)
     end
     unless y_else.is_a?(CArray)
-      y_else = CArray.new(dtype || CArray.result_type(y_else), x_else.shape).fill(y_else)
+      y_else = CArray.new(data_type || CArray.result_type(y_else), x_else.shape).fill(y_else)
     end
 
-    dt  = dtype || CArray.result_type(y_then, y_else)
+    dt  = data_type || CArray.result_type(y_then, y_else)
     out = CArray.new(dt, self.shape)
     out[cond]     = y_then
     out[cond.not] = y_else
@@ -141,7 +141,7 @@ class CArray
     out
   end
 
-  # @overload select(condlist, choicelist, default: 0, dtype: nil)
+  # @overload select(condlist, choicelist, default: 0, data_type: nil)
   #   Multi-way ternary select: for each cell, picks the value from
   #   the first `choicelist[k]` whose matching `condlist[k]` is true,
   #   falling back to `default` when no condition holds. When several
@@ -151,15 +151,15 @@ class CArray
   #   Each `choicelist[k]` is either a same-shape CArray or a scalar
   #   broadcast to every cell. The result `data_type` is the promotion
   #   of every choice plus `default` via `CArray.result_type`, or
-  #   `dtype` when given.
+  #   `data_type` when given.
   #
   #   @param condlist [Array<CArray>] boolean selectors.
   #   @param choicelist [Array<CArray, Numeric, Object>] values, one
   #     per condition (same length as `condlist`).
   #   @param default [CArray, Numeric, Object] value written where no
   #     condition holds.
-  #   @param dtype [Symbol, Integer, nil] override for the result
-  #     `data_type`.
+  #   @param data_type [Symbol, Integer, nil] override for the result
+  #     data type.
   #   @return [CArray] new array with the shape of `condlist[0]`.
   #   @raise [ArgumentError] on size mismatch, empty `condlist`, or a
   #     non-boolean / wrong-shape entry in `condlist`.
@@ -169,7 +169,7 @@ class CArray
   #                   [-x,    x * 10],
   #                   default: 999)
   #     # => [5.0, 3.0, -10.0, 0.0, 10.0, 999.0]
-  def self.select (condlist, choicelist, default: 0, dtype: nil)
+  def self.select (condlist, choicelist, default: 0, data_type: nil)
     unless condlist.is_a?(Array) && choicelist.is_a?(Array)
       raise ArgumentError, "select: condlist and choicelist must be Arrays"
     end
@@ -187,7 +187,7 @@ class CArray
     end
     shape = first.shape
 
-    dt = dtype || CArray.result_type(*choicelist, default)
+    dt = data_type || CArray.result_type(*choicelist, default)
     # `default` can be either a same-shape CArray (per-cell fallback) or a
     # scalar (broadcast to every cell).
     default_full = default.is_a?(CArray) && !default.scalar?

data/lib/carray/const_string.rb

@@ -5,12 +5,15 @@
 #  CAConstString high-level construction + conversion surface.
 #
 #  CAConstString itself (the Face + tail buffer + fetch decode + numeric gate) lives
-#  in ext/ca_obj_const_string.c.  This file provides the ergonomic builders that pack
-#  Ruby Strings into the internal length-prefix buffer + int64 offset entity
-#  and wrap them via the CAConstString.wrap C primitive.
+#  in ext/ca_obj_const_string.c.  This file provides the ergonomic builders that
+#  pack Ruby Strings into the shared buffer + (start,end) pair entity, via the
+#  CAConstString.__build__ C primitive.
 #
-#  Internal buffer format: concatenation of `[int32 length][bytes...]` records
-#  (self-delimiting → one offset per element, permutation-safe view).
+#  Internal buffer format: a pure concatenation of the element bytes, with no
+#  per-record length prefix (= the Arrow values buffer).  Each element carries
+#  its own `(start, end)` byte range in the storage, so it is self-describing
+#  and a gather / sort / select view over the pairs decodes correctly with no
+#  buffer copy.
 #
 # ----------------------------------------------------------------------------
 
@@ -89,21 +92,118 @@ class CAConstString
   # override the L1 generics where present.
   include CArray::StringOperationMixin
 
-  # @overload sort
-  #   Returns a byte-order sorted view built by gathering the
-  #   offsets with `sort_index`. Neither bytes nor offsets are
-  #   copied.
+  # ---- ordering family ---------------------------------------------------
+  #
+  # A storage cell is a `(start, end)` byte range into the shared buffer, so
+  # storage order is the order the strings were packed in, not the order they
+  # compare in.  Without these overrides the family sorted the offsets: the
+  # answers came back well-formed and wrong -- `%w[pear apple].sort_addr` gave
+  # the identity, and `partition_copy` gave NUL bytes.
+  #
+  # Every member therefore reads the bytes.  The flat forms do it natively
+  # (a byte-memcmp scan over the packed buffer, an order of magnitude faster
+  # than decoding a Ruby String per cell), the per-axis forms through
+  # {#to_string}, where a cell is the string and CArray's own kernels apply.
+  # Arguments are forwarded verbatim, so `kind:` / `masked_position:` /
+  # `keep_axis:` mean here what they mean on CArray.
+  #
+  # Anything whose cells are strings comes back a CAConstString, gathered
+  # over the same buffer where it can be (sort / sort_copy) and rebuilt where
+  # it cannot.  Indices, addresses and counts need no conversion.
+
+  # @overload sort(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns a sorted {CAConstString} view, gathered over the same buffer
+  #   and offsets.  With no `axis:` the array is flattened first, as
+  #   `CArray#sort` does.
   #   @return [CAConstString]
-  def sort
-    self[sort_index]
+  def sort (*args, **kw)
+    addr = sort_addr(*args, **kw)
+    kw[:axis].nil? ? self[addr.flatten] : self[addr]
   end
 
-  # @overload sort_copy
-  #   Returns an owned sorted {CAConstString}; the materialised
-  #   counterpart to {#sort}.
+  # @overload sort_copy(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns an owned sorted {CAConstString}; the materialised counterpart
+  #   to {#sort}.
   #   @return [CAConstString]
-  def sort_copy
-    self[sort_index].copy
+  def sort_copy (*args, **kw)
+    sort(*args, **kw).copy
+  end
+
+  # @overload sort_addr(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns the view-flat addresses that index a sort by string order.
+  #   @return [CArray] `:int64` addresses.
+  def sort_addr (*args, **kw)
+    # The native scan has no notion of an incomparable sentinel, so a masked
+    # column goes the same way a per-axis one does.
+    return __sort_addr_bytes__ if args.empty? && kw.empty? && ! has_mask?
+    to_string.sort_addr(*args, **kw)
+  end
+
+  # @overload sort_index(axis: nil, kind: :quick, masked_position: :last)
+  #   Returns the per-fiber indices that index a sort by string order.
+  #   @return [CArray] `:int64` indices.
+  def sort_index (*args, **kw)
+    to_string.sort_index(*args, **kw)
+  end
+
+  # @overload rank_index(axis: nil)
+  #   @return [CArray] each cell's rank in string order.
+  def rank_index (*args, **kw)
+    to_string.rank_index(*args, **kw)
+  end
+
+  # @overload order(*args)
+  #   @return [CArray] the ordering of the cells by string order.
+  def order (*args, **kw)
+    to_string.order(*args, **kw)
+  end
+
+  # @overload min(axis: nil, keep_axis: false)
+  #   Returns the byte-smallest string, skipping masked cells; UNDEF when
+  #   every cell is masked or the array is empty.
+  #   @return [String, CAConstString]
+  def min (*args, **kw)
+    return __min_bytes__ || UNDEF if args.empty? && kw.empty?
+    const_string_lift(to_string.min(*args, **kw))
+  end
+
+  # @overload max(axis: nil, keep_axis: false)
+  #   Byte-largest counterpart of {#min}.
+  #   @return [String, CAConstString]
+  def max (*args, **kw)
+    return __max_bytes__ || UNDEF if args.empty? && kw.empty?
+    const_string_lift(to_string.max(*args, **kw))
+  end
+
+  # @overload minmax(axis: nil, keep_axis: false)
+  #   @return [Array] `[min, max]`.
+  def minmax (*args, **kw)
+    return [min, max] if args.empty? && kw.empty?
+    to_string.minmax(*args, **kw).map { |r| const_string_lift(r) }
+  end
+
+  # @overload min_index(axis: nil)
+  #   @return [Integer, CArray] where the byte-smallest string sits.
+  def min_index (*args, **kw)
+    to_string.min_index(*args, **kw)
+  end
+
+  # @overload max_index(axis: nil)
+  #   @return [Integer, CArray] where the byte-largest string sits.
+  def max_index (*args, **kw)
+    to_string.max_index(*args, **kw)
+  end
+
+  # @overload partition_copy(kth, axis: nil)
+  #   @return [CAConstString] partitioned about the `kth` string in order.
+  def partition_copy (*args, **kw)
+    const_string_lift(to_string.partition_copy(*args, **kw))
+  end
+
+  # @overload partition_index(kth, axis: nil)
+  #   @return [CArray] the indices that partition about the `kth` string.
+  def partition_index (*args, **kw)
+    to_string.partition_index(*args, **kw)
   end
 
   # CAConstString is the one Face with three separate entities -- storage
@@ -144,14 +244,14 @@ class CAConstString
   # @overload unique(sort: false)
   #   @return [CAConstString] the distinct strings.
   def unique (sort: false)
-    to_string.unique(sort: sort).to_const_string
+    const_string_lift(to_string.unique(sort: sort))
   end
 
   # @overload value_counts(sort: false)
   #   @return [Array(CAConstString, CArray)] `[values, counts]`.
   def value_counts (sort: false)
     values, counts = to_string.value_counts(sort: sort)
-    [values.to_const_string, counts]
+    [const_string_lift(values), counts]
   end
 
   # @overload nunique(axis: nil, keep_axis: false)
@@ -164,11 +264,7 @@ class CAConstString
   #   @return [CAConstString, Array] the most frequent string(s).
   def mode (axis: nil)
     r = to_string.mode(axis: axis)
-    case r
-    when CArray then r.to_const_string
-    when Array  then r.map { |c| c.is_a?(CArray) ? c.to_const_string : c }
-    else r
-    end
+    r.is_a?(Array) ? r.map { |c| const_string_lift(c) } : const_string_lift(r)
   end
 
   # @overload is_mode(axis: nil)
@@ -180,7 +276,7 @@ class CAConstString
   # @overload mask_duplicates(axis: nil)
   #   @return [CAConstString] a copy with every repeat occurrence masked.
   def mask_duplicates (axis: nil)
-    to_string.mask_duplicates(axis: axis).to_const_string
+    const_string_lift(to_string.mask_duplicates(axis: axis))
   end
 
   # @overload is_in(values)
@@ -192,19 +288,19 @@ class CAConstString
   # @overload intersection(other, sort: false)
   #   @return [CAConstString] the distinct strings present in both.
   def intersection (other, sort: false)
-    to_string.intersection(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.intersection(string_operand(other), sort: sort))
   end
 
   # @overload difference(other, sort: false)
   #   @return [CAConstString] the distinct strings only `self` has.
   def difference (other, sort: false)
-    to_string.difference(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.difference(string_operand(other), sort: sort))
   end
 
   # @overload union(other, sort: false)
   #   @return [CAConstString] the distinct strings of either side.
   def union (other, sort: false)
-    to_string.union(string_operand(other), sort: sort).to_const_string
+    const_string_lift(to_string.union(string_operand(other), sort: sort))
   end
 
   # @overload locate_addr(ref)
@@ -225,4 +321,12 @@ class CAConstString
     other.is_a?(CAConstString) ? other.to_string : other
   end
 
+  # Pack a string-bearing result back into a column of this one's encoding.
+  # The encoding has to be carried: the builder checks each element against
+  # the column's, so a Shift_JIS column rebuilt as the UTF-8 default raised
+  # rather than coming back.
+  private def const_string_lift (x)
+    x.is_a?(CArray) ? CArray.const_string(x, encoding: encoding) : x
+  end
+
 end

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,9 +252,50 @@ end
 class CArray
   extend DataTypeExtension
   # @!visibility private
+  # @private
   TypeSymbol = nil
   # @!visibility private
   DataType   = nil
+
+  # @overload empty(data_type, dim, bytes: nil)
+  #   Returns a new CArray of `data_type` with the shape `dim`, whose
+  #   contents are **undefined**. This is {CArray.new} without the fill:
+  #   the arguments are read the same way, and the cost of zeroing the
+  #   buffer is not paid. Use it when every cell is written before it is
+  #   read; otherwise use `CArray.new`, which zero-fills.
+  #
+  #   `CA_OBJECT` is the exception: its cells are zero-initialised
+  #   anyway, because the garbage collector walks them.
+  #
+  #   @param data_type [Symbol, String, Integer] element type.
+  #   @param dim [Array<Integer>] shape of the new CArray.
+  #   @param bytes [Integer, nil] element width, for `:fixlen` only.
+  #   @return [CArray]
+  #   @raise [ArgumentError] if a block is given -- filling an array is
+  #     what `CArray.new` is for.
+  # @overload empty(*shape)
+  #   (Numo / NumPy compatibility) Returns an uninitialised CArray of
+  #   the given shape. The element type comes from the receiver, so
+  #   `CArray` itself gives `CA_FLOAT64`; see
+  #   {DataTypeExtension#empty}.
+  #   @param shape [Array<Integer>, Array<Array<Integer>>] shape.
+  #   @return [CArray]
+  def self.empty (*args, **options, &block)
+    if block
+      raise ArgumentError,
+            "CArray.empty does not take a block " \
+            "(its contents are left undefined); use CArray.new to fill."
+    end
+    if args.size == 2 and args[1].is_a?(Array)
+      return __empty__(*args, **options)
+    end
+    unless options.empty?
+      raise ArgumentError,
+            "CArray.empty(*shape) takes no options; bytes: belongs to " \
+            "CArray.empty(data_type, dim)"
+    end
+    super(*args)
+  end
 end
 
 class CArray

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)
@@ -220,6 +237,9 @@ class CArray
     #   **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.
+    #
+    #   carray's own spelling is `CArray.empty(data_type, dim)`, which
+    #   names the element type instead of taking it from the receiver.
     #   @param shape [Array<Integer>, Array<Array<Integer>>]
     #   @return [CArray]
     def empty (*args)