unit_measurements 4.12.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b4c09e16a4111f9776ae68ed43e33eccb5b2d47e6146bd32711bdaa8a72cf7
-  data.tar.gz: 1a5c0339f687684b6bb34f2bf53d9da7fd1ed8eba23bcc0c23fbc4634057dfb6
+  metadata.gz: 2a7a4305ab13c8d9d8d52eaf7c9e4646757dc8eee71af5ec8314f6a2b702f929
+  data.tar.gz: 9cb9fc75b29f7745278ca27ce32fce621a29427e6e08202590eec52ff90c4e66
 SHA512:
-  metadata.gz: ee23a940d4596e69a28f5361d037b88df37bf0d31c4b4f86a5cd11a33f201eb2f0dcf54a1579d75e54f1d5989c27751a745d755073f0d6fe5be459846daa17d1
-  data.tar.gz: aa2cd86031ecd07894fd8c0258367ae2e5bd24e4155a1137dc201a3a4bb450aa9823afc936a24db71f15b17d8bf03ba8e5a1d5516ed9ffc155059907e46e347d
+  metadata.gz: 46ddf50754159eb8dcaf4f753378fe19f912ac0d8316ecdd959b23620ed7ca2ef1a1122ce0a35d0a33bd0d643fbe7e6572a83348ca2faf3ab6815ce64c61e9d4
+  data.tar.gz: 9b84900e75d14377ebe58e8a21d75aaca6ae1329ce2be56768a7f24f4476782e27d8312fa65045c7398d6c67eb78ff2b01ea5b6da2263e53899eb21f015cb246

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [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.0.0)
       activesupport (~> 7.0)
 
 GEM

data/README.md

@@ -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
@@ -215,11 +222,22 @@ 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")
@@ -309,10 +327,14 @@ You can check more about them along with their examples
 
 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 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.
 
-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:
+#### Decimal SI prefixes
 
 | Multiplying Factor                        | SI Prefix  | Scientific Notation |
 | ----------------------------------------- | ---------- | ------------------- |
@@ -341,6 +363,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
@@ -396,9 +431,12 @@ 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"]
 

data/lib/unit_measurements/measurement.rb

@@ -101,7 +101,12 @@ module UnitMeasurements
     #   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 +115,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
 
@@ -188,7 +197,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,

data/lib/unit_measurements/unit.rb

@@ -57,7 +57,7 @@ module UnitMeasurements
       @name = name.to_s.freeze
       @value = value
       @aliases = Set.new(aliases.map(&:to_s).sort.map(&:freeze)).freeze
-      @system = system
+      @system = system.to_s
       @unit_group = unit_group
     end
 
@@ -147,35 +147,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

@@ -167,6 +167,69 @@ 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.
+    #
+    # @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

@@ -56,6 +56,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,8 +66,8 @@ 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
@@ -133,6 +136,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 +147,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.0.0"
 end

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.0.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-16 00:00:00.000000000 Z
+date: 2023-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport