unit_measurements 4.12.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b4c09e16a4111f9776ae68ed43e33eccb5b2d47e6146bd32711bdaa8a72cf7
-  data.tar.gz: 1a5c0339f687684b6bb34f2bf53d9da7fd1ed8eba23bcc0c23fbc4634057dfb6
+  metadata.gz: a8e055ec9a81c6c27050136128e36d6bceba2b3292e6494a2bbd3305ccbcb20b
+  data.tar.gz: 381e87126aaa72bd762f537fe6be8638adbf07105ed992009a8298f6d6159de4
 SHA512:
-  metadata.gz: ee23a940d4596e69a28f5361d037b88df37bf0d31c4b4f86a5cd11a33f201eb2f0dcf54a1579d75e54f1d5989c27751a745d755073f0d6fe5be459846daa17d1
-  data.tar.gz: aa2cd86031ecd07894fd8c0258367ae2e5bd24e4155a1137dc201a3a4bb450aa9823afc936a24db71f15b17d8bf03ba8e5a1d5516ed9ffc155059907e46e347d
+  metadata.gz: b8b3831f2e780623cd1d7d8e86d7f4687c58ed380dabccfa2eff81ab1c9cb13c8295970c1980acbf920ee00bffcba6fd3d310563fc3d27ecbc6946e14fadddea
+  data.tar.gz: d45c0207c736ca65b6041483d609a6390784fd60334c49220d36580f5fb3e3882c1f5a49d5951e6bc3f46386769cd18168bb8fcb6e897fb9b742fa3445acd8b7

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [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
+
+- Added support to add binary SI prefixes for the unit.
+- Added support to convert the measurement to a `primitive` unit of the unit group.
+- Added methods `UnitGroup#units_for` and `UnitGroup#units_for!` to find units within
+  the specified unit system.
+
+----------
+
 ## [4.12.0](https://github.com/shivam091/unit_measurements/compare/v4.11.0...v4.12.0) - 2023-10-16
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unit_measurements (4.12.0)
+    unit_measurements (5.1.0)
       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`.
+- Easy unit conversion.
+- Lightweight and extensible for adding custom units and conversions.
+- Supports various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
+- Well-documented: [Documentation](https://rubydoc.info/gems/unit_measurements).
+- Parses 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
 
@@ -88,6 +88,13 @@ UnitMeasurements::Length.new(1, "km").convert_to!("m")
 #=> 1000.0 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")
+#=> 0.01 m
+```
+
 You can also chain call of `#convert_to` and `#convert_to!` methods as:
 
 ```ruby
@@ -120,7 +127,7 @@ UnitMeasurements::Length.parse("2e+2 km to m")
 #=> 200000.0 m
 ```
 You can check supported special characters for exponents
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **Parse complex numbers, source unit, and (or) target unit:**
 
@@ -136,24 +143,16 @@ 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
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **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")
@@ -166,16 +165,12 @@ 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
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Formatter.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Formatter.html).
 
 **Extract the unit and the quantity from measurement:**
 
@@ -215,19 +210,28 @@ 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 units within the unit system:**
+
+You can use `#units_for` or `#units_for!` methods to find units within the unit system.
+`#units_for!` method returns an error if there are no units associated with specified
+unit system.
+
+```ruby
+UnitMeasurements::Length.units_for("metric")
+#=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>, ...]
+```
+
 **Finding units within the unit group:**
 
-You can use `#unit_for` or `#unit_for!` (aliased as `#[]`) to find units within
-the unit group. `#unit_for!` method returns error if a unit is not present in the
-unit group.
+You can use `#unit_for` or `#unit_for!` (aliased as `#[]`) methods to find units
+within the unit group. `#unit_for!` method returns an error if a unit is not present
+in the unit group.
 
 ```ruby
 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)
 ```
@@ -261,7 +265,7 @@ UnitMeasurements::Length.parse("1 km") != UnitMeasurements::Length.parse("1 m")
 ```
 
 You can check supported comparisons along with their examples
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Comparison.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Comparison.html).
 
 ### Arithmetic
 
@@ -278,7 +282,7 @@ UnitMeasurements::Length.new(2, "km") * 2+2i
 ```
 
 You can check supported arithmetic operations along with their examples
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Arithmetic.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Arithmetic.html).
 
 ### Math
 
@@ -290,7 +294,7 @@ UnitMeasurements::Length.new(17.625, "m").round
 ```
 
 You can check supported mathematical functions along with their examples
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Math.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Math.html).
 
 ### Conversions
 
@@ -303,16 +307,20 @@ UnitMeasurements::Length.new(2.25567, "km").to_i
 ```
 
 You can check more about them along with their examples
-[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Conversion.html).
+[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Conversion.html).
 
 ## Units
 
 The **`UnitMeasurements::Unit`** class is used to represent the units for a measurement.
 
