unit_measurements 5.1.0 → 5.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8e055ec9a81c6c27050136128e36d6bceba2b3292e6494a2bbd3305ccbcb20b
-  data.tar.gz: 381e87126aaa72bd762f537fe6be8638adbf07105ed992009a8298f6d6159de4
+  metadata.gz: 30ecc167254df71dd7e6415ea85e4042837d37294041d5fc1791e395711a5774
+  data.tar.gz: c7e5382424fbb305607a312e6fec931e0967c09d402f08ce88343909a7c0a89e
 SHA512:
-  metadata.gz: b8b3831f2e780623cd1d7d8e86d7f4687c58ed380dabccfa2eff81ab1c9cb13c8295970c1980acbf920ee00bffcba6fd3d310563fc3d27ecbc6946e14fadddea
-  data.tar.gz: d45c0207c736ca65b6041483d609a6390784fd60334c49220d36580f5fb3e3882c1f5a49d5951e6bc3f46386769cd18168bb8fcb6e897fb9b742fa3445acd8b7
+  metadata.gz: b50e6cf5076ed8a27b16b81246c864cb0b3dcbeba9e91b400d7e377f91bd9497667312f2ff551cb43abc4a3520ee11d31f4926b20bbf40010f0895d19d0c32e7
+  data.tar.gz: 948c1541e6e57613839a88dee8c5f99e583f0137c2bfc3114fa1e9eb758bce608b6f194adbab2f8e85216768127630ec65c90bb4fd685054cbb69000fa0a9a9e

data/.github/workflows/pages.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install Dependencies
         run: gem install yard
       - name: Generate Documentation
-        run: yardoc --private --exclude "unit_groups/*"
+        run: yardoc
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3.9.3
         with:

data/.gitignore

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

data/.yardopts

@@ -0,0 +1,2 @@
+--exclude unit_groups/*
+--private

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [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
+
+- Updated readme and documentation.
+- Updated documentation hosting link to `https://shivam091.github.io/unit_measurements`.
+
+----------
+
 ## [5.1.0](https://github.com/shivam091/unit_measurements/compare/v5.0.0...v5.1.0) - 2023-10-19
 
 ### What's new

data/Gemfile.lock

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

data/README.md

@@ -24,11 +24,12 @@ The `unit_measurements` gem is designed to simplify the handling of units for sc
 
 ## Features
 
-- Easy unit conversion.
-- Lightweight and extensible for adding custom units and conversions.
-- Supports various [unit groups](https://github.com/shivam091/unit_measurements/blob/main/units.md).
-- Well-documented: [Documentation](https://rubydoc.info/gems/unit_measurements).
-- Parses complex, fractional, mixed fractional, scientific numbers, and ratios.
+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. Ability to parse strings representing complex, fractional, mixed fractional, scientific numbers, and ratios.
+5. Well organized and descriptive documentation published [here](https://shivam091.github.io/unit_measurements).
+6. Supports caching of conversion factors between different units of the unit group.
 
 ## Disclaimer
 
@@ -74,6 +75,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 +107,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
@@ -127,7 +132,7 @@ UnitMeasurements::Length.parse("2e+2 km to m")
 #=> 200000.0 m
 ```
 You can check supported special characters for exponents
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Normalizer.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **Parse complex numbers, source unit, and (or) target unit:**
 
@@ -148,7 +153,7 @@ UnitMeasurements::Length.parse("2/3 km to m")
 ```
 
 You can check supported special characters for fractional notations
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Normalizer.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Normalizer.html).
 
 **Parse ratios, source unit, and (or) target unit:**
 
@@ -170,7 +175,7 @@ UnitMeasurements::Length.new(100, "m").to("in").format("%.4<quantity>f %<unit>s"
 ```
 
 You can check more about formatting along with their examples
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Formatter.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Formatter.html).
 
 **Extract the unit and the quantity from measurement:**
 
@@ -254,6 +259,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.
@@ -265,7 +276,7 @@ UnitMeasurements::Length.parse("1 km") != UnitMeasurements::Length.parse("1 m")
 ```
 
 You can check supported comparisons along with their examples
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Comparison.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Comparison.html).
 
 ### Arithmetic
 
@@ -282,7 +293,7 @@ UnitMeasurements::Length.new(2, "km") * 2+2i
 ```
 
 You can check supported arithmetic operations along with their examples
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Arithmetic.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Arithmetic.html).
 
 ### Math
 
@@ -294,7 +305,7 @@ UnitMeasurements::Length.new(17.625, "m").round
 ```
 
 You can check supported mathematical functions along with their examples
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Math.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Math.html).
 
 ### Conversions
 
@@ -307,7 +318,7 @@ UnitMeasurements::Length.new(2.25567, "km").to_i
 ```
 
 You can check more about them along with their examples
-[here](https://rubydoc.info/gems/unit_measurements/UnitMeasurements/Conversion.html).
+[here](https://shivam091.github.io/unit_measurements/UnitMeasurements/Conversion.html).
 
 ## Units
 
@@ -413,6 +424,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

@@ -36,6 +36,8 @@ module UnitMeasurements
     #     system :imperial do
     #       unit "in", value: "25.4 mm", aliases: ['"', "inch", "inches"]
     #     end
+    #
+    #     cache "length.json"
     #   end
     #
     # @param block
@@ -78,6 +80,7 @@ module UnitMeasurements
 end
 
 # The following requires load various components of the unit measurements library.
+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/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,35 @@ 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)
+      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.0"
+  VERSION = "5.2.0"
 end

data/unit_measurements.gemspec

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

data/units.md

@@ -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.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Harshal LADHE
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-19 00:00:00.000000000 Z
+date: 2023-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -97,6 +97,7 @@ files:
 - ".github/workflows/pages.yml"
 - ".gitignore"
 - ".rspec"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -106,6 +107,7 @@ 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/conversion.rb
 - lib/unit_measurements/errors/parse_error.rb
@@ -178,7 +180,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/shivam091/unit_measurements
-  documentation_uri: https://rubydoc.info/gems/unit_measurements
+  documentation_uri: https://shivam091.github.io/unit_measurements
   source_code_uri: https://github.com/shivam091/unit_measurements
   changelog_uri: https://github.com/shivam091/unit_measurements/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/shivam091/unit_measurements/issues