vector_number 0.4.2 → 0.5.0

data/lib/vector_number/enumerating.rb

@@ -1,128 +1,127 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Methods for enumerating values of the number.
-  #
+  # @group Hash-like operations
+
   # +Enumerable+ is included so its methods can be used.
   # @example using Enumerable methods
   #   VectorNumber["a", "b", 6].include?(["a", 1]) # => true
   #   VectorNumber["a", "b", 6].select { |u, c| u.is_a?(String) } # => [["a", 1], ["b", 1]]
-  module Enumerating
-    # @since 0.1.0
-    include ::Enumerable
+  #
+  # @since 0.1.0
+  include ::Enumerable
 
-    # Iterate through every pair of unit and coefficient.
-    # Returns +Enumerator+ (with set +size+) if no block is given.
-    #
-    # @example
-    #   v = VectorNumber["a", "b", 6]
-    #   units = []
-    #   v.each { |u, c| units << u unless u.is_a?(Numeric) } # => (1⋅'a' + 1⋅'b' + 6)
-    #   units # => ["a", "b"]
-    # @example Enumerator
-    #   v.each.size # => 3
-    #   (v.each + [["d", 0]]).map(&:first) # => ["a", "b", 1, "d"]
-    #   v.each_pair.peek # => ["a", 1]
-    #
-    # @overload each
-    #   @yieldparam unit [Object]
-    #   @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
-    #   @yieldreturn [void]
-    #   @return [VectorNumber] self
-    # @overload each
-    #   @return [Enumerator]
-    #
-    # @see Enumerable
-    # @see Enumerator
-    #
-    # @since 0.1.0
-    def each(&)
-      return to_enum { size } unless block_given?
+  # Iterate through every pair of unit and coefficient.
+  # Returns +Enumerator+ (with set +size+) if no block is given.
+  #
+  # @example
+  #   v = VectorNumber["a", "b", 6]
+  #   units = []
+  #   v.each { |u, c| units << u unless u.is_a?(Numeric) } # => (1⋅'a' + 1⋅'b' + 6)
+  #   units # => ["a", "b"]
+  # @example Enumerator
+  #   v.each.size # => 3
+  #   (v.each + [["d", 0]]).map(&:first) # => ["a", "b", 1, "d"]
+  #   v.each_pair.peek # => ["a", 1]
+  #
+  # @overload each
+  #   @yieldparam unit [Object]
+  #   @yieldparam coefficient [Numeric]
+  #   @yieldreturn [void]
+  #   @return [VectorNumber] self
+  # @overload each
+  #   @return [Enumerator]
+  #
+  # @see Enumerable
+  # @see Enumerator
+  #
+  # @since 0.1.0
+  def each(&block)
+    return to_enum { size } unless block_given?
 
-      @data.each(&)
-      self
-    end
+    @data.each(&block)
+    self
+  end
 
-    # @since 0.1.0
-    alias each_pair each
+  # @since 0.1.0
+  alias each_pair each
 
-    # Get a list of units with non-zero coefficients.
-    #
-    # @example
-    #   VectorNumber["a", "b", 6].units # => ["a", "b", 1]
-    #   VectorNumber.new.keys # => []
-    #
-    # @return [Array<Object>]
-    #
-    # @since 0.1.0
-    def units = @data.keys
+  # Get a list of units with non-zero coefficients.
+  #
+  # @example
+  #   VectorNumber["a", "b", 6].units # => ["a", "b", 1]
+  #   VectorNumber.new.keys # => []
+  #
+  # @return [Array<Object>]
+  #
+  # @since 0.1.0
+  def units = @data.keys
 
-    # @since 0.1.0
-    alias keys units
+  # @since 0.1.0
+  alias keys units
 