-### Support for SI decimal prefixes
+### SI prefixed units
 
-There is support for SI decimal prefixes through the use of `si_unit` method.
-Units declared through it will have automatic support for all decimal 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
 
 | Multiplying Factor                        | SI Prefix  | Scientific Notation |
 | ----------------------------------------- | ---------- | ------------------- |
@@ -341,6 +349,19 @@ Units declared through it will have automatic support for all decimal prefixes:
 | 0.000 000 000 000 000 000 000 000 001     | ronto (r)  | 10^-27              |
 | 0.000 000 000 000 000 000 000 000 000 001 | quecto (q) | 10^-30              |
 
+#### Binary SI prefixes
+
+| Multiplying Factor                | SI Prefix | Scientific Notation |
+| --------------------------------- | --------- | ------------------- |
+| 1 024                             | kibi (Ki) | 2^10                |
+| 1 048 576                         | mebi (Mi) | 2^20                |
+| 1 073 741 824                     | gibi (Gi) | 2^30                |
+| 1 099 511 627 776                 | tebi (Ti) | 2^40                |
+| 1 125 899 906 842 624             | pebi (Pi) | 2^50                |
+| 1 152 921 504 606 846 976         | exbi (Ei) | 2^60                |
+| 1 180 591 620 717 411 303 424     | zebi (Zi) | 2^70                |
+| 1 208 925 819 614 629 174 706 176 | yobi (Yi) | 2^80                |
+
 ### Bundled units
 
 There are tons of units that are bundled in `unit_measurements`. You can check them out
@@ -348,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"
@@ -357,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
@@ -396,14 +401,17 @@ UnitMeasurements::Time = UnitMeasurements.build do
 
   # Group units by the unit system (optional).
   system :metric do
-    # Add a SI unit to the unit group.
+    # This will add unit `m` along with all decimal SI prefixes.
     si_unit "s", aliases: ["second", "seconds"]
 
+    # This will add unit `B` along with all binary & decimal SI prefixes.
+    si_unit "B", aliases: ["byte", "bytes"], add_binary_prefixes: true
+
     # Add units to the group, along with their conversion multipliers.
     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,13 +117,19 @@ 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")
     #   => 100.0 cm
     #
-    # @param [String|Symbol] target_unit The target unit for conversion.
+    #   UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
+    #   => 0.01 m
+    #
+    # @param [String|Symbol] target_unit
+    #   The target unit for conversion. Specifing +primitive+ will convert the
+    #   measurement to a primitive unit of the unit group.
     #
     # @return [Measurement]
     #   A new +Measurement+ instance with the converted +quantity+ and
@@ -110,7 +138,11 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def convert_to(target_unit)
-      target_unit = unit_from_unit_or_name!(target_unit)
+      target_unit = if target_unit.to_s.eql?("primitive")
+        self.class.unit_group.primitive
+      else
+        unit_from_unit_or_name!(target_unit)
+      end
 
       return self if target_unit == unit
 
@@ -133,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)
@@ -188,7 +221,7 @@ module UnitMeasurements
       # Methods delegated from the unit group.
       def_delegators :unit_group, :primitive, :units, :unit_names, :unit_with_name_and_aliases,
                      :unit_names_with_aliases, :unit_for, :unit_for!, :defined?,
-                     :unit_or_alias?, :[]
+                     :unit_or_alias?, :[], :units_for, :units_for!
 
       # Parses an input string and returns a +Measurement+ instance depending on
       # the input string. This method first normalizes the +input+ internally,
@@ -266,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)
@@ -300,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
+      @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)
@@ -147,35 +156,50 @@ module UnitMeasurements
 
     private
 
+    # Binary prefixes for SI units.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.0.0
+    SI_BINARY_PREFIXES = [
+      ["Ki", %w[kibi], 2.pow(10)],
+      ["Mi", %w[mebi], 2.pow(20)],
+      ["Gi", %w[gibi], 2.pow(30)],
+      ["Ti", %w[tebi], 2.pow(40)],
+      ["Pi", %w[pebi], 2.pow(50)],
+      ["Ei", %w[exbi], 2.pow(60)],
+      ["Zi", %w[zebi], 2.pow(70)],
+      ["Yi", %w[yobi], 2.pow(80)],
+    ].map(&:freeze).freeze
+
     # Decimal prefixes for SI units.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     SI_DECIMAL_PREFIXES = [
-      ["q",  %w(quecto),    1e-30],
-      ["r",  %w(ronto),     1e-27],
-      ["y",  %w(yocto),     1e-24],
-      ["z",  %w(zepto),     1e-21],
-      ["a",  %w(atto),      1e-18],
-      ["f",  %w(femto),     1e-15],
-      ["p",  %w(pico),      1e-12],
-      ["n",  %w(nano),      1e-9],
-      ["μ",  %w(micro),     1e-6],
-      ["m",  %w(milli),     1e-3],
-      ["c",  %w(centi),     1e-2],
-      ["d",  %w(deci),      1e-1],
-      ["da", %w(deca deka), 1e+1],
-      ["h",  %w(hecto),     1e+2],
-      ["k",  %w(kilo),      1e+3],
-      ["M",  %w(mega),      1e+6],
-      ["G",  %w(giga),      1e+9],
-      ["T",  %w(tera),      1e+12],
-      ["P",  %w(peta),      1e+15],
-      ["E",  %w(exa),       1e+18],
-      ["Z",  %w(zetta),     1e+21],
-      ["Y",  %w(yotta),     1e+24],
-      ["R",  %w(ronna),     1e+27],
-      ["Q",  %w(quetta),    1e+30]
+      ["q",  %w[quecto],    1e-30],
+      ["r",  %w[ronto],     1e-27],
+      ["y",  %w[yocto],     1e-24],
+      ["z",  %w[zepto],     1e-21],
+      ["a",  %w[atto],      1e-18],
+      ["f",  %w[femto],     1e-15],
+      ["p",  %w[pico],      1e-12],
+      ["n",  %w[nano],      1e-9],
+      ["μ",  %w[micro],     1e-6],
+      ["m",  %w[milli],     1e-3],
+      ["c",  %w[centi],     1e-2],
+      ["d",  %w[deci],      1e-1],
+      ["da", %w[deca deka], 1e+1],
+      ["h",  %w[hecto],     1e+2],
+      ["k",  %w[kilo],      1e+3],
+      ["M",  %w[mega],      1e+6],
+      ["G",  %w[giga],      1e+9],
+      ["T",  %w[tera],      1e+12],
+      ["P",  %w[peta],      1e+15],
+      ["E",  %w[exa],       1e+18],
+      ["Z",  %w[zetta],     1e+21],
+      ["Y",  %w[yotta],     1e+24],
+      ["R",  %w[ronna],     1e+27],
+      ["Q",  %w[quetta],    1e+30]
     ].map(&:freeze).freeze
 
     # Parses tokens and returns a +conversion value+ and the +unit+.

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
@@ -167,6 +169,70 @@ module UnitMeasurements
       !!unit_for(name)
     end
 
+    # Returns an array of units associated with a specified +unit_system+.
+    #
+    # 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. If
+    # there are no units associated with unit system, it returns empty array.
+    #
+    # @example
+    #   UnitMeasurements::Length.units_for("metric")
+    #   => [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>]
+    #
+    #   UnitMeasurements::Length.units_for("imperial")
+    #   => [#<UnitMeasurements::Unit: in (", inch, inches)>, ...]
+    #
+    #   UnitMeasurements::Length.units_for("troy")
+    #   => []
+    #
+    # @param [String|Symbol] system_name
+    #   The name of the unit system to retrieve units for.
+    #
+    # @return [Array<Unit>]
+    #   An array of +Unit+ instances associated with the specified unit system.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.0.0
+    def units_for(system_name)
+      units.select { |unit| unit.system.to_s == system_name.to_s }
+    end
+
+    # This method works same as +units_for+ method but it raises an error if
+    # there are no units associated with the +system_name+.
+    #
+    # @example
+    #   UnitMeasurements::Length.units_for!("metric")
+    #   => [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>]
+    #
+    #   UnitMeasurements::Length.units_for!("imperial")
+    #   => [#<UnitMeasurements::Unit: in (", inch, inches)>, ...]
+    #
+    #   UnitMeasurements::Length.units_for!("troy")
+    #   => Invalid unit system 'troy' within the unit group. (UnitMeasurements::BaseError)
+    #
+    # @param [String|Symbol] system_name
+    #   The name of the unit system to retrieve units for.
+    #
+    # @return [Array<Unit>]
+    #   An array of +Unit+ instances associated with the specified unit system.
+    #
+    # @raise [BaseError]
+    #   If there are no units associated with the provided +system_name+.
+    #
+    # @see #units_for
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.0.0
+    def units_for!(system_name)
+      system_units = units_for(system_name)
+
+      unless system_units.any?
+        raise BaseError, "Invalid unit system '#{system_name}' within the unit group."
+      end
+
+      system_units
+    end
+
     private
 
     # @private

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
@@ -56,6 +58,9 @@ module UnitMeasurements
     #
     # @param [String|Symbol] name The name of the unit.
     # @param [Numeric|String] value The conversion value of the unit.
+    # @param [TrueClass|FalseClass] add_binary_prefixes
+    #   Whether the unit supports binary SI prefixes along with decimal SI
+    #   prefixes.
     # @param [Array<String|Symbol>, optional] aliases An array of alternative names for the unit.
     #
     # @return [Array<Unit>] An array of +Unit+ instances.
