unit_measurements_us_complete 5.17.0

data/lib/unit_measurements/conversion.rb

@@ -0,0 +1,92 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Conversion+ mixin module defines methods for converting
+  # quantity of the measurement to various numeric types. These methods allow for
+  # flexibility in handling measurements in different numeric formats.
+  #
+  # This module is included into the +Measurement+ class to allow conversion of
+  # the measurement quantity to other numeric types.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.7.0
+  module Conversion
+    # Converts quantity of the measurement to +Integer+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2.25567, "km").to_i
+    #   => 2 km
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to an +Integer+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
+    def to_i
+      self.class.new(quantity.to_i, unit)
+    end
+
+    # Converts quantity of the measurement to +Float+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2.25567, "km").to_f
+    #   => 2.25567 km
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Float+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
+    def to_f
+      self.class.new(quantity.to_f, unit)
+    end
+
+    # Converts quantity of the measurement to +Rational+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2.25567, "km").to_r
+    #   => 225567/100000 km
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Rational+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
+    def to_r
+      self.class.new(quantity.to_r, unit)
+    end
+
+    # Converts quantity of the measurement to +Complex+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2.25567, "km").to_c
+    #   => 2.25567+0i km
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +Complex+ number.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
+    def to_c
+      self.class.new(quantity.to_c, unit)
+    end
+
+    # Converts quantity of the measurement to +BigDecimal+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2.25567, "km").to_d
+    #   => 2.25567 km
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the quantity converted to a +BigDecimal+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.7.0
+    def to_d
+      self.class.new(quantity.to_d, unit)
+    end
+  end
+end

data/lib/unit_measurements/errors/blank_quantity_error.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::BlankQuantityError+ class represents an error that
+  # occurs when trying to initialize the +Measurement+ with a blank quantity.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.10.0
+  class BlankQuantityError < BaseError
+    # Initializes a new +BlankQuantityError+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.10.0
+    def initialize
+      super("Quantity cannot be blank.")
+    end
+  end
+end

data/lib/unit_measurements/errors/blank_unit_error.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::BlankUnitError+ class represents an error that
+  # occurs when trying to initialize the +Measurement+ with a blank unit.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.10.0
+  class BlankUnitError < BaseError
+    # Initializes a new +BlankUnitError+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.10.0
+    def initialize
+      super("Unit cannot be blank.")
+    end
+  end
+end

data/lib/unit_measurements/errors/missing_primitive_unit_error.rb

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::MissingPrimitiveUnitError+ class represents an error
+  # that occurs when the primitive unit is not set for a unit group.
+  #
+  # This error is raised when a user attempts to convert a measurement to the
+  # primitive unit of a unit group that does not have a primitive unit defined.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.12.0
+  class MissingPrimitiveUnitError < BaseError
+    # Initializes a new +MissingPrimitiveUnitError+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.12.0
+    def initialize
+      super("The primitive unit is not set for the unit group.")
+    end
+  end
+end

data/lib/unit_measurements/errors/parse_error.rb

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::ParseError+ class is used to represent an error
+  # condition where the library encounters difficulty in parsing a given string.
+  # This can occur due to invalid or unexpected input formats.
+  #
+  # The error message states that the parser encountered an error while parsing
+  # and provides the string that caused the parsing error.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
+  class ParseError < BaseError
+    # The input string that caused the error while parsing.
+    #
+    # @return [String] The input string that caused the error while parsing.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :string
+
+    # Initializes a new +ParseError+ instance.
+    #
+    # @param [String] string The input string that caused the error while parsing.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def initialize(string)
+      @string = string
+
+      super("Unable to parse: '#{string}'.")
+    end
+  end
+end

data/lib/unit_measurements/errors/primitive_unit_already_set_error.rb

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::PrimitiveUnitAlreadySetError+ class represents an
+  # error that occurs when attempting to set a primitive unit for the unit group
+  # that already has a primitive unit defined.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 4.0.0
+  class PrimitiveUnitAlreadySetError < BaseError
+    # Initializes a new +PrimitiveUnitAlreadySetError+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 4.0.0
+    def initialize
+      super("The primitive unit is already set for the unit group.")
+    end
+  end
+end

