Simple Ruby gem for calculating and converting measurements.
Latest commit 3d616d0 Dec 14, 2016 @mhuggins committed on GitHub Merge pull request #12 from mklemme/master
Fix documentation for listing all unit keys
Failed to load latest commit information.
tasks Move unit definition to Unit class, and start implementing tests Feb 6, 2013
.gitignore First commit Jan 22, 2013
.travis.yml Updated version to 1.2.3 Mar 27, 2016
Gemfile First commit Jan 22, 2013
LICENSE.txt Fix documentation for listing all unit keys Dec 14, 2016
ruby-measurement.gemspec Remove trailing whitespace Mar 28, 2016


Build Status Code Climate

ruby-measurement is a simple Ruby gem for calculating and converting units of measure.


Add this line to your application's Gemfile:

gem 'ruby-measurement'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby-measurement


The Measurement class is responsible for parsing strings to determine the quantity entered as well as the unit of measure. This can be done through the parse method, which returns a Measurement object.

Measurement.parse('3 feet')                # => 3.0 ft.
Measurement.parse('25 fl oz')              # => 25.0 fl. oz.
Measurement.parse('12 tonnes')             # => 12.0 t
Measurement.parse('25 "')                  # => 25.0 in.

A measurement includes both a quantity and a unit. Refer to the "Units" section below for more details on how to interact with a unit.

measurement = Measurement.parse('12 yd')   # => 12.0 yd.
measurement.quantity                       # => 12.0
measurement.unit                           # => yd.

The String and Numeric classes have also been extended to simplify the parsing of measurement values.

'12 yd'.to_measurement                     # => 12.0 yd.
20.to_measurement                          # => 20.0 count


The Measurement::Unit class is used to represent the units for a measurement. Predefined units can be looked up via Measurement::Unit[].

unit = Measurement::Unit[:dozen]           # => doz

Similarly, the String#to_unit and Symbol#to_unit method can be used to accomplish the same thing.

unit = 'dozen'.to_unit                     # => doz
unit = :dozen.to_unit                      # => doz

Units provide access to their names and aliases.                                  # => "yd."
unit.aliases                               # => ["yd.", "yd", "yard", "yards"]

Converting units

This gem allows you to convert among compatible units as long as a conversion has been supplied when defining a unit. The default supplied units include conversions among the same unit types (e.g.: converting feet to yards or meters to kilometers).

measurement = Measurement.parse('3 feet')  # => 3.0 ft.
measurement.convert_to(:yards)             # => 1.0 yd.
measurement.convert_to(:in)                # => 36.0 in.
measurement.convert_to(:inches)            # => 36.0 in.

NOTE: Converting between metric and U.S. customary systems is currently not included by default. It is intended to be shipped in a future release.


This gem allows you to add, subtract, multiply, or divide measurements that can be converted into one-another.

measurement1 = Measurement.parse('3 feet') # => 3.0 ft.
measurement2 = Measurement.parse('6 inch') # => 6.0 in.
measurement1 + measurement2                # => 3.5 ft.

Additionally, measurements can have basic math operations performed using basic numeric values.

measurement = Measurement.parse('2 yards') # => 2.0 yd.
measurement * 6                            # => 12.0 yd.
measurement / 5                            # => 0.4 yd.
measurement + 3                            # => 5.0 yd.
measurement - 1                            # => 1.0 yd.
measurement ** 2                           # => 4.0 yd.

Specifying units

By default, ruby-measurement ships with common areas, lengths, volumes, and weights/masses for the metric and U.S. customary systems. This happens automatically when requiring the gem in the following manner.

require 'ruby-measurement'

To include just one of these systems of measure, require the gem in per the following.

require 'ruby-measurement/measurement'

# Metric units/conversions
require 'ruby-measurement/definitions/metric'

# U.S. customary units/conversions
require 'ruby-measurement/definitions/us_customary'

Additionally, specific categories of units of measure can be included per system.

require 'ruby-measurement/measurement'

# Metric units/conversions
require 'ruby-measurement/definitions/metric/area'
require 'ruby-measurement/definitions/metric/length'
require 'ruby-measurement/definitions/metric/volume'
require 'ruby-measurement/definitions/metric/weight'

# U.S. customary units/conversions
require 'ruby-measurement/definitions/us_customary/area'
require 'ruby-measurement/definitions/us_customary/length'
require 'ruby-measurement/definitions/us_customary/volume'
require 'ruby-measurement/definitions/us_customary/weight'

Defining custom units & conversions

This gem also enabled you to define units of measure that aren't included by default.

Measurement.define(:day) do |unit|
  unit.alias :days
  unit.convert_to(:week) { |value| value / 7.0 }
  unit.convert_to(:year) { |value| value / 365.0 }

Measurement.define(:wk) do |unit|
  unit.alias :week, :weeks
  unit.convert_to(:day) { |value| value * 7.0 }
  unit.convert_to(:year) { |value| value / 52.0 }

Measurement.define(:yr) do |unit|
  unit.alias :year, :years
  unit.convert_to(:day) { |value| value * 365.0 }
  unit.convert_to(:week) { |value| value * 52.0 }

Note that the first value passed to Measurement.define is the unit format that will be used when displaying a measurement.

Measurement.parse('3 yr')                  # => 3.0 yr
Measurement.parse('3 year')                # => 3.0 yr
Measurement.parse('3 years')               # => 3.0 yr

List all units names defined

List all keys you can use as unit

Measurement::Unit.names                    # => ['count','doz','dozen',...]


  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


ruby-measurement is released under the MIT License.