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