carray 2.0.0 → 3.0.0

data/lib/carray/construct.rb

@@ -1,229 +1,28 @@
-# ----------------------------------------------------------------------------
-#
-#  carray/constructor.rb
-#
-#  This file is part of Ruby/CArray extension library.
-#
-#  Copyright (C) 2005-2020 Hiroki Motoyoshi
-#
-# ----------------------------------------------------------------------------
-
-class CArray
-  
-  #
-  # CArray.span(data_type, range[, step])
-  # CArray.span(range[, step]) -> data_type guessed by range.first type
-  #
-
-  def self.span (*argv)
-    if argv.first.is_a?(Range)
-      type = nil
-    else
-      type, = *CArray.guess_type_and_bytes(argv.shift, nil)
-    end
-    range, step = argv[0], argv[1]
-    start, stop = range.begin, range.end
-    if step == 0
-      raise "step should not be 0"
-    end
-    if not type
-      case start
-      when Integer
-        type = CA_INT32
-      when Float
-        type = CA_FLOAT64
-      else
-        type = CA_OBJECT
-      end
-    end
-    if type == CA_OBJECT and not step
-      return CA_OBJECT(range.to_a)
-    else
-      step ||= 1
-      if range.exclude_end?
-        n = ((stop - start).abs/step).floor
-      else
-        n = ((stop - start).abs/step).floor + 1
-      end
-      if start <= stop
-        return CArray.new(type, [n]).seq(start, step)
-      else
-        return CArray.new(type, [n]).seq(start, -step.abs)
-      end
-    end
-  end
-
-  def span! (range)
-    first = range.begin.to_r
-    last  = range.end.to_r
-    if integer?
-      if range.exclude_end?
-        step = ((last-1)-first+1)/elements
-      else
-        step = (last-first+1)/elements
-      end      
-    else
-      if range.exclude_end?
-        step = (last-first)/elements
-      else
-        step = (last-first)/(elements-1)
-      end
-    end
-    if integer? && step.denominator != 1
-      self[] = (first + seq * step).floor
-    else
-      seq!(first, step)
-    end
-    return self
-  end
-
-  def span (range)
-    return template.span!(range)
-  end
-
-  #
-  #
-  #
-
-  def scale! (xa, xb)
-    xa = xa.to_f
-    xb = xb.to_f
-    seq!(xa, (xb-xa)/(elements-1))
-  end
-
-  def scale (xa, xb)
-    template.scale!(xa, xb)
-  end
-  
-  # @private 
-  # Create new CArray object from the return value of the block
-  # with data type +type+. The dimensional size and the initialization value
-  # are guessed from the return value of the block.
-  # The block should return one of the following objects.
-  #
-  # * Numeric
-  # * Array
-  # * CArray
-  # * an object that has either method +to_ca+ or +to_a+ or +map+
-  #
-  # When the return value of the block is a Numeric or CScalar object,
-  # CScalar object is returned.
-  #
-  def self.__new__ (type, *args) # :nodoc:
-    case v = args.first
-    when CArray
-      return ( v.data_type == type ) ? v.to_ca : v.to_type(type)
-    when Array
-      return CArray.new(type, CArray.guess_array_shape(v)) { v }
-    when Range
-      return CArray.span(type, *args)
-    when String
-      if type == CA_OBJECT
-        return CScalar.new(CA_OBJECT) { v }
-      elsif type == CA_BOOLEAN
-          v = v.dup
-          v.tr!('^01',"1")
-          v.tr!('01',"\x0\x1")
-          return CArray.boolean(v.length).load_binary(v)
-      else
-        case v
-        when /;/
-          v = v.strip.split(/\s*;\s*/).
-                           map{|s| s.split(/\s+|\s*,\s*/).map{|x| x=='_' ? UNDEF : x} }
-        else
-          v = v.strip.split(/\s+|\s*,\s*/).map{|x| x=='_' ? UNDEF : x}
-        end
-        return CArray.new(type, CArray.guess_array_shape(v)) { v }
-      end
-    when NilClass
-      return CArray.new(type, [0])
-    else
-      if v.respond_to?(:to_ca)
-        ca = v.to_ca
-        return ( ca.data_type == type ) ? ca : ca.to_type(type)
-      else
-        return CScalar.new(type) { v }
-      end
-    end
-  end
-
-  # @private 
-  def self.__new_fixlen__ (bytes, v) # :nodoc:
-    case v
-    when CArray
-      return ( v.data_type == :fixlen ) ? v.to_ca : v.to_type(:fixlen, :bytes=>bytes)
-    when Array
-      unless bytes
-        bytes = v.map{|s| s.length}.max
-      end
-      return CArray.new(:fixlen, CArray.guess_array_shape(v), :bytes=>bytes) { v }
-    when NilClass
-      return CArray.new(type, [0])
-    else
-      if v.respond_to?(:to_ca)
-        ca = v.to_ca
-        return ( ca.data_type == :fixlen ) ? ca : ca.to_type(:fixlen, :bytes=>bytes)
-      else
-        return CScalar.new(:fixlen, :bytes=>bytes) { v }
-      end
-    end
-  end
-
-end
-
 #
 # CA_INT8(data)
 #   :
-# CA_CMPLX256(data)
+# CA_OBJECT(data)
 #
-# Create new CArray object from +data+ with data type
-# which is guessed from the method name. +data+ should be one of the following
-# objects.
+# Cast +data+ to a CArray of the data_type indicated by the method name.
+# This is a polymorphic cast (not a fresh allocator): the source +data+
+# is coerced into a CArray of the target data_type, dispatching on its
+# Ruby class. +data+ should be one of the following objects:
 #
-# * Numeric
-# * Array
-# * CArray
-# * an object that has either method +to_ca+ or +to_a+ or +map+
+# * Numeric         -> CScalar (0-d CArray)
+# * Array           -> shape-guessed CArray, element-wise cast
+# * CArray          -> data_type cast (copy if same data_type, +to_type+ otherwise)
+# * Range           -> arange-like sequence (start..stop with step 1)
+# * String          -> parsed (per-data_type parser)
+# * nil             -> empty CArray
+# * any object responding to +to_ca+ or +to_a+ -> coerced then cast
 #
 # When the block returns a Numeric or CScalar object,
 # the resulted array is a CScalar object.
 
-[
- "CA_BOOLEAN",
- "CA_INT8",
- "CA_UINT8",
- "CA_INT16",
- "CA_UINT16",
- "CA_INT32",
- "CA_UINT32",
- "CA_INT64",
- "CA_UINT64",
- "CA_FLOAT32",
- "CA_FLOAT64",
- "CA_FLOAT128",
- "CA_CMPLX64",
- "CA_CMPLX128",
- "CA_CMPLX256",
- "CA_OBJECT",
- "CA_BYTE",
- "CA_SHORT",
- "CA_INT",
- "CA_FLOAT",
- "CA_DOUBLE",
- "CA_COMPLEX",
- "CA_DCOMPLEX",
- "CA_SIZE",
-].each do |name|
-  eval %{
-    def #{name} (*val)
-      CArray.__new__(#{name}, *val)
-    end
-  }
-end
-
-def CA_FIXLEN (val, options = {})
-  CArray.__new_fixlen__(options[:bytes], val)
-end
+# CA_BOOLEAN / CA_INT8 / ... / CA_OBJECT (+ type-name aliases CA_BYTE /
+# CA_SHORT / CA_INT / CA_FLOAT / CA_DOUBLE / CA_COMPLEX / CA_DCOMPLEX /
+# CA_SIZE) and CA_FIXLEN are defined as global functions in C
+# (ext/carray_cast.c).
 
 class CArray
   
@@ -233,118 +32,198 @@ class CArray
   module DataTypeExtension
   end
 
+  # 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.
   class Boolean
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :boolean
+    # @!visibility private
     DataType   = CA_BOOLEAN
   end
 
+  # 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.
   class UInt8
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :uint8
+    # @!visibility private
     DataType   = CA_UINT8
   end
 
+  # 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.
   class UInt16
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :uint16
+    # @!visibility private
     DataType   = CA_UINT16
   end
 
+  # 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.
   class UInt32
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :uint32
+    # @!visibility private
     DataType   = CA_UINT32
   end
 
+  # 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.
   class UInt64
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :uint64
+    # @!visibility private
     DataType   = CA_UINT64
   end
 
+  # 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.
   class Int8
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :int8
+    # @!visibility private
     DataType   = CA_INT8
   end
 
+  # 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.
   class Int16
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :int16
+    # @!visibility private
     DataType   = CA_INT16
   end
 
+  # 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.
   class Int32
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :int32
+    # @!visibility private
     DataType   = CA_INT32
   end
 
+  # 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.
   class Int64
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :int64
+    # @!visibility private
     DataType   = CA_INT64
   end
 
+  # 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.
   class Float32
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :float32
+    # @!visibility private
     DataType   = CA_FLOAT32
   end
 
+  # Numo-compatible alias of {Float32}.
   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.
   class Float64
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :float64
+    # @!visibility private
     DataType   = CA_FLOAT64
   end
 
+  # Numo-compatible alias of {Float64}.
   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.
   class Complex64
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :complex64
+    # @!visibility private
     DataType   = CA_CMPLX64
   end
 
+  # Numo-compatible alias of {Complex64}.
   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.
   class Complex128
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :complex128
+    # @!visibility private
     DataType   = CA_CMPLX128
   end
 
+  # Numo-compatible alias of {Complex128}.
   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.
   class Object
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :object
+    # @!visibility private
     DataType   = CA_OBJECT
   end
 
+  # Numo-compatible alias of {Object}.
   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.
   class Fixlen
     extend DataTypeNewConstructor
     extend DataTypeExtension
+    # @!visibility private
     TypeSymbol = :fixlen
+    # @!visibility private
     DataType   = CA_FIXLEN
   end
 
@@ -352,133 +231,65 @@ end
 
 class CArray
   extend DataTypeExtension
+  # @!visibility private
   TypeSymbol = nil
+  # @!visibility private
   DataType   = nil
 end
 
 class CArray
   
+  # Constructors added to every typed class ({Float64}, {Int32}, ...) so the
+  # class itself names the element type.  Each forwards to the `CArray`
+  # equivalent with `data_type:` filled in.
   module DataTypeNewConstructor
-    
+
+    # @overload new(*shape)
+    #   Allocates a new CArray of this typed subclass with the given
+    #   shape.
+    #   @param shape [Array<Integer>] shape of the new CArray.
+    #   @return [CArray]
     def new (*shape)
       CArray.new(self::DataType, shape)
     end
-    
-  end
-  
-  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
+    # @overload from_memory_view(obj)
+    #   Returns a fresh CArray interpreted as this typed subclass's
+    #   `data_type`, imported by copy from a MemoryView producer.
+    #   Forwards to
+    #   `CArray.from_memory_view(obj, data_type: self::DataType)`; the
+    #   result is always 1-D (chain `.reshape` for higher rank).
+    #   @param obj [Object] MemoryView producer.
+    #   @return [CArray]
+    def from_memory_view (obj)
+      CArray.from_memory_view(obj, data_type: self::DataType)
     end
-    
-    private :guess_data_type_from_values
 
-    def zeros (*shape)
-      CArray.new(self::DataType || CA_FLOAT64, shape).zero
+    # @overload wrap_memory_view(obj)
+    #   Returns a zero-copy CAWrap over `obj`'s MemoryView interpreted
+    #   as this typed subclass's `data_type`. Forwards to
+    #   `CArray.wrap_memory_view(obj, data_type: self::DataType)`; the
+    #   result is always 1-D (chain `.reshape` for higher rank).
+    #
+    #   Here the receiver names the element type, not the class of the
+    #   result: the call forwards with `CArray` as the receiver, so a
+    #   `CAWrap` comes back. Choosing the class is the other reading of
+    #   the receiver, and it lives on `CArray.wrap_memory_view` itself.
+    #   @param obj [Object] MemoryView producer.
+    #   @return [CAWrap]
+    def wrap_memory_view (obj)
+      CArray.wrap_memory_view(obj, data_type: self::DataType)
     end
 
-    def ones (*shape)
-      CArray.new(self::DataType || CA_FLOAT64 , shape).one
-    end
-    
-    def eye (n, m = nil, k = 0)
-      m ||= n
-      mat = CArray.new(self::DataType || CA_FLOAT64, [n, m])
-      start = ( k == 0 ) ? k : ( k > 0 ? k : m - k - 1 )
-      mat[[start..-1,m+1]] = 1
-      mat
-    end
-    
-    def identity (n)
-      mat = CArray.new(self::DataType || CA_FLOAT64, [n, n])
-      mat[[nil,n+1]] = 1
-      mat      
-    end
-  
-    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
-      CArray.new(data_type, [n]).span(x1..x2)
-    end
-  
-    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.__new__(data_type, start..stop-step, step)
-    end
-  
-    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
-  
   end
   
-end
-
-class CArray
-
-  def self.meshgrid (*axes, indexing: "xy", copy: true, sparse: false, &block)
-    case indexing 
-    when "xy"
-      ### no operation
-    when "ij"
-      axes = axes.map{|axis| axis.seq }
-    else
-      raise ArgumentError, %{indexing option should be one of "xy" and "ij"}
-    end
-    shape = axes.map(&:size).reverse
-    if sparse                           ### => CAUnboundRepeat
-      list = axes.map.with_index do |axis, k|
-        extended_shape = (shape.size-1).downto(0).map { |i| ( i == k ) ? nil : :* }
-        if copy
-          axis[*extended_shape].to_ca
-        else
-          axis[*extended_shape]
-        end
-      end
-    else                                ### => CARepeat
-      naxes = shape.size
-      list = axes.map.with_index do |axis, k|
-        extended_shape = shape.dup
-        extended_shape[naxes - k - 1] = :%
-        if copy
-          axis[*extended_shape].to_ca
-        else
-          axis[*extended_shape]
-        end
-      end
-    end
-    return block.call(*list) if block
-    return list
+  # DataTypeExtension is the carrier module for Numo / NumPy-style
+  # factory methods that are extended onto CArray and every typed
+  # CArray::Int32 / Float64 / ... class below.  Its body is defined
+  # in lib/carray/data_type_extension.rb (required after this file),
+  # keeping the soft-compatibility surface separate from carray's
+  # native constructor API.
+  module DataTypeExtension
   end
-  
+
 end