unit_measurements 5.0.0 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a7a4305ab13c8d9d8d52eaf7c9e4646757dc8eee71af5ec8314f6a2b702f929
-  data.tar.gz: 9cb9fc75b29f7745278ca27ce32fce621a29427e6e08202590eec52ff90c4e66
+  metadata.gz: 0a5ba942c1c99f76efc0db51ce916d31d199646d5bd2a5ace71b34fadbadacb2
+  data.tar.gz: 681c3ce17cebe41d715c78b25669afe6347d726405b4fcea74ffd8da3d5e9dc4
 SHA512:
-  metadata.gz: 46ddf50754159eb8dcaf4f753378fe19f912ac0d8316ecdd959b23620ed7ca2ef1a1122ce0a35d0a33bd0d643fbe7e6572a83348ca2faf3ab6815ce64c61e9d4
-  data.tar.gz: 9b84900e75d14377ebe58e8a21d75aaca6ae1329ce2be56768a7f24f4476782e27d8312fa65045c7398d6c67eb78ff2b01ea5b6da2263e53899eb21f015cb246
+  metadata.gz: 518cdb270f00447a0a7817e4db3bf8dbd83e6ed1ccdb82e58ef60579d774eff9f40544669b216ab42ee7133e23cf69f1ce149c7d051e8ffc3e147cc356361392
+  data.tar.gz: 239e100a9b733cbe1792ffc54c812a5fce1abecc2e449bdd03ee6215b84e72ad98eaaa1abec9d9e389deee515fef04cdef022e7c8fe6ab765c8b436eb4f0b0b2

data/.github/workflows/pages.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install Dependencies
         run: gem install yard
       - name: Generate Documentation
-        run: yardoc --private --exclude "unit_groups/*"
+        run: yardoc
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3.9.3
         with:

data/.yardopts

