unit_measurements 5.1.1 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a5ba942c1c99f76efc0db51ce916d31d199646d5bd2a5ace71b34fadbadacb2
-  data.tar.gz: 681c3ce17cebe41d715c78b25669afe6347d726405b4fcea74ffd8da3d5e9dc4
+  metadata.gz: 006027cb5f557c69f5ba083f6624cf9e424fcb00cc794b8f50912907538a3689
+  data.tar.gz: 4db6ec5c12a752191933c5aa6d99837c1e2dc5e8269e5d05339a6e9b631d3e7f
 SHA512:
-  metadata.gz: 518cdb270f00447a0a7817e4db3bf8dbd83e6ed1ccdb82e58ef60579d774eff9f40544669b216ab42ee7133e23cf69f1ce149c7d051e8ffc3e147cc356361392
-  data.tar.gz: 239e100a9b733cbe1792ffc54c812a5fce1abecc2e449bdd03ee6215b84e72ad98eaaa1abec9d9e389deee515fef04cdef022e7c8fe6ab765c8b436eb4f0b0b2
+  metadata.gz: fe13840ae30879e2068b4a0628e073259d8faab8efc615f0ff6da1b4fc7307b2a4285ebe44425fc4bedf26263e02a5f29e34df6ac792e3c16429f214262dbc31
+  data.tar.gz: d9f28aecb8b8dea511466a8e4f71288581c35407d841b20d65006a9bb8e3dad8d3ec53da4b2f83c0235d9a919a2dccf572371957c1010a8d449c7b11bdf1947f

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/cache/*.json
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [5.3.0](https://github.com/shivam091/unit_measurements/compare/v5.2.0...v5.3.0) - 2023-10-24
+
+### What's new
+
+- Added ability set globally configurable options for **`unit_measurements`**.
+
+### What's improved
+
+- Code coverage improvements.
+
+----------
+
+## [5.2.0](https://github.com/shivam091/unit_measurements/compare/v5.1.1...v5.2.0) - 2023-10-22
+
+### What's new
+
+- Added ability to set name of the cache file for the unit group.
+- Added support for caching conversion factors between units of the unit group.
+
+----------
+
 ## [5.1.1](https://github.com/shivam091/unit_measurements/compare/v5.1.0...v5.1.1) - 2023-10-20
 
 ### What's updated

data/Gemfile.lock

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

data/README.md

@@ -22,13 +22,16 @@ to numerous errors.
 
 The `unit_measurements` gem is designed to simplify the handling of units for scientific calculations.
 
-## Features
-
-1. Provides easy conversion between units.
-2. Lightweight and easily extensible to include other units and conversions.
-3. Built in support for various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
-4. Well organized and very descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
-5. Parses strings representing complex, fractional, mixed fractional, scientific numbers, and ratios.
+## Key Features
+1. **Simplified Measurement Conversion:** Easily convert measurements between compatible units, reducing the likelihood of errors in scientific calculations.
+2. **Extensible Unit Groups:** Effortlessly build own unit groups with specific units and conversions tailored to your needs.
+3. **Built-in Unit Groups:** Comes bundled with a wide range of standard [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md),
+  covering various units.
+4. **String Parsing Capabilities:** Effortlessly parse strings representing complex, fractional, mixed fractional, scientific numbers, and ratios directly
+  saving you the hassle of manually extracting and converting them.
+5. **Comprehensive Documentation:** Well-organized and descriptive [documentation](https://shivam091.github.io/unit_measurements) for quick reference and implementation guidance.
+6. **Configurable Options:** Fine-tune behavior with configurable options, including caching for enhanced performance.
+7. **Error Handling:** Robust error handling ensures stability and reliability during conversions.
 
 ## Disclaimer
 
@@ -56,6 +59,23 @@ Or otherwise simply install it yourself as:
 
 `$ gem install unit_measurements`
 
+## Configuration
+
+`unit_measurements` is designed to work out of the box, but you can customize its behavior by placing
+the configuration block in an initializer file before requiring the library files:
+
+```ruby
+UnitMeasurements.configure do |config|
+  config.use_cache = false
+end
+```
+
+The current available configurable options are:
+
+| Option | Default value | Description |
+| ------ | ------------- | ----------- |
+| **use_cache** | false | Set to `true` to enable caching during conversions. |
+
 ## Usage
 
 The **`UnitMeasurements::Measurement`** class is responsible for conversion of quantity to various compatible units
@@ -74,6 +94,8 @@ UnitMeasurements::Length.new(1, "km")
 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`, `#in`, and `#as`) or `#convert_to!` (aliased as `#to!`, `#in!`, and `#as!`) methods.
 
+These methods provide `use_cache` parameter which can be used to indicate whether the caching of conversion factors should happen.
+
 You can use `#convert_to` as:
 
 ```ruby
@@ -104,6 +126,8 @@ UnitMeasurements::Length.new(100, "m").convert_to("ft").convert_to!("in")
 
 **Parse string without having to split out the quantity and source unit:**
 
+This method provides `use_cache` parameter which can be used to indicate whether the caching of conversion factors should happen.
+
 ```ruby
 UnitMeasurements::Length.parse("1 km")
 #=> 1.0 km
@@ -254,6 +278,12 @@ UnitMeasurements::Length.unit_or_alias?("metre")
 #=> true
 ```
 
+**Clear cached data for the unit group:**
+
+```ruby
+UnitMeasurements::Length.clear_cache
+```
+
 ### Comparisons
 
 You have ability to compare the measurements with the same or different units within the same unit group.
@@ -389,10 +419,9 @@ gem "unit_measurements", require: ["unit_measurements/base", "unit_measurements/
 
 ### Building new unit groups
 
-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.
+This library provides a simpler way to define your own unit groups. Use the `UnitMeasurements.build` method to define
+units within it. You can group units by the unit system using the `system` method and set the primitive unit for the
+unit group using the `primitive` method. You can specify cache file name in unit group definition using the `cache` method.
 
 ```ruby
 UnitMeasurements::Time = UnitMeasurements.build do
@@ -413,6 +442,9 @@ UnitMeasurements::Time = UnitMeasurements.build do
     # You can also specify unit value as an array.
     unit "h", value: [60, "min"], aliases: ["day", "days"]
   end
+
+  # Sets the name of the cache file (optional).
+  cache "time_cache.json"
 end
 ```
 

data/lib/unit_measurements/base.rb

@@ -7,6 +7,13 @@ require "unit_measurements/version"
 
 module UnitMeasurements
   class << self
+    # Allows setting an instance of +Configuration+ containing values of desired
+    # configurable options.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    attr_writer :configuration
+
     # Creates a new unit group based on the provided +block+ of instructions.
     #
     # The +build+ method allows you to define and create a custom unit group with
@@ -36,11 +43,9 @@ module UnitMeasurements
     #     system :imperial do
     #       unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]
     #     end
-    #   end
     #
-    # @param block
-    #   A block of instructions for defining units and their conversions within
-    #   the unit group.
+    #     cache "length.json"
+    #   end
     #
     # @yield [builder]
     #   A block that defines the units to be added to the unit group.
@@ -74,10 +79,59 @@ module UnitMeasurements
         @unit_group = builder.build
       end
     end
+
+    # Returns an instance of +Configuration+ with the values of desired configurable
+    # options of +*unit_measurements*+. If instance is not present, it initializes
+    # a new instance of {Configuration}.
+    #
+    # @return [Configuration] An instance of +Configuration+.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset the configuration to its default state.
+    #
+    # @example
+    #   UnitMeasurements.reset
+    #
+    # @return [Configuration] A new +Configuration+ object.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def reset
+      @configuration = Configuration.new
+    end
+
+    # Configures options of the +*UnitMeasurements*+ module using a block. It
+    # yields the current +Configuration+ instance for updating default values of
+    # options by new values specified within a block.
+    #
+    # @example
+    #   UnitMeasurements.configure do |config|
+    #     config.use_cache = false
+    #   end
+    #
+    # @yield [configuration] The current +Configuration+ instance.
+    #
+    # @yieldparam [Configuration] configuration
+    #   An instance of +Configuration+ with the new values of options.
+    #
+    # @yieldreturn [Configuration] The updated +Configuration+ instance.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def configure
+      yield configuration
+    end
   end
 end
 
 # The following requires load various components of the unit measurements library.
+require "unit_measurements/configuration"
+require "unit_measurements/cache"
 require "unit_measurements/unit_group_builder"
 require "unit_measurements/unit"
 require "unit_measurements/unit_group"

data/lib/unit_measurements/cache.rb

@@ -0,0 +1,173 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_string_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Cache+ class manages caching of conversion factors
+  # between different units within a unit group. It provides methods to retrieve,
+  # set, and clear cached conversion factors.
+  #
+  # Cached conversion factors are stored in JSON file on the file system.
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.2.0
+  class Cache
+    # The directory path where cache files are stored.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    CACHE_DIRECTORY = File.expand_path(File.join("..", "..", "cache"), __dir__).freeze
+
+    # Stores cached conversion factors between different units within a unit
+    # group.
+    #
+    # @return [Hash] The cached conversion factors.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    attr_reader :cached_data
+
+    # Initializes a new +Cache+ instance for a specific unit group.
+    #
+    # Initialization first ensures existence of the cache directory. If the cache
+    # directory does not exist, it gets created.
+    #
+    # @param [UnitGroup] unit_group The unit group associated with the cache.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def initialize(unit_group)
+      ensure_cache_directory_exists
+      @cache_file = build_cache_file_path(unit_group)
+      @cached_data ||= load_cache
+    end
+
+    # Retrieves the conversion factor between source and target units from the
+    # cache.
+    #
+    # @param [String] source_unit The source unit name.
+    # @param [String] target_unit The target unit name.
+    #
+    # @return [Numeric|NilClass]
+    #   The conversion factor, or +nil+ if not found in the cache.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def get(source_unit, target_unit)
+      cached_data.dig(source_unit, target_unit)
+    end
+
+    # Sets the conversion factor between source and target units in the cache.
+    #
+    # @param [String] source_unit The source unit name.
+    # @param [String] target_unit The target unit name.
+    # @param [Numeric] conversion_factor The conversion factor.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def set(source_unit, target_unit, conversion_factor)
+      cached_data[source_unit] ||= {}
+      cached_data[source_unit][target_unit] = conversion_factor
+
+      store_cache
+    end
+
+    # Clears the entire cache.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def clear_cache
+      @cached_data = {}
+      store_cache
+    end
+
+    private
+
+    # @private
+    # Loads the cache from the cache file.
+    #
+    # @return [Hash] The loaded cache data.
+    #
+    # @raise [Errno::ENOENT] If the cache file does not exist.
+    # @raise [Errno::EACCES]
+    #   If the cache file cannot be accessed due to insufficient permissions.
+    # @raise [JSON::ParserError] If there's an error parsing the cache file.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def load_cache
+      return {} unless File.exist?(@cache_file)
+
+      begin
+        File.open(@cache_file, "r") { |file| JSON.load(file.read) }
+      rescue Errno::ENOENT, Errno::EACCES, JSON::ParserError => e
+        puts "Error loading cache"
+        {}
+      end
+    end
+
+    # @private
+    # Stores the current cache data to the cache file. +cached_data+ is stored in
+    # prettier form.
+    #
+    # @raise [Errno::ENOENT] If the cache file does not exist.
+    # @raise [Errno::EACCES]
+    #   If the cache file cannot be accessed due to insufficient permissions.
+    # @raise [Errno::ENOSPC]
+    #   If there's not enough space to write to the cache file.
+    # @raise [JSON::GeneratorError] If there's an error generating JSON data.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def store_cache
+      begin
+        File.open(@cache_file, "w") do |file|
+          file.write(JSON.pretty_generate(cached_data))
+        end
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ENOSPC, JSON::GeneratorError => e
+        puts "Error saving cache: #{e.message}"
+      end
+    end
+
+    # @private
+    # Ensures that the cache directory exists. If the cache directory does not
+    # exist, it gets created.
+    #
+    # @raise [Errno::EEXIST] If the cache directory already exists.
+    # @raise [Errno::EACCES]
+    #   If the cache directory cannot be accessed due to insufficient permissions.
+    # @raise [Errno::ENOSPC]
+    #   If there's not enough space to create the cache directory.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def ensure_cache_directory_exists
+      begin
+        Dir.mkdir(CACHE_DIRECTORY) unless Dir.exist?(CACHE_DIRECTORY)
+      rescue Errno::EACCES, Errno::ENOSPC => e
+        puts "Error creating cache directory: #{e.message}"
+      end
+    end
+
+    # @private
+    # Builds and returns an absolute path of the cache file.
+    #
+    # This method first checks if the cache file name is specified for the unit
+    # group. If yes, it builds absolute path of the cache file using specified
+    # cache file name. If not, it builds file name from of the name of the unit
+    # group. This file name is then used to build absolute path of the cache file.
+    #
+    # @param [UnitGroup] unit_group The unit group associated with the cache.
+    #
+    # @return [String] An absolute path of the cache file.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def build_cache_file_path(unit_group)
+      cache_file_name = unit_group.cache_file || unit_group.to_s.split("::").last.underscore
+      cache_file_name = File.basename(cache_file_name, ".json") + ".json"
+
+      Pathname.new(File.join(CACHE_DIRECTORY, cache_file_name)).cleanpath
+    end
+  end
+end

data/lib/unit_measurements/configuration.rb

@@ -0,0 +1,64 @@
+# -*- encoding: utf-8 -*-
+# -*- frozen_stringing_literal: true -*-
+# -*- warn_indent: true -*-
+
+module UnitMeasurements
+  # The +UnitMeasurements::Configuration+ class maintains and manages the globally
+  # configurable options of +*unit_measurements*+.
+  #
+  # @note
+  #   This class is responsible for configuring globally configurable options of
+  #   +*unit_measurements*+.
+  #
+  # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+  # @since 5.3.0
+  class Configuration
+    # Get the current value of the +use_cache+ option.
+    #
+    # @note
+    #   This option controls whether caching is enabled for converting measurements.
+    #   Defaults to +false+.
+    #
+    # @return [TrueClass|FalseClass]
+    #   Returns +true+ if caching is enabled, otherwise +false+.
+    #
+    # @see Cache
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    attr_reader :use_cache
+
+    # Initializes a new +Configuration+ instance with default values of configurable
+    # options.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def initialize
+      self.use_cache = false
+    end
+
+    # Sets a value for the +use_cache+ option.
+    #
+    # It controls whether caching is enabled for converting measurements. When
+    # caching is enabled, previously computed conversion factors are stored for
+    # future use, improving conversion performance.
+    #
+    # @param [TrueClass|FalseClass] use_cache
+    #   +true+ if caching should be used while converting the measurement otherwise
+    #   +false+.
+    #
+    # @return [TrueClass|FalseClass] The updated value of +use_cache+.
+    #
+    # @raise [BaseError] if +use_cache+ is not a boolean value.
+    #
+    # @see Cache
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.3.0
+    def use_cache=(use_cache)
+      unless [true, false].include?(use_cache)
+        raise BaseError, "Configuration#use_cache= only accepts true or false, but received #{use_cache}"
+      end
+
+      @use_cache = use_cache
+    end
+  end
+end

data/lib/unit_measurements/measurement.rb

@@ -120,6 +120,11 @@ module UnitMeasurements
     # Converts the measurement to a +target_unit+ and returns new instance of the
     # measurement.
     #
+    # When +use_cache+ value is true, conversion factor between units are checked
+    # in cache file of the unit group. If cached conversion factor is present in
+    # the cache file, it is used for conversion otherwise conversion factor is
+    # stored in the cache before converting the measurement to the +target_unit+.
+    #
     # @example
     #   UnitMeasurements::Length.new(1, "m").convert_to("cm")
     #   => 100.0 cm
@@ -127,9 +132,14 @@ module UnitMeasurements
     #   UnitMeasurements::Length.new(1, "cm").convert_to("primitive")
     #   => 0.01 m
     #
+    #   UnitMeasurements::Length.new(1, "m").convert_to("cm", use_cache: true)
+    #   => 100.0 cm
+    #
     # @param [String|Symbol] target_unit
     #   The target unit for conversion. Specifing +primitive+ will convert the
     #   measurement to a primitive unit of the unit group.
+    # @param [TrueClass|FalseClass] use_cache
+    #   Indicates whether to use cached conversion factors.
     #
     # @return [Measurement]
     #   A new +Measurement+ instance with the converted +quantity+ and
@@ -137,16 +147,15 @@ module UnitMeasurements
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
-    def convert_to(target_unit)
+    def convert_to(target_unit, use_cache: false)
       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
 
-      conversion_factor = (unit.conversion_factor / target_unit.conversion_factor)
+      conversion_factor = calculate_conversion_factor(target_unit, use_cache)
 
       self.class.new((quantity * conversion_factor), target_unit)
     end
@@ -160,7 +169,17 @@ 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
+    #
+    #   UnitMeasurements::Length.new(1, "m").convert_to!("cm", use_cache: true)
+    #   => 100.0 cm
+    #
+    # @param [String|Symbol] target_unit
+    #   The target unit for conversion. Specifing +primitive+ will convert the
+    #   measurement to a primitive unit of the unit group.
+    # @param [TrueClass|FalseClass] use_cache
+    #   Indicates whether to use cached conversion factors.
     #
     # @return [Measurement]
     #   The current +Measurement+ instance with updated +quantity+ and +unit+.
@@ -168,8 +187,8 @@ module UnitMeasurements
     # @see #convert_to
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
-    def convert_to!(target_unit)
-      measurement = convert_to(target_unit)
+    def convert_to!(target_unit, use_cache: false)
+      measurement = convert_to(target_unit, use_cache: use_cache)
       @quantity, @unit = measurement.quantity, measurement.unit
 
       self
@@ -219,16 +238,20 @@ module UnitMeasurements
       extend Forwardable
 
       # 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?, :[], :units_for, :units_for!
+      def_delegators :unit_group, :primitive, :units, :cache_file, :unit_names,
+                     :unit_with_name_and_aliases, :unit_names_with_aliases,
+                     :unit_for, :unit_for!, :defined?, :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,
       # using the +Normalizer+ before parsing it using the +Parser+.
       #
+      # You can separate *source* and *target* units from each other in +input+
+      # using +to+, +in+, or +as+.
+      #
       # If only the source unit is provided, it returns a new +Measurement+
-      # instance with the quantity in the source unit.If both source and target
+      # instance with the quantity in the source unit. If both source and target
       # units are provided in the input string, it returns a new +Measurement+
       # instance with the quantity converted to the target unit.
       #
@@ -237,7 +260,7 @@ module UnitMeasurements
       #   => 2.0+3.0i km
       #
       # @example Parsing string representing a complex number, source, and target units:
-      #   UnitMeasurements::Length.parse("2+3i km to m")
+      #   UnitMeasurements::Length.parse("2+3i km in m")
       #   => 2000.0+3000.0i m
       #
       # @example Parsing string representing a rational or mixed rational number and source unit:
@@ -260,10 +283,10 @@ module UnitMeasurements
       #   UnitMeasurements::Length.parse("2/3 km to m")
       #   => 666.666666666667 m
       #
-      #   UnitMeasurements::Length.parse("2 ½ km to m")
+      #   UnitMeasurements::Length.parse("2 ½ km in m")
       #   => 2500.0 m
       #
-      #   UnitMeasurements::Length.parse("2 1/2 km to m")
+      #   UnitMeasurements::Length.parse("2 1/2 km as m")
       #   => 2500.0 m
       #
       # @example Parsing string representing a scientific number and source unit:
@@ -281,7 +304,7 @@ module UnitMeasurements
       #   UnitMeasurements::Length.parse("2e+2 km to m")
       #   => 200000.0 m
       #
-      #   UnitMeasurements::Length.parse("2e⁻² km to m")
+      #   UnitMeasurements::Length.parse("2e⁻² km as m")
       #   => 20.0 m
       #
       # @example Parsing string representing a ratio and source unit:
@@ -289,10 +312,12 @@ module UnitMeasurements
       #   => 0.5 km
       #
       # @example Parsing string representing a ratio, source, and target units:
-      #   UnitMeasurements::Length.parse("1:2 km to m")
+      #   UnitMeasurements::Length.parse("1:2 km in m")
       #   => 500.0 m
       #
       # @param [String] input The input string to be parsed.
+      # @param [TrueClass|FalseClass] use_cache
+      #   Indicates whether to use cached conversion factors.
       #
       # @return [Measurement] The +Measurement+ instance.
       #
@@ -303,11 +328,42 @@ module UnitMeasurements
       # @see #convert_to
       # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
       # @since 1.0.0
-      def parse(input)
+      def parse(input, use_cache: false)
         input = Normalizer.normalize(input)
         source, target = input.match(CONVERSION_STRING_REGEXP)&.captures
 
-        target ? _parse(source).convert_to(target) : _parse(source)
+        target ? _parse(source).convert_to(target, use_cache: use_cache) : _parse(source)
+      end
+
+      # Returns the +Cache+ instance for the unit group to store and retrieve
+      # conversion factors.
+      #
+      # @return [Cache] The +Cache+ instance.
+      #
+      # @example
+      #   UnitMeasurements::Length.cached
+      #   => #<UnitMeasurements::Cache:0x00007fe407249750>
+      #
+      # @see Cache
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 5.2.0
+      def cached
+        @cached ||= Cache.new(self)
+      end
+
+      # Clears the cached conversion factors of the unit group.
+      #
+      # @return [void]
+      #
+      # @example
+      #   UnitMeasurements::Length.clear_cache
+      #
+      # @see Cache#clear_cache
+      #
+      # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+      # @since 5.2.0
+      def clear_cache
+        cached.clear_cache
       end
 
       private
@@ -384,5 +440,37 @@ module UnitMeasurements
     def unit_from_unit_or_name!(value)
       value.is_a?(Unit) ? value : self.class.send(:unit_group).unit_for!(value)
     end
+
+    # Calculates the conversion factor between the current unit and the target
+    # unit.
+    #
+    # If caching is enabled and a cached factor is available, it will be used.
+    # Otherwise, the conversion factor will be computed and, if caching is
+    # enabled, stored in the cache.
+    #
+    # @param [Unit] target_unit The target unit for conversion.
+    # @param [TrueClass|FalseClass] use_cache
+    #   Indicates whether caching should be used.
+    #
+    # @return [Numeric] The conversion factor.
+    #
+    # @see Unit
+    # @see #convert_to
+    #
+    # @note If caching is enabled, the calculated conversion factor will be stored in the cache.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def calculate_conversion_factor(target_unit, use_cache)
+      use_cache = (UnitMeasurements.configuration.use_cache || use_cache)
+
+      if use_cache && (cached_factor = self.class.cached.get(unit.name, target_unit.name))
+        cached_factor
+      else
+        factor = unit.conversion_factor / target_unit.conversion_factor
+        self.class.cached.set(unit.name, target_unit.name, factor) if use_cache
+        factor
+      end
+    end
   end
 end

data/lib/unit_measurements/unit_group.rb

@@ -36,16 +36,30 @@ module UnitMeasurements
     # @since 1.0.0
     attr_reader :units
 
+    # The name of the cache file.
+    #
+    # @example
+    #   UnitMeasurements::Length.cache_file
+    #   => "length.json"
+    #
+    # @return [String] The name of the cache file.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    attr_reader :cache_file
+
     # Initializes a new +UnitGroup+ instance.
     #
     # @param [String|Symbol, optional] primitive The name of the primitive unit.
     # @param [Array<Unit>] units An array of +Unit+ instances.
+    # @param [String] cache_file The name of the cache file.
     #
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
-    def initialize(primitive, units)
+    def initialize(primitive, units, cache_file)
       @units = units.map { |unit| unit.with(unit_group: self) }
       @primitive = unit_for!(primitive) if primitive
+      @cache_file = cache_file
     end
 
     # Returns the unit instance for a given unit name. It returns +nil+ if unit

data/lib/unit_measurements/unit_group_builder.rb

@@ -82,7 +82,7 @@ module UnitMeasurements
     # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
     # @since 1.0.0
     def build
-      UnitGroup.new(@primitive, @units)
+      UnitGroup.new(@primitive, @units, @cache_file)
     end
 
     # Defines the +unit system+ within the unit group and evaluates the provided
@@ -130,6 +130,19 @@ module UnitMeasurements
       @primitive = primitive
     end
 
+    # Sets the name of the cache file for the unit group.
+    #
+    # @example
+    #   cache "conversion_cache.json"
+    #
+    # @param [String] cache_file The name of the cache file.
+    #
+    # @author {Harshal V. Ladhe}[https://shivam091.github.io/]
+    # @since 5.2.0
+    def cache(cache_file)
+      @cache_file = cache_file
+    end
+
     private
 
     # @private

data/lib/unit_measurements/version.rb

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

data/units.md

@@ -1,12 +1,12 @@
 # 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.
+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. 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).
+1. Unit names suffixed with `*` support [Decimal SI prefixes](README.md#decimal-si-prefixes).
+2. Unit names suffixed with `**` support [Binary SI prefixes](README.md#binary-si-prefixes)
+in addition to [Decimal SI prefixes](README.md#decimal-si-prefixes).
 3. Primitive unit of the unit group is in _emphasised typeface_.
 
 ## 1. Length/Distance
@@ -125,7 +125,7 @@ These units are defined in `UnitMeasurements::Area`.
 | 12 | fur² | fur^2, sq fur, square furlong, square furlongs |
 | 13 | rod² | rod^2, sq rod, square rod, square rods |
 
-## 9. Volume
+## 9. Volume & Capacity
 
 These units are defined in `UnitMeasurements::Volume`.
 
@@ -328,7 +328,7 @@ These units are defined in `UnitMeasurements::ElectricalElastance`.
 | _1_ | _D*_ | _F⁻¹, daraf, darafs, reciprocal farad, reciprocal farads_ |
 | 2 | V/C | V·C⁻¹, volt/coulomb, volts/coulomb, volt per coulomb, volts per coulomb |
 
-## 24. Electrical resistance
+## 24. Electrical resistance/Impedance
 
 These units are defined in `UnitMeasurements::ElectricalResistance`.
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unit_measurements
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 5.3.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-20 00:00:00.000000000 Z
+date: 2023-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -107,7 +107,9 @@ files:
 - lib/unit_measurements.rb
 - lib/unit_measurements/arithmetic.rb
 - lib/unit_measurements/base.rb
+- lib/unit_measurements/cache.rb
 - lib/unit_measurements/comparison.rb
+- lib/unit_measurements/configuration.rb
 - lib/unit_measurements/conversion.rb
 - lib/unit_measurements/errors/parse_error.rb
 - lib/unit_measurements/errors/primitive_unit_already_set_error.rb