vector_number 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05d6547284c73b585a149026d1a0a123f5914e13c81856e2419180f44f05404c
-  data.tar.gz: 2b942db9aa53c4e8027540a630355f2defd64de96d3c90bbd55e539844f32bfa
+  metadata.gz: f1f7cc1d90279440f3387287efeabb4a4c0cb40fe370b671d07623f192cccc68
+  data.tar.gz: c89b5bf8d9ad8fef73942cd3112b42cbbcbd515ca29bd61dcad0be274c5a7b0f
 SHA512:
-  metadata.gz: a8d079e1d0915ae151ac2dcb28621f672365e55efa0cb505ad3e846eb3619eababa4e39e5654098bb305fafa2ff602a1085c913c5d6fc8ea02922688087fb09b
-  data.tar.gz: f09e3d71187e9c202ff1a4960cbf19b7a02f679dc6b49b7b1e96e42e074a66990507262ab1648182217b8dacc980fe0ed777c48ac76db44734dccfdf34a7b488
+  metadata.gz: 199fa928aa2c46d6e5966d745def48284b1373c3cf3ab4b30046d0e39e7eaa91b0cf9beab690ac3a08fe3776f5a4f9726f341ff9f809b30766e645258eff6149
+  data.tar.gz: 484a9f87841252e26aad41db259304713b4deb0c93369a16254c3f413f2f986756c8a894be30b7555ef69ed1264e2b73ef33b3c0fa8b7ed9b07f2a2e74fd5137

data/README.md

@@ -147,4 +147,4 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/trini
 
 ## License
 