-    # Get a list of non-zero coefficients.
-    #
-    # @example
-    #   VectorNumber["a", "b", 6].coefficients # => [1, 1, 6]
-    #   VectorNumber.new.values # => []
-    #
-    # @return [Array<Integer, Float, Rational, BigDecimal>]
-    #
-    # @since 0.1.0
-    def coefficients = @data.values
+  # Get a list of non-zero coefficients.
+  #
+  # @example
+  #   VectorNumber["a", "b", 6].coefficients # => [1, 1, 6]
+  #   VectorNumber.new.values # => []
+  #
+  # @return [Array<Numeric>]
+  #
+  # @since 0.1.0
+  def coefficients = @data.values
 
-    # @since 0.1.0
-    alias values coefficients
+  # @since 0.1.0
+  alias values coefficients
 
-    # Get mutable hash with vector's data.
-    #
-    # Returned hash has a default value of 0.
-    #
-    # @example
-    #   VectorNumber["a", "b", 6].to_h # => {"a"=>1, "b"=>1, 1=>6}
-    #   VectorNumber["a", "b", 6].to_h["c"] # => 0
-    #
-    # @return [Hash{Object => Integer, Float, Rational, BigDecimal}]
-    #
-    # @since 0.1.0
-    def to_h(&)
-      # TODO: Remove block argument.
-      if block_given?
-        @data.to_h(&)
-      else
-        @data.dup
-      end
+  # Get mutable hash with vector's data.
+  #
+  # Returned hash has a default value of 0.
+  #
+  # @example
+  #   VectorNumber["a", "b", 6].to_h # => {"a"=>1, "b"=>1, 1=>6}
+  #   VectorNumber["a", "b", 6].to_h["c"] # => 0
+  #
+  # @return [Hash{Object => Numeric}]
+  #
+  # @since 0.1.0
+  def to_h(&block)
+    # TODO: Remove block argument.
+    if block_given?
+      @data.to_h(&block)
+    else
+      @data.dup
     end
+  end
 
-    # Get the coefficient for the unit.
-    #
-    # If the +unit?(unit)+ is false, 0 is returned.
-    # Note that units for real and imaginary parts are
-    # VectorNumber::R and VectorNumber::I respectively.
-    #
-    # @example
-    #   VectorNumber["a", "b", 6]["a"] # => 1
-    #   VectorNumber["a", "b", 6]["c"] # => 0
-    #
-    # @param unit [Object]
-    # @return [Integer, Float, Rational, BigDecimal]
-    #
-    # @since 0.2.4
-    def [](unit) = @data[unit]
+  # Get the coefficient for the unit.
+  #
+  # If the +unit?(unit)+ is false, 0 is returned.
+  # Note that units for real and imaginary parts are
+  # VectorNumber::R and VectorNumber::I respectively.
+  #
+  # @example
+  #   VectorNumber["a", "b", 6]["a"] # => 1
+  #   VectorNumber["a", "b", 6]["c"] # => 0
+  #
+  # @param unit [Object]
+  # @return [Numeric]
+  #
+  # @since 0.2.4
+  def [](unit) = @data[unit]
 
-    # Check if a unit has a non-zero coefficient.
-    #
-    # @example
-    #   VectorNumber["a", "b", 6].unit?("a") # => true
-    #   VectorNumber["a", "b", 6].key?("c") # => false
-    #
-    # @param unit [Object]
-    # @return [Boolean]
-    #
-    # @since 0.2.4
-    def unit?(unit) = @data.key?(unit)
+  # Check if a unit has a non-zero coefficient.
+  #
+  # @example
+  #   VectorNumber["a", "b", 6].unit?("a") # => true
+  #   VectorNumber["a", "b", 6].key?("c") # => false
+  #
+  # @param unit [Object]
+  # @return [Boolean]
+  #
+  # @since 0.2.4
+  def unit?(unit) = @data.key?(unit)
 
-    # @since 0.2.4
-    alias key? unit?
-  end
+  # @since 0.2.4
+  alias key? unit?
 end

data/lib/vector_number/math_converting.rb