data/lib/unit_measurements/errors/unit_already_defined_error.rb

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::UnitAlreadyDefinedError+ class is used to indicate
+  # that an attempt was made to define a unit that has already been defined
+  # within a unit group.
+  #
+  # The error message states that the unit is already defined and provides the
+  # name of the conflicting unit.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
+  class UnitAlreadyDefinedError < BaseError
+    # The name of the unit that is already defined.
+    #
+    # @return [String] The name of the unit that is already defined.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :unit
+
+    # Initializes a new +UnitAlreadyDefinedError+ instance.
+    #
+    # @param [String] unit The name of the unit that is already defined.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def initialize(unit)
+      @unit = unit
+
+      super("Unit already defined: '#{unit}'.")
+    end
+  end
+end

data/lib/unit_measurements/errors/unit_error.rb

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::UnitError+ class is used to indicate that an invalid
+  # unit was encountered. The error message states that the unit is invalid and
+  # provides the name of the problematic unit.
+  #
+  # This error is raised when the unit is not defined within the unit group.
+  #
+  # @see BaseError
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.0.0
+  class UnitError < BaseError
+    # The name of the invalid unit.
+    #
+    # @return [String] The name of the invalid unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    attr_reader :unit
+
+    # Initializes a new +UnitError+ instance.
+    #
+    # @param [String] unit The name of the invalid unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
+    def initialize(unit)
+      @unit = unit
+
+      super("Invalid unit: '#{unit}'.")
+    end
+  end
+end

data/lib/unit_measurements/extras/conversion_methods.rb

@@ -0,0 +1,87 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # This module provides functionality to define conversion methods for a list
+  # of units within a unit group. If units are empty, it defaults to defining
+  # methods for all units in the unit group. These methods allow easy conversion
+  # between different units within a given unit group.
+  #
+  # This module is included in the +Measurement+ class to allow defining conversion
+  # methods for specified units.
+  #
+  # @see Measurement
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.15.0
+  module ConversionMethods
+    # @scope class
+    # Defines conversion methods for specified +units+ within the unit group.
+    # If +units+ are empty, it defaults to defining methods for all units within
+    # the unit group.
+    #
+    # @example Define conversion methods for metres, centimetres, and millimetres:
+    #   UnitMeasurements::Length.define_conversion_methods("metres", :cm, :mm)
+    #
+    # @example Define conversion methods for all units within the unit group:
+    #   UnitMeasurements::Length.define_conversion_methods
+    #
+    # @param [Array<String|Symbol>, optional] units
+    #   An array of units' names for which conversion methods need to be defined.
+    #   If empty, methods will be defined for all units within the unit group.
+    #
+    # @return [Array<Unit>]
+    #   An array of units for which the conversion methods were defined.
+    #
+    # @note
+    #   This method defines a conversion methods specifically for units that contain
+    #   alphabetic characters in their names.
+    #
+    # @see .define_conversion_method_for
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.15.0
+    def define_conversion_methods(*units)
+      unit_group = self
+      units = units.empty? ? unit_group.units : units
+
+      units.inject([]) do |units, unit|
+        units << define_conversion_method_for(unit, unit_group)
+      end
+    end
+
+    private
+
+    # @private
+    # @scope class
+    # Defines conversion methods for a specific +unit+ within a +unit_group+.
+    # These methods are defined dynamically using +define_method+.
+    #
+    # @param [String|Symbol|Unit] unit
+    #   The unit (or its name) for which the conversion methods need to be defined.
+    # @param [UnitGroup] unit_group The unit group to which the unit belongs.
+    #
+    # @return [Unit]
+    #   The unit instance for which the conversion methods were defined.
+    #
+    # @see .define_conversion_methods
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.15.0
+    def define_conversion_method_for(unit, unit_group)
+      unit = unit.is_a?(Unit) ? unit : unit_group.unit_for!(unit)
+
+      unit.names.each do |method_name|
+        # Check if the name contains alphabetic characters
+        next unless method_name =~ /^[a-zA-Z]+$/
+
+        define_method("in_#{method_name}") do |use_cache: false|
+          convert_to(unit, use_cache: use_cache)
+        end
+        alias_method "to_#{method_name}", "in_#{method_name}"
+        alias_method "as_#{method_name}", "in_#{method_name}"
+      end
+
+      unit
+    end
+  end
+end

data/lib/unit_measurements/extras/numeric_methods.rb

@@ -0,0 +1,85 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # This module provides methods to define +Numeric+ methods for a list of units
+  # within a unit group. If units are empty, it defaults to defining methods for
+  # all units in the unit group.
+  #
+  # This module is included in the +Measurement+ class to allow defining numeric
+  # methods for specified units.
+  #
+  # @see Measurement
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.14.0
+  module NumericMethods
+    # @scope class
+    # Defines +Numeric+ methods for specified +units+ within the unit group. If
+    # +units+ are empty, it defaults to defining methods for all units within
+    # the unit group.
+    #
+    # @example Define numeric methods for metres, centimetres, and millimetres:
+    #   UnitMeasurements::Length.define_numeric_methods("metres", :cm, :mm)
+    #
+    # @example Define numeric methods for all units within the unit group:
+    #   UnitMeasurements::Length.define_numeric_methods
+    #
+    # @param [Array<String|Symbol>, optional] units
+    #   An array of units' names for which numeric methods need to be defined.
+    #   If empty, methods will be defined for all units within the unit group.
+    #
+    # @return [Array<Unit>] An array of units for which numeric methods were defined.
+    #
+    # @note
+    #   This method defines a numeric methods specifically for units that contain
+    #   alphabetic characters in their names.
+    #
+    # @see .define_numeric_method_for
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.14.0
+    def define_numeric_methods(*units)
+      unit_group = self
+      units = units.empty? ? unit_group.units : units
+
+      units.inject([]) do |units, unit|
+        units << define_numeric_method_for(unit, unit_group)
+      end
+    end
+
+    private
+
+    # @private
+    # @scope class
+    # Defines a numeric method for a specific +unit+ within a +unit_group+. The
+    # method is defined dynamically using +define_method+ and associates the unit
+    # with the numeric value.
+    #
+    # @param [String|Symbol|Unit] unit
+    #   The unit (or its name) for which the numeric method needs to be defined.
+    # @param [UnitGroup] unit_group The unit group to which the unit belongs.
+    #
+    # @return [Unit] The unit instance for which the method was defined.
+    #
+    # @see .define_numeric_methods
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.14.0
+    def define_numeric_method_for(unit, unit_group)
+      unit = unit.is_a?(Unit) ? unit : unit_group.unit_for!(unit)
+
+      unit.names.each do |method_name|
+        # Check if the name contains alphabetic characters
+        next unless method_name =~ /^[a-zA-Z]+$/
+
+        Numeric.define_method(method_name) do
+          unit_group.new(self, unit)
+        end
+      end
+
+      unit
+    end
+  end
+end

data/lib/unit_measurements/formatter.rb

