measured 1.6.0 → 2.0.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f7cc813b2c0df2dc458ec0d25e02aa5997c21114
-  data.tar.gz: 751080cdbdba93968fe94d6544fbc9af58537517
+  metadata.gz: 430f3e67cfe5f11eaa88db5f2b3d666ca5a7d557
+  data.tar.gz: 7ff421483024bec50b0703850d042eae46295b8c
 SHA512:
-  metadata.gz: 511935d3142ca49eda093620ff0db7883c217f53c7017027f6dd5c8fbf81717979ca4f15d9271bde87e25850fdf37efadf5a30359ba432f29d9fafffea6aeac4
-  data.tar.gz: f1c99f0c23bf29ddad5982db8c6546b54702b5baf54c6b5ab214ddd5549c690814134db1283e3a534096546d7e0f7030fc0dd41081ae816bd0a83cc373c4944e
+  metadata.gz: 6c15fc5aa920d22f6db7c7edd7fb52a66eb0af84b3c3326bbec64a37a387b7a764fe69d7c6d1f2ce41e2335045cfe8af5fb4c581b76ae72507c0eec7e7e21926
+  data.tar.gz: da4b602746ac0d5cb06353cc75deae90bfbcf56cec313196547dec347bbc7db50ff1f50a0d679ac95fa0fbcd715a22d0b678cef943c4ff7163aba36010ed6077

data/.travis.yml

@@ -4,7 +4,8 @@ cache: bundler
 rvm:
   - 2.1.8
   - 2.2.4
-  - 2.3.0
+  - 2.3.1
+  - 2.4.0
 gemfile:
   - Gemfile
   - gemfiles/activesupport-4.2.gemfile
@@ -12,3 +13,5 @@ matrix:
   exclude:
     - gemfile: Gemfile
       rvm: 2.1.8
+    - gemfile: gemfiles/activesupport-4.2.gemfile
+      rvm: 2.4.0

data/README.md

@@ -2,7 +2,7 @@
 
 Encapsulates measurements 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.
+Lightweight and easily extensible to include other units and conversions. Conversions done with `Rational` for precision.
 
 The adapter to integrate `measured` with Ruby on Rails is in a separate [`measured-rails`](https://github.com/Shopify/measured-rails) gem.
 
@@ -16,7 +16,9 @@ gem 'measured'
 
 Or stand alone:
 
-    $ gem install measured
+```
+$ gem install measured
+```
 
 ## Usage
 
@@ -32,12 +34,6 @@ Convert to return a new measurement:
 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
@@ -50,18 +46,6 @@ Seamlessly handles aliases:
 Measured::Weight.new(12, :oz) == Measured::Weight.new("12", :ounce)
 ```
 
-Comparison with zero works without the need to specify units, useful for validations:
-```ruby
-Measured::Weight.new(0.001, :kg) > 0
-> true
-
-Measured::Length.new(-1, :m) < 0
-> true
-
-Measured::Weight.new(0, :oz) == 0
-> true
-```
-
 Raises on unknown units:
 
 ```ruby
@@ -72,16 +56,21 @@ rescue Measured::UnitError
 end
 ```
 
-Perform mathematical operations against other units, all represented internally as `BigDecimal`:
+Perform addition / subtraction against other units, all represented internally as `Rational` or `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.new("2.1", :g) - Measured::Weight.new(1, :g)
+> #<Measured::Weight 1.1 g>
+```
+
+Multiplication and division by units is not supported, but the actual value can be scaled by a scalar:
+
+```ruby
+Measured::Weight.new(10, :g).scale(0.5)
 > #<Measured::Weight 5 g>
-Measured::Weight.new(2, :g) * Measured::Weight.new(3, :g)
+Measured::Weight.new(2, :g).scale(3)
 > #<Measured::Weight 6 g>
 ```
 
@@ -92,13 +81,6 @@ 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>
-```
-
 Converts units only as needed for equality comparison:
 
 ```ruby
@@ -174,45 +156,30 @@ Measured::Weight(1, :g)
 
 ### 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.
+Extending this library to support other units is simple. To add a new conversion, use `Measured.build` to define your base unit and 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
+Measured::Thing = Measured.build do
+  unit :base_unit,           # Add a unit to the system
+    aliases: [:bu]           # Allow it to be aliased to other names/symbols
 
-  conversion.add :different_unit
-    aliases: [:du],
-    value: [Rational(2,3), "another_unit"]  # Conversion rate can be Rational, otherwise it is coerced to BigDecimal
+  unit :another_unit,        # Add a second unit to the system
+    aliases: [:au],          # All units allow aliases, as long as they are unique
+    value: ["1.5 bu"]        # The conversion rate to another unit
 end
 ```
 
-By default all names and aliases and case insensitive. If you would like to create a new unit with names and aliases that are case sensitive, you should subclass `Measured::CaseSensitiveMeasurable` instead. Other than case sensitivity, both classes are identical to each other.
+By default all names and aliases are case insensitive. If you would like to create a new unit with names and aliases that are case sensitive, specify the case sensitive flag when building your unit:
 
 ```ruby
-class Measured::Thing < Measured::CaseSensitiveMeasurable
-  conversion.set_base :base_unit,
-    aliases: [:bu]
+Measured::Thing = Measured.build(case_sensitive: true) do
+  unit :base_unit, aliases: [:bu]
 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.
-
-The `case_sensitive` flag, which is false by default, gets taken into account any time you attempt to reference a unit by name or alias.
-
-You can also open up the existing classes and add a new conversion:
+Other than case sensitivity, both classes are identical to each other. The `case_sensitive` flag, which is false by default, gets taken into account any time you attempt to reference a unit by name or alias.
 
-```ruby
-class Measured::Length
-  conversion.add :dm,
-    aliases: [:decimeter, :decimetre, :decimeters, :decimetres],
-    value: "0.1 m"
-end
-```
+Values for conversion units can be defined as a string with two tokens `"number unit"` or as an array with two elements. All values will be parsed as / coerced to `Rational`. Conversion paths don't have to be direct as a conversion table will be built for all possible conversions.
 
 ### Namespaces
 
@@ -238,7 +205,7 @@ Existing alternatives which were considered:
 
 ### Gem: [quantified](https://github.com/Shopify/quantified)
 * **Pros**
-  * Light weight.
+  * Lightweight.
   * Included with ActiveShipping/ActiveUtils.
 * **Cons**
   * All math done with floats making it highly lossy.

data/lib/measured/arithmetic.rb

@@ -7,31 +7,30 @@ module Measured::Arithmetic
     arithmetic_operation(other, :-)
   end
 
-  def *(other)
-    arithmetic_operation(other, :*)
+  def -@
+    self.class.new(-self.value, self.unit)
   end
 
-  def /(other)
-    arithmetic_operation(other, :/)
+  def scale(other)
+    self.class.new(self.value * other, self.unit)
   end
 
-  def -@
-    self.class.new(-self.value, self.unit)
+  def coerce(other)
+    if other.is_a?(self.class)
+      [other, self]
+    else
+      raise TypeError, "Cannot coerce #{other.class} to #{self.class}"
+    end
   end
 
-  def coerce(other)
-    [self, other]
+  def to_i
+    raise TypeError, "#{self.class} cannot be converted to an integer"
   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
+    other, _ = coerce(other)
+    self.class.new(self.value.public_send(operator, other.convert_to(self.unit).value), self.unit)
   end
 end

data/lib/measured/base.rb

@@ -6,10 +6,23 @@ module Measured
   class UnitError < StandardError ; end
 
   class << self
+    def build(**kwargs, &block)
+      builder = UnitSystemBuilder.new(**kwargs)
+      builder.instance_eval(&block)
+
+      Class.new(Measurable) do
+        class << self
+          attr_reader :unit_system
+        end
+
+        @unit_system = builder.build
+      end
+    end
+
     def method_missing(method, *args)
       class_name = "Measured::#{ method }"
 
-      if Measured::Measurable.subclasses.map(&:to_s).include?(class_name)
+      if Measurable.subclasses.map(&:to_s).include?(class_name)
         klass = class_name.constantize
 
         Measured.define_singleton_method(method) do |value, unit|
@@ -26,7 +39,9 @@ end
 
 require "measured/arithmetic"
 require "measured/unit"
-require "measured/conversion"
+require "measured/unit_system"
+require "measured/case_insensitive_unit"
+require "measured/case_insensitive_unit_system"
+require "measured/unit_system_builder"
 require "measured/conversion_table"
 require "measured/measurable"
-require "measured/case_sensitive_measurable"

data/lib/measured/case_insensitive_unit.rb

@@ -0,0 +1,13 @@
+class Measured::CaseInsensitiveUnit < Measured::Unit
+  def initialize(name, aliases: [], value: nil)
+    super(name.to_s.downcase, aliases: aliases.map(&:to_s).map!(&:downcase), value: value)
+  end
+
+  def name_eql?(name_to_compare)
+    super(name_to_compare.to_s.downcase)
+  end
+
+  def names_include?(name_to_compare)
+    super(name_to_compare.to_s.downcase)
+  end
+end

data/lib/measured/case_insensitive_unit_system.rb

@@ -0,0 +1,11 @@
+class Measured::CaseInsensitiveUnitSystem < Measured::UnitSystem
+  def unit?(name)
+    super(name.to_s.downcase)
+  end
+
+  protected
+
+  def unit_for(name)
+    unit_name_to_unit[name.to_s.downcase]
+  end
+end

data/lib/measured/conversion_table.rb

@@ -1,18 +1,15 @@
-class Measured::ConversionTable
+module Measured::ConversionTable
+  extend self
 
-  def initialize(units)
-    @units = units
-  end
-
-  def to_h
+  def build(units)
     table = {}
 
-    @units.map{|u| u.name}.each do |to_unit|
+    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)
+        to_table[from_unit] = find_conversion(units, to: from_unit, from: to_unit)
+        from_table[to_unit] = find_conversion(units, to: to_unit, from: from_unit)
       end
 
       table[to_unit] = to_table
@@ -23,40 +20,40 @@ class Measured::ConversionTable
 
   private
 
-  def find_conversion(to:, from:)
-    conversion = find_direct_conversion(to: to, from: from) || find_tree_traversal_conversion(to: to, from: from)
+  def find_conversion(units, to:, from:)
+    conversion = find_direct_conversion(units, to: to, from: from) || find_tree_traversal_conversion(units, 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|
+  def find_direct_conversion(units, to:, from:)
+    units.each do |unit|
       return unit.conversion_amount if unit.name == from && unit.conversion_unit == to
     end
 
-    @units.each do |unit|
+    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: Rational(1))
+  def find_tree_traversal_conversion(units, to:, from:)
+    traverse(units, from: from, to: to, unit_names: units.map(&:name), amount: 1)
   end
 
-  def traverse(from:, to:, unit_names:, amount:)
+  def traverse(units, from:, to:, unit_names:, amount:)
     unit_names = unit_names - [from]
 
     unit_names.each do |name|
-      if conversion = find_direct_conversion(from: from, to: name)
-        new_amount = amount * conversion.to_r
+      if conversion = find_direct_conversion(units, from: from, to: name)
+        new_amount = amount * conversion
         if name == to
           return new_amount
         else
-          result = traverse(from: name, to: to, unit_names: unit_names, amount: new_amount)
+          result = traverse(units, from: name, to: to, unit_names: unit_names, amount: new_amount)
           return result if result
         end
       end

data/lib/measured/measurable.rb

@@ -1,102 +1,78 @@
-class Measured::Measurable
-  include Comparable
+class Measured::Measurable < Numeric
   include Measured::Arithmetic
 
   attr_reader :unit, :value
 
-  delegate :zero?, to: :value
-
   def initialize(value, unit)
-    raise Measured::UnitError, "Unit cannot be blank" if unit.blank?
-    raise Measured::UnitError, "Unit #{ unit } does not exist" unless self.class.conversion.unit_or_alias?(unit)
+    raise Measured::UnitError, "Unit value cannot be blank" if value.blank?
 
+    @unit = self.class.unit_system.to_unit_name!(unit)
     @value = case value
-    when NilClass
-      raise Measured::UnitError, "Unit value cannot be nil"
     when Float
-      BigDecimal(value, Float::DIG+1)
-    when BigDecimal
+      BigDecimal(value, Float::DIG + 1)
+    when BigDecimal, Rational
       value
+    when Integer
+      Rational(value)
     else
-      if value.blank?
-        raise Measured::UnitError, "Unit value cannot be blank"
-      else
-        BigDecimal(value)
-      end
+      BigDecimal(value)
     end
-
-    @unit = self.class.conversion.to_unit_name(unit)
   end
 
   def convert_to(new_unit)
-    new_unit_name = self.class.conversion.to_unit_name(new_unit)
-    return self if new_unit_name == self.class.conversion.to_unit_name(unit)
+    new_unit_name = self.class.unit_system.to_unit_name(new_unit)
+    return self if new_unit_name == @unit
 
-    value = self.class.conversion.convert(@value, from: @unit, to: new_unit_name)
+    value = self.class.unit_system.convert(@value, from: @unit, to: new_unit_name)
 
     self.class.new(value, new_unit)
   end
 
-  def convert_to!(new_unit)
-    converted = convert_to(new_unit)
-
-    @value = converted.value
-    @unit = converted.unit
-
-    self
-  end
-
   def to_s
-    [value.to_f.to_s.gsub(/\.0\Z/, ""), unit].join(" ")
+    @to_s ||= "#{value_string} #{unit}"
   end
 
   def inspect
-    "#<#{ self.class }: #{ value } #{ unit }>"
+    @inspect ||= "#<#{self.class}: #{value_string} #{unit}>"
   end
 
   def <=>(other)
     if other.is_a?(self.class)
-      other_converted = other.convert_to(unit)
-      value <=> other_converted.value
-    elsif other == 0
-      other_converted = self.class.new(0, unit)
-      value <=> other_converted.value
-    end
-  end
-
-  def ==(other)
-    if other.is_a?(self.class)
-      other_converted = other.convert_to(unit)
-      value == other_converted.value
-    elsif other == 0
-      other_converted = self.class.new(0, unit)
-      value == other_converted.value
+      value <=> other.convert_to(unit).value
+    else
+      nil
     end
   end
 
-  alias_method :eql?, :==
-
   class << self
+    extend Forwardable
 
-    def conversion
-      @conversion ||= Measured::Conversion.new
-    end
-
-    def units
-      conversion.unit_names
-    end
-
-    def valid_unit?(unit)
-      conversion.unit_or_alias?(unit)
+    def unit_system
+      raise "`Measurable` does not have a `unit_system` object. You cannot directly subclass `Measurable`. Instead, build a new unit system by calling `Measured.build`."
     end
 
-    def units_with_aliases
-      conversion.unit_names_with_aliases
-    end
+    delegate unit_names: :unit_system
+    delegate unit_names_with_aliases: :unit_system
+    delegate unit_or_alias?: :unit_system
 
     def name
       to_s.split("::").last.underscore.humanize.downcase
     end
+  end
+
+  private
 
+  def value_string
+    @value_string ||= begin
+      str = case value
+      when Rational
+        value.denominator == 1 ? value.numerator.to_s : value.to_f.to_s
+      when BigDecimal
+        value.to_s("F")
+      else
+        value.to_f.to_s
+      end
+      str.gsub(/\.0*\Z/, "")
+    end
   end
 end

data/lib/measured/unit.rb

@@ -1,31 +1,14 @@
 class Measured::Unit
   include Comparable
 
+  attr_reader :name, :names, :conversion_amount, :conversion_unit
+
   def initialize(name, aliases: [], value: nil)
     @name = name.to_s
-    @names = ([@name] + aliases.map{|n| n.to_s }).sort
-
+    @names = ([@name] + aliases.map(&:to_s)).sort
     @conversion_amount, @conversion_unit = parse_value(value) if value
   end
 
-  attr_reader :name, :names, :conversion_amount, :conversion_unit
-
-  def name_eql?(name_to_compare, case_sensitive: false)
-    return false unless name_to_compare.present?
-    name_to_compare = name_to_compare.to_s
-    case_sensitive ? @name.eql?(name_to_compare) : case_insensitive(@name).include?(name_to_compare.downcase)
-  end
-
-  def names_include?(name_to_compare, case_sensitive: false)
-    return false unless name_to_compare.present?
-    name_to_compare = name_to_compare.to_s
-    case_sensitive ? @names.include?(name_to_compare) : case_insensitive(@names).include?(name_to_compare.downcase)
-  end
-
-  def add_alias(aliases)
-    @names = (@names << aliases).flatten.sort unless aliases.nil? || aliases.empty?
-  end
-
   def to_s
     if conversion_string
       "#{ @name } (#{ conversion_string })"
@@ -56,20 +39,15 @@ class Measured::Unit
 
   private
 
-  def case_insensitive(comparison)
-    [comparison].flatten.map(&:downcase)
-  end
-
   def conversion_string
     "#{ conversion_amount } #{ conversion_unit }" if @conversion_amount || @conversion_unit
   end
 
   def parse_value(tokens)
     tokens = tokens.split(" ") if tokens.is_a?(String)
-    raise Measured::UnitError, "Cannot parse 'number unit' or [number, unit] formatted tokens from #{ tokens }." unless tokens.size == 2
 
-    tokens[0] = BigDecimal(tokens[0]) unless tokens[0].is_a?(BigDecimal) || tokens[0].is_a?(Rational)
+    raise Measured::UnitError, "Cannot parse 'number unit' or [number, unit] formatted tokens from #{tokens}." unless tokens.size == 2
 
-    tokens
+    [tokens[0].to_r, tokens[1]]
   end
 end

data/lib/measured/unit_system.rb

@@ -0,0 +1,67 @@
+class Measured::UnitSystem
+  attr_reader :units
+
+  def initialize(units)
+    @units = units.dup
+  end
+
+  def unit_names_with_aliases
+    @unit_names_with_aliases ||= @units.flat_map(&:names).sort
+  end
+
+  def unit_names
+    @unit_names ||= @units.map(&:name).sort
+  end
+
+  def unit_or_alias?(name)
+    !!unit_for(name)
+  end
+
+  def unit?(name)
+    unit = unit_for(name)
+    unit ? unit.name == name.to_s : false
+  end
+
+  def to_unit_name(name)
+    to_unit_name!(name)
+  rescue Measured::UnitError
+    nil
+  end
+
+  def to_unit_name!(name)
+    unit_for!(name).name
+  end
+
+  def convert(value, from:, to:)
+    from_unit = unit_for!(from)
+    to_unit = unit_for!(to)
+    conversion = conversion_table[from][to]
+
+    raise Measured::UnitError, "Cannot find conversion entry from #{from} to #{to}" unless conversion
+
+    value.to_r * conversion
+  end
+
+  protected
+
+  def conversion_table
+    @conversion_table ||= Measured::ConversionTable.build(@units)
+  end
+
+  def unit_name_to_unit
+    @unit_name_to_unit ||= @units.inject({}) do |hash, unit|
+      unit.names.each { |name| hash[name.to_s] = unit }
+      hash
+    end
+  end
+
+  def unit_for(name)
+    unit_name_to_unit[name.to_s]
+  end
+
+  def unit_for!(name)
+    unit = unit_for(name)
+    raise Measured::UnitError, "Unit '#{name}' does not exist" unless unit
+    unit
+  end
+end

data/lib/measured/unit_system_builder.rb

@@ -0,0 +1,38 @@
+class Measured::UnitSystemBuilder
+  def initialize(case_sensitive: false)
+    @units = []
+    @case_sensitive = case_sensitive
+  end
+
+  def unit(unit_name, aliases: [], value: nil)
+    @units << build_unit(unit_name, aliases: aliases, value: value)
+    nil
+  end
+
+  def build
+    unit_system_class.new(@units)
+  end
+
+  private
+
+  def build_unit(name, aliases: [], value: nil)
+    unit = unit_class.new(name, aliases: aliases, value: value)
+    check_for_duplicate_unit_names!(unit)
+    unit
+  end
+
+  def unit_class
+    @case_sensitive ? Measured::Unit : Measured::CaseInsensitiveUnit
+  end
+
+  def unit_system_class
+    @case_sensitive ? Measured::UnitSystem : Measured::CaseInsensitiveUnitSystem
+  end
+
+  def check_for_duplicate_unit_names!(unit)
+    names = @units.flat_map(&:names)
+    if names.any? { |name| unit.names.include?(name) }
+      raise Measured::UnitError, "Unit #{unit.name} has already been added."
+    end
+  end
+end