carray 3.0.1 → 3.0.3

data/lib/carray/iterator.rb

@@ -29,6 +29,16 @@ class CAIterator
   attr_reader :ndim, :shape
   alias dim shape
 
+  # The keywords a member passes on to a core reduction over its own axes.
+  # The member sets `axis:`, so one from the caller is refused; the rest go
+  # to the core, which checks them.
+  def self.reduce_keywords (op, kw) # :nodoc:
+    if kw.key?(:axis)
+      raise ArgumentError, "#{op}: unknown keyword: :axis (the iterator sets the axes)"
+    end
+    kw
+  end
+
   # The required reduction surface, modelled on the two reference members
   # CASlabIterator and CACategoricalIterator (the surface they both provide).
   # Declared abstract so a later member
@@ -36,7 +46,115 @@ class CAIterator
   # rather than reading as "no such method" -- that gap is the member's to close.
   # A member that genuinely cannot provide one overrides it to raise with its
   # own reason.
-  [
+  # The methods below are declared here, so that the family surface is
+  # documented in one place; each member generates its own implementation and
+  # a member for which one is ill-defined overrides it to raise with a reason.
+  # "Piece" is the unit a member iterates over: a slab, a window, a block, a
+  # category, or a group.
+  #
+  # @!method sum
+  #   Returns the sum of each piece.
+  #   @return [CArray] one value per piece, shaped {#shape}.
+  # @!method accumulate
+  #   Returns the sum of each piece kept in the source's own `data_type`,
+  #   wrapping at its width, where {#sum} answers in the type the core
+  #   promotes to (`:float64` for integers).
+  #   @return [CArray] one value per piece.
+  # @!method prod
+  #   Returns the product of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method mean
+  #   Returns the arithmetic mean of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method min
+  #   Returns the smallest value in each piece.
+  #   @return [CArray] one value per piece.
+  # @!method max
+  #   Returns the largest value in each piece.
+  #   @return [CArray] one value per piece.
+  # @!method minmax
+  #   Returns the smallest and largest value of each piece, found in one pass.
+  #   @return [Array<CArray>] the pair `[min, max]`.
+  # @!method variance
+  #   Returns the sample variance (divisor `n - 1`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method variancep
+  #   Returns the population variance (divisor `n`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method stddev
+  #   Returns the sample standard deviation (divisor `n - 1`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method stddevp
+  #   Returns the population standard deviation (divisor `n`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method all
+  #   Returns whether every cell of each piece is true.
+  #   @return [CArray] `:boolean`, one value per piece.
+  # @!method any
+  #   Returns whether any cell of each piece is true.
+  #   @return [CArray] `:boolean`, one value per piece.
+  # @!method min_index
+  #   Returns the position of the smallest value **within** each piece.
+  #   @return [CArray] one index per piece.
+  # @!method max_index
+  #   Returns the position of the largest value within each piece.
+  #   @return [CArray] one index per piece.
+  # @!method min_addr
+  #   Returns the flat address **in the source** of the smallest value of each
+  #   piece -- which source cell holds it, rather than where it sits inside the
+  #   piece. Use it to read the same cell out of another source-shaped array.
+  #   @return [CArray] one flat address per piece.
+  # @!method max_addr
+  #   Returns the flat address in the source of the largest value of each piece.
+  #   @return [CArray] one flat address per piece.
+  # @!method wsum(weights)
+  #   Returns the weighted sum of each piece.
+  #   @param weights [CArray] one weight per source cell, shaped like the source.
+  #   @return [CArray] one value per piece.
+  # @!method wmean(weights)
+  #   Returns the weighted mean of each piece.
+  #   @param weights [CArray] one weight per source cell, shaped like the source.
+  #   @return [CArray] one value per piece.
+  # @!method median
+  #   Returns the median of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method percentile(*pers)
+  #   Returns the requested percentile(s) of each piece.
+  #   @param pers [Array<Numeric>] percentile positions in `0..100`.
+  #   @return [CArray, Array<CArray>] one array per requested position; a
+  #     single position returns that array directly.
+  # @!method quantile
+  #   Returns the five-number summary of each piece,
+  #   `[min, Q1, median, Q3, max]`.
+  #   @return [Array<CArray>] five arrays, one per position.
+  # @!method count(value = nil)
+  #   Returns a count per piece: with no argument the cells that are not
+  #   masked, with `UNDEF` the masked cells, and with any other value the
+  #   cells equal to it.
+  #   @param value [Object] value to match, or `UNDEF`.
+  #   @return [CArray] one count per piece.
+  # @!method count_not_masked
+  #   Returns the number of cells of each piece that are not masked.
+  #   @return [CArray] one count per piece.
+  # @!method count_masked
+  #   Returns the number of masked cells of each piece.
+  #   @return [CArray] one count per piece.
+  # @!method elements
+  #   Returns the total number of cells in each piece, masked or not.
+  #   @return [CArray] one count per piece.
+  # @!method each
+  #   Yields each piece in turn as a CArray.
+  #   @yieldparam piece [CArray]
+  #   @return [Enumerator, self] an Enumerator when no block is given.
+  # @!method reduce(init = nil)
+  #   Folds the pieces with a block, for a reduction the family does not name.
+  #   Without `init` the first piece seeds the accumulator.
+  #   @param init [Object] initial accumulator value.
+  #   @yieldparam acc [Object] running accumulator.
+  #   @yieldparam piece [CArray] next piece.
+  #   @yieldreturn [Object] updated accumulator.
+  #   @return [Object] the final accumulator.
+  REQUIRED_SURFACE = [
     :sum, :accumulate, :prod, :mean, :min, :max,                      # tier 1
     :variance, :stddev, :all, :any,
     :variancep, :stddevp, :minmax,                                    # tier 2
@@ -45,7 +163,9 @@ class CAIterator
     :median, :percentile, :quantile,                                 # tier 3
     :count, :count_not_masked, :count_masked, :elements,             # count family
     :each, :reduce,                                                   # generic iterate
-  ].each do |name|
+  ].freeze
+
+  REQUIRED_SURFACE.each do |name|
     define_method(name) do |*, **, &_blk|
       raise NotImplementedError, "#{self.class} must implement ##{name}"
     end
@@ -66,6 +186,41 @@ class CAIterator
   # sort_addr.  Un-overridden each is simply unavailable, not a contract
   # violation.  min_addr / max_addr stay required: a single winner address is
   # well-defined even for an overlapping window.
+  # @!method map
+  #   Returns a source-shaped array built by applying the block to each piece
+  #   and scattering the result back into that piece's cells.
+  #   @yieldparam piece [CArray]
+  #   @yieldreturn [CArray, Numeric] replacement values for the piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell would receive more than one value.
+  # @!method sort_addr
+  #   Returns a source-shaped array whose cells, read piece by piece, give the
+  #   flat source addresses that put that piece in ascending order.
+  #   @return [CArray] `:int64`, shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cumsum
+  #   Returns a source-shaped array of the running sum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell has no single running value.
+  # @!method cumprod
+  #   Returns a source-shaped array of the running product within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cummax
+  #   Returns a source-shaped array of the running maximum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cummin
+  #   Returns a source-shaped array of the running minimum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cumcount
+  #   Returns a source-shaped array of the running count of cells that are not
+  #   masked within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
   [:map, :sort_addr,
    :cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |name|
     define_method(name) do |*, **, &_blk|

data/lib/carray/lazy.rb

@@ -133,6 +133,10 @@ class CArray
   __abs_eager_um__ = instance_method(:__abs_eager__)
   define_method(:abs) do
     if __lazy_view__?
+      # A boolean has no absolute value to change type for, as eager says.
+      raise CArray::DataTypeError,
+            "data_type-changing monop not implemented for input data_type " \
+            "#{CArray.data_type_code(CA_BOOLEAN)}" if boolean?
       abs_i_node = CAMonOp.__build__(self, CAMonOp::OP_ABS_I)
       if complex?
         # float_dt is a Symbol; convert via data_type_code so the cast
@@ -206,7 +210,11 @@ class CArray
   define_method(:imag) do
     if __lazy_view__?
       imag_i_node = CAMonOp.__build__(self, CAMonOp::OP_IMAG_I)
-      if complex?
+      if boolean?
+        # imag_i reads a boolean as int64; the eager imag stays boolean.
+        CAMonOp.__build__(imag_i_node,
+                          CAMonOp::CAST_BASE + CArray.data_type_code(CA_BOOLEAN))
+      elsif complex?
         float_dt = (data_type == CA_CMPLX64) ? CA_FLOAT32 : CA_FLOAT64
         # float_dt is a Symbol; convert via data_type_code for kernel
         # op_id arithmetic.
@@ -235,8 +243,7 @@ class CArray
   #
   # Both paths keep the operand's float / complex width (f32 → f32,
   # cmplx64 → f32), and both send integers to f64 since pi does not fit
-  # an integer slot.  That agrees with the general lazy-substrate rule
-  # "scalar keeps operand's precision" (see ca_lazy_wrap_scalar header).
+  # an integer slot.
   # ---------------------------------------------------------------------------
 
   # @private
@@ -244,8 +251,11 @@ class CArray
   __arg_eager_um__ = instance_method(:__arg_eager__)
   define_method(:arg) do
     if __lazy_view__?
+      raise CArray::DataTypeError,
+            "data_type-changing monop not implemented for input data_type " \
+            "#{CArray.data_type_code(CA_BOOLEAN)}" if boolean?
       parent = self
-      if integer? || boolean?
+      if integer?
         parent = CAMonOp.__build__(parent,
                                    CAMonOp::CAST_BASE +
                                    CArray.data_type_code(CA_FLOAT64))
@@ -326,6 +336,10 @@ class CArray
     end
   end
 
+  # The shift count of an Integer is brought into the array's type before
+  # either form sees it (see CArray::IntegerShiftCount).
+  prepend IntegerShiftCount
+
   # Binop word aliases (`add` -> `+`, `mul` -> `*`, `bit_and` -> `&`, …) were
   # installed by rb_define_alias at Init time (see MkKernel.alias_binop in
   # ext/carray_kernels_*.c) BEFORE the redefinitions above.  The C alias
@@ -529,23 +543,48 @@ class CArray
     end
   end
 
+  # A lazy receiver takes the scalar the eager coerce makes, and stays
+  # lazy itself: the builder promotes the pair as the eager operator does.
   # @!visibility private
   alias_method :__coerce_eager__, :coerce
   coerce_um = instance_method(:__coerce_eager__)
   define_method(:coerce) do |other|
-    if __lazy_view__?
-      dt_name = data_type_name
-      if CScalar.respond_to?(dt_name)
-        s = CScalar.public_send(dt_name)
-        s[0] = other
-        [s, self]
-      else
-        coerce_um.bind_call(self, other)
-      end
-    else
-      coerce_um.bind_call(self, other)
+    begin
+      scalar, receiver = coerce_um.bind_call(self, other)
+    rescue RangeError => e
+      raise unless other.is_a?(Integer)
+      return [OutOfRangeInteger.new(other, self, e), self]
+    end
+    __lazy_view__? ? [scalar, self] : [scalar, receiver]
+  end
+
+  # An Integer the array's type cannot hold, on the left of an operator.
+  # A comparison is answered from the array's side, where it compares by
+  # value; any other operator refuses the Integer as the array would.
+  class OutOfRangeInteger
+    def initialize (value, array, error)
+      @value, @array, @error = value, array, error
+    end
+
+    def <  (other) = flip(other, :>)
+    def <= (other) = flip(other, :>=)
+    def >  (other) = flip(other, :<)
+    def >= (other) = flip(other, :<=)
+
+    def method_missing (*)
+      raise @error
+    end
+
+    def respond_to_missing? (*) = false
+
+    private
+
+    def flip (other, op)
+      raise @error unless other.equal?(@array)
+      @array.send(op, @value)
     end
   end
+  private_constant :OutOfRangeInteger
 end
 
 # ---------------------------------------------------------------------------
@@ -618,14 +657,6 @@ class CAMonOp
     to_ca.to_a
   end
 
-  # @overload sort(*args, **kwargs)
-  #   Materialises `self` into a copy and returns
-  #   `entity.sort(*args, **kwargs)`.
-  #   @return [CArray]
-  def sort(*args, **kwargs)
-    copy.sort(*args, **kwargs)
-  end
-
   # --- MemoryView export → TypeError + .copy recommendation -----------
 
   # bulk-memory-view / Numo / Apache Arrow consumers go through the MV
@@ -714,13 +745,6 @@ class CABinOp
     to_ca.to_a
   end
 
-  # @overload sort(*args, **kwargs)
-  #   Materialises `self` and sorts the resulting entity.
-  #   @return [CArray]
-  def sort(*args, **kwargs)
-    to_ca.sort(*args, **kwargs)
-  end
-
   # @overload to_memory_view
   #   Not supported for lazy binops.
   #   @raise [TypeError] always.
@@ -901,41 +925,4 @@ class << CArray
     end
     CArray::FuseSource.evaluate(block)
   end
-
-  # @overload jit_for (*extents) { |i, j, ...| ... }
-  #   Runs a block over an index space, so that a cell may reach the ones
-  #   around it -- a recurrence, a stencil.  The block is compiled, and the
-  #   compiler is the carray-jit gem.
-  #   @raise [NotImplementedError] when that gem is not installed.
-  def jit_for (*extents, **options)
-    raise NotImplementedError, no_compiler("jit_for")
-  end
-
-  # @overload jit_each { ... }
-  #   Runs a block over the cells of arrays at once, naming each cell by the
-  #   array it came from, and writing what it computes into arrays of yours:
-  #   `CArray.jit_each { out = a + b * c }`.  The block is compiled, and the
-  #   compiler is the carray-jit gem.
-  #   @raise [NotImplementedError] when that gem is not installed.
-  def jit_each (&block)
-    raise NotImplementedError, no_compiler("jit_each")
-  end
-
-  # @overload jit_map { ... }
-  #   The same block with its value asked for: the last statement is what
-  #   every cell of the result gets, and the result comes back.  The block is
-  #   compiled, and the compiler is the carray-jit gem.
-  #   @raise [NotImplementedError] when that gem is not installed.
-  def jit_map (&block)
-    raise NotImplementedError, no_compiler("jit_map")
-  end
-
-  private
-
-  def no_compiler (name)
-    "CArray.#{name} compiles its block, and the compiler is the carray-jit " \
-    "gem, which is not installed.  An expression over whole arrays can be " \
-    "written as `CArray.fuse { ... }` instead, which needs no compiler; " \
-    "reaching a neighbouring cell, or writing the loop itself, does."
-  end
 end

data/lib/carray/mask_gap_fill.rb

@@ -46,15 +46,10 @@ class CArray
         raise ArgumentError,
               "unmask: pass either a constant fill value or method:, not both"
       end
-      held = __gap_fill__(method, axis)
-      # Copy the filled values in place.  A Face writes through its storage: a
-      # bulk store into its surface would try to cast the storage values to the
-      # surface type (int64 ticks to fixlen, for a time array).
-      if face?
-        parent.value[] = held.parent.value
-      else
-        value[] = held.value
-      end
+      held = __gap_fill__(method, axis, "unmask")
+      # Copy the filled values in place (a Face takes a Face of its own kind
+      # as it is).
+      value[] = held.value
       if held.has_mask?
         self.mask = held.mask              # residual leading/trailing mask
       else
@@ -71,7 +66,7 @@ class CArray
         raise ArgumentError,
               "strip_mask: pass either a constant fill value or method:, not both"
       end
-      return __gap_fill__(method, axis)
+      return __gap_fill__(method, axis, "strip_mask")
     end
     if fill.equal?(MASK_FILL_UNSET)
       raise ArgumentError, "strip_mask: a fill value is required (or method:)"
@@ -85,7 +80,8 @@ class CArray
   # unfillable cells stay masked; a fully filled result carries no mask
   # (hold allocates the output mask only when a leading run goes UNDEF;
   # :linear masks only the exterior via mask_invalid).
-  def __gap_fill__ (method, axis)
+  def __gap_fill__ (method, axis, name)
+    axis = normalize_axis(axis, name) unless axis.nil?
     case method
     when :forward, :ffill
       __hold_axis__(axis, false)
@@ -100,8 +96,8 @@ class CArray
     end
   end
 
-  # Forward (backward = false) or backward (true) hold along `axis`
-  # (axis nil = flatten).  Backward reuses the forward primitive on the
+  # Forward (backward = false) or backward (true) hold along `axis`, already
+  # normalised by __gap_fill__ (axis nil = flatten).  Backward reuses the forward primitive on the
   # reversed view; flatten flattens, holds axis 0, reshapes back.
   def __hold_axis__ (axis, backward)
     if axis.nil?
@@ -111,11 +107,10 @@ class CArray
       held = held.reverse if backward
       held.reshape(*shape)
     else
-      ax = axis < 0 ? axis + ndim : axis
       if backward
-        flip(ax).send(:__hold__, ax).flip(ax)
+        flip(axis).send(:__hold__, axis).flip(axis)
       else
-        send(:__hold__, ax)
+        send(:__hold__, axis)
       end
     end
   end
@@ -123,11 +118,18 @@ class CArray
   # Linear-by-index gap fill: interpolate each masked cell from the two
   # bracketing valid cells, x = cell index along the axis.  Cells outside the
   # valid range (leading/trailing) stay masked.  A Face goes through its own
-  # linear_fetch, which keeps its unit and rounds to its grid; whether that
-  # means anything is the Face's call (an ORDERABLE numeric one answers, the
-  # rest raise from there), so this gate only asks that it be one.
+  # linear_fetch, which keeps its unit and rounds to its grid.  Defining one
+  # is how a Face says it interpolates: without it, the core linear_fetch
+  # reads the Face's storage and fails from inside.
   def __gap_fill_linear__ (axis)
-    unless numeric? || face?
+    if face?
+      unless __interpolable__
+        raise ArgumentError,
+              "unmask/strip_mask(method: :linear): #{self.class} does not " \
+              "interpolate (it defines no linear_fetch of its own); " \
+              "use method: :forward or :backward"
+      end
+    elsif ! numeric?
       raise ArgumentError,
             "unmask/strip_mask(method: :linear): numeric or time data_type " \
             "required (got #{data_type_name})"
@@ -135,44 +137,58 @@ class CArray
     if axis.nil?
       return __linear_fiber__(flatten).reshape(*shape)
     end
-    ax = axis < 0 ? axis + ndim : axis
-    if ax < 0 || ax >= ndim
-      raise ArgumentError, "axis #{axis} out of range for ndim #{ndim}"
-    end
-    # A Face assembles in storage space -- its linear_fetch has already rounded
-    # to the grid, so there is nothing left to hold in float64.  A numeric
-    # array assembles in float64 and casts back once at the end.
-    out  = face? ? template : float64.copy
-    sink = face? ? out.parent : out
+    ax = axis
+    # A fiber comes back in self's own type (a Face's linear_fetch has already
+    # rounded to its grid), so the result assembles in that type and the
+    # present cells are never carried through float64.
+    out = face? ? template : value.copy
     __each_fiber_key__(ax) do |key|
-      fiber = __linear_fiber__(self[*key])
-      sink[*key] = face? ? fiber.parent : fiber
+      out[*key] = __linear_fiber__(self[*key])
     end
-    face? ? out : out.to_type(data_type)
+    out
   end
 
-  # 1-D linear-by-index fill of a single (possibly masked) fiber.  Present
-  # cells reproduce exactly; interior masked cells interpolate; exterior
-  # masked cells become UNDEF (linear_section returns NaN out of range,
-  # mask_invalid marks it).  Returns the same kind as `vec`: a Face fiber
-  # comes back as that Face, on its own unit.
+  # Whether linear interpolation can fill this array: a numeric array, or a
+  # Face that defines a linear_fetch of its own -- which is how a Face says it
+  # interpolates (the core linear_fetch would read its storage).
+  private def __interpolable__
+    face? ? self.class.instance_method(:linear_fetch).owner != CArray : numeric?
+  end
+
+  # 1-D linear-by-index fill of a single (possibly masked) fiber.
   def __linear_fiber__ (vec)
-    n = vec.elements
-    present = vec.is_not_masked
+    vec.send(:__linear_fill_along__, CArray.float64(vec.elements) { |i| i.to_f })
+  end
+
+  # Fill the masked cells of this 1-D array by linear interpolation against
+  # the coordinate `x` (same length, ascending over the present cells).
+  # The one rule both the core (x = cell position) and CAFrame (x = index)
+  # use: present cells come back exactly as they are, in this array's own
+  # type; a masked cell inside the span of the present ones takes the
+  # interpolated value; one outside it stays masked.  Outside is where
+  # linear_section answers NaN -- a property of x, not of the values, so a
+  # NaN or Inf stored in a present cell is left alone.  A Face goes through
+  # its own linear_fetch, which keeps its unit and rounds to its grid.
+  def __linear_fill_along__ (x)
+    present = is_not_masked
     # Fewer than two valid points -> nothing to interpolate between; leave
-    # every masked cell masked (the copy carries vec's mask).
-    if present.count(true) < 2
-      return vec.face? ? vec.copy : vec.float64.copy
-    end
-    pos  = CArray.float64(n) { |i| i.to_f }
-    addr = pos[present].linear_section(pos)   # valid positions -> monotonic grid
-    if vec.face?
+    # every masked cell masked.
+    return copy if present.count(true) < 2
+    addr = x[present].linear_section(x)       # valid positions -> monotonic grid
+    if face?
       # The Face's linear_fetch already masks the exterior (out of range) and
-      # lands on its own grid, so it needs no cast and no mask_invalid.
-      return vec[present].linear_fetch(addr)
+      # lands on its own grid.
+      return self[present].linear_fetch(addr)
     end
-    vval = vec.value.float64[present]         # valid values
-    vval.linear_fetch(addr).to_type(vec.data_type).mask_invalid
+    interp = value.float64[present].linear_fetch(addr)
+    # Built from the values alone, so a fully filled result carries no mask.
+    out      = value.copy
+    masked   = is_masked
+    fill     = masked & addr.is_finite
+    exterior = masked & fill.not
+    out[fill] = interp[fill] if fill.any
+    out[exterior] = UNDEF if exterior.any
+    out
   end
 
   # Yield an index key (Array with `nil` at `axis`, integers elsewhere)

data/lib/carray/math.rb

@@ -3,23 +3,30 @@ module CAMath
   module_function
 
   # Module-function front-ends for binop math methods registered on
-  # CArray by mkkernel. The first argument is auto-wrapped to CArray
-  # via `CArray.wrap_readonly`, so `CAMath.hypot(3, arr)` continues to
-  # work. Integer input is unsupported at the kernel layer -- the
-  # caller must cast to float64 explicitly (e.g.
-  # `arr.as_float64.hypot(...)`).
+  # CArray by mkkernel.  A CArray first argument answers through its own
+  # method, in its own data_type; any other first argument, and an
+  # integer CArray for a function defined only on floats, is taken as
+  # float64, so `CAMath.hypot(3, arr)` works.
 
   # @overload expm1(x)
-  #   Returns `exp(x) - 1` element-wise as float64.
+  #   Returns `exp(x) - 1` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#expm1}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def expm1(x);  CArray.wrap_readonly(x, :float64).expm1;  end
+  def expm1(x)
+    x.is_a?(CArray) ? x.expm1 : CArray.wrap_readonly(x, :float64).expm1
+  end
 
   # @overload log1p(x)
-  #   Returns `log(1 + x)` element-wise as float64.
+  #   Returns `log(1 + x)` element-wise.  A CArray answers in its own
+  #   `data_type` (integer input widens to float64, as {CArray#log1p}
+  #   does); any other value is taken as float64.
   #   @param x [CArray, Numeric] input value.
   #   @return [CArray]
-  def log1p(x);  CArray.wrap_readonly(x, :float64).log1p;  end
+  def log1p(x)
+    x.is_a?(CArray) ? x.log1p : CArray.wrap_readonly(x, :float64).log1p
+  end
 
   # @overload atan2(y, x)
   #   Returns the element-wise arc tangent of `y / x` with quadrant
@@ -27,21 +34,21 @@ module CAMath
   #   @param y [CArray, Numeric] numerator.
   #   @param x [CArray, Numeric] denominator.
   #   @return [CArray]
-  def atan2(y, x);     CArray.wrap_readonly(y, :float64).atan2(x);     end
+  def atan2(y, x); float_operand(y).atan2(x); end
 
   # @overload hypot(x, y)
   #   Returns the element-wise Euclidean distance `sqrt(x^2 + y^2)`.
   #   @param x [CArray, Numeric] first leg.
   #   @param y [CArray, Numeric] second leg.
   #   @return [CArray]
-  def hypot(x, y);     CArray.wrap_readonly(x, :float64).hypot(y);     end
+  def hypot(x, y); float_operand(x).hypot(y); end
 
   # @overload copysign(x, y)
   #   Returns `|x|` with the sign of `y`, element-wise.
   #   @param x [CArray, Numeric] magnitude source.
   #   @param y [CArray, Numeric] sign source.
   #   @return [CArray]
-  def copysign(x, y);  CArray.wrap_readonly(x, :float64).copysign(y);  end
+  def copysign(x, y); float_operand(x).copysign(y); end
 
   # @overload logaddexp(x, y)
   #   Returns `log(exp(x) + exp(y))` computed to avoid overflow,
@@ -49,7 +56,7 @@ module CAMath
   #   @param x [CArray, Numeric] first log-space value.
   #   @param y [CArray, Numeric] second log-space value.
   #   @return [CArray]
-  def logaddexp(x, y); CArray.wrap_readonly(x, :float64).logaddexp(y); end
+  def logaddexp(x, y); float_operand(x).logaddexp(y); end
 
   # @overload nextafter(x, y)
   #   Returns the next representable float from `x` toward `y`,
@@ -57,21 +64,27 @@ module CAMath
   #   @param x [CArray, Numeric] starting value.
   #   @param y [CArray, Numeric] direction target.
   #   @return [CArray]
-  def nextafter(x, y); CArray.wrap_readonly(x, :float64).nextafter(y); end
+  def nextafter(x, y); float_operand(x).nextafter(y); end
 
   # @overload fmod(x, y)
   #   Returns the C-style `fmod(x, y)` element-wise (sign follows `x`).
   #   @param x [CArray, Numeric] dividend.
   #   @param y [CArray, Numeric] divisor.
   #   @return [CArray]
-  def fmod(x, y);      CArray.wrap_readonly(x, :float64).fmod(y);      end
+  def fmod(x, y);      (x.is_a?(CArray) ? x : CArray.wrap_readonly(x, :float64)).fmod(y); end
+
+  # A float or complex CArray as it is; anything else as float64.
+  def float_operand(x)
+    x.is_a?(CArray) && (x.float? || x.complex?) ? x : CArray.wrap_readonly(x, :float64)
+  end
+  private_class_method :float_operand
 
   # @overload min(*argv)
   #   Returns the element-wise minimum of the given CArray and other
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running min.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def min (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -80,7 +93,7 @@ module CAMath
         out.pmin!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end
@@ -90,7 +103,7 @@ module CAMath
   #   arguments. At least one argument must be a CArray.
   #   @param argv [Array<CArray, Numeric>] operands.
   #   @return [CArray] fresh CArray holding the running max.
-  #   @raise [RuntimeError] when no CArray argument is present.
+  #   @raise [ArgumentError] when no CArray argument is present.
   def max (*argv)
     if ary = argv.find{|x| x.is_a?(CArray) }
       out = ary.copy
@@ -99,7 +112,7 @@ module CAMath
         out.pmax!(x)
       end
     else
-      raise "args should contain more than one CArray object"
+      raise ArgumentError, "args should contain more than one CArray object"
     end
     return out
   end