@@ -0,0 +1,58 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Formatter+ mixin module contains methods for formatting
+  # measurements into human-readable strings. It provides the ability to customize
+  # the output format based on user-defined preferences.
+  #
+  # This module is included in the +Measurement+ class to allow customization of
+  # the output of the measurements.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.1.0
+  module Formatter
+    # The default format used for formatting measurements. It is a format string
+    # containing placeholders for +quantity+ and +unit+.
+    DEFAULT_FORMAT = "%.2<quantity>f %<unit>s".freeze
+
+    # @deprecated This method has been deprecated in favour of {#to_fs}.
+    #
+    # This method is no longer recommended for use. Please use {#to_fs}
+    # instead.
+    def format(format = nil)
+      warn "DEPRECATION WARNING: The `format` method is deprecated and will be removed in upcoming release. Please use `to_fs` instead."
+      to_fs(format)
+    end
+
+    # Formats measurement to certain formatted string specified by +format+.
+    # If +format+ is not specified, it uses {DEFAULT_FORMAT} for formatting the
+    # measurement.
+    #
+    # The {#to_fs} method allows for customization of the output format of a
+    # measurement. It uses format placeholders for +quantity+ and +unit+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").to("in").to_fs
+    #   => "39.37 in"
+    #
+    #   UnitMeasurements::Length.new(1, "m").to("in").to_fs("%.4<quantity>f %<unit>s")
+    #   => "39.3701 in"
+    #
+    # @param [String, optional] format
+    #   The custom format string for formatting the measurement. If not provided,
+    #   +DEFAULT_FORMAT+ is used.
+    #
+    # @return [String] A formatted string representing the measurement.
+    #
+    # @see DEFAULT_FORMAT
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.10.0
+    def to_fs(format = nil)
+      kwargs = {quantity: quantity, unit: unit.to_s}
+      (format || DEFAULT_FORMAT) % kwargs
+    end
+  end
+end

data/lib/unit_measurements/math.rb

@@ -0,0 +1,120 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Math+ mixin module provides methods for performing
+  # mathematical functions on the measurement.
+  #
+  # This module is included in the +Measurement+ class to allow mathematical
+  # functions on the measurement.
+  #
+  # @see Measurement
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 1.6.0
+  module Math
+    # Rounds quantity of the measurement. If +ndigits+ is not specified, quantity
+    # is rounded to +Integer+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(17.625, "m").round
+    #   => 18 m
+    #
+    #   UnitMeasurements::Length.new(17.625, "m").round(2)
+    #   => 17.63 m
+    #
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the rounded quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def round(ndigits = 0)
+      self.class.new(quantity.round(ndigits), unit)
+    end
+
+    # Returns absolute value of the measurement quantity.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(-17.625, "m").abs
+    #   => 17.625 m
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with the absolute value of the quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def abs
+      self.class.new(quantity.abs, unit)
+    end
+
+    # Returns floored quantity of the measurement. If +ndigits+ is not specified,
+    # quantity is rounded to next lower +Integer+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(17.625, "m").floor
+    #   => 17 m
+    #
+    #   UnitMeasurements::Length.new(17.625, "m").floor(2)
+    #   => 17.62 m
+    #
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the floored quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def floor(ndigits = 0)
+      self.class.new(quantity.floor(ndigits), unit)
+    end
+
+    # Returns ceiled quantity of the measurement. If +ndigits+ is not specified,
+    # quantity is rounded to next higher +Integer+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(17.625, "m").ceil
+    #   => 18 m
+    #
+    #   UnitMeasurements::Length.new(17.625, "m").ceil(2)
+    #   => 17.63 m
+    #
+    # @param [Integer, optional] ndigits The number of digits to round to.
+    #
+    # @return [Measurement] A new +Measurement+ instance with the ceiled quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.6.0
+    def ceil(ndigits = 0)
+      self.class.new(quantity.ceil(ndigits), unit)
+    end
+
+    # Returns square root of the measurement quantity.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(9, "m").sqrt
+    #   => 3.0 m
+    #
+    # @return [Measurement] A new +Measurement+ instance with square root of quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.13.0
+    def sqrt
+      self.class.new((quantity ** Rational(1, 2)), unit)
+    end
+
+    # Returns cube root of the measurement quantity.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(27, "m").cbrt
+    #   => 3.0 m
+    #
+    # @return [Measurement]
+    #   A new +Measurement+ instance with cube root of quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.13.0
+    def cbrt
+      self.class.new((quantity ** Rational(1, 3)), unit)
+    end
+  end
+end