unit_measurements 5.11.1 → 5.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 299b2e4f1e3ebfedd82a18f0010b1aef87e464a00b17bb0fdccbd3d1d1d43807
-  data.tar.gz: a80df705e041ae39d0008e8f4e58b792850fc0b5cd74c4983846e02a371b7216
+  metadata.gz: 98def91ad4bff4c38e579a967b82ae5467e52db044246e6c91d00ccee9ea8070
+  data.tar.gz: 5e7c0aca97692daf71dc1923aabfca63f99ccfa0e246e1ec83665c8f821eb784
 SHA512:
-  metadata.gz: 5c01c9a8d9b7fd6f3315b8befea0d852cb3e9c8ba8b2866975f60055c697f5fbb8af8fb7844f94144ca1b3919107bc8fb4570945974a1a62568febe1d665cd61
-  data.tar.gz: 880f955b5cf1ff30c51247ed3338a68ed78b4a9d416d9f7a594ca377b403749f5c3fad8b1515c56b2cf5b2656ddaa7b4759bad8ca38e8b383043b12b1853b597
+  metadata.gz: e9a2f7bb789161cdd305eeec424d8b60eaf50c0ce6daa6868699c872ed5abf6bd06ba7fb9d5ae6cdb2d9021c837081553b984d29fb67b75c03af46e1f0b36fd2
+  data.tar.gz: 6098f3468240de037f7a39ec5f0a4ea8e431379523bee2da921f5dbe17368ea772d545e41e187341dfb48749168895a3d24d2a89c70e0b10dc18d9fe2656932a

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [5.13.0](https://github.com/shivam091/unit_measurements/compare/v5.12.0...v5.13.0) - 2023-11-27
+
+### What's new
+
+- Added `Measurement#to_primitive` to convert the measurement to the primitive unit.
+- Added `#cbrt` method to calculate cube root of the measurement quantity.
+- Added `#sqrt` method to calculate square root of the measurement quantity.
+- Aliased `#to_primitive` method as `#in_primitive` and `#as_primitive`.
+
+----------
+
+## [5.12.0](https://github.com/shivam091/unit_measurements/compare/v5.11.1...v5.12.0) - 2023-11-25
+
+### What's new
+
+- Added `MissingPrimitiveUnitError` error if user tries to convert measurement to
+  the primitive unit but it's not set for the unit group.
+- Aliased `#+` method as `#add`.
+- Aliased `#-` method as `#subtract`.
+- Aliased `#*` method as `#times` and `#multiply`.
+- Aliased `#/` method as `#divide`.
+
+----------
+
 ## [5.11.1](https://github.com/shivam091/unit_measurements/compare/v5.11.0...v5.11.1) - 2023-11-16
 
 ### What's changed

data/Gemfile.lock

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

data/README.md

@@ -116,10 +116,12 @@ UnitMeasurements::Length.new(1, "km").convert_to!("m")
 You can convert the measurement directly to the `primitive` unit of the unit group as:
 
 ```ruby
-UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
+UnitMeasurements::Length.new(1, "cm").to_primitive
 #=> 0.01 m
 ```
 
+Note: `#to_primitive` method is aliased as `#in_primitive` and `#as_primitive`.
+
 **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.
@@ -444,7 +446,7 @@ unit group using the `primitive` method. You can specify cache file name in unit
 
 ```ruby
 UnitMeasurements::MyUnitGroup = UnitMeasurements.build do
-  # Set primitive unit for the unit group (optional).
+  # Set primitive unit for the unit group.
   primitive "s"
 
   # Group units by the unit system (optional).

data/lib/unit_measurements/arithmetic.rb

@@ -41,6 +41,7 @@ module UnitMeasurements
     def +(other)
       arithmetic_operation(other, :+)
     end
+    alias_method :add, :+
 
     # Subtracts the quantity of the other measurement or a numeric value from the
     # quantity of the current measurement.
@@ -62,6 +63,7 @@ module UnitMeasurements
     def -(other)
       arithmetic_operation(other, :-)
     end
+    alias_method :subtract, :-
 
     # Multiplies the quantity of the current measurement by the quantity of the
     # other measurement or a numeric value.
@@ -84,6 +86,8 @@ module UnitMeasurements
       arithmetic_operation(other, :*)
     end
     alias_method :scale, :*
+    alias_method :times, :*
+    alias_method :multiply, :*
 
     # Divides the quantity of the current measurement by the quantity of the other
     # measurement or a numeric value.
@@ -105,6 +109,7 @@ module UnitMeasurements
     def /(other)
       arithmetic_operation(other, :/)
     end
+    alias_method :divide, :/
 
     # Raises the quantity of the current measurement to the power of the quantity of
     # the other measurement or numeric value.

data/lib/unit_measurements/base.rb

@@ -16,10 +16,13 @@ require "unit_measurements/version"
 module UnitMeasurements
   # This is the base class for custom errors in the +UnitMeasurements+ module.
   #
+  # @see UnitError
   # @see ParseError
-  # @see PrimitiveUnitAlreadySetError
+  # @see BlankUnitError
+  # @see BlankQuantityError
   # @see UnitAlreadyDefinedError
-  # @see UnitError
+  # @see MissingPrimitiveUnitError
+  # @see PrimitiveUnitAlreadySetError
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.1.0
   class BaseError < StandardError; end
@@ -168,3 +171,4 @@ 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"
+require "unit_measurements/errors/missing_primitive_unit_error"

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

@@ -87,5 +87,34 @@ module UnitMeasurements
     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

data/lib/unit_measurements/measurement.rb

@@ -131,15 +131,11 @@ module UnitMeasurements
     #   UnitMeasurements::Length.new(1, "m").convert_to("cm")
     #   => 100.0 cm
     #
-    #   UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
-    #   => 0.01 m
-    #
-    #   UnitMeasurements::Length.new(1, "m").convert_to("cm", use_cache: true)
-    #   => 100.0 cm
+    #   UnitMeasurements::Length.new(1, "m").convert_to("mm", use_cache: true)
+    #   => 1000.0 cm
     #
     # @param [String|Symbol] target_unit
-    #   The target unit for conversion. Specifing +primitive+ will convert the
-    #   measurement to a primitive unit of the unit group.
+    #   The target unit for conversion.
     # @param [TrueClass|FalseClass] use_cache
     #   Indicates whether to use cached conversion factors.
     #
@@ -150,11 +146,7 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def convert_to(target_unit, use_cache: false)
-      target_unit = if target_unit.to_s.eql?("primitive")
-        self.class.unit_group.primitive
-      else
-        unit_from_unit_or_name!(target_unit)
-      end
+      target_unit = unit_from_unit_or_name!(target_unit)
       return self if target_unit == unit
 
       conversion_factor = calculate_conversion_factor(target_unit, use_cache)
@@ -171,15 +163,11 @@ module UnitMeasurements
     #   UnitMeasurements::Length.new(1, "m").convert_to!("cm")
     #   => 100.0 cm
     #
-    #   UnitMeasurements::Length.new(1, "cm").convert_to!("primitive")
-    #   => 0.01 m
-    #
-    #   UnitMeasurements::Length.new(1, "m").convert_to!("cm", use_cache: true)
-    #   => 100.0 cm
+    #   UnitMeasurements::Length.new(1, "m").convert_to!("mm", use_cache: true)
+    #   => 1000.0 mm
     #
     # @param [String|Symbol] target_unit
-    #   The target unit for conversion. Specifing +primitive+ will convert the
-    #   measurement to a primitive unit of the unit group.
+    #   The target unit for conversion.
     # @param [TrueClass|FalseClass] use_cache
     #   Indicates whether to use cached conversion factors.
     #
@@ -199,6 +187,41 @@ module UnitMeasurements
     alias_method :in!, :convert_to!
     alias_method :as!, :convert_to!
 
+    # Converts the measurement to its primitive unit and returns a new instance
+    # of the +Measurement+.
+    #
+    # The method first retrieves the primitive unit of the unit group associated
+    # with the measurement. If the primitive unit is not set, it raises a
+    # +MissingPrimitiveUnitError+.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(1, "m").to_primitive
+    #   => 1 m
+    #
+    #   UnitMeasurements::Length.new(1, "cm").to_primitive
+    #   => 0.01 m
+    #
+    # @param [TrueClass|FalseClass] use_cache
+    #   Indicates whether to use cached conversion factors.
+    # @return [Measurement]
+    #   A new +Measurement+ instance representing the measurement in its
+    #   primitive unit.
+    #
+    # @raise [MissingPrimitiveUnitError]
+    #   If the primitive unit is not set for the unit group associated with the
+    #   measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.13.0
+    def to_primitive(use_cache: false)
+      primitive_unit = self.class.primitive
+      raise MissingPrimitiveUnitError if primitive_unit.nil?
+
+      convert_to(primitive_unit, use_cache: use_cache)
+    end
+    alias_method :in_primitive, :to_primitive
+    alias_method :as_primitive, :to_primitive
+
     # Returns an object representation of the +Measurement+.
     #
     # @param [TrueClass|FalseClass] dump If +true+, returns the dump representation.
@@ -474,7 +497,7 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def unit_from_unit_or_name!(value)
-      value.is_a?(Unit) ? value : self.class.send(:unit_group).unit_for!(value)
+      value.is_a?(Unit) ? value : self.class.unit_for!(value)
     end
 
     # Calculates the conversion factor between the current unit and the target

data/lib/unit_measurements/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.11.1
+  version: 5.13.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2023-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -113,6 +113,7 @@ files:
 - 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/missing_primitive_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