Measurement

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

Installation

Add this line to your application's Gemfile:

gem 'ruby-measurement'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ruby-measurement

Usage

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.

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.

The object returned by Measurement.parse is of type Measurement.

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

The object returned by Measurement#unit is of type Measurement::Unit.

u = Measurement.unit             # => yd.
u.name                           # => "yd."
u.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).

m = Measurement.parse('3 feet')  # => 3.0 ft.
m.convert_to(:yards)             # => 1.0 yd.
m.convert_to(:in)                # => 36.0 in.
m.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.

Calculations

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

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

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

m = Measurement.parse('2 yards') # => 2.0 yd.
m * 6                            # => 12.0 yd.
m / 5                            # => 0.4 yd.
m + 3                            # => 5.0 yd.
m - 1                            # => 1.0 yd.
m ** 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 }
end

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 }
end

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 }
end

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

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

ruby-measurement is released under the MIT License.