red_amber 0.2.2 → 0.3.0

data/lib/red_amber/vector_selectable.rb

@@ -4,91 +4,122 @@
 # reference: https://arrow.apache.org/docs/cpp/compute.html
 
 module RedAmber
-  # mix-ins for class Vector
-  # Functions to select some data.
+  # mix-in for class Vector
+  #   Functions to select some data.
   module VectorSelectable
-    def drop_nil
-      datum = find(:drop_null).execute([data])
-      Vector.new(datum.value)
-    end
+    using RefineArray
+    using RefineArrayLike
+
+    # Select elements in the self by indices.
+    #
+    # @param indices [Array<Numeric>, Vector] indices.
+    # @yield [Array<Numeric>, Vector] indices.
+    # @return [Vector] Vector by selected elements.
+    #
+    #   TODO: support for the option `boundscheck: true`
+    def take(*indices, &block)
+      if block
+        unless indices.empty?
+          raise VectorArgumentError, 'Must not specify both arguments and block.'
+        end
 
-    # vector calculation version of selection by indices
-    # TODO: support for option {boundscheck: true}
-    def take(*indices)
-      indices.flatten!
-      return Vector.new([]) if indices.empty?
+        indices = [yield]
+      end
 
-      indices = indices[0] if indices.one? && !indices[0].is_a?(Numeric)
-      indices = Vector.new(indices) unless indices.is_a?(Vector)
+      vector =
+        case indices
+        in [Vector => v] if v.numeric?
+          return Vector.create(take_by_vector(v))
+        in []
+          return Vector.new
+        in [(Arrow::Array | Arrow::ChunkedArray) => aa]
+          Vector.create(aa)
+        else
+          Vector.new(indices.flatten)
+        end
 
-      take_by_vector(indices) # returns sub Vector
+      unless vector.numeric?
+        raise VectorArgumentError, "argument must be a integers: #{indices}"
+      end
+
+      Vector.create(take_by_vector(vector))
     end
 
-    # TODO: support for option {null_selection_behavior: :drop}
+    # Select elements in the self by booleans.
+    #
+    # @param booleans [Array<true, false, nil>, Vector] booleans.
+    # @yield [Array<true, false, nil>, Vector] booleans.
+    # @return [Vector] Vector by selected elements.
+    #
+    #   TODO: support for the option `null_selection_behavior: :drop`
     def filter(*booleans, &block)
       if block
-        raise VectorArgumentError, 'Must not specify both arguments and block.' unless booleans.empty?
+        unless booleans.empty?
+          raise VectorArgumentError, 'Must not specify both arguments and block.'
+        end
 
         booleans = [yield]
       end
 
-      booleans.flatten!
-      return Vector.new([]) if booleans.empty?
-
-      b = booleans[0]
-      boolean_array =
-        case b
-        when Vector
-          raise VectorTypeError, 'Argument is not a boolean.' unless b.boolean?
+      case booleans
+      in [Vector => v]
+        raise VectorTypeError, 'Argument is not a boolean.' unless v.boolean?
 
-          b.data
-        when Arrow::BooleanArray
-          b
+        Vector.create(filter_by_array(v.data))
+      in [Arrow::BooleanArray => ba]
+        Vector.create(filter_by_array(ba))
+      in []
+        Vector.new
+      else
+        booleans.flatten!
+        a = Arrow::Array.new(booleans)
+        if a.boolean?
+          Vector.create(filter_by_array(a))
+        elsif booleans.compact.empty? # [nil, nil] becomes string array
+          Vector.new
         else
-          raise VectorTypeError, 'Argument is not a boolean.' unless booleans?(booleans)
-
-          Arrow::BooleanArray.new(booleans)
+          raise VectorTypeError, "Argument is not a boolean: #{booleans}"
         end
-
-      filter_by_array(boolean_array) # returns sub Vector
+      end
     end
     alias_method :select, :filter
     alias_method :find_all, :filter
 
