unit_measurements 5.12.0 → 5.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e01978467f274548e8cf792d9b7bfe26ab85155a2c099482cb8b4017641ed900
-  data.tar.gz: d09990112a19291527059e822906a802a051541b654babad13e97110c5557dea
+  metadata.gz: d59abc6cd3128c515be37c2e7bcc40cbbaa73530a4a5ed1ce6d5e7093202e063
+  data.tar.gz: 22091e2ce789b4a064fb0f06fb704805b69cc86601334ab4d9f8a7afe9c6a0fd
 SHA512:
-  metadata.gz: 0faa94f0a962f19134ff58276c6c876a30a81817172039c4261eaa9a15eeb61dd7047f61b96168c2115c4ba40711fee42cb4ceb832c6e6640bd9c8e7e0f4343b
-  data.tar.gz: d9213995299feeb51dda98cc4dbbd3bd76f6c4782a8e04b9612cc7f3134b192c74aa80b027779c1b8c862358a84a8c40469753a086ceb94fd5b5ee2b8d33e973
+  metadata.gz: 4e16e3e25e06d155664fab616cf4e3147d75cf4aef71c15c6312572418fd124d11436c402fbe7e83e984e483c737a073ad180947f0ee071fab170a59c8f880a4
+  data.tar.gz: b6e6bd19810a115b48d7107859b82e21d8b5dc231455d8a995a9ea5157c44d38c53c287a15945a342f1b376fcfe80b539de29ad1be9ca112e5750ac866013cbc

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [5.14.0](https://github.com/shivam091/unit_measurements/compare/v5.13.0...v5.14.0) - 2023-11-29
+
+### What's new
+
+- Added `.define_numeric_methods` support to define numeric extension methods for units.
+
+----------
+
+## [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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements (5.12.0)
+    unit_measurements (5.14.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).
@@ -480,6 +482,31 @@ Length = UnitMeasurements::Length
 Volume = UnitMeasurements::Volume
 ```
 
+## Extras
+
+### Numeric extension methods
+
+The `.define_numeric_methods` method allows you to instantiate measurements in a
+manner similar to how `ActiveSupport::Duration` objects are created in Rails,
+providing a familiar syntax and functionality.
+
+To define numeric extension methods for specific units within a unit group, use
+the following syntax:
+
+```ruby
+UnitMeasurements::Length.define_numeric_methods("metre", "foot", "inch")
+```
+
+This will enable the usage of these units as methods to instantiate and use measurements:
+
+```ruby
+1.m                 #=> Instantiate a measurement representing 1 metre.
+5.feet              #=> Instantiate a measurement representing 5 feet.
+10.inches           #=> Instantiate a measurement representing 10 inches.
+1.foot == 12.inches #=> equality comparison between two measurements.
+1.ft + 12.in        #=> adds quantity of two measurements.
+```
+
 ## Contributing
 
 1. Fork it

data/lib/unit_measurements/base.rb

@@ -151,6 +151,8 @@ module UnitMeasurements
 end
 
 # The following requires load various components of the unit measurements library.
+require "unit_measurements/extras/numeric_methods"
+
 require "unit_measurements/configuration"
 require "unit_measurements/cache"
 require "unit_measurements/unit_group_builder"

data/lib/unit_measurements/extras/numeric_methods.rb

@@ -0,0 +1,81 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # This module provides methods to define +Numeric+ extension 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
+  # extension methods for specified units.
+  #
+  # @see Measurement
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.14.0
+  module NumericMethods
+    # @scope class
+    # Defines +Numeric+ extension methods for specified units within the unit
+    # group. If units are empty, it defaults to defining methods for all units
+    # within the unit group.
+    #
+    # @param [Array<String|Symbol>] units
+    #   An array of units' names for which numeric methods need to be defined.
+    #   If empty, methods will be defined for all units in the unit group.
+    #
+    # @return [Array<Unit>] An array of units for which methods are defined.
+    #
+    # @example Define numeric methods for metres, centimetres, and millimetres:
+    #   UnitMeasurements::Length.define_numeric_methods("metres", :cm, :mm)
+    #
+    # @example Define numeric methods for all units in the unit group:
+    #   UnitMeasurements::Length.define_numeric_methods
+    #
+    # @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
+    # This method 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 for which the numeric method is 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/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

@@ -23,6 +23,7 @@ module UnitMeasurements
   # @see Conversion
   # @see Formatter
   # @see Math
+  # @see NumericMethods
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.0.0
   class Measurement
@@ -32,6 +33,8 @@ module UnitMeasurements
     include Formatter
     include Math
 
+    extend NumericMethods
+
     # Regular expression to match conversion strings.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
@@ -131,15 +134,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.
     #
@@ -147,20 +146,10 @@ module UnitMeasurements
     #   A new +Measurement+ instance with the converted +quantity+ and
     #   +target unit+.
     #
-    # @raise [MissingPrimitiveUnitError]
-    #   if primitive unit is not set for the unit group.
-    #
     # @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")
-        primitive_unit = self.class.primitive
-
-        raise MissingPrimitiveUnitError if primitive_unit.nil?
-        primitive_unit
-      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)
@@ -177,15 +166,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.
     #
@@ -205,6 +190,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.

data/lib/unit_measurements/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.12.0
+  version: 5.14.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-25 00:00:00.000000000 Z
+date: 2023-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -118,6 +118,7 @@ files:
 - lib/unit_measurements/errors/primitive_unit_already_set_error.rb
 - lib/unit_measurements/errors/unit_already_defined_error.rb
 - lib/unit_measurements/errors/unit_error.rb
+- lib/unit_measurements/extras/numeric_methods.rb
 - lib/unit_measurements/formatter.rb
 - lib/unit_measurements/math.rb
 - lib/unit_measurements/measurement.rb