composite_unit_measurements 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd67813e0e00bce4c907e7076ec4a62994570585875da38dfa72bc968b3c0c20
-  data.tar.gz: c9de7ccfd6e0ede94d8cd5976174a1a60ed4f4cf3566bc613349a211ea9e4309
+  metadata.gz: c25131e598e9fb02e3b569eeb45df0f39b254d5d85ab7e60ee729365b70c59cc
+  data.tar.gz: c659dea44b220217466355182589a808a098d1d654efbc664f55e6556198422f
 SHA512:
-  metadata.gz: 7291bb98bb1e404be485f5f89de9f7594a7093f89cb98c4fd27310051804bfd22ea891acdfffed137ed466b0d9e778d6034439561dffe5e1e5b8b354093044b0
-  data.tar.gz: d86f50e73b9044cd8248bf49454c8c036a99b0bd2577fe21554b2c52ff14d1951bf19a11c388b9c0ddfed1670a1d315b054cda0d191909b1ae29cdc8793bf1e9
+  metadata.gz: ca73e1e52c1c40b08f95ce7196bdb5c290dbe4d955c8c9c80affc6210b5657cb05a013e5352467412a8139cb1ef927914b96cd59843565fb30462ba4ce77419f
+  data.tar.gz: 7528d84b11c1eeb86eea5b5683e581513695b816662669711fa8a567a9fba1c7b4f505d19dd250c6b1175c5e9bdea896f5f483e0096c35b38a591aa7477124fa

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.4.0](https://github.com/shivam091/composite_unit_measurements/compare/v0.2.0...v0.3.0) - 2023-11-30
+
+### What's new
+
+- Added ability to parse `litre-millilitre` volume measurements.
+- Updated readme with parsing examples.
+
+-----------
+
 ## [0.3.0](https://github.com/shivam091/composite_unit_measurements/compare/v0.2.0...v0.3.0) - 2023-11-27
 
 ### What's new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    composite_unit_measurements (0.3.0)
+    composite_unit_measurements (0.4.0)
       activesupport (~> 7.0)
       unit_measurements (~> 5)
 

data/README.md

@@ -13,7 +13,7 @@ A collection of specialized parsers designed for handling composite measurement
 
 ## Introduction
 
-The `CompositeUnitMeasurements` gem offers versatile parsers for efficiently parsing
+The `composite_unit_measurements` gem offers versatile parsers for efficiently parsing
 composite measurement strings. Leveraging the power of the `unit_measurements` gem,
 it enables smooth handling of composite measurements in various units.
 
@@ -23,7 +23,7 @@ it enables smooth handling of composite measurements in various units.
 
 ## Installation
 
-To use `composite_unit_measurements-rails` in your Rails application, add the
+To use `composite_unit_measurements` in your Rails application, add the
 following line to your Gemfile:
 
 ```ruby
@@ -40,10 +40,13 @@ Or otherwise simply install it yourself as:
 
 ## Usage
 
-Each packaged parser includes the `#parse` method to parse composite measurements.
-You can use an appropriate parser to parse measurements. The final result of `#parse`
+Each packaged parser includes the `.parse` method to parse composite measurements.
+You can use an appropriate parser to these measurements and the final result of
 is returned in the leftmost unit of your measurement.
 
+The result of each parser method returns an instance of measurement on which we can
+perform any functionality offered by `unit_measurements`.
+
 This gem internally uses [`unit_measurements`](https://github.com/shivam091/unit_measurements)
 to perform conversions and arithmetic operations. You can build supported composite measurements
 using any [unit alias](https://github.com/shivam091/unit_measurements/blob/main/units.md).
@@ -53,32 +56,25 @@ using any [unit alias](https://github.com/shivam091/unit_measurements/blob/main/
 **Parsing length measurements:**
 
 ```ruby
-CompositeUnitMeasurements::Length.parse("5 ft 6 in")
-#=> 5.5 ft
-CompositeUnitMeasurements::Length.parse("6 m 50 cm")
-#=> 6.5 m
-CompositeUnitMeasurements::Length.parse("5 km 500 m")
-#=> 5.5 km
+CompositeUnitMeasurements::Length.parse("5 km 500 m") #=> 5.5 km
 ```
 
 **Parsing weight measurements:**
 
 ```ruby
-CompositeUnitMeasurements::Weight.parse("8 lb 12 oz")
-#=> 8.75 lb
-CompositeUnitMeasurements::Weight.parse("2 st 6 lb")
-#=> 2.428571428571429 st
-CompositeUnitMeasurements::Weight.parse("2 st 6 lb")
-# 4.5 kg
+CompositeUnitMeasurements::Weight.parse("4 kg 500 g") # 4.5 kg
 ```
 
 **Parsing time measurements:**
 
 ```ruby
-CompositeUnitMeasurements::Time.parse("3 h 45 min")
-#=> 3.75 hx
-CompositeUnitMeasurements::Time.parse("12:60:3600,360000000")
-#=> 14.1 h
+CompositeUnitMeasurements::Time.parse("3 h 45 min") #=> 3.75 hr
+```
+
+**Parsing volume measurements:**
+
+```ruby
+CompositeUnitMeasurements::Volume.parse("2 l 250 ml") #=> 2.25 l
 ```
 
 ### Support for numeric types
@@ -86,16 +82,11 @@ CompositeUnitMeasurements::Time.parse("12:60:3600,360000000")
 Each parser can handle various numeric types, including scientific notation, rational numbers, and complex numbers.
 
 ```ruby
-CompositeUnitMeasurements::Length.parse("1+2i ft 12 in")
-#=> 2.0+2.0i ft
-CompositeUnitMeasurements::Length.parse("1.5 ft 12e2 in")
-#=> 101.5 ft
-CompositeUnitMeasurements::Length.parse("1 1/2 ft 1+2i in")
-#=> 1.5833333333333333+0.16666666666666669i ft
-CompositeUnitMeasurements::Length.parse("2 ft 1+2i in")
-#=> 2.0833333333333335+0.16666666666666669i ft
-CompositeUnitMeasurements::Length.parse("1e-2 ft 1+2i in")
-#=> 0.09333333333333334+0.16666666666666669i ft
+CompositeUnitMeasurements::Length.parse("1+2i ft 12 in")    #=> 2.0+2.0i ft
+CompositeUnitMeasurements::Length.parse("1.5 ft 12e2 in")   #=> 101.5 ft
+CompositeUnitMeasurements::Length.parse("1 1/2 ft 1+2i in") #=> 1.5833333333333333+0.16666666666666669i ft
+CompositeUnitMeasurements::Length.parse("2 ft 1+2i in")     #=> 2.0833333333333335+0.16666666666666669i ft
+CompositeUnitMeasurements::Length.parse("1e-2 ft 1+2i in")  #=> 0.09333333333333334+0.16666666666666669i ft
 ```
 
 ## Packaged parsers & supported composite measurements
@@ -103,19 +94,22 @@ CompositeUnitMeasurements::Length.parse("1e-2 ft 1+2i in")
 The `composite_unit_measurements` gem supports parsing various composite measurements, including:
 
 **1. CompositeUnitMeasurements::Length**
-- foot-inch (5 ft 6 in)
 - metre-centimetre (6 m 50 cm)
 - kilometre-metre (5 km 500 m)
+- foot-inch (5 ft 6 in)
 
 **2. CompositeUnitMeasurements::Weight**
+- kilogramme-gramme (4 kg 500 g)
 - pound-ounce (8 lb 12 oz)
 - stone-pound (2 st 6 lb)
-- kilogramme-gramme (4 kg 500 g)
 
 **3. CompositeUnitMeasurements::Time**
 - hour-minute (3 h 45 min)
 - hour-minute-second-microsecond (12:60,3600:360000000)
 
+**4. CompositeUnitMeasurements::Volume**
+- litre-millilitre (2 l 250 ml)
+
 ### Specifing parsers
 
 By default, `composite_unit_measurements` includes all packaged parsers automatically
@@ -141,4 +135,4 @@ Contributions to this project are welcomed! To contribute:
 
 ## License
 
-Copyright 2023 [Harshal V. LADHE]((https://shivam091.github.io)), Released under the [MIT License](http://opensource.org/licenses/MIT).
+Copyright 2023 [Harshal V. LADHE](https://shivam091.github.io), Released under the [MIT License](http://opensource.org/licenses/MIT).

data/lib/composite_unit_measurements/base.rb

@@ -54,4 +54,7 @@ module CompositeUnitMeasurements
 
   # Matches any number, including scientific, complex, rational, and real numbers.
   ANY_NUMBER = /(?<number>#{SCIENTIFIC_NUMBER}|#{COMPLEX_NUMBER}|#{RATIONAL_NUMBER}|#{REAL_NUMBER})/.freeze
+
+  private_constant :REAL_NUMBER, :RATIONAL_NUMBER, :SCIENTIFIC_NUMBER, :COMPLEX_NUMBER,
+                   :ANY_NUMBER
 end

data/lib/composite_unit_measurements/length.rb

@@ -14,6 +14,13 @@ module CompositeUnitMeasurements
     class << self
       # Parses a given +string+ into a +UnitMeasurements::Length+ object.
       #
+      # @example Parse 'metre-centimetre' measurement:
+      #   CompositeUnitMeasurements::Length.parse("6 m 50 cm") #=> 6.5 m
+      # @example Parse 'kilometre-metre' measurement:
+      #   CompositeUnitMeasurements::Length.parse("5 km 500 m") #=> 5.5 km
+      # @example Parse 'foot-inch' measurement:
+      #   CompositeUnitMeasurements::Length.parse("5 ft 6 in") #=> 5.5 ft
+      #
       # @param [String] string The string to parse for length measurement.
       # @return [UnitMeasurements::Length]
       #   Returns a UnitMeasurements::Length object if parsing is successful.
@@ -35,7 +42,8 @@ module CompositeUnitMeasurements
       private
 
       # @private
-      # Parses a +string+ representing a length in the format of +foot-inch+.
+      # Parses a +string+ representing a length in the format of +foot-inch+
+      # into a +UnitMeasurements::Length+ object.
       #
       # @param [String] string
       #   The string representing length measurement in the format of *foot-inch*.
@@ -54,7 +62,8 @@ module CompositeUnitMeasurements
       end
 
       # @private
-      # Parses a +string+ representing a length in the format of +metre-centimetre+.
+      # Parses a +string+ representing a length in the format of +metre-centimetre+
+      # into a +UnitMeasurements::Length+ object.
       #
       # @param [String] string
       #   The string representing length measurement in the format of *metre-centimetre*.
@@ -73,7 +82,8 @@ module CompositeUnitMeasurements
       end
 
       # @private
-      # Parses a +string+ representing a length in the format of +kilometre-metre+.
+      # Parses a +string+ representing a length in the format of +kilometre-metre+
+      # into a +UnitMeasurements::Length+ object.
       #
       # @param [String] string
       #   The string representing length measurement in the format of *kilometre-metre*.
@@ -92,8 +102,6 @@ module CompositeUnitMeasurements
       end
     end
 
-    private
-
     # Regex pattern for aliases of +foot+ unit.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
@@ -141,5 +149,8 @@ module CompositeUnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 0.3.0
     KILOMETRE_METRE = /\A#{ANY_NUMBER}\s*#{KILOMETRE_ALIASES}\s*#{ANY_NUMBER}\s*#{METRE_ALIASES}\z/.freeze
+
+    private_constant :FOOT_ALIASES, :INCH_ALIASES, :METRE_ALIASES, :CENTIMETRE_ALIASES,
+                     :KILOMETRE_ALIASES, :FOOT_INCH, :KILOMETRE_METRE, :METRE_CENTIMETRE
   end
 end

data/lib/composite_unit_measurements/time.rb

@@ -14,6 +14,12 @@ module CompositeUnitMeasurements
     class << self
       # Parses a given +string+ into a +UnitMeasurements::Time+ object.
       #
+      # @example Parse 'hour-minute' measurement:
+      #   CompositeUnitMeasurements::Time.parse("3 h 45 min") #=> 3.75 h
+      # @example Parse 'duration':
+      #   CompositeUnitMeasurements::Time.parse("12:60:3600,360000000") #=> 14.1 h
+      #   CompositeUnitMeasurements::Time.parse("12:60:3600") #=> 14.0 h
+      #
       # @param [String] string The string to parse for time measurement.
       # @return [UnitMeasurements::Time]
       #   Returns a UnitMeasurements::Time object if parsing is successful.
@@ -33,7 +39,8 @@ module CompositeUnitMeasurements
       private
 
       # @private
-      # Parses a +string+ representing a time in the format of +hour-minute+.
+      # Parses a +string+ representing a time in the format of +hour-minute+
+      # into a +UnitMeasurements::Time+ object.
       #
       # @param [String] string
       #   The string representing time measurement in the format of *hour-minute*.
@@ -53,7 +60,8 @@ module CompositeUnitMeasurements
 
       # @private
       # Parses a +string+ representing time duration in the format of
-      # +hour:minute:second,microsecond+ or +hour:minute:second+.
+      # +hour:minute:second,microsecond+ or +hour:minute:second+ into a
+      # +UnitMeasurements::Time+ object.
       #
       # @param [String] string The string representing time duration.
       # @return [UnitMeasurements::Time]
@@ -75,8 +83,6 @@ module CompositeUnitMeasurements
       end
     end
 
-    private
-
     # Regex pattern for aliases of +hour+ unit.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
@@ -101,5 +107,7 @@ module CompositeUnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 0.2.0
     DURATION = /\A(?<hour>#{REAL_NUMBER}):(?<min>#{REAL_NUMBER}):(?:(?<sec>#{REAL_NUMBER}))?(?:,(?<msec>#{REAL_NUMBER}))?\z/.freeze
+
+    private_constant :HOUR_ALIASES, :MINUTE_ALIASES, :HOUR_MINUTE, :DURATION
   end
 end

data/lib/composite_unit_measurements/version.rb

@@ -25,5 +25,5 @@
 # @since 0.1.0
 module CompositeUnitMeasurements
   # Current stable version
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/composite_unit_measurements/volume.rb

@@ -0,0 +1,79 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+require "unit_measurements/unit_groups/volume"
+
+module CompositeUnitMeasurements
+  # A parser handling +volume+ measurements, particularly for composite units
+  # like +litre-millilitre+, +gallon-quart+, +quart-pint+, etc.
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 0.4.0
+  class Volume
+    class << self
+      # Parses a given +string+ into a +UnitMeasurements::Volume+ object.
+      #
+      # @example Parse 'litre-millilitre' measurement:
+      #   CompositeUnitMeasurements::Volume.parse("2 l 250 ml") #=> 2.25 l
+      #
+      # @param [String] string The string to parse for volume measurement.
+      # @return [UnitMeasurements::Volume]
+      #   Returns a UnitMeasurements::Volume object if parsing is successful.
+      #
+      # @raise [UnitMeasurements::ParseError]
+      #   If the string does not match any known format.
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 0.4.0
+      def parse(string)
+        case string
+        when LITRE_MILLILITRE then parse_litre_millilitre(string)
+        else                       raise UnitMeasurements::ParseError, string
+        end
+      end
+
+      private
+
+      # @private
+      # Parses a +string+ representing a volume in the format of +litre-millilitre+
+      # into a +UnitMeasurements::Volume+ object.
+      #
+      # @param [String] string
+      #   The string representing volume measurement in the format of *litre-millilitre*.
+      # @return [UnitMeasurements::Volume]
+      #   Returns a UnitMeasurements::Volume object if parsing is successful.
+      #
+      # @see LITRE_MILLILITRE
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 0.4.0
+      def parse_litre_millilitre(string)
+        litre, millilitre = string.match(LITRE_MILLILITRE)&.captures
+
+        if litre && millilitre
+          UnitMeasurements::Volume.new(litre, "l") + UnitMeasurements::Volume.new(millilitre, "ml")
+        end
+      end
+    end
+
+    # Regex pattern for aliases of +litre+ unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 0.4.0
+    LITRE_ALIASES = /(?:l|L|liter(?:s)?|litre(?:s)?)/.freeze
+
+    # Regex pattern for aliases of +millilitre+ unit.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 0.4.0
+    MILLILITRE_ALIASES = /(?:ml|mL|milliliter(?:s)?|millilitre(?:s)?)/.freeze
+
+    # Regex pattern for parsing a volume measurement in the format of +litre-millilitre+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 0.4.0
+    LITRE_MILLILITRE = /\A#{ANY_NUMBER}\s*#{LITRE_ALIASES}\s*#{ANY_NUMBER}\s*#{MILLILITRE_ALIASES}\z/.freeze
+
+    private_constant :LITRE_MILLILITRE, :LITRE_ALIASES, :MILLILITRE_ALIASES
+  end
+end

data/lib/composite_unit_measurements/weight.rb

@@ -6,7 +6,7 @@ require "unit_measurements/unit_groups/weight"
 
 module CompositeUnitMeasurements
   # A parser handling +weight+ measurements, particularly for composite units
-  # like +pound-ounce+, +stone-pound+, +kilogramme-gramme+, etc.
+  # like +kilogramme-gramme+, +pound-ounce+, +stone-pound+ etc.
   #
   # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
   # @since 0.2.0
@@ -14,6 +14,13 @@ module CompositeUnitMeasurements
     class << self
       # Parses a given +string+ into a +UnitMeasurements::Weight+ object.
       #
+      # @example Parse 'kilogramme-gramme' measurement:
+      #   CompositeUnitMeasurements::Weight.parse("4 kg 500 g") #=> 4.5 kg
+      # @example Parse 'pound-ounce' measurement:
+      #   CompositeUnitMeasurements::Weight.parse("8 lb 12 oz") #=> 8.75 lb
+      # @example Parse 'stone-pound' measurement:
+      #   CompositeUnitMeasurements::Weight.parse("2 st 6 lb") #=> 2.428571428571429 st
+      #
       # @param [String] string The string to parse for weight measurement.
       # @return [UnitMeasurements::Weight]
       #   Returns a UnitMeasurements::Weight object if parsing is successful.
@@ -34,7 +41,8 @@ module CompositeUnitMeasurements
       private
 
       # @private
-      # Parses a +string+ representing a weight in the format of +pound-ounce+.
+      # Parses a +string+ representing a weight in the format of +pound-ounce+
+      # into a +UnitMeasurements::Weight+ object.
       #
       # @param [String] string
       #   The string representing weight measurement in the format of *pound-ounce*.
@@ -53,7 +61,8 @@ module CompositeUnitMeasurements
       end
 
       # @private
-      # Parses a +string+ representing a weight in the format of +stone-pound+.
+      # Parses a +string+ representing a weight in the format of +stone-pound+
+      # into a +UnitMeasurements::Weight+ object.
       #
       # @param [String] string
       #   The string representing weight measurement in the format of *stone-pound*.
@@ -72,7 +81,8 @@ module CompositeUnitMeasurements
       end
 
       # @private
-      # Parses a +string+ representing a weight in the format of +kilogramme-gramme+.
+      # Parses a +string+ representing a weight in the format of +kilogramme-gramme+
+      # into a +UnitMeasurements::Weight+ object.
       #
       # @param [String] string
       #   The string representing weight measurement in the format of *kilogramme-gramme*.
@@ -91,8 +101,6 @@ module CompositeUnitMeasurements
       end
     end
 
-    private
-
     # Regex pattern for aliases of +pound+ unit.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
@@ -140,5 +148,8 @@ module CompositeUnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 0.3.0
     KILOGRAMME_GRAMME = /\A#{ANY_NUMBER}\s*#{KILOGRAMME_ALIASES}\s*#{ANY_NUMBER}\s*#{GRAMME_ALIASES}\z/.freeze
+
+    private_constant :KILOGRAMME_GRAMME, :POUND_ALIASES, :OUNCE_ALIASES, :STONE_ALIASES ,
+                     :GRAMME_ALIASES, :KILOGRAMME_ALIASES, :POUND_OUNCE, :STONE_POUND
   end
 end

data/lib/composite_unit_measurements.rb

@@ -7,3 +7,4 @@ require "composite_unit_measurements/base"
 require "composite_unit_measurements/length"
 require "composite_unit_measurements/time"
 require "composite_unit_measurements/weight"
+require "composite_unit_measurements/volume"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: composite_unit_measurements
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-27 00:00:00.000000000 Z
+date: 2023-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -124,6 +124,7 @@ files:
 - lib/composite_unit_measurements/length.rb
 - lib/composite_unit_measurements/time.rb
 - lib/composite_unit_measurements/version.rb
+- lib/composite_unit_measurements/volume.rb
 - lib/composite_unit_measurements/weight.rb
 homepage: https://github.com/shivam091/composite_unit_measurements
 licenses: