measured 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1534c3781494b704e57f0a027deed911ee1bd826
+  data.tar.gz: 182ba934b6b9f2eb9ab75cd15f1465f7e8e568e3
+SHA512:
+  metadata.gz: ccf9e081f0e5bba182c1dac65b3fe25d77cb709fb4a32257f9bdc58bd2b0be7239363c51839509ba4fa1bf09d40e72ec0ae5dbfe97a9105585723600d4759b8e
+  data.tar.gz: fd9cfc068c0d6157f62dda09420ba9adda1f4135cdf7abbbd2cfd2ab6c50d9802983db3791116cbedc9df1fe18712e1da0726eac736475f2b4c874c09cc3502d

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Kevin McPhillips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,208 @@
+# Measured
+
+Encapsulates measruements with their units. Provides easy conversion between units.
+
+Light weight and easily extensible to include other units and conversions. Conversions done with `BigDecimal` for precision.
+
+## Installation
+
+Using bundler, add to the Gemfile:
+
+```ruby
+gem 'measured'
+```
+
+Or stand alone:
+
+    $ gem install measured
+
+## Usage
+
+Initialize a measurement:
+
+```ruby
+Measured::Weight.new("12", "g")
+```
+
+Convert to return a new measurement:
+
+```ruby
+Measured::Weight.new("12", "g").convert_to("kg")
+```
+
+Or convert inline:
+
+```ruby
+Measured::Weight.new("12", "g").convert_to!("kg")
+```
+
+Agnostic to symbols/strings:
+
+```ruby
+Measured::Weight.new(1, "kg") == Measured::Weight.new(1, :kg)
+```
+
+Seamlessly handles aliases:
+
+```ruby
+Measured::Weight.new(12, :oz) == Measured::Weight.new("12", :ounce)
+```
+
+Raises on unknown units:
+
+```ruby
+begin
+  Measured::Weight.new(1, :stone)
+rescue Measured::UnitError
+  puts "Unknown unit"
+end
+```
+
+Perform mathematical operations against other units, all represented internally as `BigDecimal`:
+
+```ruby
+Measured::Weight.new(1, :g) + Measured::Weight.new(2, :g)
+> #<Measured::Weight 3 g>
+Measured::Weight.new(2, :g) - Measured::Weight.new(1, :g)
+> #<Measured::Weight 1 g>
+Measured::Weight.new(10, :g) / Measured::Weight.new(2, :g)
+> #<Measured::Weight 5 g>
+Measured::Weight.new(2, :g) * Measured::Weight.new(3, :g)
+> #<Measured::Weight 6 g>
+```
+
+In cases of differing units, the left hand side takes precedence:
+
+```ruby
+Measured::Weight.new(1000, :g) + Measured::Weight.new(1, :kg)
+> #<Measured::Weight 2000 g>
+```
+
+Also perform mathematical operations against `Numeric` things:
+
+```ruby
+Measured::Weight.new(3, :g) * 2
+> #<Measured::Weight 6 g>
+```
+
+Extract the unit and the value:
+
+```ruby
+weight = Measured::Weight.new("1.2", "grams")
+weight.value
+> #<BigDecimal 1.2>
+weight.unit
+> "g"
+```
+
+See all valid units:
+
+```ruby
+Measured::Weight.units
+> ["g", "kg", "lb", "oz"]
+```
+
+See all valid units with their aliases:
+
+```ruby
+Measured::Weight.units_with_aliases
+> ["g", "gram", "grams", "kg", "kilogram", "kilograms", "lb", "lbs", "ounce", "ounces", "oz", "pound", "pounds"]
+```
+
+## Units and conversions
+
+### Bundled unit conversion
+
+* `Measured::Weight`
+  * g, gram, grams
+  * kg, kilogram, kilograms
+  * lb, lbs, pound, pounds
+  * oz, ounce, ounces
+* `Measured::Length`
+  * m, meter, metre, meters, metres
+  * cm, centimeter, centimetre, centimeters, centimetres
+  * mm, millimeter, millimetre, millimeters, millimetres
+  * in, inch, inches
+  * ft, foot, feet
+  * yd, yard, yards
+
+You can skip these and only define your own units by doing:
+
+```ruby
+gem 'measured', require: 'measured/base'
+```
+
+### Adding new units
+
+Extending this library to support other units is simple. To add a new conversion, subclass `Measured::Measurable`, define your base units, then add your conversion units.
+
+```ruby
+class Measured::Thing < Measured::Measurable
+  conversion.set_base :base_unit,           # Define the basic unit for the system
+    aliases: [:bu]                          # Allow it to be aliased to other names/symbols
+
+  conversion.add :another_unit,             # Add a second unit to the system
+    aliases: [:au],                         # All units allow aliases, as long as they are unique
+    value: ["1.5 base_unit"]                # The conversion rate to another unit
+
+  conversion.add :different_unit
+    aliases: [:du],
+    value: [Rational(2/3), "another_unit"]  # Conversion rate can be Rational, otherwise it is coerced to BigDecimal
+end
+```
+
+The base unit takes no value. Values for conversion units can be defined as a string with two tokens `"number unit"` or as an array with two elements. The numbers must be `Rational` or `BigDecimal`, else they will be coerced to `BigDecimal`. Conversion paths don't have to be direct as a conversion table will be built for all possible conversions using tree traversal.
+
+You can also open up the existing classes and add a new conversion:
+
+```ruby
+class Measured::Length
+  conversion.add :dm,
+    aliases: [:decimeter, :decimetre, :decimeters, :decimetres],
+    value: "0.1 m"
+end
+```
+
+### Namespaces
+
+All units and classes are namespaced by default, but can be aliased in your application.
+
+```ruby
+Weight = Measured::Weight
+Length = Measured::Length
+```
+
+## Alternatives
+
+Existing alternatives which were considered:
+
+### Gem: [ruby-units](https://github.com/olbrich/ruby-units)
+* **Pros**
+  * Accurate math and conversion factors.
+  * Includes nearly every unit you could ask for.
+* **Cons**
+  * Opens up and modifies `Array`, `Date`, `Fixnum`, `Math`, `Numeric`, `String`, `Time`, and `Object`, then depends on those changes internally.
+  * Lots of code to solve a relatively simple problem.
+  * No ActiveRecord adapter.
+
+### Gem: [quantified](https://github.com/Shopify/quantified)
+* **Pros**
+  * Light weight.
+  * Included with ActiveShipping/ActiveUtils.
+* **Cons**
+  * All math done with floats making it highly lossy.
+  * All units assumed to be pluralized, meaning using unit abbreviations is not possible.
+  * Not actively maintained.
+  * No ActiveRecord adapter.
+
+## Contributing
+
+1. Fork it ( https://github.com/Shopify/measured/fork )
+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 a new Pull Request
+
+## Authors
+
+* [Kevin McPhillips](https://github.com/kmcphillips) at [Shopify](http://shopify.com/careers)

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "measured/version"
+
+task default: :test
+
+desc 'Run the test stuite'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib/**/*"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task tag: :build do
+  system "git commit -m'Released version #{ Measured::VERSION }' --allow-empty"
+  system "git tag -a v#{ Measured::VERSION } -m 'Tagging #{ Measured::VERSION }'"
+  system "git push --tags"
+end

data/lib/measured/arithmetic.rb

@@ -0,0 +1,37 @@
+module Measured::Arithmetic
+  def +(other)
+    arithmetic_operation(other, :+)
+  end
+
+  def -(other)
+    arithmetic_operation(other, :-)
+  end
+
+  def *(other)
+    arithmetic_operation(other, :*)
+  end
+
+  def /(other)
+    arithmetic_operation(other, :/)
+  end
+
+  def -@
+    self.class.new(-self.value, self.unit)
+  end
+
+  def coerce(other)
+    [self, other]
+  end
+
+  private
+
+  def arithmetic_operation(other, operator)
+    if other.is_a?(self.class)
+      self.class.new(self.value.send(operator, other.convert_to(self.unit).value), self.unit)
+    elsif other.is_a?(Numeric)
+      self.class.new(self.value.send(operator, other), self.unit)
+    else
+      raise TypeError, "Invalid operation #{ operator } between #{ self.class } to #{ other.class }"
+    end
+  end
+end

data/lib/measured/base.rb

@@ -0,0 +1,13 @@
+require "measured/version"
+require "active_support"
+require "bigdecimal"
+
+module Measured
+  class UnitError < StandardError ; end
+end
+
+require "measured/arithmetic"
+require "measured/unit"
+require "measured/conversion"
+require "measured/conversion_table"
+require "measured/measurable"

data/lib/measured/conversion.rb

@@ -0,0 +1,91 @@
+class Measured::Conversion
+  def initialize
+    @base_unit = nil
+    @units = []
+  end
+
+  attr_reader :base_unit, :units
+
+  def set_base(unit_name, aliases: [])
+    add_new_unit(unit_name, aliases: aliases, base: true)
+  end
+
+  def add(unit_name, aliases: [], value:)
+    add_new_unit(unit_name, aliases: aliases, value: value)
+  end
+
+  def unit_names_with_aliases
+    @units.map{|u| u.names}.flatten.sort
+  end
+
+  def unit_names
+    @units.map{|u| u.name}.sort
+  end
+
+  def unit_or_alias?(name)
+    unit_names_with_aliases.include?(name.to_s)
+  end
+
+  def unit?(name)
+    unit_names.include?(name.to_s)
+  end
+
+  def to_unit_name(name)
+    unit_for(name).name
+  end
+
+  def convert(value, from:, to:)
+    raise Measured::UnitError, "Source unit #{ from } does not exits." unless unit?(from)
+    raise Measured::UnitError, "Converted unit #{ to } does not exits." unless unit?(to)
+
+    from_unit = unit_for(from)
+    to_unit = unit_for(to)
+
+    raise Measured::UnitError, "Cannot find conversion entry from #{ from } to #{ to }" unless conversion = conversion_table[from][to]
+
+    value * conversion
+  end
+
+  def conversion_table
+    @conversion_table ||= Measured::ConversionTable.new(@units).to_h
+  end
+
+  private
+
+  def add_new_unit(unit_name, aliases:, value: nil, base: false)
+    if base && @base_unit
+      raise Measured::UnitError, "Can only have one base unit. Adding #{ unit_name } but already defined #{ @base_unit }."
+    elsif !base && !@base_unit
+      raise Measured::UnitError, "A base unit has not yet been set."
+    end
+
+    check_for_duplicate_unit_names([unit_name] + aliases)
+
+    unit = Measured::Unit.new(unit_name, aliases: aliases, value: value)
+    @units << unit
+    @base_unit = unit if base
+
+    clear_conversion_table
+
+    unit
+  end
+
+  def check_for_duplicate_unit_names(names)
+    names.each do |name|
+      raise Measured::UnitError, "Unit #{ name } has already been added." if unit_or_alias?(name)
+    end
+  end
+
+  def unit_for(name)
+    @units.each do |unit|
+      return unit if unit.names.include?(name.to_s)
+    end
+
+    raise Measured::UnitError, "Cannot find unit for #{ name }."
+  end
+
+  def clear_conversion_table
+    @conversion_table = nil
+  end
+
+end

data/lib/measured/conversion_table.rb

@@ -0,0 +1,67 @@
+class Measured::ConversionTable
+
+  def initialize(units)
+    @units = units
+  end
+
+  def to_h
+    table = {}
+
+    @units.map{|u| u.name}.each do |to_unit|
+      to_table = {to_unit => BigDecimal("1")}
+
+      table.each do |from_unit, from_table|
+        to_table[from_unit] = find_conversion(to: from_unit, from: to_unit)
+        from_table[to_unit] = find_conversion(to: to_unit, from: from_unit)
+      end
+
+      table[to_unit] = to_table
+    end
+
+    table
+  end
+
+  private
+
+  def find_conversion(to:, from:)
+    conversion = find_direct_conversion(to: to, from: from) || find_tree_traversal_conversion(to: to, from: from)
+
+    raise Measured::UnitError, "Cannot find conversion path from #{ from } to #{ to }." unless conversion
+
+    conversion
+  end
+
+  def find_direct_conversion(to:, from:)
+    @units.each do |unit|
+      return unit.conversion_amount if unit.name == from && unit.conversion_unit == to
+    end
+
+    @units.each do |unit|
+      return unit.inverse_conversion_amount if unit.name == to && unit.conversion_unit == from
+    end
+
+    nil
+  end
+
+  def find_tree_traversal_conversion(to:, from:)
+    traverse(from: from, to: to, unit_names: @units.map{|u| u.name }, amount: BigDecimal("1"))
+  end
+
+  def traverse(from:, to:, unit_names:, amount:)
+    unit_names = unit_names - [from]
+
+    unit_names.each do |name|
+      if conversion = find_direct_conversion(from: from, to: name)
+        if name == to
+          return amount * conversion
+        else
+          result = traverse(from: name, to: to, unit_names: unit_names, amount: amount * conversion)
+          return result if result
+        end
+      end
+    end
+
+    nil
+  end
+
+end