unit_measurements_us_complete 5.17.0

data/lib/unit_measurements/parser.rb

@@ -0,0 +1,220 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_stringing_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Parser+ class provides methods for parsing strings to
+  # extract quantity and associated unit. It can handle various formats, including
+  # complex numbers, scientific numbers, and rational numbers for the +quantity+.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
+  class Parser
+    # Matches any character sequence that does not consist of digits, whitespace,
+    # or forward slashes.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    UNIT_REGEX        = /
+                          (                    # Start of the capturing group
+                            [^\d\s\/]          # Match any character that is not a digit, whitespace, or a forward slash
+                            .*                 # Match zero or more of any character (except for a newline)
+                          )                    # End of the capturing group
+                        /x.freeze
+
+    # Matches scientific numbers (e.g., +1.23e-4+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    SCIENTIFIC_NUMBER = /
+                          (                    # Start of a capturing group (denoted by parentheses)
+                            [+-]?              # Match an optional plus or minus sign (+ or -)
+                            \d*                # Match zero or more digits
+                            \.?                # Match an optional dot (.)
+                            \d+                # Match one or more digits
+                            (?:                # Start of a non-capturing group
+                              [Ee]             # Match either 'E' or 'e'
+                              [+-]?            # Match an optional plus or minus sign (+ or -)
+                            )?                 # End of the non-capturing group; ? makes it optional
+                            \d*                # Match zero or more digits
+                          )                    # End of the capturing group
+                        /x.freeze
+
+    # Matches rational numbers (e.g., +1/2+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    RATIONAL_NUMBER   = /
+                          (                    # Start of the first capturing group
+                            [+-]?              # Match an optional plus or minus sign (+ or -)
+                            \d+                # Match one or more digits
+                            \s+                # Match one or more whitespace characters
+                          )?                   # End of the first capturing group
+                          (                    # Start of the second capturing group (the fraction part)
+                            (\d+)              # Start of the third capturing group (one or more digits, the numerator)
+                            \/                 # Match a forward slash - the division symbol
+                            (\d+)              # Start of the fourth capturing group (one or more digits, the denominator)
+                          )                    # End of the second capturing group (the fraction part)
+                        /x.freeze
+
+    # Matches complex numbers (e.g., +1-2i+).
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    COMPLEX_NUMBER    = /
+                          #{SCIENTIFIC_NUMBER} # Pattern for scientific number
+                          #{SCIENTIFIC_NUMBER} # Pattern for scientific number
+                          i                    # Match the letter 'i' (the imaginary unit)
+                        /x.freeze
+
+    # Matches strings containing scientific numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    SCIENTIFIC_REGEX  = /
+                          \A                   # Anchor at the start of the string
+                          #{SCIENTIFIC_NUMBER} # Match a scientific number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z                   # Anchor at the end of the string
+                        /x.freeze
+
+    # Matches strings containing rational numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    RATIONAL_REGEX    = /
+                          \A                   # Anchor at the start of the string
+                          #{RATIONAL_NUMBER}   # Match a rational number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z
+                        /x.freeze
+
+    # Matches strings containing complex numbers and unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    COMPLEX_REGEX     = /
+                          \A                   # Anchor at the start of the string
+                          #{COMPLEX_NUMBER}    # Match a complex number (as defined earlier)
+                          \s*                  # Match zero or more whitespace characters
+                          #{UNIT_REGEX}?       # Match a unit, the '?' makes it optional
+                          \z
+                        /x.freeze
+
+    class << self
+      # Parses a string to extract a +quantity+ and its associated +unit+. This
+      # method first extracts a +quantity+ and converts it to +Float+ before
+      # returning it.
+      #
+      # To get the correct parsed results, you must first normalize the +string+
+      # with +Normalizer+ if using the parser standalone.
+      #
+      # @example Parsing string representing a complex number:
+      #   UnitMeasurements::Parser.parse("1+2i m")
+      #   => [(1.0+2.0i), "m"]
+      #
+      # @example Parsing string representing a rational number:
+      #   UnitMeasurements::Parser.parse("1/2 m")
+      #   => [0.5, "m"]
+      #
+      # @example Parsing string representing a mixed rational number:
+      #   UnitMeasurements::Parser.parse("2 1/2 km")
+      #   => [2.5, "km"]
+      #
+      # @example Parsing string representing a scientific number:
+      #   UnitMeasurements::Parser.parse("1e+2 km")
+      #   => [100.0, "km"]
+      #
+      # @param [String] string
+      #   The input string containing a +quantity+ and an optional +unit+.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed +quantity+ and the +unit+ associated with it (or +nil+ if
+      #   no unit is specified in the +string+).
+      #
+      # @raise [ParseError] If the string is invalid and cannot be parsed.
+      #
+      # @see Measurement
+      # @see Normalizer
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def parse(string)
+        case string
+        when COMPLEX_REGEX    then parse_complex(string)
+        when SCIENTIFIC_REGEX then parse_scientific(string)
+        when RATIONAL_REGEX   then parse_rational(string)
+        else                       raise ParseError, string
+        end
+      end
+
+      private
+
+      # @private
+      # Parses a string representing a complex number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a complex number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed complex number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def parse_complex(string)
+        real, imaginary, unit = string.match(COMPLEX_REGEX)&.captures
+        quantity = Complex(real.to_f, imaginary.to_f)
+
+        [quantity, unit]
+      end
+
+      # @private
+      # Parses a string representing a scientific number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a scientific number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed scientific number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def parse_scientific(string)
+        whole, unit = string.match(SCIENTIFIC_REGEX)&.captures
+        quantity = whole.to_f
+
+        [quantity, unit]
+      end
+
+      # @private
+      # Parses a string representing a rational number with an optional unit.
+      #
+      # @param [String] string
+      #   The input string containing a rational number and an optional unit.
+      #
+      # @return [Array<Numeric, String|NilClass>]
+      #   The parsed rational number and the associated unit (or +nil+ if no unit
+      #   is specified in the string).
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 1.0.0
+      def parse_rational(string)
+        whole, _, numerator, denominator, unit = string.match(RATIONAL_REGEX)&.captures
+
+        if numerator && denominator
+          numerator = numerator.to_f + (denominator.to_f * whole.to_f)
+          denominator = denominator.to_f
+          quantity = Rational(numerator, denominator).to_f
+        else
+          quantity = whole.to_f
+        end
+
+        [quantity, unit]
+      end
+    end
+  end
+end