@@ -0,0 +1,2 @@
+--exclude unit_groups/*
+--private

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [5.1.1](https://github.com/shivam091/unit_measurements/compare/v5.1.0...v5.1.1) - 2023-10-20
+
+### What's updated
+
+- Updated readme and documentation.
+- Updated documentation hosting link to `https://shivam091.github.io/unit_measurements`.
+
+----------
+
+## [5.1.0](https://github.com/shivam091/unit_measurements/compare/v5.0.0...v5.1.0) - 2023-10-19
+
+### What's new
+
+- Added new methods (`**`, `-@`, `nonzero?`, `zero?`, `positive?`, `negative?`,
+  `finite?`, and `infinite?`) to perform arithmetic operations.
+- Added new alias `scale` for `**` arithmetic method.
+
+### What's updated
+
+- Updated readme and documentation.
+- Updated documentation hosting link to `https://rubydoc.info/gems/unit_measurements`.
+
+----------
+
 ## [5.0.0](https://github.com/shivam091/unit_measurements/compare/v4.12.0...v5.0.0) - 2023-10-18
 
 ### What's new

data/Gemfile.lock

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

data/README.md

@@ -22,19 +22,19 @@ to numerous errors.
 
 The `unit_measurements` gem is designed to simplify the handling of units for scientific calculations.
 
-## Advantages
+## Features
 
-1. It provides easy conversion between units.
-2. It is lightweight and easily extensible to include other units and conversions.
-3. It has built in support for various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
-4. It has well organized and very descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
-5. It can convert `complex`, `fractional`, `mixed fractional`, `scientific` numbers, and `ratios`.
+1. Provides easy conversion between units.
+2. Lightweight and easily extensible to include other units and conversions.
+3. Built in support for various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
+4. Well organized and very descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
+5. Parses strings representing complex, fractional, mixed fractional, scientific numbers, and ratios.
 
 ## Disclaimer
 
-_The unit conversions presented in `unit_measurements` are provided for reference and general informational purposes.
-While we aim to offer accurate conversions, we cannot guarantee their precision in all scenarios.
-Users are advised to cross-verify conversions as needed for their specific use cases._
+_The unit conversions provided here are for reference and general informational
+purposes. While we aim for accuracy, we cannot guarantee precision in all scenarios.
+Users are advised to cross-verify conversions for their specific use cases._
 
 ## Minimum Requirements
 
@@ -143,14 +143,8 @@ UnitMeasurements::Length.parse("2+3i km to m")
 ```ruby
 UnitMeasurements::Length.parse("2 ½ km").convert_to("m")
 #=> 2500.0 m
-UnitMeasurements::Length.parse("2/3 km").convert_to("m")
-#=> 666.666666666667 m
 UnitMeasurements::Length.parse("2/3 km to m")
 #=> 666.666666666667 m
-UnitMeasurements::Length.parse("2 1/2 km").convert_to("m")
-#=> 2500.0 m
-UnitMeasurements::Length.parse("2 ½ km to m")
-#=> 2500.0 m
 ```
 
 You can check supported special characters for fractional notations
@@ -159,8 +153,6 @@ You can check supported special characters for fractional notations
 **Parse ratios, source unit, and (or) target unit:**
 
 ```ruby
-UnitMeasurements::Length.new("1:2", "km").convert_to("m")
-#=> 500.0 m
 UnitMeasurements::Length.parse("1:2 km").convert_to("m")
 #=> 500.0 m
 UnitMeasurements::Length.parse("1:2 km to m")
@@ -173,12 +165,8 @@ If you want to format measurement to certain format, you can use `#format` metho
 If format is not specified, it defaults to `"%.2<value>f %<unit>s"`.
 
 ```ruby
-UnitMeasurements::Length.new(100, "m").to("in").format
-#=> "3937.01 in"
 UnitMeasurements::Length.new(100, "m").to("in").format("%.4<quantity>f %<unit>s")
 #=> "3937.0079 in"
-UnitMeasurements::Length.new(100, "m").to("in").format("%.4<quantity>f")
-#=> "3937.0079"
 ```
 
 You can check more about formatting along with their examples
@@ -244,8 +232,6 @@ UnitMeasurements::Length.unit_for("m")
 #=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>
 UnitMeasurements::Length.unit_for("z")
 #=> nil
-UnitMeasurements::Length.unit_for!("m")
-#=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>
 UnitMeasurements::Length.unit_for!("z")
 #=> Invalid unit: 'z'. (UnitMeasurements::UnitError)
 ```
@@ -329,10 +315,10 @@ The **`UnitMeasurements::Unit`** class is used to represent the units for a meas
 
 ### SI prefixed units
 
-There is support for SI prefixed units through the use of `si_unit` method.
-Units declared through it will have automatic support for all decimal SI prefixes.
-This method takes `add_binary_prefixes` parameter which can be set to true, if the
-unit supports binary SI prefixes along with decimal SI prefixes.
+Support for SI prefixed units is provided through the `si_unit` method. Units
+declared this way automatically support all decimal SI prefixes. This method takes
+an optional `add_binary_prefixes` parameter, which can be set to `true` if the
+unit supports binary SI prefixes in addition to decimal SI prefixes.
 
 #### Decimal SI prefixes
 
@@ -383,8 +369,7 @@ There are tons of units that are bundled in `unit_measurements`. You can check t
 
 ### Specifing units
 
-By default, `unit_measurements` ships with all the unit groups and this happens automatically
-when requiring the gem in the following manner.
+By default, `unit_measurements` includes all unit groups automatically when you require the gem using:
 
 ```ruby
 require "unit_measurements"
@@ -392,37 +377,22 @@ require "unit_measurements"
 
 **You can skip these unit groups and only [build your own unit groups](#building-new-unit-groups) by doing:**
 
-```ruby
-require "unit_measurements/base"
-```
-
-or simply
-
 ```ruby
 gem "unit_measurements", require: "unit_measurements/base"
 ```
 
 **You can also use unit groups in your application as per your need as:**
 
-```ruby
-require "unit_measurements/base"
-
-require "unit_measurements/unit_groups/length"
-```
-
-or
-
 ```ruby
 gem "unit_measurements", require: ["unit_measurements/base", "unit_measurements/unit_groups/length"]
 ```
 
 ### Building new unit groups
 
-This library provides simpler way to build your own unit groups. To build new unit group,
-use `UnitMeasurements.build` method in order to define units within it:
-
-For convenience, you also have ability to group units by the unit system using `system` method
-and set primitive unit for each unit group using `primitive` method.
+This library provides a simpler way to define your own unit groups. Use the
+`UnitMeasurements.build` method to define units within it. You can also group
+units by the unit system using the `system` method and set the primitive unit for
+ each unit group using the `primitive` method.
 
 ```ruby
 UnitMeasurements::Time = UnitMeasurements.build do
@@ -441,7 +411,7 @@ UnitMeasurements::Time = UnitMeasurements.build do
     unit "min", value: "60 s", aliases: ["hour", "hours"]
 
     # You can also specify unit value as an array.
-    unit :h, value: [60, "min"], aliases: ["day", "days"]
+    unit "h", value: [60, "min"], aliases: ["day", "days"]
   end
 end
 ```

data/lib/unit_measurements/arithmetic.rb

@@ -16,6 +16,11 @@ module UnitMeasurements
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 1.4.0
   module Arithmetic
+    extend Forwardable
+
+    # Methods delegated from the Numeric.
+    def_delegators :@quantity, :zero?, :positive?, :negative?, :finite?, :infinite?
+
     # Adds the quantity of the other measurement or a numeric value to the
     # quantity of the current measurement.
     #
@@ -78,6 +83,7 @@ module UnitMeasurements
     def *(other)
       arithmetic_operation(other, :*)
     end
+    alias_method :scale, :*
 
     # Divides the quantity of the current measurement by the quantity of the other
     # measurement or a numeric value.
@@ -100,6 +106,70 @@ module UnitMeasurements
       arithmetic_operation(other, :/)
     end
 
+    # Raises the quantity of the current measurement to the power of the quantity of
+    # the other measurement or numeric value.
+    #
+    # When +other+ is an instance of +Measurement+, the quantity to raise
+    # is calculated by converting the +other+ measurement to the unit of the +current+
+    # measurement, and then the quantity of the +current+ measurement is raised to
+    # the converted quantity.
+    #
+    # @param [Numeric|Measurement] other
+    #   The value to be raised. It can be a numeric value or another measurement.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2, "km") ** UnitMeasurements::Length.new(3, "m")
+    #   => 1.00208160507963279 km
+    #
+    #   UnitMeasurements::Length.new(2, "km") ** 3
+    #   => 8 km
+    #
+    #   UnitMeasurements::Length.new(8, "km") ** 1/3r
+    #   => 2 km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the raised quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.1.0
+    def **(other)
+      arithmetic_operation(other, :**)
+    end
+
+    # Negates the quantity of the measurement.
+    #
+    # @example
+    #   -UnitMeasurements::Length.new(2, "km")
+    #   => -2 km
+    #
+    #   -UnitMeasurements::Length.new(-2, "km")
+    #   => 2 km
+    #
+    # @return [Measurement] A new +Measurement+ instance with the negated quantity.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.1.0
+    def -@
+      self.class.new(-self.quantity, self.unit)
+    end
+
+    # Checks whether the quantity of the measurement is nonzero.
+    #
+    # @example
+    #   UnitMeasurements::Length.new(2, "km").nonzero?
+    #   => true
+    #
+    #   UnitMeasurements::Length.new(0, "km").nonzero?
+    #   => false
+    #
+    # @return [TrueClass|FalseClass]
+    #   +true+ if the quantity is nonzero otherwise it returns +false+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.1.0
+    def nonzero?
+      quantity.nonzero? ? true : false
+    end
+
     private
 
     # @private

data/lib/unit_measurements/errors/parse_error.rb

@@ -16,6 +16,8 @@ module UnitMeasurements
   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

data/lib/unit_measurements/errors/unit_already_defined_error.rb

@@ -16,6 +16,8 @@ module UnitMeasurements
   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

data/lib/unit_measurements/errors/unit_error.rb

@@ -15,6 +15,8 @@ module UnitMeasurements
   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

data/lib/unit_measurements/measurement.rb

@@ -33,12 +33,25 @@ module UnitMeasurements
     include Math
 
     # Regular expression to match conversion strings.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     CONVERSION_STRING_REGEXP = /(.+?)\s?(?:\s+(?:in|to|as)\s+(.+)|\z)/i.freeze
 
     # Quantity of the measurement.
+    #
+    # @return [Numeric] Quantity of the measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :quantity
 
     # The unit associated with the measurement.
+    #
+    # @return [Unit] The +unit+ instance associated with the measurement.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 1.0.0
     attr_reader :unit
 
     # Initializes a new instance of +Measurement+ with a specified +quantity+
@@ -55,6 +68,12 @@ module UnitMeasurements
     #   UnitMeasurements::Length.new("2e+2", "km")
     #   => 200.0 km
     #
+    #   UnitMeasurements::Length.new("2e²", "km")
+    #   => 200.0 km
+    #
+    #   UnitMeasurements::Length.new("2e⁻²", "km")
+    #   => 0.02 km
+    #
     # @example Initializing the measurement with complex number and unit:
     #   UnitMeasurements::Length.new(Complex(2, 3), "km")
     #   => 2+3i km
@@ -75,6 +94,9 @@ module UnitMeasurements
     #   UnitMeasurements::Length.new("½", "km")
     #   => 0.5 km
     #
+    #   UnitMeasurements::Length.new("2 ½", "km")
+    #   => 2.5 km
+    #
     # @example Initializing the measurement with ratio and unit:
     #   UnitMeasurements::Length.new("1:2", "km")
     #   => 0.5 km
@@ -95,7 +117,8 @@ module UnitMeasurements
       @unit = unit_from_unit_or_name!(unit)
     end
 
-    # Converts the measurement to a +target_unit+.
+    # Converts the measurement to a +target_unit+ and returns new instance of the
+    # measurement.
     #
     # @example
     #   UnitMeasurements::Length.new(1, "m").convert_to("cm")
@@ -142,6 +165,7 @@ module UnitMeasurements
     # @return [Measurement]
     #   The current +Measurement+ instance with updated +quantity+ and +unit+.
     #
+    # @see #convert_to
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def convert_to!(target_unit)
@@ -275,7 +299,8 @@ module UnitMeasurements
       # @see Parser
       # @see Normalizer
       # @see CONVERSION_STRING_REGEXP
-      # @see _parse
+      # @see ._parse
+      # @see #convert_to
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
       def parse(input)
@@ -309,6 +334,7 @@ module UnitMeasurements
       #
       # @return [Measurement] The +Measurement+ instance.
       #
+      # @see Parser.parse
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
       def _parse(string)

data/lib/unit_measurements/unit.rb

@@ -13,6 +13,8 @@ module UnitMeasurements
   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
@@ -20,24 +22,33 @@ module UnitMeasurements
     # 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
@@ -50,14 +61,13 @@ module UnitMeasurements
     # @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.
     #
-    # @see UnitGroup
     # @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
+      @system = system.to_s.freeze
       @unit_group = unit_group
     end
 
@@ -71,7 +81,6 @@ module UnitMeasurements
     #
     # @return [Unit] A new unit with specified parameters.
     #
-    # @see UnitGroup
     # @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)

data/lib/unit_measurements/unit_group.rb

@@ -30,6 +30,8 @@ module UnitMeasurements
     #   UnitMeasurements::Length.units
     #   => [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>, ...]
     #
+    # @return [Array<Unit>] An array of +Unit+ instances.
+    #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     attr_reader :units
@@ -171,7 +173,8 @@ module UnitMeasurements
     #
     # This method takes a unit system name as an argument and filters the units
     # in the unit group to return only those units that belong to the specified
-    # unit system. It then returns an array containing these filtered units.
+    # unit system. It then returns an array containing these filtered units. If
+    # there are no units associated with unit system, it returns empty array.
     #
     # @example
     #   UnitMeasurements::Length.units_for("metric")
@@ -217,7 +220,7 @@ module UnitMeasurements
     # @raise [BaseError]
     #   If there are no units associated with the provided +system_name+.
     #
-    # @see units_for
+    # @see #units_for
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 5.0.0
     def units_for!(system_name)

data/lib/unit_measurements/unit_group_builder.rb

@@ -18,6 +18,8 @@ module UnitMeasurements
   class UnitGroupBuilder
     # An array to store the units defined using the builder.
     #
+    # @return [Array<Unit>] An array of +Unit+ instances.
+    #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     attr_reader :units
@@ -70,7 +72,7 @@ module UnitMeasurements
       @units += build_si_units(name, value: value, add_binary_prefixes: add_binary_prefixes, aliases: aliases)
     end
 
-    # Constructs and returns a +UnitGroup+ object based on the units defined
+    # Constructs and returns a +UnitGroup+ instance based on the units defined
     # using the builder.
     #
     # @return [UnitGroup]

data/lib/unit_measurements/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.1
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-18 00:00:00.000000000 Z
+date: 2023-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -97,6 +97,7 @@ files:
 - ".github/workflows/pages.yml"
 - ".gitignore"
 - ".rspec"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock