Convertable

Convertable

Convertible was taken, and convertable was close enough.

Installation

Add this line to your application's Gemfile:

gem 'convertable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install convertable

Usage

Convertable is composed of two main ideas:

Units

Units are the basic building blocks of the library. There are two types of units, simple and composed. They both know how to convert to other units with convert_to(magnitude, new_unit). Composed units can be any permutation of multiple simple units. All units are namespaced under Convertable::Units.

e.g. convert 1.0 square meter to square feet

Convertable::Units::SquareMeter.convert_to(1.0, Convertable::Units::SquareFoot)
=> 10.7639

If a unit does not know how to convert to another unit an exception is raised

Convertable::Units::SquareMeter.convert_to(1.0, Convertable::Units::Year)
=> Convertable::Units::UnsupportedConversion (Convertable::Units::UnsupportedConversion)

Simple Units

  • Year
  • Month
  • SquareFoot
  • SquareMeter
  • Currency (Usd, Eur, Gbp)

Composed Units

Convertable::Units::ComposedUnit.new("Usd/SquareFoot/Year").inspect

 => <Convertable::Units::ComposedUnit:0x00007fa4819c7638
      @multiplying_unit=Convertable::Units::Usd,
      @dividing_units=[Convertable::Units::SquareFoot, Convertable::Units::Year]
    >

currency = Convertable::Units::Usd
area = Convertable::Units::SquareFoot
period = Convertable::Units::Year
Convertable::Units::ComposedUnit.new("#{currency}/#{area}/#{period}").inspect

 => <Convertable::Units::ComposedUnit:0x00007fa4819c7638
      @multiplying_unit=Convertable::Units::Usd,
      @dividing_units=[Convertable::Units::SquareFoot, Convertable::Units::Year]
    >

Measures

A measure is a standardized representation of a real-life physical quantity relative to some reference, called unit of measurement. It is described by its class name (UsdPerAreaPerYear) and has two components

  • Magnitude - numeric value - 20.5
  • Unit - one of the units above - Convertable::Units::ComposedUnit.new('Usd/SquareFoot/Year')

All Convertable are namespaced under Convertable::Measures.

e.g. $20.5 / square foot / year

magnitude = 20.5
unit = Convertable::Units::ComposedUnit.new('Usd/SquareFoot/Year')
measure = Convertable::Measures::MoneyPerAreaPerPeriod.new(magnitude, unit)
Unit Conversions

Measures can be converted to different units with Measure#in(new_unit):

$/sf/year => $/sm/year

measure.in(Convertable::Units::ComposedUnit.new('Usd/SquareMeter/Year')).inspect

=> <Convertable::Measures::MoneyPerAreaPerPeriod:0x00007fbcb32dcf40
     @magnitude=220.65994999999998,
     @unit=Convertable::Units::ComposedUnit.new('Usd/SquareMeter/Year')
   >

$/sf/year => $/sf/month

measure.in(Convertable::Units::ComposedUnit.new('Usd/SquareFoot/Month')).inspect

=> <Convertable::Measures::MoneyPerAreaPerPeriod:0x00007fbcaefc07e8
     @magnitude=1.7083333333333333,
     @unit=Convertable::Units::ComposedUnit.new('Usd/SquareFoot/Month')
   >
Measure Conversions

Measures can be converted to other measures provided a measure:

provided sf we can convert $/year to $/sf/year

unit = Convertable::Units::MoneyPerYear
magnitude = 200.0
measure = Convertable::Measures::MoneyPerPeriod.new(magnitude, unit)

magnitude = 50.0
area = Convertable::Measures::Area.new(magnitude, Convertable::Units::SquareFoot)
measure.to_money_per_area_per_period(area)

=> <Convertable::Measures::MoneyPerAreaPerPeriod:0x00007fc0551720d8
     @magnitude=4.0,
     @unit=Convertable::Units::ComposedUnit.new('Usd/SquareFoot/Year')
   >

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/viewthespace/convertable.