-    #   @param indices
-    #   @param booleans
+    # Select elements in the self by indices or booleans.
+    #
+    # @param args [Array<Numeric, true, false, nil>, Vector] specifier.
+    # @yield [Array<Numeric, true, false, nil>, Vector] specifier.
+    # @return [scalar, Array] returns scalar or array.
+    #
     def [](*args)
-      args.flatten!
-      return Vector.new([]) if args.empty?
-
-      arg = args[0]
-      case arg
-      when Vector
-        return take_by_vector(arg) if arg.numeric?
-        return filter_by_array(arg.data) if arg.boolean?
-
-        raise VectorTypeError, "Argument must be numeric or boolean: #{arg}"
-      when Arrow::BooleanArray
-        return filter_by_array(arg)
-      when Arrow::Array
-        array = arg
-      when Range
-        array = normalize_element(arg)
-      else
-        unless arg.is_a?(Numeric) || booleans?([arg])
-          raise VectorArgumentError, "Argument must be numeric or boolean: #{args}"
+      array =
+        case args
+        in [Vector => v]
+          return scalar_or_array(take_by_vector(v)) if v.numeric?
+          return scalar_or_array(filter_by_array(v.data)) if v.boolean?
+
+          raise VectorTypeError, "Argument must be numeric or boolean: #{args}"
+        in [Arrow::BooleanArray => ba]
+          return scalar_or_array(filter_by_array(ba))
+        in []
+          return nil
+        in [Arrow::Array => arrow_array]
+          arrow_array
+        in [Range => r]
+          Arrow::Array.new(parse_range(r, size))
+        else
+          Arrow::Array.new(args.flatten)
         end
-      end
-      array ||= Arrow::Array.new(args)
-      return filter_by_array(array) if array.is_a?(Arrow::BooleanArray)
+
+      return scalar_or_array(filter_by_array(array)) if array.boolean?
 
       vector = Vector.new(array)
-      return take_by_vector(vector) if vector.numeric?
+      return scalar_or_array(take_by_vector(vector)) if vector.numeric?
 
       raise VectorArgumentError, "Invalid argument: #{args}"
     end
 
-    #   @param values [Array, Arrow::Array, Vector]
+    # @param values [Array, Arrow::Array, Vector]
     def is_in(*values)
       self_data = chunked? ? data.pack : data
 
@@ -100,7 +131,7 @@ module RedAmber
           Array(values).flatten
         end
 
-      Vector.new(self_data.is_in(array))
+      Vector.create(self_data.is_in(array))
     end
 
     # Arrow's support required
@@ -108,28 +139,44 @@ module RedAmber
       to_a.index(element)
     end
 
+    def drop_nil
+      datum = find(:drop_null).execute([data])
+      Vector.create(datum.value)
+    end
+
     private
 
     # Accepts indices by numeric Vector
     def take_by_vector(indices)
-      raise VectorTypeError, "Indices must be numeric Vector: #{indices}" unless indices.numeric?
-      raise VectorArgumentError, "Index out of range: #{indices.min}" if indices.min <= -size - 1
+      indices = (indices < 0).if_else(indices + size, indices) if (indices < 0).any?
 
-      normalized_indices = (indices < 0).if_else(indices + size, indices) # normalize index from tail
-      raise VectorArgumentError, "Index out of range: #{normalized_indices.max}" if normalized_indices.max >= size
+      min, max = indices.min_max
+      raise VectorArgumentError, "Index out of range: #{min}" if min < 0
+      raise VectorArgumentError, "Index out of range: #{max}" if max >= size
 
-      index_array = Arrow::UInt64ArrayBuilder.build(normalized_indices.data) # round to integer array
+      index_array =
+        if indices.float?
+          Arrow::UInt64ArrayBuilder.build(indices.data)
+        else
+          indices.data
+        end
 
-      datum = find(:take).execute([data, index_array]) # :array_take will fail with ChunkedArray
-      Vector.new(datum.value)
+      # :array_take will fail with ChunkedArray
+      find(:take).execute([data, index_array]).value
     end
 
     # Accepts booleans by Arrow::BooleanArray
     def filter_by_array(boolean_array)
-      raise VectorArgumentError, 'Booleans must be same size as self.' unless boolean_array.length == size
+      unless boolean_array.length == size
+        raise VectorArgumentError, 'Booleans must be same size as self.'
+      end
+
+      find(:array_filter).execute([data, boolean_array]).value
+    end
 
-      datum = find(:array_filter).execute([data, boolean_array])
-      Vector.new(datum.value)
+    def scalar_or_array(arrow_array)
+      a = arrow_array.to_a
+      a.size > 1 ? a : a[0]
     end
   end
 end

data/lib/red_amber/vector_updatable.rb

@@ -4,41 +4,52 @@
 # reference: https://arrow.apache.org/docs/cpp/compute.html
 
 module RedAmber
-  # mix-ins for class Vector
+  # mix-in for class Vector
   # Functions to make up some data (especially missing) for new data.
   module VectorUpdatable
+    # Add properties to Arrow::Array and Arrow::ChunkedArray
+    using RefineArrayLike
+
     # Replace data
-    # @param arg [Array, Vector, Arrow::Array] index specifier or boolean
-    # @param replacer [Array, Vector, Arrow::Array] new data to replace for.
+    # @param specifier [Array, Vector, Arrow::Array] index or booleans.
+    # @param replacer [Scalar, Array, Vector, Arrow::Array] new data to replace for.
     # @return [Vector] Replaced new Vector.
-    #   If arg has no true, return self.
-    def replace(args, replacer)
-      args =
-        case args
-        when Array
-          args
-        when Range
-          normalize_element(args)
-        else
-          Array(args)
-        end
-      replacer = Array(replacer)
-      return self if args.empty? || args[0].nil?
+    #   If specifier has no true, return self.
+    #
+    def replace(specifier, replacer)
+      vector = Vector.new(parse_args(Array(specifier), size))
+      return self if vector.empty? || empty?
 
-      vector = parse_to_vector(args)
-      replacer = nil if replacer.empty?
       booleans =
         if vector.boolean?
-          return self unless vector.any
-
           vector
         elsif vector.numeric?
-          replacer.sort_by! { |x| args[replacer.index(x)] } if replacer # rubocop:disable Style/SafeNavigation
           Vector.new(indices).is_in(vector)
         else
-          raise VectorArgumentError, "Invalid data type #{args}"
+          raise VectorArgumentError, "Invalid data type #{specifier}"
+        end
+      return self if booleans.sum.zero?
+
+      replacer_array =
+        case replacer
+        in []
+          return self
+        in nil | [nil]
+          return replace_to_nil(booleans.data)
+        in Arrow::Array
+        # nop
+        in Vector
+          replacer.data
+        in Array
+          Arrow::Array.new(replacer)
+        else # Broadcast scalar to Array
+          Arrow::Array.new(Array(replacer) * booleans.to_a.count(true))
         end
-      replace_with(booleans, replacer)
+      if booleans.sum != replacer_array.length
+        raise VectorArgumentError, 'Replacements size unmatch'
+      end
+
+      replace_with(booleans.data, replacer_array)
     end
 
     # (related functions)
@@ -51,7 +62,7 @@ module RedAmber
       raise VectorTypeError, 'Reciever must be a boolean' unless boolean?
 
       datum = find(:if_else).execute([data, true_choice, false_choice])
-      Vector.new(datum.value)
+      Vector.create(datum.value)
     end
 
     # same behavior as Ruby's invert
@@ -74,55 +85,168 @@ module RedAmber
       end
     end
 
-    private
+    # Split string Vector and returns Array of columns.
+    #
+    # @param sep [nil, String, Regexp] separater.
+    #   If separator is nil (or no argeument given), the column will be splitted by
+    #   Arrow's split function using any ASCII whitespace.
+    #   Otherwise sep will passed to String#split.
+    # @param limit [Integer] maximum number to limit separation. Passed to String#split.
+    # @return [Array<Vector>] an Array of Vectors.
+    # @note nil will separated as nil's at same row. ex) `nil => [nil, nil]`
+    #
+    def split_to_columns(sep = nil, limit = 0)
+      l = split(sep, limit)
+      l.list_separate
+    end
+
+    # Split string Vector and flatten into rows.
+    #
+    # @param sep [nil, String, Regexp] separater.
+    #   If separator is nil (or no argeument given), the column will be splitted by
+    #   Arrow's split function using any ASCII whitespace.
+    #   Otherwise sep will passed to String#split.
+    # @param limit [Integer] maximum number to limit separation. Passed to String#split.
+    # @return [Vector] a flatten Vector.
+    # @note nil will separated as nil's at same row. ex) `nil => [nil, nil]`
+    #
+    def split_to_rows(sep = nil, limit = 0)
+      l = split(sep, limit)
+      l.list_flatten
+    end
+
+    # return element size Array for list Vector.
+    #
+    # @api private
+    #
+    def list_sizes
+      Vector.create find(:list_value_length).execute([data]).value
+    end
+
+    # Separate list Vector by columns.
+    #
+    # @api private
+    #
+    def list_separate
+      len = list_sizes.data
+      min, max = Arrow::Function.find(:min_max).execute([len]).value.value.map(&:value)
+
+      result = []
+      (0...min).each do |i|
+        result << Vector.create(find(:list_element).execute([data, i]).value)
+      end
+      return result if min == max
+
+      (min...max).each do |i|
+        result << Vector.new(data.map { |e| e&.[](i) })
+      end
+      result
+    end
 
-    # [Ternary]: replace_with(booleans, replacements) => vector
-    # Replace items selected with a boolean mask
-    #
-    # (from Arrow C++ inline doc.)
-    # Given an array and a boolean mask (either scalar or of equal length),
-    # along with replacement values (either scalar or array),
-    # each element of the array for which the corresponding mask element is
-    # true will be replaced by the next value from the replacements,
-    # or with null if the mask is null.
-    # Hence, for replacement arrays, len(replacements) == sum(mask == true).
-
-    def replace_with(booleans, replacer = nil)
-      specifier =
-        if booleans.is_a?(Arrow::BooleanArray)
-          booleans
-        elsif booleans.is_a?(Vector) && booleans.boolean?
-          booleans.data
-        elsif booleans.is_a?(Array) && booleans?(booleans)
-          Arrow::BooleanArray.new(booleans)
+    # Flatten list Vector for rows.
+    #
+    # @api private
+    #
+    def list_flatten
+      Vector.create find(:list_flatten).execute([data]).value
+    end
+
+    # Split string Vector by each element with separator and returns list Array.
+    #
+    # @note if sep is not specified, use Arrow's ascii_split_whitespace.
+    #   It will separate string by ascii whitespaces.
+    # @note if sep specified, sep and limit will passed to String#split.
+    #
+    def split(sep = nil, limit = 0)
+      if empty? || !string?
+        raise VectorTypeError, "self is not a valid string Vector: #{self}"
+      end
+      if self[0].nil? && uniq.to_a == [nil] # Avoid heavy check to be activated always.
+        raise VectorTypeError, 'self contains only nil'
+      end
+
+      list =
+        if sep
+          Arrow::Array.new(to_a.map { |e| e&.split(sep, limit) })
         else
-          raise VectorTypeError, 'Not a valid type'
+          find(:ascii_split_whitespace).execute([data]).value
         end
-      raise VectorArgumentError, 'Booleans size unmatch' if specifier.length != size
-      raise VectorArgumentError, 'Booleans not have any `true`' unless specifier.any?
-
-      r = Array(replacer) # scalar to [scalar]
-      r = [nil] if r.empty?
-
-      replacer =
-        if r.size == 1
-          case replacer
-          when Arrow::Array then replacer
-          when Vector then replacer.data
-          else
-            Arrow::Array.new(r * specifier.to_a.count(true)) # broadcast
-          end
+      Vector.create(list)
+    end
+
+    # Merge String or other string Vector to self.
+    #   Self must be a string Vector.
+    #
+    # @param other [String, Vector]
+    #   merger from right. It will be broadcasted if it is a scalar String.
+    # @param sep [String] separator.
+    # @return [Vector] merged Vector
+    #
+    def merge(other, sep: ' ')
+      if empty? || !string?
+        raise VectorTypeError,
+              "self is not a string Vector: #{self}"
+      end
+      unless sep.is_a?(String)
+        raise VectorArgumentError, "separator is not a String: #{sep}"
+      end
+
+      other_array =
+        case other
+        in String => s
+          [s] * size
+        in (Vector | Arrow::Array | Arrow::ChunkedArray) => x if x.string?
+          x.to_a
         else