-This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT), see [LICENSE.txt](https://github.com/trinistr/vector_number/blob/main/LICENSE.txt).
+This gem is available as open source under the terms of the MIT License, see [LICENSE.txt](https://github.com/trinistr/vector_number/blob/main/LICENSE.txt).

data/lib/vector_number/comparing.rb

@@ -1,125 +1,128 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Methods for comparing with other numbers.
-  #
-  # +Comparable+ is included for parity with numbers.
+  # @group Comparing
+
+  # +Comparable+ is included for parity with +Numeric+.
   # @example using Comparable methods
   #   VectorNumber[12] < 0 # => false
   #   VectorNumber[12, "a"] < 0 # ArgumentError
   #   (VectorNumber[12]..VectorNumber[15]).include?(13) # => true
-  module Comparing
-    # @since 0.2.0
-    include ::Comparable
+  #
+  # @since 0.2.0
+  include ::Comparable
 
-    # Compare to +other+ for equality.
-    #
-    # Values are considered equal if
-    # - +other+ is a VectorNumber and it is +eql?+ to this one, or
-    # - +other+ is a Numeric equal in value to this (real or complex) number.
-    #
-    # @example
-    #   VectorNumber[3.13] == 3.13 # => true
-    #   VectorNumber[1.4, 1.5i] == Complex(1.4, 1.5) # => true
-    #   VectorNumber["a", "b", "c"] == VectorNumber["c", "b", "a"] # => true
-    #   VectorNumber["a", 14] == 14 # => false
-    #   VectorNumber["a"] == "a" # => false
-    #
-    # @param other [Object]
-    # @return [Boolean]
-    #
-    # @since 0.2.0
-    def ==(other)
-      return true if eql?(other)
+  # Test whether +other+ has the same value with +==+ semantics.
+  #
+  # Values are considered equal if
+  # - +other+ is a VectorNumber and it has the same units and equal coefficients, or
+  # - +other+ is a Numeric equal in value to this (real or complex) number.
+  #
+  # @example
+  #   VectorNumber[3.13] == 3.13 # => true
+  #   VectorNumber[1.4, 1.5i] == Complex(1.4, 1.5) # => true
+  #   VectorNumber["a", "b", "c"] == VectorNumber["c", "b", "a"] # => true
+  #   VectorNumber["a", 14] == 14 # => false
+  #   VectorNumber["a"] == "a" # => false
+  #
+  # @param other [Object]
+  # @return [Boolean]
+  #
+  # @since 0.2.0
+  def ==(other)
+    return true if equal?(other)
 
-      case other
-      when Numeric
-        numeric?(2) && other.real == real && other.imaginary == imaginary
-      else
-        # Can't compare a number-like value to a non-number.
-        false
-      end
+    case other
+    when VectorNumber
+      size == other.size && @data == other.to_h
+    when Numeric
+      numeric?(2) && other.real == real && other.imaginary == imaginary
+    else
+      # Can't compare a number-like value to a non-number.
+      false
     end
+  end
 
-    # Compare to +other+ for strict equality.
-    #
-    # Values are considered equal only if +other+ is a VectorNumber
-    # and it has exactly the same units and coefficients, though possibly in a different order.
-    # Additionally, `a.eql?(b)` implies `a.hash == b.hash`.
-    #
-    # Note that {#options} are not considered for equality.
-    #
-    # @example
-    #   VectorNumber["a", "b", "c"].eql? VectorNumber["c", "b", "a"] # => true
-    #   VectorNumber[3.13].eql? 3.13 # => false
-    #   VectorNumber[1.4, 1.5i].eql? Complex(1.4, 1.5) # => false
-    #   VectorNumber["a", 14].eql? 14 # => false
-    #   VectorNumber["a"].eql? "a" # => false
-    #
-    # @param other [Object]
-    # @return [Boolean]
-    #
-    # @since 0.1.0
-    def eql?(other)
-      return true if equal?(other)
+  # Test whether +other+ is VectorNumber and has the same value with +eql?+ semantics.
+  #
+  # Values are considered equal only if +other+ is a VectorNumber
+  # and it has exactly the same units and coefficients, though possibly in a different order.
+  # Additionally, `a.eql?(b)` implies `a.hash == b.hash`.
+  #
+  # Note that {#options} are not considered for equality.
+  #
+  # @example
+  #   VectorNumber["a", "b", "c"].eql? VectorNumber["c", "b", "a"] # => true
+  #   VectorNumber[3.13].eql? 3.13 # => false
+  #   VectorNumber[1.4, 1.5i].eql? Complex(1.4, 1.5) # => false
+  #   VectorNumber["a", 14].eql? 14 # => false
+  #   VectorNumber["a"].eql? "a" # => false
+  #
+  # @param other [Object]
+  # @return [Boolean]
+  #
+  # @since 0.1.0
+  def eql?(other)
+    return true if equal?(other)
+    return false unless other.is_a?(VectorNumber)
 
-      if other.is_a?(VectorNumber)
-        other.size == size && other.each_pair.all? { |u, c| @data[u] == c }
-      else
-        false
-      end
-    end
+    size.eql?(other.size) && @data.eql?(other.to_h)
+  end
 
-    # Generate an Integer hash value for self.
-    #
-    # Hash values are stable during runtime, but not between processes.
-    #
-    # @example
-    #   VectorNumber["b", "a"].hash # => 3081872088394655324
-    #   VectorNumber["a", "b", mult: :cross].hash # => 3081872088394655324
-    #   VectorNumber["b", "c"].hash # => -1002381358514682371
-    #
-    # @return [Integer]
-    #
-    # @since 0.4.2
-    def hash
-      [self.class, @data].hash
-    end
+  # Generate an Integer hash value for self.
+  #
+  # Hash values are stable during runtime, but not between processes.
+  # Options are disregarded for hash calculation.
+  #
+  # @example
+  #   VectorNumber["b", "a"].hash # => 3081872088394655324
+  #   VectorNumber["a", "b", mult: :cross].hash # => 3081872088394655324
+  #   VectorNumber["b", "c"].hash # => -1002381358514682371
+  #
+  # @return [Integer]
+  #
+  # @since 0.4.2
+  def hash
+    [self.class, @data].hash
+  end
 
-    # Compare to +other+ and return -1, 0, or 1
-    # if +self+ is less than, equal, or larger than +other+.
-    #
-    # @example
-    #   VectorNumber[130] <=> 12 # => 1
-    #   1 <=> VectorNumber[13] # => -1
-    #   VectorNumber[12.1] <=> Complex(12.1, 0) # => 0
-    #   # This doesn't work as expected without NumericRefinements:
-    #   Complex(12.1, 0) <=> VectorNumber[12.1] # => nil
-    #
-    #   # Any non-real comparison returns nil:
-    #   VectorNumber[12.1] <=> Complex(12.1, 1) # => nil
-    #   VectorNumber[12.1i] <=> 2 # => nil
-    #   VectorNumber["a"] <=> 2 # => nil
-    #
-    # @param other [Object]
-    # @return [Integer]
-    # @return [nil] if +self+ or +other+ isn't a real number.
-    #
-    # @see Comparable
-    # @see NumericRefinements
-    #
-    # @since 0.2.0
-    def <=>(other)
-      return nil unless numeric?(1)
+  # Compare to +other+ and return -1, 0, or 1
+  # if +self+ is less than, equal, or larger than +other+ on real number line,
+  # or +nil+ if any or both values are non-real.
+  #
+  # Most VectorNumbers are non-real and therefore not comparable with this method.
+  #
+  # @example
+  #   VectorNumber[130] <=> 12 # => 1
+  #   1 <=> VectorNumber[13] # => -1
+  #   VectorNumber[12.1] <=> Complex(12.1, 0) # => 0
+  #   # This doesn't work as expected without NumericRefinements:
+  #   Complex(12.1, 0) <=> VectorNumber[12.1] # => nil
+  #
+  #   # Any non-real comparison returns nil:
+  #   VectorNumber[12.1] <=> Complex(12.1, 1) # => nil
+  #   VectorNumber[12.1i] <=> 2 # => nil
+  #   VectorNumber["a"] <=> 2 # => nil
+  #
+  # @see #numeric?
+  # @see Comparable
+  # @see NumericRefinements
+  #
+  # @param other [Object]
+  # @return [Integer]
+  # @return [nil] if +self+ or +other+ isn't a real number.
+  #
+  # @since 0.2.0
+  def <=>(other)
+    return nil unless numeric?(1)
 
-      case other
-      when VectorNumber
-        other.numeric?(1) ? real <=> other.real : nil
-      when Numeric
-        other.imaginary.zero? ? real <=> other.real : nil
-      else
-        nil
-      end
+    case other
+    when VectorNumber
+      other.numeric?(1) ? real <=> other.real : nil
+    when Numeric
+      other.imaginary.zero? ? real <=> other.real : nil
+    else
+      nil
     end
   end
 end

data/lib/vector_number/converting.rb

@@ -1,152 +1,157 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Methods for converting to different number classes.
-  module Converting
-    # Return real part of the number.
-    #
-    # @example
-    #   VectorNumber[23, "a"].real # => 23
-    #   VectorNumber["a"].real # => 0
-    #
-    # @return [Integer, Float, Rational, BigDecimal]
-    #
-    # @since 0.1.0
-    def real = @data[R]
-
-    # Return imaginary part of the number.
-    #
-    # @example
-    #   VectorNumber[23, "a"].imaginary # => 0
-    #   VectorNumber["a", Complex(1, 2r)].imag # => (2/1)
-    #
-    # @return [Integer, Float, Rational, BigDecimal]
-    #
-    # @since 0.1.0
-    def imaginary = @data[I]
-
-    # @since 0.2.1
-    alias imag imaginary
-
-    # Return value as an Integer, truncating it, if only real part is non-zero.
-    #
-    # @example
-    #   VectorNumber[13.5].to_i # => 13
-    #   VectorNumber[13r/12].to_int # => 1
-    #   [1.1, 2.2, 3.3][VectorNumber[2]] # => 3.3
-    #   VectorNumber[2, 2i].to_i # RangeError
-    #   VectorNumber[2, :i].to_f # RangeError
-    #
-    #   Integer(VectorNumber[2]) # => 2
-    #   Integer(VectorNumber[2, "i"]) # RangeError
-    #
-    # @return [Integer]
-    # @raise [RangeError] if any non-real part is non-zero
-    #
-    # @since 0.1.0
-    def to_i
-      numeric?(1) ? real.to_i : raise_convert_error(Integer)
-    end
-
-    # @since 0.1.0
-    alias to_int to_i
-
-    # Return value as a Float if only real part is non-zero.
-    #
-    # @example
-    #   VectorNumber[13.5].to_f # => 13.5
-    #   VectorNumber[13r/12].to_f # => 1.0833333333333333
-    #   VectorNumber[2, 2i].to_f # RangeError
-    #   VectorNumber[2, :i].to_f # RangeError
-    #
-    #   Float(VectorNumber[2]) # => 2.0
-    #   Float(VectorNumber[2, "i"]) # RangeError
-    #
-    # @return [Float]
-    # @raise [RangeError] if any non-real part is non-zero
-    #
-    # @since 0.1.0
-    def to_f
-      numeric?(1) ? real.to_f : raise_convert_error(Float)
-    end
-
-    # Return value as a Rational if only real part is non-zero.
-    #
-    # @example
-    #   VectorNumber[13.5].to_r # => (27/2)
-    #   VectorNumber[13r/12].to_r # => (13/12)
-    #   VectorNumber[2, 2i].to_r # RangeError
-    #   VectorNumber[2, :i].to_r # RangeError
-    #
-    #   Rational(VectorNumber[2]) # => (2/1)
-    #   Rational(VectorNumber[2, "i"]) # RangeError
-    #
-    # @return [Rational]
-    # @raise [RangeError] if any non-real part is non-zero
-    #
-    # @since 0.1.0
-    def to_r
-      numeric?(1) ? real.to_r : raise_convert_error(Rational)
-    end
-
-    # Return value as a BigDecimal if only real part is non-zero.
-    #
-    # @example
-    #   VectorNumber[13.5].to_d # => 0.135e2
-    #   VectorNumber[13r/12].to_d # ArgumentError
-    #   VectorNumber[13r/12].to_d(5) # => 0.10833e1
-    #   VectorNumber[2, 2i].to_d # RangeError
-    #   VectorNumber[2, :i].to_d # RangeError
-    #
-    #   # This does't work without NumericRefinements:
-    #   BigDecimal(VectorNumber[2]) # TypeError
-    #   # #to_s can be used as a workaround if refinements aren't used:
-    #   BigDecimal(VectorNumber[2].to_s) # => 0.2e1
-    #   BigDecimal(VectorNumber[2, "i"].to_s) # => ArgumentError
-    #
-    # @param ndigits [Integer] precision
-    # @return [BigDecimal]
-    # @raise [RangeError] if any non-real part is non-zero
-    # @raise [NameError] if BigDecimal is not defined
-    #
-    # @see Kernel.BigDecimal
-    # @see NumericRefinements
-    #
-    # @since 0.1.0
-    def to_d(ndigits = nil)
-      if numeric?(1)
-        return BigDecimal(real, ndigits) if ndigits
-        return BigDecimal(real, Float::DIG) if real.is_a?(Float)
-
-        BigDecimal(real)
-      else
-        raise_convert_error(BigDecimal)
-      end
-    end
-
-    # Return value as a Complex if only real and/or imaginary parts are non-zero.
-    #
-    # @example
-    #   VectorNumber[13.5].to_c # => (13.5+0i)
-    #   VectorNumber[13r/12].to_c # => ((13/12)+0i)
-    #   VectorNumber[2, 2i].to_c # => (2+2i)
-    #   VectorNumber[2, :i].to_c # RangeError
-    #
-    #   Complex(VectorNumber[2]) # => (2+0i)
-    #   Complex(VectorNumber[2, "i"]) # RangeError
-    #
-    # @return [Complex]
-    # @raise [RangeError] if any non-real, non-imaginary part is non-zero
-    #
-    # @since 0.1.0
-    def to_c
-      numeric?(2) ? Complex(real, imaginary) : raise_convert_error(Complex)
-    end
-
-    private
-
-    def raise_convert_error(klass)
-      raise RangeError, "can't convert #{self} into #{klass}", caller
-    end
+  # @group Converting to different numeric classes
+
+  # Return real part of the number.
+  #
+  # @example
+  #   VectorNumber[23, "a"].real # => 23
+  #   VectorNumber["a"].real # => 0
+  #
+  # @return [Integer, Float, Rational, BigDecimal]
+  #
+  # @since 0.1.0
+  def real = @data[R]
+
+  # Return imaginary part of the number.
+  #
+  # @example
+  #   VectorNumber[23, "a"].imaginary # => 0
+  #   VectorNumber["a", Complex(1, 2r)].imag # => (2/1)
+  #
+  # @return [Integer, Float, Rational, BigDecimal]
+  #
+  # @since 0.1.0
+  def imaginary = @data[I]
+
+  # @since 0.2.1
+  alias imag imaginary
+
+  # Return value as an Integer, truncating it, if only real part is non-zero.
+  #
+  # @example
+  #   VectorNumber[13.5].to_i # => 13
+  #   VectorNumber[13r/12].to_int # => 1
+  #   [1.1, 2.2, 3.3][VectorNumber[2]] # => 3.3
+  #   VectorNumber[2, 2i].to_i # RangeError
+  #   VectorNumber[2, :i].to_f # RangeError
+  #
+  #   Integer(VectorNumber[2]) # => 2
+  #   Integer(VectorNumber[2, "i"]) # RangeError
+  #
+  # @return [Integer]
+  # @raise [RangeError] if any non-real part is non-zero
+  #
+  # @since 0.1.0
+  def to_i
+    raise_convert_error(Integer) unless numeric?(1)
+
+    real.to_i
+  end
+
+  # @since 0.1.0
+  alias to_int to_i
+
+  # Return value as a Float if only real part is non-zero.
+  #
+  # @example
+  #   VectorNumber[13.5].to_f # => 13.5
+  #   VectorNumber[13r/12].to_f # => 1.0833333333333333
+  #   VectorNumber[2, 2i].to_f # RangeError
+  #   VectorNumber[2, :i].to_f # RangeError
+  #
+  #   Float(VectorNumber[2]) # => 2.0
+  #   Float(VectorNumber[2, "i"]) # RangeError
+  #
+  # @return [Float]
+  # @raise [RangeError] if any non-real part is non-zero
+  #
+  # @since 0.1.0
+  def to_f
+    raise_convert_error(Float) unless numeric?(1)
+
+    real.to_f
+  end
+
+  # Return value as a Rational if only real part is non-zero.
+  #
+  # @example
+  #   VectorNumber[13.5].to_r # => (27/2)
+  #   VectorNumber[13r/12].to_r # => (13/12)
+  #   VectorNumber[2, 2i].to_r # RangeError
+  #   VectorNumber[2, :i].to_r # RangeError
+  #
+  #   Rational(VectorNumber[2]) # => (2/1)
+  #   Rational(VectorNumber[2, "i"]) # RangeError
+  #
+  # @return [Rational]
+  # @raise [RangeError] if any non-real part is non-zero
+  #
+  # @since 0.1.0
+  def to_r
+    raise_convert_error(Rational) unless numeric?(1)
+
+    real.to_r
+  end
+
+  # Return value as a BigDecimal if only real part is non-zero.
+  #
+  # @example
+  #   VectorNumber[13.5].to_d # => 0.135e2
+  #   VectorNumber[13r/12].to_d # ArgumentError
+  #   VectorNumber[13r/12].to_d(5) # => 0.10833e1
+  #   VectorNumber[2, 2i].to_d # RangeError
+  #   VectorNumber[2, :i].to_d # RangeError
+  #
+  #   # This does't work without NumericRefinements:
+  #   BigDecimal(VectorNumber[2]) # TypeError
+  #   # #to_s can be used as a workaround if refinements aren't used:
+  #   BigDecimal(VectorNumber[2].to_s) # => 0.2e1
+  #   BigDecimal(VectorNumber[2, "i"].to_s) # => ArgumentError
+  #
+  # @param ndigits [Integer] precision
+  # @return [BigDecimal]
+  # @raise [RangeError] if any non-real part is non-zero
+  # @raise [NameError] if BigDecimal is not defined
+  #
+  # @see Kernel.BigDecimal
+  # @see NumericRefinements
+  #
+  # @since 0.1.0
+  def to_d(ndigits = nil)
+    raise_convert_error(BigDecimal) unless numeric?(1)
+
+    return BigDecimal(real, ndigits) if ndigits
+    return BigDecimal(real, Float::DIG) if real.is_a?(Float)
+
+    BigDecimal(real)
+  end
+
+  # Return value as a Complex if only real and/or imaginary parts are non-zero.
+  #
+  # @example
+  #   VectorNumber[13.5].to_c # => (13.5+0i)
+  #   VectorNumber[13r/12].to_c # => ((13/12)+0i)
+  #   VectorNumber[2, 2i].to_c # => (2+2i)
+  #   VectorNumber[2, :i].to_c # RangeError
+  #
+  #   Complex(VectorNumber[2]) # => (2+0i)
+  #   Complex(VectorNumber[2, "i"]) # RangeError
+  #
+  # @return [Complex]
+  # @raise [RangeError] if any non-real, non-imaginary part is non-zero
+  #
+  # @since 0.1.0
+  def to_c
+    raise_convert_error(Complex) unless numeric?(2)
+
+    Complex(real, imaginary)
+  end
+
+  private
+
+  def raise_convert_error(klass)
+    raise RangeError, "can't convert #{self} into #{klass}", caller
   end
 end