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.
unit.name # => "yd."
unit.aliases # => ["yd.", "yd", "yard", "yards"]
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.
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'
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 keys you can use as unit
Measurement::Unit.names # => ['count','doz','dozen',...]
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
ruby-measurement is released under the MIT License.