Unit Measurements

A library that encapsulate measurements and their units in Ruby.

Harshal V. Ladhe, Master of Computer Science.

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.

The unit_measurements gem is designed to simplify the handling of units for scientific calculations.

1. Flexible 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, 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 for quick reference and implementation guidance.
6. Caching Support: Option to cache conversion factors for improved performance.
7. Configurable Options: Fine-tune behavior with configurable options, including caching for enhanced performance.
8. Error Handling: Robust error handling ensures stability and reliability during conversions.

The unit conversions provided here are for reference and general informational purposes. While we aim for accuracy, we cannot guarantee precision in all scenarios. Users are advised to cross-verify conversions for their specific use cases.

• Ruby 3.2.2+ (Download Ruby)

To use unit_measurements in your Rails application, add the following line to your Gemfile:

gem "unit_measurements"

And then execute:

$ bundle install

Or otherwise simply install it yourself as:

$ gem install unit_measurements

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:

UnitMeasurements.configure do |config|
  config.use_cache = false
end

The current available configurable options are:

The UnitMeasurements::Measurement class is responsible for conversion of quantity to various compatible units but it can't be directly initialized or converted to other units, but rather it is done with the unit group classes viz., UnitMeasurements::Weight, UnitMeasurements::Length, etc.

Initialize a measurement:

UnitMeasurements::Length.new(1, "km") #=> 1 km

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, #in, and #as) or #convert_to! (aliased as #to!, #in!, and #as!) methods. You can also chain call of #convert_to and #convert_to! methods.

These methods provide use_cache parameter which defaults to false to indicate whether the caching of conversion factors should happen.

You can use #convert_to as:

UnitMeasurements::Length.new(1, "km").convert_to("m", use_cache: true) #=> 1000.0 m

If you want to modify measurement object itself, you can use #convert_to! method as:

UnitMeasurements::Length.new(1, "km").convert_to!("m") #=> 1000.0 m

You can convert the measurement directly to the primitive unit of the unit group as:

UnitMeasurements::Length.new(1, "cm").to_primitive #=> 0.01 m

Note: #to_primitive method is aliased as #in_primitive and #as_primitive.

Parse string without having to split out the quantity and source unit:

This method provides use_cache parameter which defaults to false to indicate whether the caching of conversion factors should happen.

UnitMeasurements::Length.parse("1 km") #=> 1.0 km

Parse string that mentions quantity, source unit, and target unit:

A source unit can be separated from the target unit using the in, to, or as operators.

UnitMeasurements::Length.parse("1 km to m") #=> 1000.0 m

Parse scientific numbers, source unit, and (or) target unit:

UnitMeasurements::Length.parse("2e+2 km").convert_to("m") #=> 200000.0 m
UnitMeasurements::Length.parse("2e+2 km to m") #=> 200000.0 m

You can check supported special characters for exponents here.

Parse complex numbers, source unit, and (or) target unit:

UnitMeasurements::Length.parse("2+3i km").convert_to("m") #=> 2000.0+3000.0i m
UnitMeasurements::Length.parse("2+3i km to m") #=> 2000.0+3000.0i m

Parse fractional/mixed fractional numbers, source unit, and (or) target unit:

UnitMeasurements::Length.parse("2 ½ km").convert_to("m") #=> 2500.0 m
UnitMeasurements::Length.parse("2/3 km to m") #=> 666.666666666667 m

You can check supported special characters for fractional notations here.

Parse ratios, source unit, and (or) target unit:

UnitMeasurements::Length.parse("1:2 km").convert_to("m") #=> 500.0 m
UnitMeasurements::Length.parse("1:2 km to m") #=> 500.0 m

Calculate the ratio between two units:

UnitMeasurements::Length.ratio("in", "ft") #=> "12.0 in/ft"

Formatting measurement:

If you want to format the measurement to certain format, you can use #to_fs method. If format is not specified, it defaults to "%.2<value>f %<unit>s".

UnitMeasurements::Length.new(100, "m").to("in").to_fs("%.4<quantity>f %<unit>s") #=> "3937.0079 in"

You can check more about formatting along with their examples here.

Extract the quantity and the unit from measurement:

length = UnitMeasurements::Length.new(1, "km")
length.quantity #=> 1
length.unit #=> #<UnitMeasurements::Unit: km (kilometer, kilometers, kilometre, kilometres)>

Unit object can be interrogated for a range of attributes:

# Alternative names for the unit.
length.unit.aliases #=> #<Set: {"kilometer", "kilometers", "kilometre", "kilometres"}>
# Conversion factor relative to primitive unit.
length.unit.conversion_factor #=> 1000.0

See primitive unit of the unit group:

UnitMeasurements::Length.primitive #=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>

See all units of the unit group:

UnitMeasurements::Length.units
#=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>, ..., ...]

See names of all valid units of the unit group:

UnitMeasurements::Length.unit_names #=> ["ft", "in", "m", "mi", "yd"]

See all valid units of the unit group along with their aliases:

UnitMeasurements::Length.unit_names_with_aliases
#=> ["\"", "'", "feet", "foot", "ft", "in", "inch", "inches", "m", "meter", "meters", "metre", "metres", "mi", "mile", "miles", "yard", "yards", "yd"]

See list of unit systems defined within the unit group:

UnitMeasurements::Length.systems #=> ["metric", "imperial", "us_customary", "astronomical"]

See list of units within the unit system:

You can use #units_for or #units_for! methods to find all the units defined within the unit system. #units_for! method returns a runtime error if the unit system is not defined within the unit group.

UnitMeasurements::Length.units_for("metric")
#=> [#<UnitMeasurements::Unit: m (meter, meters, metre, metres)>, ...]

Finding units within the unit group:

You can use #unit_for or #unit_for! (aliased as #[]) methods to find units within the unit group. #unit_for! method returns an error if the unit is not defined within the unit group.

UnitMeasurements::Length.unit_for("m") #=> #<UnitMeasurements::Unit: m (meter, meters, metre, metres)>
UnitMeasurements::Length.unit_for("z") #=> nil
UnitMeasurements::Length.unit_for!("z") #=> Invalid unit: 'z'. (UnitMeasurements::UnitError)

Finding whether the unit is defined within the unit group:

UnitMeasurements::Length.defined?("m") #=> true
UnitMeasurements::Length.defined?("metre") #=> false

Check if the unit is a valid unit or alias within the unit group:

UnitMeasurements::Length.unit_or_alias?("m") #=> true
UnitMeasurements::Length.unit_or_alias?("metre") #=> true

Clear cached data for the unit group:

UnitMeasurements::Length.clear_cache

You have ability to compare the measurements with the same or different units within the same unit group. For example, comparing length with length will work, comparing a length with a area would fail.

UnitMeasurements::Length.parse("1 km") != UnitMeasurements::Length.parse("1 m") #=> true

You can check supported comparisons along with their examples here.

You have ability to perform arithmetic operations on measurements with the same or different units within a same unit group. You can perform arithmetic operations on measurement by either other measurement with compatible unit or numeric value. In cases of different units, the left hand side takes precedence.

UnitMeasurements::Length.new(1, "km") + UnitMeasurements::Length.new(1, "m") #=> 1.001 km
UnitMeasurements::Length.new(2, "km") * 2+2i #=> 4+2i km

You can check supported arithmetic operations along with their examples here.

You can perform mathematical functions on the measurements.

UnitMeasurements::Length.new(17.625, "m").round #=> 18 m

You can check supported mathematical functions along with their examples here.

You can convert measurement quantity directly to other numeric types viz. Integer, BigDecimal, Rational, Complex, and Float.

UnitMeasurements::Length.new(2.25567, "km").to_i #=> 2 km

You can check more about them along with their examples here.

The UnitMeasurements::Unit class is used to represent the units for a measurement.

Support for SI prefixed units is provided through the si_unit method. Units declared this way automatically support all decimal SI prefixes. This method takes an optional add_binary_prefixes parameter, which can be set to true if the unit supports binary SI prefixes in addition to decimal SI prefixes.

There are tons of units that are bundled in unit_measurements. You can check them out here.

By default, unit_measurements includes all unit groups automatically when you require the gem using:

require "unit_measurements"

You can skip these unit groups and only build your own unit groups by doing:

gem "unit_measurements", require: "unit_measurements/base"

You can also use unit groups in your application as per your need as:

gem "unit_measurements", require: ["unit_measurements/base", "unit_measurements/unit_groups/length"]

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.

UnitMeasurements::MyUnitGroup = UnitMeasurements.build do
  # Set primitive unit for the unit group.
  primitive "s"

  # Group units by the unit system (optional).
  system :metric do
    # This will add unit `m` along with all decimal SI prefixes.
    si_unit "s", aliases: ["second", "seconds"]

    # This will add unit `B` along with all binary & decimal SI prefixes.
    si_unit "B", aliases: ["byte", "bytes"], add_binary_prefixes: true

    # Add units to the group, along with their conversion multipliers.
    unit "min", value: "60 s", aliases: ["hour", "hours"]

    # 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 "my_units_cache.json"
end

All units allow aliases, as long as they are unique. Unit name can be used to define the unit as long as it is unique. All unit names are case sensitive.

All unit groups and their definition classes are namespaced by default, but can be aliased in your application.

Weight = UnitMeasurements::Weight
Length = UnitMeasurements::Length
Volume = UnitMeasurements::Volume

The .define_numeric_methods method allows you to define numeric methods that help you to initialize measurements in a manner similar to how ActiveSupport::Duration objects are created in Rails, providing a familiar syntax and functionality.

To define numeric methods for specific units within the unit group, use the following syntax:

UnitMeasurements::Length.define_numeric_methods("metre", "foot", "inch")

This will enable the usage of these units as methods to instantiate and use measurements:

# Initialize a measurement
1.m       #=> 1 m
5.feet    #=> 5 ft
10.inches #=> 10 in

# Usage
## Equality comparison
1.foot == 12.inches #=> true
## Arithmetic operation
1.ft + 12.in        #=> 2.0 ft

The .define_conversion_methods method allows you to define conversion methods that help you to easily convert measurements to a different unit.

To define conversion methods for specific units within the unit group, use the following syntax:

UnitMeasurements::Length.define_conversion_methods("metre", "foot", "inch")

This will enable you to convert units as:

UnitMeasurements::Length.new(1, "ft").in_inches #=> 12.0 in
12.in.in_foot                                   #=> 1.0 ft

Contributions to this project are welcomed! To contribute:

1. Fork this repository
2. Create a new branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am "Add some feature")
4. Push the changes to your branch (git push origin my-new-feature)
5. Create new Pull Request

Copyright 2023 Harshal V. LADHE, Released under the MIT License.