@@ -1,121 +1,125 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Various mathematical operations that are also conversions.
-  module MathConverting
-    # Calculate the absolute value of the vector, i.e. its length.
-    #
-    # @example
-    #   VectorNumber[5.3].abs # => 5.3
-    #   VectorNumber[-5.3i].magnitude # => 5.3
-    #   VectorNumber[-5.3i, "i"].abs # => 5.3935146240647205
-    #
-    # @return [Float]
-    #
-    # @since 0.2.2
-    def abs
-      Math.sqrt(abs2)
-    end
+  # @group Mathematical operations
 
-    alias magnitude abs
+  # Calculate the absolute value of the vector (its length).
+  #
+  # @example
+  #   VectorNumber[5.3].abs # => 5.3
+  #   VectorNumber[-5.3i].magnitude # => 5.3
+  #   VectorNumber[-5.3i, "i"].abs # => 5.3935146240647205
+  #
+  # @return [Float]
+  #
+  # @since 0.2.2
+  def abs
+    Math.sqrt(abs2)
+  end
 
-    # Calculate the square of absolute value.
-    #
-    # @example
-    #   VectorNumber[5.3].abs2 # => 5.3
-    #   VectorNumber[-5.3i].abs2 # => 5.3
-    #   VectorNumber[-5.3i, "i"].abs2 # => 29.09
-    #
-    # @return [Float]
-    #
-    # @since 0.2.2
-    def abs2
-      coefficients.sum(&:abs2)
-    end
+  alias magnitude abs
 
-    # Return a new vector with every coefficient truncated using their +#truncate+.
-    #
-    # @example
-    #   VectorNumber[5.39].truncate # => (5)
-    #   VectorNumber[-5.35i].truncate # => (-5i)
-    #   VectorNumber[-5.35i, "i"].truncate # => (-5i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].truncate(1) # => (-5.3i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].truncate(-1) # => (0)
-    #
-    # @param digits [Integer]
-    # @return [VectorNumber]
-    #
-    # @since 0.2.1
-    def truncate(digits = 0)
-      new { _1.truncate(digits) }
-    end
+  # Calculate the square of absolute value.
+  #
+  # @example
+  #   VectorNumber[5.3].abs2 # => 5.3
+  #   VectorNumber[-5.3i].abs2 # => 5.3
+  #   VectorNumber[-5.3i, "i"].abs2 # => 29.09
+  #
+  # @return [Float]
+  #
+  # @since 0.2.2
+  def abs2
+    coefficients.sum(&:abs2)
+  end
 
-    # Return a new vector with every coefficient rounded using their +#ceil+.
-    #
-    # @example
-    #   VectorNumber[5.39].ceil # => (6)
-    #   VectorNumber[-5.35i].ceil # => (-5i)
-    #   VectorNumber[-5.35i, "i"].ceil # => (-5i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].ceil(1) # => (-5.3i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].ceil(-1) # => (10⋅'i')
-    #
-    # @param digits [Integer]
-    # @return [VectorNumber]
-    #
-    # @since 0.2.2
-    def ceil(digits = 0)
-      new { _1.ceil(digits) }
-    end
+  # Return a new vector with every coefficient truncated using their +#truncate+.
+  #
+  # @example
+  #   VectorNumber[5.39].truncate # => (5)
+  #   VectorNumber[-5.35i].truncate # => (-5i)
+  #   VectorNumber[-5.35i, "i"].truncate # => (-5i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].truncate(1) # => (-5.3i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].truncate(-1) # => (0)
+  #
+  # @param digits [Integer]
+  # @return [VectorNumber]
+  #
+  # @since 0.2.1
+  def truncate(digits = 0)
+    new { _1.truncate(digits) }
+  end
 
