unit_measurements 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a244f904f5d302745d9ba41a499eba18381cd6398a73fc50fbd1a4b24fbba6ec
-  data.tar.gz: 51728722a5dba75a93982ce5e6bbff4e064546698992c2dc7dcdef63d20bc3a2
+  metadata.gz: 24b2504d7feb77f54138260f7e0947bd86e00225dbe3c6d9e575da3050a24eeb
+  data.tar.gz: 7d9b84113fbf2a2cd5ca1c5a46467296b15f1bf1016c1775b854098245998cee
 SHA512:
-  metadata.gz: a875fd0267562a5a63cd1914acedb4d2231950401d99427134366f8b80dabe335c0102f927c710555e13ab4746718e12b203f41a96747926f62b57c0f9869e0a
-  data.tar.gz: 4d6b39afd51c5e7787305156e43663f0231f46ba45738b2f81888b9a8e07ccbcf661c3f8d73ff4d8d9c0236673c73643e0eae0baa3f96700579a8f3d15dbb547
+  metadata.gz: b5fc7c6e1b2b580fcd5477941e239e8d06a79416b90a7c36145f8d50d32c40c7430b83273038b2974ec51df90673e46672207f8d8ae975c31e99b3612cd3b446
+  data.tar.gz: 7730a9813366e4b36dbf98873a575cf89a33963ee998da6c84d7e6b5fd7c7f5c197530e23f1acaeb2a44e339667f9665d7e3bc62c5164579df06765e01426d85

data/CHANGELOG.md

@@ -1,6 +1,27 @@
+## [1.1.0](https://github.com/shivam091/unit_measurements/compare/v1.0.0...v1.1.0) - 2023-08-14
+
+### What's new
+
+- Added `#format` method to format quantity of the measurement.
+
+----------
+
+## [1.0.0](https://github.com/shivam091/unit_measurements/compare/v0.1.0...v1.0.0) - 2023-09-14
+
+### What's new
+
+- Added support to build unit groups.
+- Added unit group for `length` units.
+- Added unit group for `weight` units.
+- Added support to build `si` units.
+- Added support to parse `Complex`, `Rational`, `Scientific` numbers, and `ratios`.
+- Added support to convert quantity between two units using `#convert_to`, `#convert_to!`, and `#parse` methods.
+
+----------
+
 ## [0.1.0] - 2023-09-13
 
-- Initial release
+### Initial release
 
 -----------
 

data/Gemfile.lock

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

data/README.md

@@ -0,0 +1,440 @@
+# Unit Measurements
+
+A library that encapsulate measurements and their units in Ruby.
+
+[![Ruby](https://github.com/shivam091/unit_measurements/actions/workflows/main.yml/badge.svg)](https://github.com/shivam091/unit_measurements/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/unit_measurements.svg)](https://badge.fury.io/rb/unit_measurements)
+[![Gem Downloads](https://img.shields.io/gem/dt/unit_measurements.svg)](http://rubygems.org/gems/unit_measurements)
+[![Maintainability](https://api.codeclimate.com/v1/badges/b8aec9bffa356d108784/maintainability)](https://codeclimate.com/github/shivam091/unit_measurements/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/b8aec9bffa356d108784/test_coverage)](https://codeclimate.com/github/shivam091/unit_measurements/test_coverage)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/shivam091/unit_measurements/blob/main/LICENSE)
+
+**Harshal V. Ladhe, M.Sc. Computer Science.**
+
+## Introduction
+
+Many technical applications need use of specialized calculations at some point of time.
+Frequently, these calculations require unit conversions to ensure accurate
+results. Needless to say, this is a pain to properly keep track of, and is prone
+to numerous errors.
+
+## Solution
+
+The `unit_measurements` gem is designed to simplify the handling of units for scientific calculations.
+
+## Advantages
+
+1. Provides easy conversion between units.
+2. Built in support for various [unit groups](units.md).
+3. Lightweight and easily extensible to include other units and conversions.
+4. Can convert `complex`, `rational`, `fractions`, `exponents`, `scientific notations`, 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._
+
+## Minimum Requirements
+
+* Ruby 3.2.2+ (https://www.ruby-lang.org/en/downloads/branches/)
+
+## Installation
+
+If using bundler, first add this line to your application's Gemfile:
+
+```ruby
+gem "unit_measurements"
+```
+
+And then execute:
+
+`$ bundle install`
+
+Or otherwise simply install it yourself as:
+
+`$ gem install unit_measurements`
+
+## Usage
+
+The **`UnitMeasurements::Measurement`** class is responsible for conversion of quantity to various compatble units.
+
+Measurements can't be initialized or converted to other units directly with the `UnitMeasurements::Measurement` class,
+but rather with the unit group classes viz., `UnitMeasurements::Weight`, `UnitMeasurements::Length`, etc.
+
+**Initialize a measurement:**
+
+```ruby
+UnitMeasurements::Weight.new(1, :kg)
+#=> 1 kg
+```
+
+**Converting to other units:**
+
+This gem allows you to convert among units of same unit group.
+You can convert measurement to other unit using `#convert_to` (aliased as `#to`)
+or `#convert_to!` (aliased as `#to!`) methods.
+
+You can use `#convert_to` as:
+
+```ruby
+UnitMeasurements::Weight.new(1, :kg).convert_to(:g)
+#=> 1000 g
+```
+
+If you want to modify measurement object itself, you can use `#convert_to!` method as:
+
+```ruby
+UnitMeasurements::Weight.new(1, :kg).convert_to!(:g)
+#=> 1000 g
+```
+
+You can also chain call of `#convert_to` and `#convert_to!` methods as:
+
+```ruby
+UnitMeasurements::Weight.new(1, :kg).convert_to(:g).convert_to(:t).convert_to!(:q)
+#=> 0.01 q
+```
+
+**Parse string without having to split out the quantity and source unit:**
+
+```ruby
+UnitMeasurements::Weight.parse("1 kg")
+#=> 1 kg
+```
+
+**Parse string that mentions quantity, source unit, and target unit:**
+
+```ruby
+UnitMeasurements::Weight.parse("1 kg to g")
+#=> 1000 g
+UnitMeasurements::Weight.parse("1 kg as g")
+#=> 1000 g
+UnitMeasurements::Weight.parse("1 kg in g")
+#=> 1000 g
+```
+
+**Parse rational numbers, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new(Rational(2, 3), :kg).convert_to(:g)
+#=> 666.666666666667 g
+UnitMeasurements::Weight.new("2/3", :kg).convert_to(:g)
+#=> 666.666666666667 g
+UnitMeasurements::Weight.parse("2/3 kg").convert_to(:g)
+#=> 666.666666666667 g
+UnitMeasurements::Weight.parse("2/3 kg to g")
+#=> 666.666666666667 g
+```
+
+**Parse complex numbers, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new(Complex(2, 3), :kg).convert_to(:g)
+#=> 2000.0+3000.0i g
+UnitMeasurements::Weight.new("2+3i", :kg).convert_to(:g)
+#=> 2000.0+3000.0i g
+UnitMeasurements::Weight.parse("2+3i kg").convert_to(:g)
+#=> 2000.0+3000.0i g
+UnitMeasurements::Weight.parse("2+3i kg to g")
+#=> 2000.0+3000.0i g
+```
+
+**Parse scientific numbers, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new(BigDecimal(2), :kg).convert_to(:g)
+#=> 2000 g
+UnitMeasurements::Weight.new(0.2e1, :kg).convert_to(:g)
+#=> 2000 g
+UnitMeasurements::Weight.parse("0.2e1 kg").convert_to(:g)
+#=> 2000 g
+UnitMeasurements::Weight.parse("0.2e1 kg to g")
+#=> 2000 g
+```
+
+**Parse ratios, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new("1:2", :kg).convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("1:2 kg").convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("1:2 kg to g")
+#=> 500 g
+```
+
+**Parse fractional notations, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new("1/2", :kg).convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("1/2 kg").convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("1/2 kg to g")
+#=> 500 g
+UnitMeasurements::Weight.new("½", :kg).convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("½ kg").convert_to(:g)
+#=> 500 g
+UnitMeasurements::Weight.parse("½ kg to g")
+#=> 500 g
+```
+
+**Parse mixed fractional notations, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new("2 1/2", :kg).convert_to(:g)
+#=> 2500 g
+UnitMeasurements::Weight.parse("2 1/2 kg").convert_to(:g)
+#=> 2500 g
+UnitMeasurements::Weight.parse("2 1/2 kg to g")
+#=> 2500 g
+UnitMeasurements::Weight.new("2 ½", :kg).convert_to(:g)
+#=> 2500 g
+UnitMeasurements::Weight.parse("2 ½ kg").convert_to(:g)
+#=> 2500 g
+UnitMeasurements::Weight.parse("2 ½ kg to g")
+#=> 2500 g
+```
+
+Supported special characters for fractional notations are `¼`, `½`, `¾`, `⅓`, `⅔`, `⅕`, `⅖`, `⅗`, `⅘`, `⅙`, `⅚`, `⅐`, `⅛`, `⅜`, `⅝`, `⅞`, `⅑`, `⅒`, `↉`, `⁄`.
+
+**Parse exponents, source unit, and (or) target unit:**
+
+```ruby
+UnitMeasurements::Weight.new("2e+2", :kg).convert_to(:g)
+#=> 200000 g
+UnitMeasurements::Weight.parse("2e² kg").convert_to(:g)
+#=> 200000 g
+UnitMeasurements::Weight.parse("2e+2 kg to g")
+#=> 200000 g
+UnitMeasurements::Weight.new("2e⁺²", :kg).convert_to(:g)
+#=> 200000 g
+UnitMeasurements::Weight.parse("2e⁺2 kg").convert_to(:g)
+#=> 200000 g
+UnitMeasurements::Weight.parse("2e⁻² kg to g")
+#=> 20 g
+```
+
+Supported special characters for exponents are `⁰`, `¹`, `²`, `³`, `⁴`, `⁵`, `⁶`, `⁷`, `⁸`, `⁹`, `⁺`, `⁻`.
+
+**Formatting measurement:**
+
+If you want to format measurement to certain format, you can use `#format` method.
+If format is not specified, it defaults to `"%.2<value>f %<unit>s"`.
+
+```ruby
+UnitMeasurements::Weight.parse("2 kg").to(:st).format
+#=> "0.31 st"
+UnitMeasurements::Weight.parse("2 kg").to(:st).format("%.4<quantity>f %<unit>s")
+#=> "0.3149 st"
+UnitMeasurements::Weight.parse("2 kg").to(:st).format("%.4<quantity>f")
+#=> "0.3149"
+```
+
+**Extract the unit and the quantity from measurement:**
+
+```ruby
+weight = UnitMeasurements::Weight.new(1.0, :kg)
+weight.quantity
+#=> 0.1e1
+weight.unit
+#=> #<UnitMeasurements::Unit: kg (kilogram, kilogramme, kilogrammes, kilograms)>
+```
+
+**See all units of the unit group:**
+
+```ruby
+UnitMeasurements::Weight.units
+#=> [#<UnitMeasurements::Unit: g (gram, gramme, grammes, grams)>, ..., ...]
+```
+
+**See names of all valid units of the unit group:**
+
+```ruby
+UnitMeasurements::Weight.unit_names
+#=> ["g", "kg", "lb", "oz", ...]
+```
+
+**See all valid units of the unit group along with their aliases:**
+
+```ruby
+UnitMeasurements::Weight.unit_names_with_aliases
+#=> ["g", "gram", "gramme", "grammes", "grams", "kg", "kilogram", "kilogramme", "kilogrammes", "kilograms", "lb", "ounce", "ounces", "oz", "pound", "pounds", ...]
+```
+
+**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.
+
+```ruby
+UnitMeasurements::Weight.unit_for(:g)
+#=> #<UnitMeasurements::Unit: g (gram, gramme, grammes, grams)>
+UnitMeasurements::Weight.unit_for(:z)
+#=> nil
+UnitMeasurements::Weight.unit_for!(:g)
+#=> #<UnitMeasurements::Unit: g (gram, gramme, grammes, grams)>
+UnitMeasurements::Weight.unit_for!(:z)
+#=> Invalid unit: 'z'. (UnitMeasurements::UnitError)
+```
+
+**Finding whether the unit is defined within the unit group:**
+
+```ruby
+UnitMeasurements::Weight.defined?(:g)
+#=> true
+UnitMeasurements::Weight.defined?(:kg)
+#=> true
+UnitMeasurements::Weight.defined?(:gramme)
+#=> false
+```
+
+**Check if the unit is a valid unit or alias within the unit group:**
+
+```ruby
+UnitMeasurements::Weight.unit_or_alias?(:g)
+#=> true
+UnitMeasurements::Weight.unit_or_alias?(:kg)
+#=> true
+UnitMeasurements::Weight.unit_or_alias?(:gramme)
+#=> true
+```
+
+## Units
+
+The **`UnitMeasurements::Unit`** class is used to represent the units for a measurement.
+
+### SI units support
+
+There is support for SI units through the use of `si_unit` method.
+Units declared through it will have automatic support for all SI prefixes:
+
+| Multiplying Factor                        | SI Prefix  | Scientific Notation |
+| ----------------------------------------- | ---------- | ------------------- |
+| 1 000 000 000 000 000 000 000 000 000 000 | quetta (Q) | 10^30               |
+| 1 000 000 000 000 000 000 000 000 000     | ronna (R)  | 10^27               |
+| 1 000 000 000 000 000 000 000 000         | yotta (Y)  | 10^24               |
+| 1 000 000 000 000 000 000 000             | zetta (Z)  | 10^21               |
+| 1 000 000 000 000 000 000                 | exa (E)    | 10^18               |
+| 1 000 000 000 000 000                     | peta (P)   | 10^15               |
+| 1 000 000 000 000                         | tera (T)   | 10^12               |
+| 1 000 000 000                             | giga (G)   | 10^9                |
+| 1 000 000                                 | mega (M)   | 10^6                |
+| 1 000                                     | kilo (k)   | 10^3                |
+| 1 00                                      | hecto (h)  | 10^2                |        
+| 1 0                                       | deca (da)  | 10^1                |
+| 0.1                                       | deci (d)   | 10^-1               |
+| 0.01                                      | centi (c)  | 10^-2               |
+| 0.001                                     | milli (m)  | 10^-3               |
+| 0.000 001                                 | micro (µ)  | 10^-6               |
+| 0.000 000 001                             | nano (n)   | 10^-9               |
+| 0.000 000 000 001                         | pico (p)   | 10^-12              |
+| 0.000 000 000 000 001                     | femto (f)  | 10^-15              |
+| 0.000 000 000 000 000 001                 | atto (a)   | 10^-18              |
+| 0.000 000 000 000 000 000 001             | zepto (z)  | 10^-21              |
+| 0.000 000 000 000 000 000 000 001         | yocto (y)  | 10^-24              |
+| 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              |
+
+### Bundled units
+
+There are tons of units that are bundled in `unit_measurements`. You can check them out [here](units.md).
+
+### Specifing units
+
+By default, `unit_measurements` ships with all the unit groups and this happens automatically
+when requiring the gem in the following manner.
+
+```ruby
+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"
+require "unit_measurements/unit_groups/weight"
+require "unit_measurements/unit_groups/volume"
+```
+
+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` in order to define base units and conversion units within it:
+
+If you build unit using `base` method, base unit automatically gets set for the unit group.
+
+```ruby
+UnitMeasurements::Time = UnitMeasurements.build do
+  # Add a base unit to the group.
+  base :s, aliases: [:second, :seconds]
+
+  # Add other units to the group, along with their conversion multipliers against
+  # base unit.
+  unit :min, value: 60.0, aliases: [:minute, :minutes]
+
+  # You can also specify conversion string if it's converted against a unit other
+  # than the unit group's base unit.
+  unit :h, value: "60 min", aliases: [:hour, :hours]
+end
+```
+
+If the unit is supporting [si prefixes](#si-units-support), you can use `si_unit` method to build it.
+If you build unit using `si_unit`, Base unit is automatically added to the group along with all SI prefixes for it.
+
+```ruby
+UnitMeasurements::Time = UnitMeasurements.build do
+  # Add a SI unit to the unit group
+  si_unit :s, aliases: [:second, :seconds]
+
+  unit :min, value: "60 s", aliases: [:minute, :minutes]
+end
+```
+
+All units allow aliases, as long as they are unique. Unit symbol can be used to
+define the unit as long as it is unique. All unit names are case sensitive.
+
+### Namespaces
+
+All unit groups and their definition classes are namespaced by default, but can be aliased in your application.
+
+```ruby
+Weight = UnitMeasurements::Weight
+Length = UnitMeasurements::Length
+Volume = UnitMeasurements::Volume
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am "Add some feature"`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Copyright 2023 [Harshal V. LADHE](https://github.com/shivam091), Released under the [MIT License](http://opensource.org/licenses/MIT).

data/lib/unit_measurements/base.rb

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+require "active_support/all"
+require "unit_measurements/version"
+
+module UnitMeasurements
+  class << self
+    def build(&block)
+      builder = UnitGroupBuilder.new
+      builder.instance_eval(&block)
+
+      Class.new(Measurement) do
+        class << self
+          attr_reader :unit_group
+        end
+
+        @unit_group = builder.build
+      end
+    end
+  end
+end
+
+require "unit_measurements/unit_group_builder"
+require "unit_measurements/unit"
+require "unit_measurements/unit_group"
+require "unit_measurements/normalizer"
+require "unit_measurements/parser"
+require "unit_measurements/formatter"
+require "unit_measurements/measurement"
+
+require "unit_measurements/errors/unit_error"
+require "unit_measurements/errors/unit_already_defined_error"
+require "unit_measurements/errors/parse_error"

data/lib/unit_measurements/errors/parse_error.rb

@@ -0,0 +1,14 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class ParseError < BaseError
+    attr_reader :string
+
+    def initialize(string)
+      @string = string
+      super("Unable to parse: '#{string}'.")
+    end
+  end
+end

data/lib/unit_measurements/errors/unit_already_defined_error.rb

@@ -0,0 +1,14 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class UnitAlreadyDefinedError < BaseError
+    attr_reader :unit
+
+    def initialize(unit)
+      @unit = unit
+      super("Unit already defined: '#{unit}'.")
+    end
+  end
+end

data/lib/unit_measurements/errors/unit_error.rb

@@ -0,0 +1,14 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class UnitError < BaseError
+    attr_reader :unit
+
+    def initialize(unit)
+      @unit = unit
+      super("Invalid unit: '#{unit}'.")
+    end
+  end
+end

data/lib/unit_measurements/formatter.rb

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  module Formatter
+    # The default format for formatting measurements.
+    DEFAULT_FORMAT = "%.2<quantity>f %<unit>s".freeze
+
+    # Formats measurement to certain formatted string specified by +format+.
+    # If +format+ is not specified, it uses +DEFAULT_FORMAT+ for
+    # formatting the measurement
+    #
+    # @example
+    #   UnitMeasurements::Weight.parse("2 kg").to(:st).format
+    #   => "0.31 st"
+    #   UnitMeasurements::Weight.parse("2 kg").to(:st).format("%.4<quantity>f %<unit>s")
+    #   => "0.3149 st"
+    #
+    # @param [String] format
+    #
+    # @return [String]
+    def format(format = nil)
+      kwargs = {quantity: quantity, unit: unit.to_s}
+      (format || DEFAULT_FORMAT) % kwargs
+    end
+  end
+end

data/lib/unit_measurements/measurement.rb

@@ -0,0 +1,103 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class Measurement
+    include Formatter
+    CONVERSION_STRING_REGEXP = /(.+?)\s?(?:\s+(?:in|to|as)\s+(.+)|\z)/i.freeze
+
+    attr_reader :quantity, :unit
+
+    def initialize(quantity, unit)
+      raise BaseError, "Quantity cannot be blank." if quantity.blank?
+      raise BaseError, "Unit cannot be blank." if unit.blank?
+
+      @quantity = convert_quantity(quantity)
+      @unit = unit_from_unit_or_name!(unit)
+    end
+
+    def convert_to(target_unit)
+      target_unit = unit_from_unit_or_name!(target_unit)
+
+      return self if target_unit == unit
+
+      conversion_factor = (unit.conversion_factor / target_unit.conversion_factor)
+      self.class.new((quantity * conversion_factor), target_unit)
+    end
+    alias_method :to, :convert_to
+
+    def convert_to!(target_unit)
+      measurement = convert_to(target_unit)
+      @quantity, @unit = measurement.quantity, measurement.unit
+      self
+    end
+    alias_method :to!, :convert_to!
+
+    def inspect(dump: false)
+      return super() if dump
+
+      to_s
+    end
+
+    def to_s
+      "#{humanized_quantity} #{unit.to_s}"
+    end
+
+    class << self
+      extend Forwardable
+
+      def unit_group
+        raise "`Measurement` does not have a `unit_group` object. You cannot directly use `Measurement`. Instead, build a new unit group by calling `UnitMeasurements.build`."
+      end
+
+      def_delegators :unit_group, :units, :unit_names, :unit_with_name_and_aliases,
+                     :unit_names_with_aliases, :unit_for, :unit_for!, :defined?,
+                     :unit_or_alias?, :[]
+
+      def parse(input)
+        input = Normalizer.normalize(input)
+        source, target = input.match(CONVERSION_STRING_REGEXP)&.captures
+        target ? _parse(source).convert_to(target) : _parse(source)
+      end
+
+      private
+
+      def _parse(string)
+        quantity, unit = Parser.parse(string)
+        new(quantity, unit)
+      end
+    end
+
+    private
+
+    def convert_quantity(quantity)
+      case quantity
+      when Float
+        BigDecimal(quantity, Float::DIG)
+      when Integer
+        Rational(quantity)
+      when String
+        quantity = Normalizer.normalize(quantity)
+        quantity, _ = Parser.parse(quantity)
+        quantity
+      else
+        quantity
+      end
+    end
+
+    def unit_from_unit_or_name!(value)
+      value.is_a?(Unit) ? value : self.class.unit_group.unit_for!(value)
+    end
+
+    def humanized_quantity
+      case quantity
+      when Complex
+        quantity
+      when Numeric
+        num = quantity.to_r
+        num.denominator == 1 ? num.numerator.to_s : num.to_f.to_s
+      end
+    end
+  end
+end

data/lib/unit_measurements/normalizer.rb

@@ -0,0 +1,73 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_stringing_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class Normalizer
+    FRACTIONS_SYMBOLS = {
+      "¼"  => "1/4",
+      "½"  => "1/2",
+      "¾"  => "3/4",
+      "⅓"  => "1/3",
+      "⅔"  => "2/3",
+      "⅕"  => "1/5",
+      "⅖"  => "2/5",
+      "⅗"  => "3/5",
+      "⅘"  => "4/5",
+      "⅙"  => "1/6",
+      "⅚"  => "5/6",
+      "⅐"  => "1/7",
+      "⅛"  => "1/8",
+      "⅜"  => "3/8",
+      "⅝"  => "5/8",
+      "⅞"  => "7/8",
+      "⅑"  => "1/9",
+      "⅒" => "1/10",
+      "↉"  => "0/3",
+      "⁄"   => "/"
+    }.freeze
+
+    EXPONENTS_SYMBOLS = {
+      "⁰" => "0",
+      "¹" => "1",
+      "²" => "2",
+      "³" => "3",
+      "⁴" => "4",
+      "⁵" => "5",
+      "⁶" => "6",
+      "⁷" => "7",
+      "⁸" => "8",
+      "⁹" => "9",
+      "⁺" => "+",
+      "⁻" => "-",
+    }
+
+    FRACTION_REGEX = /(#{FRACTIONS_SYMBOLS.keys.join("|")})/
+    EXPONENT_REGEX = /([\d]+[Ee]?[+-]?)(#{EXPONENTS_SYMBOLS.keys.join("|")})/
+    RATIO_REGEX    = /([\d]+):([\d]+)/
+
+    class << self
+      def normalize(string)
+        string.dup.tap do |str|
+          if str =~ Regexp.new(FRACTION_REGEX)
+            FRACTIONS_SYMBOLS.each do |search, replace|
+              str.gsub!(search) { " #{replace}" }
+            end
+          end
+
+          if str =~ Regexp.new(EXPONENT_REGEX)
+            EXPONENTS_SYMBOLS.each do |search, replace|
+              str.gsub!(search) { "#{replace}" }
+            end
+          end
+
+          if str =~ Regexp.new(RATIO_REGEX)
+            str.gsub!(RATIO_REGEX) { "#{$1.to_i}/#{$2.to_i}" }
+          end
+
+          str.strip!
+        end
+      end
+    end
+  end
+end

data/lib/unit_measurements/parser.rb

@@ -0,0 +1,58 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_stringing_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class Parser
+    UNIT_REGEX        = /([^\d\s\/].*)/.freeze
+
+    SCIENTIFIC_NUMBER = /([+-]?\d*\.?\d+(?:[Ee][+-]?)?\d*)/.freeze
+    RATIONAL_NUMBER   = /([+-]?\d+\s+)?((\d+)\/(\d+))/.freeze
+    COMPLEX_NUMBER    = /#{SCIENTIFIC_NUMBER}#{SCIENTIFIC_NUMBER}i/.freeze
+
+    SCIENTIFIC_REGEX  = /\A#{SCIENTIFIC_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
+    RATIONAL_REGEX    = /\A#{RATIONAL_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
+    COMPLEX_REGEX     = /\A#{COMPLEX_NUMBER}\s*#{UNIT_REGEX}?\z/.freeze
+
+    class << self
+      def parse(string)
+        case string
+        when COMPLEX_REGEX    then parse_complex(string)
+        when SCIENTIFIC_REGEX then parse_scientific(string)
+        when RATIONAL_REGEX   then parse_rational(string)
+        else                       raise ParseError, string
+        end
+      end
+
+      private
+
+      def parse_complex(string)
+        real, imaginary, unit = string.match(COMPLEX_REGEX)&.captures
+        quantity = Complex(real.to_f, imaginary.to_f)
+
+        [quantity, unit]
+      end
+
+      def parse_scientific(string)
+        whole, unit = string.match(SCIENTIFIC_REGEX)&.captures
+        quantity = whole.to_f
+
+        [quantity, unit]
+      end
+
+      def parse_rational(string)
+        whole, _, numerator, denominator, unit = string.match(RATIONAL_REGEX)&.captures
+
+        if numerator && denominator
+          numerator = numerator.to_f + (denominator.to_f * whole.to_f)
+          denominator = denominator.to_f
+          quantity = Rational(numerator, denominator).to_f
+        else
+          quantity = whole.to_f
+        end
+
+        [quantity, unit]
+      end
+    end
+  end
+end

data/lib/unit_measurements/unit.rb

@@ -0,0 +1,79 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+require "set"
+
+module UnitMeasurements
+  class Unit
+    attr_reader :name, :value, :aliases, :unit_group
+
+    def initialize(name, value:, aliases:, unit_group: nil)
+      @name = name.to_s.freeze
+      @value = value
+      @aliases = Set.new(aliases.sort.map(&:to_s).map(&:freeze)).freeze
+      @unit_group = unit_group
+    end
+
+    def with(name: nil, value: nil, aliases: nil, unit_group: nil)
+      self.class.new(
+        (name || self.name),
+        value: (value || self.value),
+        aliases: (aliases || self.aliases),
+        unit_group: (unit_group || self.unit_group)
+      )
+    end
+
+    def names
+      (aliases + [name]).sort.freeze
+    end
+
+    def to_s
+      name
+    end
+
+    def inspect
+      aliases = "(#{@aliases.join(", ")})" if @aliases.any?
+      "#<#{self.class.name}: #{name} #{aliases}>"
+    end
+
+    def conversion_factor
+      if value.is_a?(String)
+        measurement_value, measurement_unit = Parser.parse(value)
+        conversion_factor = unit_group.unit_for!(measurement_unit).conversion_factor
+        conversion_factor * measurement_value
+      else
+        value
+      end
+    end
+
+    private
+
+    SI_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]
+    ].map(&:freeze).freeze
+  end
+end

data/lib/unit_measurements/unit_group.rb

@@ -0,0 +1,51 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class UnitGroup
+    attr_reader :units
+
+    def initialize(units)
+      @units = units.map { |unit| unit.with(unit_group: self) }
+    end
+
+    def unit_for(name)
+      unit_name_to_unit(name)
+    end
+
+    def unit_for!(name)
+      unit = unit_for(name)
+      raise UnitError, name unless unit
+      unit
+    end
+    alias_method :[], :unit_for!
+
+    def unit_with_name_and_aliases
+      units.each_with_object({}) do |unit, hash|
+        unit.names.each { |name| hash[name.to_s] = unit }
+      end
+    end
+
+    def unit_names
+      units.map(&:name).sort
+    end
+
+    def unit_names_with_aliases
+      units.flat_map(&:names).sort
+    end
+
+    def unit_name_to_unit(name)
+      unit_with_name_and_aliases[name.to_s]
+    end
+
+    def defined?(name)
+      unit = unit_for(name)
+      unit ? unit.name == name.to_s : false
+    end
+
+    def unit_or_alias?(name)
+      !!unit_for(name)
+    end
+  end
+end

data/lib/unit_measurements/unit_group_builder.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class UnitGroupBuilder
+    attr_reader :units
+
+    def initialize
+      @units = []
+    end
+
+    def base(name, aliases: [])
+      @units << build_unit(name, value: 1.0, aliases: aliases)
+    end
+
+    def unit(name, value: 1.0, aliases: [])
+      @units << build_unit(name, value: value, aliases: aliases)
+    end
+
+    def si_unit(name, value: 1.0, aliases: [])
+      @units += build_si_units(name, value: value, aliases: aliases)
+    end
+
+    def build
+      UnitGroup.new(@units)
+    end
+
+    private
+
+    def build_si_units(name, value:, aliases:)
+      si_units = [build_unit(name, value: value, aliases: aliases)]
+
+      Unit::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
+        si_units << build_unit("#{short_prefix}#{name}", value: "#{multiplier} #{name}", aliases: si_aliases)
+      end
+      si_units
+    end
+
+    def build_unit(name, value:, aliases:)
+      unit = Unit.new(name, value: value, aliases: aliases)
+      check_for_duplicate_unit_names!(unit)
+      unit
+    end
+
+    def check_for_duplicate_unit_names!(unit)
+      names = @units.flat_map(&:names)
+      if names.any? { |name| unit.names.include?(name) }
+        raise UnitAlreadyDefinedError.new(unit.name)
+      end
+    end
+  end
+end

data/lib/unit_measurements/unit_groups/all.rb

@@ -0,0 +1,6 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+require_relative "length"
+require_relative "weight"

data/lib/unit_measurements/unit_groups/length.rb

@@ -0,0 +1,12 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+UnitMeasurements::Length = UnitMeasurements.build do
+  si_unit :m, aliases: %i[meter metre meters metres]
+
+  unit :in, value: "25.4 mm", aliases: %i[" inch inches]
+  unit :ft, value: "12 in", aliases: %i[' foot feet]
+  unit :yd, value: "3 ft", aliases: %i[yard yards]
+  unit :mi, value: "1760 yd", aliases: %i[mile miles]
+end

data/lib/unit_measurements/unit_groups/weight.rb

@@ -0,0 +1,10 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+UnitMeasurements::Weight = UnitMeasurements.build do
+  si_unit :g, aliases: %i[gram grams gramme grammes]
+
+  unit :q, value: "100 kg", aliases: %i[quintal quintals]
+  unit :t, value: "10 q", aliases: %i[tonne tonnes metric\ tonne metric\ tonnes]
+end

data/lib/unit_measurements/version.rb

@@ -3,5 +3,5 @@
 # -*- warn_indent: true -*-
 
 module UnitMeasurements
-  VERSION = "0.1.0"
+  VERSION = "1.1.0"
 end

data/lib/unit_measurements.rb

@@ -1,3 +1,11 @@
 # -*- encoding: utf-8 -*-
 # -*- frozen_string_literal: true -*-
 # -*- warn_indent: true -*-
+
+module UnitMeasurements
+  class BaseError < StandardError; end
+end
+
+require "unit_measurements/base"
+
+require "unit_measurements/unit_groups/all"

data/units.md

@@ -0,0 +1,32 @@
+# Bundled unit groups and units
+
+As there are lots of units bundled with `unit_measurements`, we recommend you to check below list of
+bundled units before converting your measurements.
+
+**Notes:**
+1. Base unit for each unit group is highlighted.
+2. Unit numbers suffixed with `*` support all [SI prefixes](README.md#si-units-support).
+
+Below are the units which are bundled in the unit_measurements.
+
+## 1. Length/Distance
+
+These units are defined in `UnitMeasurements::Length`.
+
+| # | Symbol | Aliases |
+|:--|:--|:--|
+| **1\*** | **m** | **meter, metre, meters, metres** |
+| 2 | in | ", inch, inches |
+| 3 | ft | ', foot, feet |
+| 4 | yd | yard, yards |
+| 5 | mi | mile, miles |
+
+## 2. Weight/Mass
+
+These units are defined in `UnitMeasurements::Weight`.
+
+| # | Symbol | Aliases |
+|--|--|--|
+| **1\*** | **g** | **gram, grams, gramme, grammes** |
+| 2 | q | quintal, quintals |
+| 3 | t | tonne, tonnes, metric tonne, metric tonnes |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-09-13 00:00:00.000000000 Z
+date: 2023-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -100,10 +100,26 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- README.md
 - Rakefile
 - lib/unit_measurements.rb
+- lib/unit_measurements/base.rb
+- lib/unit_measurements/errors/parse_error.rb
+- lib/unit_measurements/errors/unit_already_defined_error.rb
+- lib/unit_measurements/errors/unit_error.rb
+- lib/unit_measurements/formatter.rb
+- lib/unit_measurements/measurement.rb
+- lib/unit_measurements/normalizer.rb
+- lib/unit_measurements/parser.rb
+- lib/unit_measurements/unit.rb
+- lib/unit_measurements/unit_group.rb
+- lib/unit_measurements/unit_group_builder.rb
+- lib/unit_measurements/unit_groups/all.rb
+- lib/unit_measurements/unit_groups/length.rb
+- lib/unit_measurements/unit_groups/weight.rb
 - lib/unit_measurements/version.rb
 - unit_measurements.gemspec
+- units.md
 homepage: https://github.com/shivam091/unit_measurements
 licenses:
 - MIT