-          Arrow::Array.new(r)
+          raise VectorArgumentError,
+                "other is not a String or a string Vector: #{self}"
         end
-      replacer = data.class.new(replacer) if replacer.uniq == [nil]
 
-      raise VectorArgumentError, 'Replacements size unmatch' if Array(specifier).count(true) != replacer.length
+      list = Arrow::Array.new(to_a.zip(other_array))
+      datum = find(:binary_join).execute([list, sep])
+      Vector.create(datum.value)
+    end
+
+    private
+
+    # Replace elements selected with a boolean mask
+    #
+    # @param boolean_mask [Arrow::BooleanArray]
+    #   Boolean mask which indicates the position to be replaced.
+    #   - Position with true will be replaced.
+    #   - Position with nil will be nil.
+    #
+    # @param replacer [Arrow::Array] Values after replaced
+    #   (either scalar or array). If Array is given, original values are replaced by
+    #   each element of the array at the corresponding position of mask element.
+    #   - `replacer.size` must be equal to `mask.count(true)`.
+    #   - Types of self and replacer must be same
+    #
+    # @return [Vector] Replaced vector.
+    #   Type of returned Vector is upcasted if needed.
+    #
+    def replace_with(boolean_mask, replacer)
+      raise VectorArgumentError, 'Booleans size unmatch' if boolean_mask.length != size
+      raise VectorArgumentError, 'Booleans not have any `true`' unless boolean_mask.any?
+
+      values = replacer.class.new(data) # Upcast
 
-      values = replacer.class.new(data)
+      datum = find(:replace_with_mask).execute([values, boolean_mask, replacer])
+      Vector.create(datum.value)
+    end
 
-      datum = find('replace_with_mask').execute([values, specifier, replacer])
-      Vector.new(datum.value)
+    # Replace elements selected with a boolean mask by nil
+    #
+    # @param boolean_mask [Arrow::BooleanArray]
+    #   Boolean mask which indicates the position to be replaced.
+    #   - Position with true will be replaced by nil
+    #   - Position with nil will remain as nil.
+    # @return [Vector] Replaced vector.
+    #
+    def replace_to_nil(boolean_mask)
+      nil_array = data.class.new([nil] * size) # Casted nil Array
+      datum = find(:if_else).execute([boolean_mask, nil_array, data])
+      Vector.create(datum.value)
     end
   end
 end

data/lib/red_amber/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RedAmber
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

data/lib/red_amber.rb

@@ -2,7 +2,10 @@
 
 require 'arrow'
 
+require_relative 'red_amber/refinements'
 require_relative 'red_amber/helper'
+
+require_relative 'red_amber/data_frame_combinable'
 require_relative 'red_amber/data_frame_displayable'
 require_relative 'red_amber/data_frame_indexable'
 require_relative 'red_amber/data_frame_loadsave'

data/red_amber.gemspec

@@ -9,10 +9,11 @@ Gem::Specification.new do |spec|
   spec.email = ['heronshoes877@gmail.com']
 
   spec.summary = 'Simple dataframe library for Ruby'
-  spec.description = 'RedAmber is a simple dataframe library inspired by Rover-df and powered by Red Arrow.'
+  spec.description = 'RedAmber is a simple dataframe library' \
+                     'inspired by Rover-df and powered by Red Arrow.'
   spec.homepage = 'https://github.com/heronshoes/red_amber'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.7'
+  spec.required_ruby_version = '>= 3.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/heronshoes/red_amber'
@@ -30,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'red-arrow', '>= 9.0.0'
+  spec.add_dependency 'red-arrow', '~> 10.0.0'
 
   # Development dependency has gone to the Gemfile (rubygems/bundler#7237)