unit_measurements 5.9.0 → 5.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08305aaf9558055931b73b625212941d80d625e042933de660624d1786af7bc9'
-  data.tar.gz: 28b9f54eeb207abef81d9d908b040e1e1da4e7426c1f69d0be2332f3611c0d16
+  metadata.gz: ca26bc8965c93c692a72e788ab2577f2bad297909372a72d3cc2fec93a45b5bd
+  data.tar.gz: 581d716cb56cf59c89eeb69d01095c4c0c14054006dc6bb0822580e3d6750ffd
 SHA512:
-  metadata.gz: b2e8e679fff2e9590c5c8a3f4a72da21ad58c216d0556154529b5e5ad9cab92f78f4dc2ec7c8f7297653755c5cadbd8e246546b7092b983b14c824ccd5acf3ff
-  data.tar.gz: 006037a17c4b9616550757994f7e384b2344a3fc6651a05243cf19e4e326101bfdb90cb9075e070c54759c9a113d853a43157c1333994b0e4b088db3e2cfb504
+  metadata.gz: ed994225ecb853f8ce577e0b53a863b0f091980ee33f054b50f69d156ad0a7e393a4a59d962d665aa52fa6cdc077f19f42bc27d0b1d8e7413f359dbde8e6a9fb
+  data.tar.gz: 889e45c784390c89a46079067ca9493253e638b1117ee88c16c5ab2ed60db89a855a11bf487f2a6536b1729a2704983fbfcb5fa60959a2b8eed79dae4957d920

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [5.11.0](https://github.com/shivam091/unit_measurements/compare/v5.10.0...v5.11.0) - 2023-11-11
+
+### What's new
+
+- Added `#systems` method to return unit systems within the unit group.
+- Added `#ratio` method to calculate the ratio between two units.
+
+----------
+
+## [5.10.0](https://github.com/shivam091/unit_measurements/compare/v5.9.0...v5.10.0) - 2023-11-09
+
+### What's new
+
+- Added new method `#to_fs` to format the measurement.
+- Aliased arithmetic method `#**` to `#pow` and `#^`.
+- Aliased arithmetic method `#-@` to `#inverse` and `#negate`.
+- Added `UnitMeasurements::BlankQuantityError` error if tried to initialize the `Measurement` with a blank quantity.
+- Added `UnitMeasurements::BlankUnitError` error if tried to initialize the `Measurement` with a blank unit.
+
+### What's deprecated
+
+- `#format` method in favour of `#to_fs`.
+
+----------
+
 ## [5.9.0](https://github.com/shivam091/unit_measurements/compare/v5.8.0...v5.9.0) - 2023-11-08
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements (5.9.0)
+    unit_measurements (5.11.0)
       activesupport (~> 7.0)
 
 GEM

data/README.md

@@ -95,6 +95,7 @@ UnitMeasurements::Length.new(1, "km")
 
 This gem allows you to convert among units of same unit group. You can convert measurement to other unit using `#convert_to`
 (aliased as `#to`, `#in`, and `#as`) or `#convert_to!` (aliased as `#to!`, `#in!`, and `#as!`) methods.
+You can also chain call of `#convert_to` and `#convert_to!` methods.
 
 These methods provide `use_cache` parameter which defaults to `false` to indicate whether the caching of conversion factors should happen.
 
@@ -119,13 +120,6 @@ UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
 #=> 0.01 m
 ```
 
-You can also chain call of `#convert_to` and `#convert_to!` methods as:
-
-```ruby
-UnitMeasurements::Length.new(100, "m").convert_to("ft").convert_to!("in", use_cache: true)
-#=> 3937.00787401574071916010498688 in
-```
-
 **Parse string without having to split out the quantity and source unit:**
 
 This method provides `use_cache` parameter which defaults to `false` to indicate whether the caching of conversion factors should happen.
@@ -185,6 +179,13 @@ UnitMeasurements::Length.parse("1:2 km to m")
 #=> 500.0 m
 ```
 
+**Calculate the ratio between two units:**
+
+```ruby
+UnitMeasurements::Length.ratio("in", "ft")
+#=> "12.0 in/ft"
+```
+
 **Formatting measurement:**
 
 If you want to format the measurement to certain format, you can use `#to_fs` method.
@@ -198,7 +199,7 @@ UnitMeasurements::Length.new(100, "m").to("in").to_fs("%.4<quantity>f %<unit>s")
 You can check more about formatting along with their examples
 [here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Formatter.html).
 
-**Extract the unit and the quantity from measurement:**
+**Extract the quantity and the unit from measurement:**
 
 ```ruby
 length = UnitMeasurements::Length.new(1, "km")
@@ -208,6 +209,15 @@ length.unit
 #=> #<UnitMeasurements::Unit: km (kilometer, kilometers, kilometre, kilometres)>
 ```
 
+Unit object can be interrogated for a range of attributes:
+
+```ruby
+length.unit.aliases # Alternative names for the unit.
+#=> #<Set: {"kilometer", "kilometers", "kilometre", "kilometres"}>
+length.unit.conversion_factor # Conversion factor relative to primitive unit.
+#=> 1000.0
+```
+
 **See primitive unit of the unit group:**
 
 ```ruby
@@ -236,6 +246,13 @@ UnitMeasurements::Length.unit_names_with_aliases
 #=> ["\"", "'", "feet", "foot", "ft", "in", "inch", "inches", "m", "meter", "meters", "metre", "metres", "mi", "mile", "miles", "yard", "yards", "yd"]
 ```
 
+**See list of unit systems defined within the unit group:**
+
+```ruby
+UnitMeasurements::Length.systems
+#=> ["metric", "imperial", "us_customary", "astronomical"]
+```
+
 **See list of units within the unit system:**
 
 You can use `#units_for` or `#units_for!` methods to find units within the unit system.

data/lib/unit_measurements/arithmetic.rb

@@ -134,6 +134,8 @@ module UnitMeasurements
     def **(other)
       arithmetic_operation(other, :**)
     end
+    alias_method :pow, :**
+    alias_method :^, :**
 
     # Negates the quantity of the measurement.
     #
@@ -151,6 +153,8 @@ module UnitMeasurements
     def -@
       self.class.new(-self.quantity, self.unit)
     end
+    alias_method :inverse, :-@
+    alias_method :negate, :-@
 
     # Checks whether the quantity of the measurement is nonzero.
     #

data/lib/unit_measurements/base.rb

@@ -148,3 +148,5 @@ require "unit_measurements/errors/unit_error"
 require "unit_measurements/errors/parse_error"
 require "unit_measurements/errors/unit_already_defined_error"
 require "unit_measurements/errors/primitive_unit_already_set_error"
+require "unit_measurements/errors/blank_quantity_error"
+require "unit_measurements/errors/blank_unit_error"

data/lib/unit_measurements/configuration.rb

@@ -55,7 +55,7 @@ module UnitMeasurements
     # @since 5.3.0
     def use_cache=(use_cache)
       unless [true, false].include?(use_cache)
-        raise BaseError, "Configuration#use_cache= only accepts true or false, but received #{use_cache}"
+        raise ArgumentError, "Configuration#use_cache= only accepts true or false, but received #{use_cache}"
       end
 
       @use_cache = use_cache

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/formatter.rb

@@ -18,19 +18,27 @@ module UnitMeasurements
     # 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
+    # If +format+ is not specified, it uses {DEFAULT_FORMAT} for formatting the
     # measurement.
     #
-    # The format method allows for customization of the output format of a
-    # measurement. It uses format placeholders for +quantity+ and +unit+. If no
-    # custom format is provided, it will use the +DEFAULT_FORMAT+.
+    # 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").format
+    #   UnitMeasurements::Length.new(1, "m").to("in").to_fs
     #   => "39.37 in"
     #
-    #   UnitMeasurements::Length.new(1, "m").to("in").format("%.4<quantity>f %<unit>s")
+    #   UnitMeasurements::Length.new(1, "m").to("in").to_fs("%.4<quantity>f %<unit>s")
     #   => "39.3701 in"
     #
     # @param [String, optional] format
@@ -41,10 +49,9 @@ module UnitMeasurements
     #
     # @see DEFAULT_FORMAT
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
-    # @since 1.1.0
-    def format(format = nil)
+    # @since 5.10.0
+    def to_fs(format = nil)
       kwargs = {quantity: quantity, unit: unit.to_s}
-
       (format || DEFAULT_FORMAT) % kwargs
     end
   end

data/lib/unit_measurements/math.rb

@@ -64,7 +64,7 @@ module UnitMeasurements
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.6.0
-    def floor(ndigits =0)
+    def floor(ndigits = 0)
       self.class.new(quantity.floor(ndigits), unit)
     end
 
@@ -84,7 +84,7 @@ module UnitMeasurements
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.6.0
-    def ceil(ndigits =0)
+    def ceil(ndigits = 0)
       self.class.new(quantity.ceil(ndigits), unit)
     end
   end

data/lib/unit_measurements/measurement.rb

@@ -104,14 +104,16 @@ module UnitMeasurements
     # @param [Numeric|String] quantity The quantity of the measurement.
     # @param [String|Unit] unit The unit of the measurement.
     #
-    # @raise [BaseError] If +quantity+ or +unit+ is blank.
+    # @raise [BlankQuantityError] If +quantity+ is blank.
+    # @raise [BlankUnitError] If +unit+ is blank.
     #
-    # @see BaseError
+    # @see BlankQuantityError
+    # @see BlankUnitError
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def initialize(quantity, unit)
-      raise BaseError, "Quantity cannot be blank." if quantity.blank?
-      raise BaseError, "Unit cannot be blank." if unit.blank?
+      raise BlankQuantityError if quantity.blank?
+      raise BlankUnitError if unit.blank?
 
       @quantity = convert_quantity(quantity)
       @unit = unit_from_unit_or_name!(unit)
@@ -241,7 +243,7 @@ module UnitMeasurements
       def_delegators :unit_group, :primitive, :units, :cache_file, :unit_names,
                      :unit_with_name_and_aliases, :unit_names_with_aliases,
                      :unit_for, :unit_for!, :defined?, :unit_or_alias?, :[],
-                     :units_for, :units_for!
+                     :units_for, :units_for!, :systems
 
       # Parses an input string and returns a +Measurement+ instance depending on
       # the input string. This method first normalizes the +input+ internally,
@@ -366,6 +368,40 @@ module UnitMeasurements
         cached.clear_cache
       end
 
+      # Calculates the ratio between two units.
+      #
+      # This method takes a source unit and a target unit, and returns the ratio
+      # between them as a string representation.
+      #
+      # @example Calculating the ratio between 'in' and 'ft':
+      #   UnitMeasurements::Length.ratio("in", "ft")
+      #   => "12.0 in/ft"
+      #
+      #   UnitMeasurements::Length.ratio(UnitMeasurements::Length.unit_for("in"), "ft")
+      #   => "12.0 in/ft"
+      #
+      # @param [Unit|String|Symbol] source_unit
+      #   The source unit for the ratio calculation.
+      # @param [Unit|String|Symbol] target_unit
+      #   The target unit for the ratio calculation.
+      #
+      # @return [String] The ratio between the source and target units.
+      #
+      # @raise [UnitError]
+      #   If either the source unit or the target unit is not found in the unit group.
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 5.11.0
+      def ratio(source_unit, target_unit)
+        source_unit = source_unit.is_a?(Unit) ? source_unit : unit_for!(source_unit)
+        target_unit = target_unit.is_a?(Unit) ? target_unit : unit_for!(target_unit)
+
+        source_quantity = 1
+        target_quantity = new(source_quantity, target_unit).convert_to(source_unit).quantity
+
+        "#{target_quantity} #{source_unit}/#{target_unit}"
+      end
+
       private
 
       # @private

data/lib/unit_measurements/unit_group.rb

@@ -247,6 +247,22 @@ module UnitMeasurements
       system_units
     end
 
+    # Returns an array of unit system names defined within the unit group.
+    #
+    # It scans through the units and compiles a list of unique system names.
+    #
+    # @example
+    #   UnitMeasurements::Length.systems
+    #   => ["metric", "imperial", "us_customary", "astronomical"]
+    #
+    # @return [Array<String>] An array of unit system names.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.11.0
+    def systems
+      units.map { _1.system }.uniq
+    end
+
     private
 
     # @private

data/lib/unit_measurements/version.rb

@@ -4,5 +4,5 @@
 
 module UnitMeasurements
   # Current stable version.
-  VERSION = "5.9.0"
+  VERSION = "5.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.9.0
+  version: 5.11.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-08 00:00:00.000000000 Z
+date: 2023-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -111,6 +111,8 @@ files:
 - lib/unit_measurements/comparison.rb
 - lib/unit_measurements/configuration.rb
 - lib/unit_measurements/conversion.rb
+- lib/unit_measurements/errors/blank_quantity_error.rb
+- lib/unit_measurements/errors/blank_unit_error.rb
 - lib/unit_measurements/errors/parse_error.rb
 - lib/unit_measurements/errors/primitive_unit_already_set_error.rb
 - lib/unit_measurements/errors/unit_already_defined_error.rb