ruby-units 3.0.0 → 4.0.1

data/lib/ruby_units/unit.rb

@@ -1,6 +1,6 @@
 require 'date'
 module RubyUnits
-  # Copyright 2006-2022
+  # Copyright 2006-2023
   # @author Kevin C. Olbrich, Ph.D.
   # @see https://github.com/olbrich/ruby-units
   #
@@ -22,56 +22,85 @@ module RubyUnits
   #  end
   #
   class Unit < ::Numeric
-    @@definitions      = {}
-    @@prefix_values    = {}
-    @@prefix_map       = {}
-    @@unit_map         = {}
-    @@unit_values      = {}
-    @@unit_regex       = nil
-    @@unit_match_regex = nil
+    class << self
+      # return a list of all defined units
+      # @return [Hash{Symbol=>RubyUnits::Units::Definition}]
+      attr_accessor :definitions
+
+      # @return [Hash{Symbol => String}] the list of units and their prefixes
+      attr_accessor :prefix_values
+
+      # @return [Hash{Symbol => String}]
+      attr_accessor :prefix_map
+
+      # @return [Hash{Symbol => String}]
+      attr_accessor :unit_map
+
+      # @return [Hash{Symbol => String}]
+      attr_accessor :unit_values
+
+      # @return [Hash{Integer => Symbol}]
+      attr_reader :kinds
+    end
+    self.definitions = {}
+    self.prefix_values = {}
+    self.prefix_map = {}
+    self.unit_map = {}
+    self.unit_values = {}
+    @unit_regex = nil
+    @unit_match_regex = nil
     UNITY              = '<1>'.freeze
     UNITY_ARRAY        = [UNITY].freeze
+
+    SIGN_REGEX = /(?:[+-])?/.freeze # +, -, or nothing
+
+    # regex for matching an integer number but not a fraction
+    INTEGER_DIGITS_REGEX = %r{(?<!/)\d+(?!/)}.freeze # 1, 2, 3, but not 1/2 or -1
+    INTEGER_REGEX = /(#{SIGN_REGEX}#{INTEGER_DIGITS_REGEX})/.freeze # -1, 1, +1, but not 1/2
+    UNSIGNED_INTEGER_REGEX = /((?<!-)#{INTEGER_DIGITS_REGEX})/.freeze # 1, 2, 3, but not -1
+    DIGITS_REGEX = /\d+/.freeze # 0, 1, 2, 3
+    DECIMAL_REGEX = /\d*[.]?#{DIGITS_REGEX}/.freeze # 1, 0.1, .1
+    # Rational number, including improper fractions: 1 2/3, -1 2/3, 5/3, etc.
+    RATIONAL_NUMBER = %r{\(?(?:(?<proper>#{SIGN_REGEX}#{DECIMAL_REGEX})[ -])?(?<numerator>#{SIGN_REGEX}#{DECIMAL_REGEX})/(?<denominator>#{SIGN_REGEX}#{DECIMAL_REGEX})\)?} # 1 2/3, -1 2/3, 5/3, 1-2/3, (1/2) etc.
+    # Scientific notation: 1, -1, +1, 1.2, +1.2, -1.2, 123.4E5, +123.4e5,
+    #   -123.4E+5, -123.4e-5, etc.
+    SCI_NUMBER = /([+-]?\d*[.]?\d+(?:[Ee][+-]?\d+(?![.]))?)/
     # ideally we would like to generate this regex from the alias for a 'feet'
     # and 'inches', but they aren't defined at the point in the code where we
     # need this regex.
-    FEET_INCH_UNITS_REGEX = /(?:'|ft|feet)\s*(\d+)\s*(?:"|in|inch(?:es)?)/.freeze
-    FEET_INCH_REGEX    = /(\d+)\s*#{FEET_INCH_UNITS_REGEX}/.freeze
+    FEET_INCH_UNITS_REGEX = /(?:'|ft|feet)\s*(?<inches>#{RATIONAL_NUMBER}|#{SCI_NUMBER})\s*(?:"|in|inch(?:es)?)/.freeze
+    FEET_INCH_REGEX    = /(?<feet>#{INTEGER_REGEX})\s*#{FEET_INCH_UNITS_REGEX}/.freeze
     # ideally we would like to generate this regex from the alias for a 'pound'
     # and 'ounce', but they aren't defined at the point in the code where we
     # need this regex.
-    LBS_OZ_UNIT_REGEX  = /(?:#|lbs?|pounds?|pound-mass)+[\s,]*(\d+)\s*(?:ozs?|ounces?)/.freeze
-    LBS_OZ_REGEX       = /(\d+)\s*#{LBS_OZ_UNIT_REGEX}/.freeze
+    LBS_OZ_UNIT_REGEX  = /(?:#|lbs?|pounds?|pound-mass)+[\s,]*(?<oz>#{RATIONAL_NUMBER}|#{UNSIGNED_INTEGER_REGEX})\s*(?:ozs?|ounces?)/.freeze
+    LBS_OZ_REGEX       = /(?<pounds>#{INTEGER_REGEX})\s*#{LBS_OZ_UNIT_REGEX}/.freeze
     # ideally we would like to generate this regex from the alias for a 'stone'
     # and 'pound', but they aren't defined at the point in the code where we
     # need this regex. also note that the plural of 'stone' is still 'stone',
     # but we accept 'stones' anyway.
-    STONE_LB_UNIT_REGEX = /(?:sts?|stones?)+[\s,]*(\d+)\s*(?:#|lbs?|pounds?|pound-mass)*/.freeze
-    STONE_LB_REGEX     = /(\d+)\s*#{STONE_LB_UNIT_REGEX}/.freeze
+    STONE_LB_UNIT_REGEX = /(?:sts?|stones?)+[\s,]*(?<pounds>#{RATIONAL_NUMBER}|#{UNSIGNED_INTEGER_REGEX})\s*(?:#|lbs?|pounds?|pound-mass)*/.freeze
+    STONE_LB_REGEX     = /(?<stone>#{INTEGER_REGEX})\s*#{STONE_LB_UNIT_REGEX}/.freeze
     # Time formats: 12:34:56,78, (hh:mm:ss,msec) etc.
-    TIME_REGEX         = /(?<hour>\d+):(?<min>\d+):(?:(?<sec>\d+))?(?:,(?<msec>\d+))?/.freeze
-    # Scientific notation: 1, -1, +1, 1.2, +1.2, -1.2, 123.4E5, +123.4e5,
-    #   -123.4E+5, -123.4e-5, etc.
-    SCI_NUMBER         = /([+-]?\d*[.]?\d+(?:[Ee][+-]?)?\d*)/.freeze
-    # Rational number, including improper fractions: 1 2/3, -1 2/3, 5/3, etc.
-    RATIONAL_NUMBER    = %r{\(?([+-])?(\d+[ -])?(\d+)/(\d+)\)?}.freeze
+    TIME_REGEX         = /(?<hour>\d+):(?<min>\d+):?(?:(?<sec>\d+))?(?:[.](?<msec>\d+))?/.freeze
     # Complex numbers: 1+2i, 1.0+2.0i, -1-1i, etc.
-    COMPLEX_NUMBER     = /#{SCI_NUMBER}?#{SCI_NUMBER}i\b/.freeze
+    COMPLEX_NUMBER     = /(?<real>#{SCI_NUMBER})?(?<imaginary>#{SCI_NUMBER})i\b/.freeze
     # Any Complex, Rational, or scientific number
     ANY_NUMBER         = /(#{COMPLEX_NUMBER}|#{RATIONAL_NUMBER}|#{SCI_NUMBER})/.freeze
     ANY_NUMBER_REGEX   = /(?:#{ANY_NUMBER})?\s?([^-\d.].*)?/.freeze
-    NUMBER_REGEX       = /#{SCI_NUMBER}*\s*(.+)?/.freeze
+    NUMBER_REGEX       = /(?<scalar>#{SCI_NUMBER}*)\s*(?<unit>.+)?/.freeze # a number followed by a unit
     UNIT_STRING_REGEX  = %r{#{SCI_NUMBER}*\s*([^/]*)/*(.+)*}.freeze
     TOP_REGEX          = /([^ *]+)(?:\^|\*\*)([\d-]+)/.freeze
     BOTTOM_REGEX       = /([^* ]+)(?:\^|\*\*)(\d+)/.freeze
     NUMBER_UNIT_REGEX  = /#{SCI_NUMBER}?(.*)/.freeze
-    COMPLEX_REGEX      = /#{COMPLEX_NUMBER}\s?(.+)?/.freeze
-    RATIONAL_REGEX     = /#{RATIONAL_NUMBER}\s?(.+)?/.freeze
+    COMPLEX_REGEX      = /#{COMPLEX_NUMBER}\s?(?<unit>.+)?/.freeze
+    RATIONAL_REGEX     = /#{RATIONAL_NUMBER}\s?(?<unit>.+)?/.freeze
     KELVIN             = ['<kelvin>'].freeze
     FAHRENHEIT         = ['<fahrenheit>'].freeze
     RANKINE            = ['<rankine>'].freeze
     CELSIUS            = ['<celsius>'].freeze
-    @@temp_regex       = nil
-    SIGNATURE_VECTOR   = %i[
+    @temp_regex = nil
+    SIGNATURE_VECTOR = %i[
       length
       time
       temperature
@@ -83,7 +112,7 @@ module RubyUnits
       information
       angle
     ].freeze
-    @@kinds = {
+    @kinds = {
       -312_078 => :elastance,
       -312_058 => :resistance,
       -312_038 => :inductance,
@@ -140,15 +169,15 @@ module RubyUnits
     # @return [Boolean]
     def self.setup
       clear_cache
-      @@prefix_values    = {}
-      @@prefix_map       = {}
-      @@unit_values      = {}
-      @@unit_map         = {}
-      @@unit_regex       = nil
-      @@unit_match_regex = nil
-      @@prefix_regex     = nil
-
-      @@definitions.each_value do |definition|
+      self.prefix_values = {}
+      self.prefix_map = {}
+      self.unit_map = {}
+      self.unit_values = {}
+      @unit_regex = nil
+      @unit_match_regex = nil
+      @prefix_regex = nil
+
+      definitions.each_value do |definition|
         use_definition(definition)
       end
 
@@ -160,7 +189,7 @@ module RubyUnits
     # @param [String] unit
     # @return [Boolean]
     def self.defined?(unit)
-      definitions.values.any? { |d| d.aliases.include?(unit) }
+      definitions.values.any? { _1.aliases.include?(unit) }
     end
 
     # return the unit definition for a unit
@@ -168,13 +197,7 @@ module RubyUnits
     # @return [RubyUnits::Unit::Definition, nil]
     def self.definition(unit_name)
       unit = unit_name =~ /^<.+>$/ ? unit_name : "<#{unit_name}>"
-      @@definitions[unit]
-    end
-
-    # return a list of all defined units
-    # @return [Array<RubyUnits::Units::Definition>]
-    def self.definitions
-      @@definitions
+      definitions[unit]
     end
 
     # @param  [RubyUnits::Unit::Definition, String] unit_definition
@@ -217,7 +240,7 @@ module RubyUnits
       raise(ArgumentError, "'#{name}' Unit not recognized") unless unit_definition
 
       yield unit_definition
-      @@definitions.delete("<#{name}>")
+      definitions.delete("<#{name}>")
       define(unit_definition)
       setup
     end
@@ -227,7 +250,7 @@ module RubyUnits
     # @param unit [String] name of unit to undefine
     # @return (see RubyUnits::Unit.setup)
     def self.undefine!(unit)
-      @@definitions.delete("<#{unit}>")
+      definitions.delete("<#{unit}>")
       setup
     end
 
@@ -275,7 +298,7 @@ module RubyUnits
       [[num, 1], [den, -1]].each do |array, increment|
         array.chunk_while { |elt_before, _| definition(elt_before).prefix? }
              .to_a
-             .each { |unit| combined[unit] += increment }
+             .each { combined[_1] += increment }
       end
 
       num = []
@@ -302,7 +325,7 @@ module RubyUnits
     # return an array of base units
     # @return [Array]
     def self.base_units
-      @@base_units ||= @@definitions.dup.select { |_, definition| definition.base? }.keys.map { |u| new(u) }
+      @base_units ||= definitions.dup.select { |_, definition| definition.base? }.keys.map { new(_1) }
     end
 
     # Parse a string consisting of a number and a unit string
@@ -337,27 +360,27 @@ module RubyUnits
     # Unit names are reverse sorted by length so the regexp matcher will prefer longer and more specific names
     # @return [String]
     def self.unit_regex
-      @@unit_regex ||= @@unit_map.keys.sort_by { |unit_name| [unit_name.length, unit_name] }.reverse.join('|')
+      @unit_regex ||= unit_map.keys.sort_by { [_1.length, _1] }.reverse.join('|')
     end
 
     # return a regex used to match units
     # @return [Regexp]
     def self.unit_match_regex
-      @@unit_match_regex ||= /(#{prefix_regex})??(#{unit_regex})\b/
+      @unit_match_regex ||= /(#{prefix_regex})??(#{unit_regex})\b/
     end
 
     # return a regexp fragment used to match prefixes
     # @return [String]
     # @private
     def self.prefix_regex
-      @@prefix_regex ||= @@prefix_map.keys.sort_by { |prefix| [prefix.length, prefix] }.reverse.join('|')
+      @prefix_regex ||= prefix_map.keys.sort_by { [_1.length, _1] }.reverse.join('|')
     end
 
     # Generates (and memoizes) a regexp matching any of the temperature units or their aliases.
     #
     # @return [Regexp]
     def self.temp_regex
-      @@temp_regex ||= begin
+      @temp_regex ||= begin
         temp_units = %w[tempK tempC tempF tempR degK degC degF degR]
         aliases = temp_units.map do |unit|
           d = definition(unit)
@@ -372,19 +395,19 @@ module RubyUnits
     #
     # @param definition [RubyUnits::Unit::Definition]
     def self.use_definition(definition)
-      @@unit_match_regex = nil # invalidate the unit match regex
-      @@temp_regex       = nil # invalidate the temp regex
+      @unit_match_regex = nil # invalidate the unit match regex
+      @temp_regex = nil # invalidate the temp regex
       if definition.prefix?
-        @@prefix_values[definition.name] = definition.scalar
-        definition.aliases.each { |alias_name| @@prefix_map[alias_name] = definition.name }
-        @@prefix_regex = nil # invalidate the prefix regex
+        prefix_values[definition.name] = definition.scalar
+        definition.aliases.each { prefix_map[_1] = definition.name }
+        @prefix_regex = nil # invalidate the prefix regex
       else
-        @@unit_values[definition.name]          = {}
-        @@unit_values[definition.name][:scalar] = definition.scalar
-        @@unit_values[definition.name][:numerator] = definition.numerator if definition.numerator
-        @@unit_values[definition.name][:denominator] = definition.denominator if definition.denominator
-        definition.aliases.each { |alias_name| @@unit_map[alias_name] = definition.name }
-        @@unit_regex = nil # invalidate the unit regex
+        unit_values[definition.name]          = {}
+        unit_values[definition.name][:scalar] = definition.scalar
+        unit_values[definition.name][:numerator] = definition.numerator if definition.numerator
+        unit_values[definition.name][:denominator] = definition.denominator if definition.denominator
+        definition.aliases.each { unit_map[_1] = definition.name }
+        @unit_regex = nil # invalidate the unit regex
       end
     end
 
@@ -513,7 +536,7 @@ module RubyUnits
         raise ArgumentError, 'Invalid Unit Format'
       end
       update_base_scalar
-      raise ArgumentError, 'Temperatures must not be less than absolute zero' if temperature? && base_scalar < 0
+      raise ArgumentError, 'Temperatures must not be less than absolute zero' if temperature? && base_scalar.negative?
 
       unary_unit = units || ''
       if options.first.instance_of?(String)
@@ -535,7 +558,7 @@ module RubyUnits
     # return the kind of the unit (:mass, :length, etc...)
     # @return [Symbol]
     def kind
-      @@kinds[signature]
+      self.class.kinds[signature]
     end
 
     # Convert the unit to a Unit, possibly performing a conversion.
@@ -558,8 +581,8 @@ module RubyUnits
       @base = (@numerator + @denominator)
               .compact
               .uniq
-              .map { |unit| self.class.definition(unit) }
-              .all? { |element| element.unity? || element.base? }
+              .map { self.class.definition(_1) }
+              .all? { _1.unity? || _1.base? }
       @base
     end
 
@@ -572,8 +595,8 @@ module RubyUnits
     def to_base
       return self if base?
 
-      if @@unit_map[units] =~ /\A<(?:temp|deg)[CRF]>\Z/
-        @signature = @@kinds.key(:temperature)
+      if self.class.unit_map[units] =~ /\A<(?:temp|deg)[CRF]>\Z/
+        @signature = self.class.kinds.key(:temperature)
         base = if temperature?
                  convert_to('tempK')
                elsif degree?
@@ -589,21 +612,21 @@ module RubyUnits
       den = []
       q   = Rational(1)
       @numerator.compact.each do |num_unit|
-        if @@prefix_values[num_unit]
-          q *= @@prefix_values[num_unit]
+        if self.class.prefix_values[num_unit]
+          q *= self.class.prefix_values[num_unit]
         else
-          q *= @@unit_values[num_unit][:scalar] if @@unit_values[num_unit]
-          num << @@unit_values[num_unit][:numerator] if @@unit_values[num_unit] && @@unit_values[num_unit][:numerator]
-          den << @@unit_values[num_unit][:denominator] if @@unit_values[num_unit] && @@unit_values[num_unit][:denominator]
+          q *= self.class.unit_values[num_unit][:scalar] if self.class.unit_values[num_unit]
+          num << self.class.unit_values[num_unit][:numerator] if self.class.unit_values[num_unit] && self.class.unit_values[num_unit][:numerator]
+          den << self.class.unit_values[num_unit][:denominator] if self.class.unit_values[num_unit] && self.class.unit_values[num_unit][:denominator]
         end
       end
       @denominator.compact.each do |num_unit|
-        if @@prefix_values[num_unit]
-          q /= @@prefix_values[num_unit]
+        if self.class.prefix_values[num_unit]
+          q /= self.class.prefix_values[num_unit]
         else
-          q /= @@unit_values[num_unit][:scalar] if @@unit_values[num_unit]
-          den << @@unit_values[num_unit][:numerator] if @@unit_values[num_unit] && @@unit_values[num_unit][:numerator]
-          num << @@unit_values[num_unit][:denominator] if @@unit_values[num_unit] && @@unit_values[num_unit][:denominator]
+          q /= self.class.unit_values[num_unit][:scalar] if self.class.unit_values[num_unit]
+          den << self.class.unit_values[num_unit][:numerator] if self.class.unit_values[num_unit] && self.class.unit_values[num_unit][:numerator]
+          num << self.class.unit_values[num_unit][:denominator] if self.class.unit_values[num_unit] && self.class.unit_values[num_unit][:denominator]
         end
       end
 
@@ -632,27 +655,34 @@ module RubyUnits
     #
     # @note Rational scalars that are equal to an integer will be represented as integers (i.e, 6/1 => 6, 4/2 => 2, etc..)
     # @param [Symbol] target_units
+    # @param [Float] precision - the precision to use when converting to a rational
     # @return [String]
-    def to_s(target_units = nil)
+    def to_s(target_units = nil, precision: 0.0001)
       out = @output[target_units]
       return out if out
 
       separator = RubyUnits.configuration.separator
       case target_units
       when :ft
-        inches = convert_to('in').scalar.to_int
-        out    = "#{(inches / 12).truncate}\'#{(inches % 12).round}\""
+        feet, inches = convert_to('in').scalar.abs.divmod(12)
+        improper, frac = inches.divmod(1)
+        frac = frac.zero? ? '' : "-#{frac.rationalize(precision)}"
+        out = "#{negative? ? '-' : nil}#{feet}'#{improper}#{frac}\""
       when :lbs
-        ounces = convert_to('oz').scalar.to_int
-        out    = "#{(ounces / 16).truncate}#{separator}lbs, #{(ounces % 16).round}#{separator}oz"
+        pounds, ounces = convert_to('oz').scalar.abs.divmod(16)
+        improper, frac = ounces.divmod(1)
+        frac = frac.zero? ? '' : "-#{frac.rationalize(precision)}"
+        out  = "#{negative? ? '-' : nil}#{pounds}#{separator}lbs #{improper}#{frac}#{separator}oz"
       when :stone
-        pounds = convert_to('lbs').scalar.to_int
-        out = "#{(pounds / 14).truncate}#{separator}stone, #{(pounds % 14).round}#{separator}lb"
+        stone, pounds = convert_to('lbs').scalar.abs.divmod(14)
+        improper, frac = pounds.divmod(1)
+        frac = frac.zero? ? '' : "-#{frac.rationalize(precision)}"
+        out = "#{negative? ? '-' : nil}#{stone}#{separator}stone #{improper}#{frac}#{separator}lbs"
       when String
         out = case target_units.strip
               when /\A\s*\Z/ # whitespace only
                 ''
-              when /(%[\-+.\w#]+)\s*(.+)*/ # format string like '%0.2f in'
+              when /(%[-+.\w#]+)\s*(.+)*/ # format string like '%0.2f in'
                 begin
                   if Regexp.last_match(2) # unit specified, need to convert
                     convert_to(Regexp.last_match(2)).to_s(Regexp.last_match(1))
@@ -713,7 +743,7 @@ module RubyUnits
     def temperature_scale
       return nil unless temperature?
 
-      "deg#{@@unit_map[units][/temp([CFRK])/, 1]}"
+      "deg#{self.class.unit_map[units][/temp([CFRK])/, 1]}"
     end
 
     # returns true if no associated units
@@ -771,9 +801,10 @@ module RubyUnits
       end
     end
 
-    # check to see if units are compatible, but not the scalar part
-    # this check is done by comparing signatures for performance reasons
-    # if passed a string, it will create a unit object with the string and then do the comparison
+    # Check to see if units are compatible, ignoring the scalar part.  This check is done by comparing unit signatures
+    # for performance reasons.  If passed a string, this will create a [Unit] object with the string and then do the
+    # comparison.
+    #
     # @example this permits a syntax like:
     #  unit =~ "mm"
     # @note if you want to do a regexp comparison of the unit string do this ...
@@ -781,17 +812,12 @@ module RubyUnits
     # @param [Object] other
     # @return [Boolean]
     def =~(other)
-      case other
-      when Unit
-        signature == other.signature
-      else
-        begin
-          x, y = coerce(other)
-          x =~ y
-        rescue ArgumentError
-          false
-        end
-      end
+      return signature == other.signature if other.is_a?(Unit)
+
+      x, y = coerce(other)
+      x =~ y
+    rescue ArgumentError # return false when `other` cannot be converted to a [Unit]
+      false
     end
 
     alias compatible? =~
@@ -941,27 +967,50 @@ module RubyUnits
       end
     end
 
-    # divide two units and return quotient and remainder
-    # when both units are in the same units we just use divmod on the raw scalars
-    # otherwise we use the scalar of the base unit which will be a float
-    # @param [Object] other
-    # @return [Array]
+    # Returns the remainder when one unit is divided by another
+    #
+    # @param [Unit] other
+    # @return [Unit]
+    # @raise [ArgumentError] if units are not compatible
+    def remainder(other)
+      raise ArgumentError, "Incompatible Units ('#{self}' not compatible with '#{other}')" unless compatible_with?(other)
+
+      self.class.new(base_scalar.remainder(other.to_unit.base_scalar), to_base.units).convert_to(self)
+    end
+
+    # Divide two units and return quotient and remainder
+    #
+    # @param [Unit] other
+    # @return [Array(Integer, Unit)]
+    # @raise [ArgumentError] if units are not compatible
     def divmod(other)
-      raise ArgumentError, "Incompatible Units ('#{self}' not compatible with '#{other}')" unless self =~ other
-      return scalar.divmod(other.scalar) if units == other.units
+      raise ArgumentError, "Incompatible Units ('#{self}' not compatible with '#{other}')" unless compatible_with?(other)
 
-      to_base.scalar.divmod(other.to_base.scalar)
+      [quo(other).to_base.floor, self % other]
     end
 
-    # perform a modulo on a unit, will raise an exception if the units are not compatible
-    # @param [Object] other
+    # Perform a modulo on a unit, will raise an exception if the units are not compatible
+    #
+    # @param [Unit] other
     # @return [Integer]
+    # @raise [ArgumentError] if units are not compatible
     def %(other)
-      divmod(other).last
+      raise ArgumentError, "Incompatible Units ('#{self}' not compatible with '#{other}')" unless compatible_with?(other)
+
+      self.class.new(base_scalar % other.to_unit.base_scalar, to_base.units).convert_to(self)
+    end
+    alias modulo %
+
+    # @param [Object] other
+    # @return [Unit]
+    # @raise [ZeroDivisionError] if other is zero
+    def quo(other)
+      self / other
     end
+    alias fdiv quo
 
     # Exponentiation.  Only takes integer powers.
-    # Note that anything raised to the power of 0 results in a Unit object with a scalar of 1, and no units.
+    # Note that anything raised to the power of 0 results in a [Unit] object with a scalar of 1, and no units.
     # Throws an exception if exponent is not an integer.
     # Ideally this routine should accept a float for the exponent
     # It should then convert the float to a rational and raise the unit by the numerator and root it by the denominator
@@ -990,7 +1039,7 @@ module RubyUnits
       when Float
         return self**other.to_i if other == other.to_i
 
-        valid = (1..9).map { |n| Rational(1, n) }
+        valid = (1..9).map { Rational(1, _1) }
         raise ArgumentError, 'Not a n-th root (1..9), use 1/n' unless valid.include? other.abs
 
         root(Rational(1, other).to_int)
@@ -1029,23 +1078,23 @@ module RubyUnits
       raise ArgumentError, 'Exponent must an Integer' unless n.is_a?(Integer)
       raise ArgumentError, '0th root undefined' if n.zero?
       return self if n == 1
-      return root(n.abs).inverse if n < 0
+      return root(n.abs).inverse if n.negative?
 
       vec = unit_signature_vector
-      vec = vec.map { |x| x % n }
+      vec = vec.map { _1 % n }
       raise ArgumentError, 'Illegal root' unless vec.max.zero?
 
       num = @numerator.dup
       den = @denominator.dup
 
       @numerator.uniq.each do |item|
-        x = num.find_all { |i| i == item }.size
+        x = num.find_all { _1 == item }.size
         r = ((x / n) * (n - 1)).to_int
         r.times { num.delete_at(num.index(item)) }
       end
 
       @denominator.uniq.each do |item|
-        x = den.find_all { |i| i == item }.size
+        x = den.find_all { _1 == item }.size
         r = ((x / n) * (n - 1)).to_int
         r.times { den.delete_at(den.index(item)) }
       end
@@ -1102,7 +1151,7 @@ module RubyUnits
         return self if target_unit == start_unit
 
         # @type [Numeric]
-        @base_scalar ||= case @@unit_map[start_unit]
+        @base_scalar ||= case self.class.unit_map[start_unit]
                          when '<tempC>'
                            @scalar + 273.15
                          when '<tempK>'
@@ -1113,7 +1162,7 @@ module RubyUnits
                            @scalar.to_r * Rational(5, 9)
                          end
         # @type [Numeric]
-        q = case @@unit_map[target_unit]
+        q = case self.class.unit_map[target_unit]
             when '<tempC>'
               @base_scalar - 273.15
             when '<tempK>'
@@ -1138,10 +1187,10 @@ module RubyUnits
 
         raise ArgumentError, "Incompatible Units ('#{self}' not compatible with '#{other}')" unless self =~ target
 
-        numerator1   = @numerator.map { |x| @@prefix_values[x] || x }.map { |i| i.is_a?(Numeric) ? i : @@unit_values[i][:scalar] }.compact
-        denominator1 = @denominator.map { |x| @@prefix_values[x] || x }.map { |i| i.is_a?(Numeric) ? i : @@unit_values[i][:scalar] }.compact
-        numerator2   = target.numerator.map { |x| @@prefix_values[x] || x }.map { |x| x.is_a?(Numeric) ? x : @@unit_values[x][:scalar] }.compact
-        denominator2 = target.denominator.map { |x| @@prefix_values[x] || x }.map { |x| x.is_a?(Numeric) ? x : @@unit_values[x][:scalar] }.compact
+        numerator1   = @numerator.map { self.class.prefix_values[_1] || _1 }.map { _1.is_a?(Numeric) ? _1 : self.class.unit_values[_1][:scalar] }.compact
+        denominator1 = @denominator.map { self.class.prefix_values[_1] || _1 }.map { _1.is_a?(Numeric) ? _1 : self.class.unit_values[_1][:scalar] }.compact
+        numerator2   = target.numerator.map { self.class.prefix_values[_1] || _1 }.map { _1.is_a?(Numeric) ? _1 : self.class.unit_values[_1][:scalar] }.compact
+        denominator2 = target.denominator.map { self.class.prefix_values[_1] || _1 }.map { _1.is_a?(Numeric) ? _1 : self.class.unit_values[_1][:scalar] }.compact
 
         # If the scalar is an Integer, convert it to a Rational number so that
         # if the value is scaled during conversion, resolution is not lost due
@@ -1216,26 +1265,26 @@ module RubyUnits
       den                = @denominator.clone.compact
 
       unless num == UNITY_ARRAY
-        definitions = num.map { |element| self.class.definition(element) }
+        definitions = num.map { self.class.definition(_1) }
         definitions.reject!(&:prefix?) unless with_prefix
         definitions = definitions.chunk_while { |definition, _| definition.prefix? }.to_a
-        output_numerator = definitions.map { |element| element.map(&:display_name).join }
+        output_numerator = definitions.map { _1.map(&:display_name).join }
       end
 
       unless den == UNITY_ARRAY
-        definitions = den.map { |element| self.class.definition(element) }
+        definitions = den.map { self.class.definition(_1) }
         definitions.reject!(&:prefix?) unless with_prefix
         definitions = definitions.chunk_while { |definition, _| definition.prefix? }.to_a
-        output_denominator = definitions.map { |element| element.map(&:display_name).join }
+        output_denominator = definitions.map { _1.map(&:display_name).join }
       end
 
       on  = output_numerator
             .uniq
-            .map { |x| [x, output_numerator.count(x)] }
+            .map { [_1, output_numerator.count(_1)] }
             .map { |element, power| (element.to_s.strip + (power > 1 ? "^#{power}" : '')) }
       od  = output_denominator
             .uniq
-            .map { |x| [x, output_denominator.count(x)] }
+            .map { [_1, output_denominator.count(_1)] }
             .map { |element, power| (element.to_s.strip + (power > 1 ? "^#{power}" : '')) }
       "#{on.join('*')}#{od.empty? ? '' : "/#{od.join('*')}"}".strip
     end
@@ -1414,19 +1463,16 @@ module RubyUnits
     alias after from
     alias from_now from
 
-    # automatically coerce objects to units when possible
-    # if an object defines a 'to_unit' method, it will be coerced using that method
+    # Automatically coerce objects to [Unit] when possible. If an object defines a '#to_unit' method, it will be coerced
+    # using that method.
+    #
     # @param other [Object, #to_unit]
-    # @return [Array]
+    # @return [Array(Unit, Unit)]
+    # @raise [ArgumentError] when `other` cannot be converted to a [Unit]
     def coerce(other)
-      return [other.to_unit, self] if other.respond_to? :to_unit
+      return [other.to_unit, self] if other.respond_to?(:to_unit)
 
-      case other
-      when Unit
-        [other, self]
-      else
-        [self.class.new(other), self]
-      end
+      [self.class.new(other), self]
     end
 
     # returns a new unit that has been scaled to be more in line with typical usage.
@@ -1434,11 +1480,11 @@ module RubyUnits
       return to_base if scalar.zero?
 
       best_prefix = if kind == :information
-                      @@prefix_values.key(2**((::Math.log(base_scalar, 2) / 10.0).floor * 10))
+                      self.class.prefix_values.key(2**((::Math.log(base_scalar, 2) / 10.0).floor * 10))
                     else
-                      @@prefix_values.key(10**((::Math.log10(base_scalar) / 3.0).floor * 3))
+                      self.class.prefix_values.key(10**((::Math.log10(base_scalar) / 3.0).floor * 3))
                     end
-      to(self.class.new(@@prefix_map.key(best_prefix) + units(with_prefix: false)))
+      to(self.class.new(self.class.prefix_map.key(best_prefix) + units(with_prefix: false)))
     end
 
     # override hash method so objects with same values are considered equal
@@ -1475,18 +1521,19 @@ module RubyUnits
     # @raise [ArgumentError] when exponent associated with a unit is > 20 or < -20
     def unit_signature_vector
       return to_base.unit_signature_vector unless base?
+
       vector = ::Array.new(SIGNATURE_VECTOR.size, 0)
       # it's possible to have a kind that misses the array... kinds like :counting
       # are more like prefixes, so don't use them to calculate the vector
-      @numerator.map { |element| self.class.definition(element) }.each do |definition|
+      @numerator.map { self.class.definition(_1) }.each do |definition|
         index = SIGNATURE_VECTOR.index(definition.kind)
         vector[index] += 1 if index
       end
-      @denominator.map { |element| self.class.definition(element) }.each do |definition|
+      @denominator.map { self.class.definition(_1) }.each do |definition|
         index = SIGNATURE_VECTOR.index(definition.kind)
         vector[index] -= 1 if index
       end
-      raise ArgumentError, 'Power out of range (-20 < net power of a unit < 20)' if vector.any? { |x| x.abs >= 20 }
+      raise ArgumentError, 'Power out of range (-20 < net power of a unit < 20)' if vector.any? { _1.abs >= 20 }
 
       vector
     end
@@ -1534,27 +1581,45 @@ module RubyUnits
       unit_string = "#{Regexp.last_match(1)} USD" if unit_string =~ /\$\s*(#{NUMBER_REGEX})/
       unit_string.gsub!("\u00b0".force_encoding('utf-8'), 'deg') if unit_string.encoding == Encoding::UTF_8
 
-      unit_string.gsub!(/[%'"#]/, '%' => 'percent', "'" => 'feet', '"' => 'inch', '#' => 'pound')
+      unit_string.gsub!(/(\d)[_,](\d)/, '\1\2') # remove underscores and commas in numbers
 
-      if defined?(Complex) && unit_string =~ COMPLEX_NUMBER
-        real, imaginary, unit_s = unit_string.scan(COMPLEX_REGEX)[0]
-        result                  = self.class.new(unit_s || '1') * Complex(real.to_f, imaginary.to_f)
+      unit_string.gsub!(/[%'"#]/, '%' => 'percent', "'" => 'feet', '"' => 'inch', '#' => 'pound')
+      if unit_string.start_with?(COMPLEX_NUMBER)
+        match = unit_string.match(COMPLEX_REGEX)
+        real = Float(match[:real]) if match[:real]
+        imaginary = Float(match[:imaginary])
+        unit_s = match[:unit]
+        real = real.to_i if real.to_i == real
+        imaginary = imaginary.to_i if imaginary.to_i == imaginary
+        complex = Complex(real || 0, imaginary)
+        complex = complex.to_i if complex.imaginary.zero? && complex.real == complex.real.to_i
+        result = self.class.new(unit_s || 1) * complex
         copy(result)
         return
       end
 
-      if defined?(Rational) && unit_string =~ RATIONAL_NUMBER
-        sign, proper, numerator, denominator, unit_s = unit_string.scan(RATIONAL_REGEX)[0]
-        sign = sign == '-' ? -1 : 1
-        rational = sign * (proper.to_i + Rational(numerator.to_i, denominator.to_i))
-        result = self.class.new(unit_s || '1') * rational
+      if unit_string.start_with?(RATIONAL_NUMBER)
+        match = unit_string.match(RATIONAL_REGEX)
+        numerator = Integer(match[:numerator])
+        denominator = Integer(match[:denominator])
+        raise ArgumentError, 'Improper fractions must have a whole number part' if !match[:proper].nil? && !match[:proper].match?(/^#{INTEGER_REGEX}$/)
+
+        proper = match[:proper].to_i
+        unit_s = match[:unit]
+        rational = if proper.negative?
+                     (proper - Rational(numerator, denominator))
+                   else
+                     (proper + Rational(numerator, denominator))
+                   end
+        rational = rational.to_int if rational.to_int == rational
+        result = self.class.new(unit_s || 1) * rational
         copy(result)
         return
       end
 
-      unit_string =~ NUMBER_REGEX
-      unit = self.class.cached.get(Regexp.last_match(2))
-      mult = Regexp.last_match(1).nil? ? 1.0 : Regexp.last_match(1).to_f
+      match = unit_string.match(NUMBER_REGEX)
+      unit = self.class.cached.get(match[:unit])
+      mult = match[:scalar] == '' ? 1.0 : match[:scalar].to_f
       mult = mult.to_int if mult.to_int == mult
 
       if unit
@@ -1564,52 +1629,70 @@ module RubyUnits
         return self
       end
 
-      while unit_string.gsub!(/(<#{@@unit_regex})><(#{@@unit_regex}>)/, '\1*\2')
+      while unit_string.gsub!(/(<#{self.class.unit_regex})><(#{self.class.unit_regex}>)/, '\1*\2')
         # collapse <x><y><z> into <x*y*z>...
       end
       # ... and then strip the remaining brackets for x*y*z
       unit_string.gsub!(/[<>]/, '')
 
-      if unit_string =~ TIME_REGEX
-        hours, minutes, seconds, microseconds = unit_string.scan(TIME_REGEX)[0]
-        raise ArgumentError, 'Invalid Duration' if [hours, minutes, seconds, microseconds].all?(&:nil?)
+      if (match = unit_string.match(TIME_REGEX))
+        hours = match[:hour]
+        minutes = match[:min]
+        seconds = match[:sec]
+        milliseconds = match[:msec]
+        raise ArgumentError, 'Invalid Duration' if [hours, minutes, seconds, milliseconds].all?(&:nil?)
 
-        result = self.class.new("#{hours || 0} h") +
+        result = self.class.new("#{hours || 0} hours") +
                  self.class.new("#{minutes || 0} minutes") +
                  self.class.new("#{seconds || 0} seconds") +
-                 self.class.new("#{microseconds || 0} usec")
+                 self.class.new("#{milliseconds || 0} milliseconds")
         copy(result)
         return
       end
 
       # Special processing for unusual unit strings
       # feet -- 6'5"
-      feet, inches = unit_string.scan(FEET_INCH_REGEX)[0]
-      if feet && inches
-        result = self.class.new("#{feet} ft") + self.class.new("#{inches} inches")
+      if (match = unit_string.match(FEET_INCH_REGEX))
+        feet = Integer(match[:feet])
+        inches = match[:inches]
+        result = if feet.negative?
+                   self.class.new("#{feet} ft") - self.class.new("#{inches} inches")
+                 else
+                   self.class.new("#{feet} ft") + self.class.new("#{inches} inches")
+                 end
         copy(result)
         return
       end
 
       # weight -- 8 lbs 12 oz
-      pounds, oz = unit_string.scan(LBS_OZ_REGEX)[0]
-      if pounds && oz
-        result = self.class.new("#{pounds} lbs") + self.class.new("#{oz} oz")
+      if (match = unit_string.match(LBS_OZ_REGEX))
+        pounds = Integer(match[:pounds])
+        oz = match[:oz]
+        result = if pounds.negative?
+                   self.class.new("#{pounds} lbs") - self.class.new("#{oz} oz")
+                 else
+                   self.class.new("#{pounds} lbs") + self.class.new("#{oz} oz")
+                 end
         copy(result)
         return
       end
 
       # stone -- 3 stone 5, 2 stone, 14 stone 3 pounds, etc.
-      stone, pounds = unit_string.scan(STONE_LB_REGEX)[0]
-      if stone && pounds
-        result = self.class.new("#{stone} stone") + self.class.new("#{pounds} lbs")
+      if (match = unit_string.match(STONE_LB_REGEX))
+        stone = Integer(match[:stone])
+        pounds = match[:pounds]
+        result = if stone.negative?
+                   self.class.new("#{stone} stone") - self.class.new("#{pounds} lbs")
+                 else
+                   self.class.new("#{stone} stone") + self.class.new("#{pounds} lbs")
+                 end
         copy(result)
         return
       end
 
       # more than one per.  I.e., "1 m/s/s"
       raise(ArgumentError, "'#{passed_unit_string}' Unit not recognized") if unit_string.count('/') > 1
-      raise(ArgumentError, "'#{passed_unit_string}' Unit not recognized") if unit_string =~ /\s[02-9]/
+      raise(ArgumentError, "'#{passed_unit_string}' Unit not recognized #{unit_string}") if unit_string =~ /\s[02-9]/
 
       @scalar, top, bottom = unit_string.scan(UNIT_STRING_REGEX)[0] # parse the string into parts
       top.scan(TOP_REGEX).each do |item|
@@ -1617,7 +1700,7 @@ module RubyUnits
         x = "#{item[0]} "
         if n >= 0
           top.gsub!(/#{item[0]}(\^|\*\*)#{n}/) { x * n }
-        elsif n < 0
+        elsif n.negative?
           bottom = "#{bottom} #{x * -n}"
           top.gsub!(/#{item[0]}(\^|\*\*)#{n}/, '')
         end
@@ -1652,11 +1735,11 @@ module RubyUnits
       raise(ArgumentError, "'#{passed_unit_string}' Unit not recognized") unless used.empty?
 
       @numerator = @numerator.map do |item|
-        @@prefix_map[item[0]] ? [@@prefix_map[item[0]], @@unit_map[item[1]]] : [@@unit_map[item[1]]]
+        self.class.prefix_map[item[0]] ? [self.class.prefix_map[item[0]], self.class.unit_map[item[1]]] : [self.class.unit_map[item[1]]]
       end.flatten.compact.delete_if(&:empty?)
 
       @denominator = @denominator.map do |item|
-        @@prefix_map[item[0]] ? [@@prefix_map[item[0]], @@unit_map[item[1]]] : [@@unit_map[item[1]]]
+        self.class.prefix_map[item[0]] ? [self.class.prefix_map[item[0]], self.class.unit_map[item[1]]] : [self.class.unit_map[item[1]]]
       end.flatten.compact.delete_if(&:empty?)
 
       @numerator = UNITY_ARRAY if @numerator.empty?