@@ -63,11 +68,11 @@ module UnitMeasurements
     # @see #build_si_units
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
-    def si_unit(name, value: 1.0, aliases: [])
-      @units += build_si_units(name, value: value, aliases: aliases)
+    def si_unit(name, value: 1.0, add_binary_prefixes: false, aliases: [])
+      @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]
@@ -133,6 +138,9 @@ module UnitMeasurements
     #
     # @param [String|Symbol] name The name of the unit.
     # @param [Numeric|String] value The conversion value of the unit.
+    # @param [TrueClass|FalseClass] add_binary_prefixes
+    #   Whether the unit supports binary SI prefixes along with decimal SI
+    #   prefixes.
     # @param [Array<String|Symbol>, optional] aliases
     #   An array of alternative names for the unit.
     #
@@ -141,10 +149,12 @@ module UnitMeasurements
     # @see #build_unit
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
-    def build_si_units(name, value:, aliases:)
+    def build_si_units(name, value:, add_binary_prefixes:, aliases:)
       si_units = [build_unit(name, value: value, aliases: aliases)]
 
-      Unit::SI_DECIMAL_PREFIXES.each do |short_prefix, long_prefix, multiplier|
+      si_prefixes = add_binary_prefixes ? (Unit::SI_DECIMAL_PREFIXES + Unit::SI_BINARY_PREFIXES) : Unit::SI_DECIMAL_PREFIXES
+
+      si_prefixes.each do |short_prefix, long_prefix, multiplier|
         si_aliases = long_prefix.product(aliases.to_a).flat_map do |prefix, unit|
           aliases.map { |alias_unit| prefix + alias_unit.to_s }
         end

data/lib/unit_measurements/unit_groups/information_entropy.rb

@@ -5,8 +5,8 @@
 UnitMeasurements::InformationEntropy = UnitMeasurements.build do
   primitive "nat"
 
-  si_unit "b", value: "1 Sh", aliases: ["bit", "bits"]
-  si_unit "B", value: [2.pow(3), "b"], aliases: ["byte", "bytes"]
+  si_unit "b", value: "1 Sh", aliases: ["bit", "bits"], add_binary_prefixes: true
+  si_unit "B", value: [2.pow(3), "b"], aliases: ["byte", "bytes"], add_binary_prefixes: true
 
   unit "Sh", value: [Math.log(2), "nat"], aliases: ["shannon", "shannons"]
   unit "nat", aliases: ["nit", "nepit", "natural unit of information"]

data/lib/unit_measurements/version.rb

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

data/unit_measurements.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["documentation_uri"] = "https://shivam091.github.io/unit_measurements"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/unit_measurements"
   spec.metadata["source_code_uri"] = "https://github.com/shivam091/unit_measurements"
   spec.metadata["changelog_uri"] = "https://github.com/shivam091/unit_measurements/blob/main/CHANGELOG.md"
   spec.metadata["bug_tracker_uri"] = "https://github.com/shivam091/unit_measurements/issues"

data/units.md

@@ -4,8 +4,10 @@ As there are lots of units bundled with `unit_measurements`, we recommend you to
 bundled units before converting your measurements.
 
 **Notes:**
-1. Unit names suffixed with `*` support all [SI prefixes](README.md#support-for-si-decimal-prefixes).
-2. Primitive unit of the unit group is in _emphasised typeface_.
+1. Unit names suffixed with `*` support all [Decimal SI prefixes](README.md#decimal-si-prefixes).
+2. Unit names suffixed with `**` support all [Decimal SI prefixes](README.md#decimal-si-prefixes)
+and [Binary SI prefixes](README.md#binary-si-prefixes).
+3. Primitive unit of the unit group is in _emphasised typeface_.
 
 ## 1. Length/Distance
 
@@ -594,8 +596,8 @@ These units are defined in `UnitMeasurements::InformationEntropy`.
 
 | # | Name | Aliases |
 |:--|:--|:--|
-| 1 | b* | bit, bits |
-| 2 | B* | byte, bytes |
+| 1 | b*\* | bit, bits |
+| 2 | B*\* | byte, bytes |
 | 3 | Sh | shannon, shannons |
 | _4_ | _nat_ | _nit, nepit, natural unit of information_ |
 | 5 | nybl | nibble, nibbles, nybble, nyble |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 4.12.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-16 00:00:00.000000000 Z
+date: 2023-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -178,7 +178,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/shivam091/unit_measurements
-  documentation_uri: https://shivam091.github.io/unit_measurements
+  documentation_uri: https://rubydoc.info/gems/unit_measurements
   source_code_uri: https://github.com/shivam091/unit_measurements
   changelog_uri: https://github.com/shivam091/unit_measurements/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/shivam091/unit_measurements/issues