data/lib/unit_measurements/unit.rb

@@ -0,0 +1,243 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+require "set"
+
+module UnitMeasurements
+  # The +UnitMeasurements::Unit+ class represents a unit of measurement and
+  # provides methods to interact with its properties and conversion factors.
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
+  class Unit
+    # The name of the unit.
+    #
+    # @return [String] Name of the unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :name
+
+    # The conversion value of the unit. It can be a numeric value or a string in
+    # the form of a number followed by a unit name (e.g., “10 m”).
+    #
+    # @return [String|Numeric|Array<Numeric, String>]
+    #   Conversion value of the unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :value
+
+    # A set of alternative names for the unit.
+    #
+    # @return [Set<String>] A set of alternative names.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :aliases
+
+    # The system to which the unit belongs (e.g., “metric”, “imperial”).
+    #
+    # @return [String] Unit system in which the unit belongs.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 4.0.0
+    attr_reader :system
+
+    # The unit group to which the unit belongs.
+    #
+    # @return [UnitGroup] Unit group in which the unit belongs.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :unit_group
+
+    # Initializes a new +Unit+ instance.
+    #
+    # @param [String|Symbol] name The name of the unit.
+    # @param [String|Numeric] value The conversion value of the unit.
+    # @param [Array<String|Symbol>] aliases Alternative names for the unit.
+    # @param [String|Symbol|NilClass] system The system to which the unit belongs.
+    # @param [UnitGroup|NilClass] unit_group The unit group to which the unit belongs.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def initialize(name, value:, aliases:, system:, unit_group: nil)
+      @name = name.to_s.freeze
+      @value = value
+      @aliases = Set.new(aliases.map(&:to_s).sort.map(&:freeze)).freeze
+      @system = system.to_s.freeze
+      @unit_group = unit_group
+    end
+
+    # Returns a new +Unit+ instance with specified attributes.
+    #
+    # @param [String|Symbol] name The new name of the unit.
+    # @param [String|Numeric] value The new conversion value of the unit.
+    # @param [Set<String>] aliases New alternative names for the unit.
+    # @param [String|Symbol|NilClass] system The new system to which the unit belongs.
+    # @param [UnitGroup|NilClass] unit_group The new unit group to which the unit belongs.
+    #
+    # @return [Unit] A new unit with specified parameters.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def with(name: nil, value: nil, aliases: nil, system: nil, unit_group: nil)
+      self.class.new(
+        (name || self.name),
+        value: (value || self.value),
+        aliases: (aliases || self.aliases),
+        system: (system || self.system),
+        unit_group: (unit_group || self.unit_group)
+      )
+    end
+
+    # Returns an array containing the name of the unit and its aliases, sorted
+    # alphabetically.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").unit.names
+    #   => ["m", "meter", "meters", "metre", "metres"]
+    #
+    # @return [Array<String>] An array of unit names.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def names
+      (aliases + [name]).sort.freeze
+    end
+
+    # Returns the name of the unit as a string.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").unit.to_s
+    #   => "m"
+    #
+    # @return [String] The name of the unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def to_s
+      name
+    end
+
+    # Returns an object representation of the unit, including its aliases if present.
+    #
+    # @return [Object] An object representation of the +unit+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def inspect
+      aliases = "(#{@aliases.join(", ")})" if @aliases.any?
+      "#<#{self.class.name}: #{name} #{aliases}>"
+    end
+
+    # Calculates the conversion factor for the unit. This method is recursively
+    # invoked to calculate the conversion factor of the unit, if unit conversion
+    # +value+ is specified with respect to the other unit.
+    #
+    # This method uses +parse_value+ method to extract the conversion value and
+    # the unit.
+    #
+    # @return [Numeric] The conversion factor as a numeric value.
+    #
+    # @see #parse_value
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def conversion_factor
+      return value if value.is_a?(Numeric)
+
+      measurement_value, measurement_unit = parse_value(value)
+      conversion_factor = unit_group.unit_for!(measurement_unit).conversion_factor
+
+      conversion_factor * measurement_value
+    end
+
+    private
+
+    # Binary prefixes for SI units.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.0.0
+    SI_BINARY_PREFIXES = [
+      ["Ki", %w[kibi], 2.pow(10)],
+      ["Mi", %w[mebi], 2.pow(20)],
+      ["Gi", %w[gibi], 2.pow(30)],
+      ["Ti", %w[tebi], 2.pow(40)],
+      ["Pi", %w[pebi], 2.pow(50)],
+      ["Ei", %w[exbi], 2.pow(60)],
+      ["Zi", %w[zebi], 2.pow(70)],
+      ["Yi", %w[yobi], 2.pow(80)],
+    ].map(&:freeze).freeze
+
+    # Decimal prefixes for SI units.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    SI_DECIMAL_PREFIXES = [
+      ["q",  %w[quecto],    1e-30],
+      ["r",  %w[ronto],     1e-27],
+      ["y",  %w[yocto],     1e-24],
+      ["z",  %w[zepto],     1e-21],
+      ["a",  %w[atto],      1e-18],
+      ["f",  %w[femto],     1e-15],
+      ["p",  %w[pico],      1e-12],
+      ["n",  %w[nano],      1e-9],
+      ["μ",  %w[micro],     1e-6],
+      ["m",  %w[milli],     1e-3],
+      ["c",  %w[centi],     1e-2],
+      ["d",  %w[deci],      1e-1],
+      ["da", %w[deca deka], 1e+1],
+      ["h",  %w[hecto],     1e+2],
+      ["k",  %w[kilo],      1e+3],
+      ["M",  %w[mega],      1e+6],
+      ["G",  %w[giga],      1e+9],
+      ["T",  %w[tera],      1e+12],
+      ["P",  %w[peta],      1e+15],
+      ["E",  %w[exa],       1e+18],
+      ["Z",  %w[zetta],     1e+21],
+      ["Y",  %w[yotta],     1e+24],
+      ["R",  %w[ronna],     1e+27],
+      ["Q",  %w[quetta],    1e+30]
+    ].map(&:freeze).freeze
+
+    # Parses tokens and returns a +conversion value+ and the +unit+.
+    #
+    # This method is used internally to parse the conversion value of the unit
+    # while calculating the conversion factor. It handles cases where the value
+    # can be provided as a string or an array containing a number and a unit.
+    #
+    # For example, if the value is provided as a string in the form of "10 m",
+    # it will be parsed to return 10.0 as the conversion value and "m" as the
+    # unit.
+    #
+    # This method returns conversion value in +rational+ number to avoid precision
+    # errors and frozen string of unit name.
+    #
+    # @param [String|Array] tokens
+    #   The value to be parsed. It can be either a string or an array containing
+    #   a number and a unit.
+    #
+    # @return [Array<Numeric, String>] The array of conversion value and the unit.
+    #
+    # @raise [BaseError]
+    #   if +tokens+ is not an instance of +Array+ or +String+, or +tokens+ array
+    #   contains more than two elements.
+    #
+    # @see #conversion_factor
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.2.0
+    def parse_value(tokens)
+      case tokens
+      when String
+        tokens = Parser.parse(value)
+      when Array
+        raise BaseError, "Cannot parse [number, unit] formatted tokens from #{tokens}." unless tokens.size == 2
+      else
+        raise BaseError, "Value of the unit must be defined as string or array, but received #{tokens}"
+      end
+      [tokens[0].to_r, tokens[1].freeze]
+    end
+  end
+end