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.