-    # Return a new vector with every coefficient rounded using their +#floor+.
-    #
-    # @example
-    #   VectorNumber[5.39].floor # => (5)
-    #   VectorNumber[-5.35i].floor # => (-6i)
-    #   VectorNumber[-5.35i, "i"].floor # => (-6i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].floor(1) # => (-5.4i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].floor(-1) # => (-10i)
-    #
-    # @param digits [Integer]
-    # @return [VectorNumber]
-    #
-    # @since 0.2.2
-    def floor(digits = 0)
-      new { _1.floor(digits) }
-    end
+  # Return a new vector with every coefficient rounded using their +#ceil+.
+  #
+  # @example
+  #   VectorNumber[5.39].ceil # => (6)
+  #   VectorNumber[-5.35i].ceil # => (-5i)
+  #   VectorNumber[-5.35i, "i"].ceil # => (-5i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].ceil(1) # => (-5.3i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].ceil(-1) # => (10⋅'i')
+  #
+  # @param digits [Integer]
+  # @return [VectorNumber]
+  #
+  # @since 0.2.2
+  def ceil(digits = 0)
+    new { _1.ceil(digits) }
+  end
+
+  # Return a new vector with every coefficient rounded using their +#floor+.
+  #
+  # @example
+  #   VectorNumber[5.39].floor # => (5)
+  #   VectorNumber[-5.35i].floor # => (-6i)
+  #   VectorNumber[-5.35i, "i"].floor # => (-6i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].floor(1) # => (-5.4i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].floor(-1) # => (-10i)
+  #
+  # @param digits [Integer]
+  # @return [VectorNumber]
+  #
+  # @since 0.2.2
+  def floor(digits = 0)
+    new { _1.floor(digits) }
+  end
 
-    # Return a new vector with every coefficient rounded using their +#round+.
-    #
-    # @example
-    #   VectorNumber[-4.5i, "i"].round(half: :up) # => (-5i + 1⋅'i')
-    #   VectorNumber[-4.5i, "i"].round(half: :even) # => (-4i + 1⋅'i')
-    #   VectorNumber[-5.5i, "i"].round(half: :even) # => (-6i + 1⋅'i')
-    #   VectorNumber[-5.5i, "i"].round(half: :down) # => (-5i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].round(1) # => (-5.4i + 1⋅'i')
-    #   VectorNumber[-5.35i, "i"].round(-1) # => (-10i)
-    #
-    # @param digits [Integer]
-    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+,
-    #   see +Float#round+ for meaning
-    # @return [VectorNumber]
-    #
-    # @see Float#round
-    #
-    # @since 0.2.2
-    def round(digits = 0, half: :up)
-      if defined?(BigDecimal)
-        bd_mode =
-          case half
-          when :down then :half_down
-          when :even then :half_even
-          else :half_up
-          end
-        new { _1.is_a?(BigDecimal) ? _1.round(digits, bd_mode) : _1.round(digits, half:) }
-      # :nocov:
-      else
-        new { _1.round(digits, half:) }
-      end
-      # :nocov:
+  # Return a new vector with every coefficient rounded using their +#round+.
+  #
+  # In the case of +BigDecimal+ coefficients, the +half+ parameter is converted
+  # to the corresponding +BigDecimal+ rounding mode
+  # (one of +:half_up+, +:half_down+, or +:half_even+).
+  # Other modes can not be specified.
+  #
+  # @example
+  #   VectorNumber[-4.5i, "i"].round(half: :up) # => (-5i + 1⋅'i')
+  #   VectorNumber[-4.5i, "i"].round(half: :even) # => (-4i + 1⋅'i')
+  #   VectorNumber[-5.5i, "i"].round(half: :even) # => (-6i + 1⋅'i')
+  #   VectorNumber[-5.5i, "i"].round(half: :down) # => (-5i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].round(1) # => (-5.4i + 1⋅'i')
+  #   VectorNumber[-5.35i, "i"].round(-1) # => (-10i)
+  #
+  # @param digits [Integer]
+  # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+,
+  #   see +Float#round+ for meaning
+  # @return [VectorNumber]
+  #
+  # @see Float#round
+  #
+  # @since 0.2.2
+  def round(digits = 0, half: :up)
+    if defined?(BigDecimal)
+      bd_mode =
+        case half
+        when :down then :half_down
+        when :even then :half_even
+        else :half_up
+        end
+      new { _1.is_a?(BigDecimal) ? _1.round(digits, bd_mode) : _1.round(digits, half: half) }
+    # :nocov:
+    else
+      new { _1.round(digits, half: half) }
     end
+    # :nocov:
   end
 end