Measurement

Build Status Code Climate

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, 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

Units

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.

unit.name                                  # => "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.

Calculations

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

List all units names defined

List all keys you can use as unit

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

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.