quantity 0.0.0 → 0.1.1

data/README

@@ -1,5 +1,209 @@
 Quantity.rb: Units and Quantities for Ruby
 ==========================================
+Quantity.rb provides first-class support for units and quantities in Ruby.
+The right abstractions for true quantity representation and complex conversions.
+Hopefully this readme will be all you need, but [there are yardocs](http://quantity.rubyforge.org)
+
+## Overview
+    require 'quantity/all'
+    1.meter                                                 #=> 1 meter
+    1.meter.to_feet                                         #=> 3.28083... foot
+    c = 299792458.meters / 1.second                         #=> 299792458 meter/second
+    
+    newton = 1.meter * 1.kilogram / 1.second**2             #=> 1 meter*kilogram/second^2
+    newton.to_feet                                          #=> 3.28083989501312 foot*kilogram/second^2
+    newton.convert(:feet)                                   #=> 3.28083989501312 foot*kilogram/second^2
+    jerk_newton / 1.second                                  #=> 1 meter*kilogram/second^3
+    jerk_newton * 1.second == newton                        #=> true
+
+    mmcubed = 1.mm.cubed                                    #=> 1 millimeter^3
+    mmcubed * 1000 == 1.milliliter                          #=> true
+
+    [1.meter, 1.foot, 1.inch].sort                          #=> [1 inch, 1 foot, 1 meter]
+
+    m_to_f = Quantity::Unit.for(:meter).convert_proc(:feet)
+    m_to_f.call(1)                                          #=> 3.28083... (or a Rational)
+
+Quantity.rb provides full-featured support for quantities, units, and
+dimensions in Ruby.  Some terminology:
+
+  * Quantity: An amount of a unit, such as 12 meters.
+  * Unit: An amount of a given dimension to be measured, such as 'meter'
+  * Dimension: Some base quantity to be measured, such as 'length'
+
+Quantities perform complete mathematical operations over their units,
+including `+`, `-`, `\*`, `/`, `\*`\*`, `%`, `abs`, `divmod`, `<=>`, and negation.  Units
+and the dimensions they measure are fully represented and support
+`\*` and `/`.
+
+Quantity extends Numeric to allow easy creation of quantities, but there
+are direct interfaces to the library as well.
+
+    1.meter                == Quantity.new(1,Quantity::Unit.for(:meter)) 
+    1.meter.unit           == Quantity::Unit.for(:meter)
+    1.meter.unit.dimension == Quantity::Dimension.for(:length)
+
+See the units section for supported units, and how to add your own.
+
+Quantities are first-class citizens which do a fair job of imitating
+Numeric.  Quantities support coerce, and can thus be used in almost
+any situation a numeric can:
+
+    2.5 + 5.meters    # => 7.5 meters
+    5 == 5.meters     # => true
+
+## Status and TODO
+Quantity.rb is not ready for production use for some areas, but should be
+fine for simple conversion use cases.  If it breaks, please email the
+author for a full refund.
+
+Specifically broken in this version are some operations on named
+higher dimensions:
+
+    1.liter / 1.second                      #=> should be 1 liter/second, but explodes
+    1.liter.convert(:'mm^3') / 1.second     #=> 1000000.0 millimeter^3/second
+    
+If you just work with units derived from the base dimensions, there aren't
+known bugs.  Please add a spec if you find one.
+
+### TODO
+ * Lots more units are planned.
+ * BigDecimal support a la Rational.
+ * Supporting lambdas for unit values
+ * BigDecimal/Rational compatible values for existing units
+ * Some DSL sugar for adding derived dimension units
+
+## Units
+Quantity.rb comes with a sizable collection of units, but still needs significant expansion.
+
+A number of base unit sets exist:
+    require 'quantity/all'                    #=> load everything.  uses US versions of foot, lb, etc
+    require 'quantity/systems/si'             #=> load SI
+    require 'quantity/systems/us'             #=> load US versions of foot, lb, etc
+    require 'quantity/systems/imperial'       #=> load British versions of foot, lb, etc
+    require 'quantity/systems/information'    #=> bits, bytes, and all that
+    require 'quantity/systems/enumerable'     #=> countable things--dozen, score, etc
+
+Note that US and Imperial conflict with each other.  Loading both is unsupported.
+
+Adding your own units is simple:
+
+    Quantity::Unit.add_unit :furlong, :length, 201168, :furlongs
+    1.furlong  #=> 1 furlong
+
+201168 represents 1 furlong in millimeters.  Each base dimension, such as length, time,
+current, temperature, etc, is represented by a reference unit, which is generally the
+milli-version of the SI unit referencing that domain.  [NIST](http://physics.nist.gov/cuu/Units/units.html)
+has an explanation of how the SI system works, and how all units are actually derived from
+very few.
+
+All units for derived dimensions used the derived reference unit.  For example, length
+is referenced to millimeters, so each unit of length is defined in terms of them:
+
+    Quantity::Unit.add_unit :meter, :length, 1000
+    Quantity::Unit.add_unit :millimeter, :length, 1, :mm
+
+Thus, the base unit for volume is 1 mm^3:
+     volume = Quantity::Dimension.add_dimension length**3, :volume
+     ml = Quantity::Dimension.add_unit :milliliter, :volume, 1000, :ml, :milliliters
+     1.mm**3 * 1000 == 1.milliliter   #=> true
+
+See the bugs section for some current issues using units defined on derived dimensions.
+
+The full list of included base dimensions and their reference units:
+    * :length       => :millimeter
+    * :time         => :millisecond
+    * :current      => :milliampere
+    * :luminosity   => :millicandela
+    * :substance    => :millimole
+    * :temperature  => :millikelvin
+    * :mass         => :milligram
+    * :information  => :bit     # use :megabytes and :mebibytes
+    * :quantity     => :item    # for countable quantities.  units include 1.dozen, for example
+    * :currency     => :dollar  # These are not really implemented yet
+
+To determine the base unit for a derived dimension, you can use Quantity.rb itself:
+
+    force = Quantity::Dimension.for(:force)
+    newton = 1.meter * 1.kilogram / 1.second**2
+    newton.measures == force #=> true
+    newton_value = newton.to_mm.to_mg.to_ms  #=> 1000.0 millimeter*milligram/millisecond^2
+
+Thus, a newton would be 1000 when added specifically:
+
+    Quantity::Unit.add_unit :newton, :force, 1000, :newtons
+    1.newton  == newton   #=> true
+
+## Dimensions
+A dimension is a measurable thing, often called a 'base quantity' in scientific literature,
+but Quantity.rb specifically avoids that nomenclature, reserving 'quantity' for the class
+representing a unit and a value.  As always, [wikipedia has the answers.](http://en.wikipedia.org/wiki/Physical_quantity)
+
+Dimensions are not very useful by themselves, but you can play with them
+if you want.
+
+    length = Quantity::Dimension.for(:length)
+    time = Quantity::Dimension.for(:time)
+    speed = length / time
+
+A number of dimensions are enabled by default (see dimension/base.rb).
+
+A DSL of sorts is provided for declaring dimensions:
+
+    length  = Quantity::Dimension.add_dimenson :length
+    area    = Quantity::Dimension.add_dimension length**2, :area
+
+    length = Quantity::Dimension.for(:length)
+    area   = Quantity::Dimension.for(:area)
+    area == length * length                   #=> true
+
+Quantity::Dimension is extended with empty subclasses for some base dimensions,
+so you can do pattern patching on the class:
+
+    case 1.meter.measures
+      when Quantity::Dimension::Length
+        puts "I am printed"
+    end
+
+## I just want to convert things, this is all just too much
+Quantity.rb provides you the ability to intuitively create the conversions
+your application needs, and then bypass the rest of the library.
+
+    m_to_f = 1.meter.measures.convert_proc(:feet)
+    m_to_f.call(5)    # => 5 meters in feet
+
+This Proc object has been broken down into a single division; it no longer references
+any units, dimensions, or quantities.  It's hard to be faster in pure Ruby.
+
+### On precision and speed
+
+By default, whatever Numeric you are using will be the stored value for the
+quantity.
+
+    5.meters
+    Rational(5).meters
+    5.0.meters
+
+This value will be held.  However, divisions are required for conversions,
+and the default is to force values into floats.
+
+If accuracy is required, just require 'rational'.  If Rational is defined,
+you'll get rationals instead of divided floats everywhere.  In tests, this
+is an order of magnitude slower.
+
+## 'Why' and previous work
+This is by no means the first unit conversion/quantity library for Ruby, but
+none of the existing ones scratched my itch just right.  My goal is that this will
+be the last one I (and you) need.  The abstractions go all the way down, and
+any conceivable conversion or munging functionality should be buildable on top
+of this.
+
+Inspiration comes from:
+
+  * [Quanty](http://narray.rubyforge.org/quanty/quanty-en.html)
+    Why oh why did they involve yacc?
+  * [Ruby Units](http://ruby-units.rubyforge.org/ruby-units/)
+  * [Alchemist](http://github.com/toastyapps/alchemist)
 
 Authors
 -------

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.1

data/lib/quantity.rb

@@ -1,17 +1,376 @@
 require 'quantity/version'
+require 'quantity/dimension'
+require 'quantity/dimension/base'
+require 'quantity/unit'
+require 'quantity/systems/si'
+require 'quantity/systems/us'
 
+#
+# A quantity of something.  Quantities are immutable; conversions and other operations return
+# a new quantity.
+#
+# ## General Use
+#     require 'quantity/all'
+#
+#     12.meters                                     #=> Quantity
+#     12.meters.measures                            #=> :length
+#     12.meters.units                               #=> :meters
+#     12.meters.unit                                #=> Quantity::Unit::Length
+#     12.meters.in_centimeters == 1200.centimeters  #=> true
+#     12.meters == 12                               #=> true
+#     12.meters == 12.centimeters                   #=> false
+#     12.meters + 5.centimeters == 12.05.meters     #=> true
+#     12.meters.in_picograms                        #=> raises ArgumentError
+#
+# ## Derived Units
+#     require 'quantity/si'
+#     speed_of_light = 299_752_458.meters / 1.second    #=>Quantity::Unit::Derived
+#     speed_of_light.measures                           #=> "meters per second"
+#     speed_of_light.units                              #=> "meters per second"
+#   
+#     ludicrous_speed = speed_of_light * 1000
+#     ludicrous_speed.measures                #=> "meters per second"  #TODO: velocity, accleration ?
+#     ludicrous_speed.to_s                    #=> "299752458000 meters per second"
+#
+# If the default to_s isn't what you want, you can buld it with 12.meters.value and 12.meters.units
+#
+# @see Quantity::Unit
 class Quantity
+  include Comparable
   autoload :Unit, 'quantity/unit'
 
-  undef_method *(instance_methods - %w(__id__ __send__ __class__ __eval__ instance_eval inspect))
+  #undef_method *(instance_methods - %w(__id__ __send__ __class__ __eval__ instance_eval inspect should))
 
+  # User-visible value, i.e. 2.meters.value == 2
   attr_reader :value
+
+  # Unit of measurement
   attr_reader :unit
 
-  ##
-  # @param  [Numeric] value
-  # @param  [Unit]    unit
-  def initialize(value, unit)
-    @value, @unit = value, unit
+  # This quantity in terms of the reference value, declared by fiat for everything measurable
+  attr_reader :reference_value
+
+  #
+  # Initialize a new, immutable quantity
+  # @overload initialize(value, unit, options)
+  #   @param [Numeric] value
+  #   @param [Unit] unit
+  #   @return [Quantity]
+  #
+  # @overload initialize(options)
+  #   Only one of value or reference value can be used, if both are given, reference
+  #   value will be used.
+  #   @param [Hash{Symbol => Object}] options
+  #   @option options [Numeric] :value Visible value
+  #   @option options [Numeric] :reference_value Reference value
+  #   @option options [Symbol Unit] :unit Units
+  #   @return [Quantity]
+  #
+  def initialize(value, unit = nil )
+    case value
+      when Hash
+        @unit = Unit.for(value[:unit])
+        @reference_value = value[:reference_value] || (value[:value] * @unit.value)
+        @value = @unit.value_for(@reference_value) #dimension.reference.convert_proc(@unit).call(@reference_value)
+        #@value = @unit.convert_proc(@unit).call(@reference_value)
+      when Numeric
+        @unit = Unit.for(unit)
+        if @unit.nil?
+          @unit = Unit.from_string_form(unit)
+        end
+        @value = value
+        @reference_value = value * @unit.value 
+    end
+  end
+
+  # String version of this quantity
+  # @param [String] format Format for sprintf, will be given
+  # @return [String]
+  def to_s
+    @unit.s_for(value)
+  end
+
+  # What this measures
+  # @return [Symbol String] What this measures.  Derived types will be a string
+  def measures
+    @unit.dimension
+  end
+
+  # Units of measurement
+  # @return [Symbol String] Units of measurement.  Derived types will be a string
+  def units
+    @unit.name
+  end
+
+  # Abs implementation
+  # @return [Quantity]
+  def abs
+    if @reference_value < 0
+      -self
+    else
+      self
+    end
+  end
+
+  # Ruby coercion.  Allows things like 2 + 5.meters
+  # @return [Quantity, Quantity]
+  def coerce(other)
+    if other.class == @value.class
+      [Quantity.new(other, @unit),self]
+    elsif defined?(Rational) && (@value.is_a?(Fixnum)) && (other.is_a?(Fixnum))
+      [Quantity.new(Rational(other), @unit), self] 
+    elsif defined?(Rational) && (other.is_a?(Rational))
+      [Quantity.new(other, @unit), self] 
+    else
+      [Quantity.new(other.to_f, @unit),Quantity.new(@value.to_f, @unit)]
+    end
+  end
+
+
+  # Addition.  Add two quantities of the same type.  Do not need to have the same units.
+  # @param [Quantity Numeric] other
+  # @return [Quantity]
+  def +(other)
+    if (other.is_a?(Numeric))
+      Quantity.new(@value + other, @unit)
+    elsif(other.is_a?(Quantity) && @unit.dimension == other.unit.dimension)
+      Quantity.new({:unit => @unit,:reference_value => @reference_value + other.reference_value})
+    else
+      raise ArgumentError,"Cannot add #{self} to #{other}"
+    end
+  end
+
+  # Subtraction.  Subtract a quantity from another of the same type.  They do not need 
+  # to share units.
+  # @param [Quantity Numeric] other
+  # @return [Quantity]
+  def -(other)
+    if (other.is_a?(Numeric))
+      Quantity.new(@value - other, @unit)
+    elsif(other.is_a?(Quantity) && @unit.dimension == other.unit.dimension)
+      Quantity.new({:unit => @unit,:reference_value => @reference_value - other.reference_value})
+    else
+      raise ArgumentError, "Cannot subtract #{other} from #{self}"
+    end
+  end
+
+  # Comparison.  Compare this to another quantity or numeric.  Compared to a numeric,
+  # this will assume a numeric of the same unit as self.
+  # @param [Quantity Numeric] other
+  # @return [-1 0 1]
+  def <=>(other)
+    if (other.is_a?(Numeric))
+      @value <=> other
+    elsif(other.is_a?(Quantity) && measures == other.measures)
+      @reference_value <=> other.reference_value
+    else
+      nil
+    end
+  end
+
+  # Type-aware equality
+  # @param [Any]
+  # @return [Boolean]
+  def eql?(other)
+    other.is_a?(Quantity) && other.units == units && self == other
+  end
+
+  # Multiplication.
+  # @param [Numeric, Quantity]
+  # @return [Quantity]
+  def *(other)
+    if (other.is_a?(Numeric))
+      Quantity.new(@value * other, @unit)
+    elsif(other.is_a?(Quantity))
+      Quantity.new({:unit => other.unit * @unit, :reference_value => @reference_value * other.reference_value})
+    else
+      raise ArgumentError, "Cannot multiply #{other} with #{self}"
+    end
+  end
+
+  # Division
+  # @param [Numeric, Quantity]
+  # @return [Quantity]
+  def /(other)
+    if (other.is_a?(Numeric))
+      Quantity.new(@value / other, @unit)
+    elsif(other.is_a?(Quantity))
+      ref = nil
+      if defined?(Rational) && (@value.is_a?(Fixnum)) && (other.is_a?(Fixnum))
+        ref = Rational(@reference_value,other.reference_value)
+      elsif defined?(Rational) && (@value.is_a?(Rational)) && (other.is_a?(Rational))
+        ref = @reference_value / other.reference_value
+      else
+        ref = @reference_value / other.reference_value.to_f
+      end
+      Quantity.new({:unit => @unit / other.unit, :reference_value => ref})
+    else
+      raise ArgumentError, "Cannot multiply #{other} with #{self}"
+    end
+  end
+
+  # Exponentiation.  Quantities cannot be raised to negative or fractional powers, only
+  # positive Fixnum.
+  # @param [Numeric]
+  # @return [Quantity]
+  def **(power)
+    unless power.is_a?(Fixnum) && power > 0
+      raise ArgumentError, "Quantities can only be raised to fixed powers (given #{power})"
+    end
+    if power == 1
+      self
+    else
+      self * self**(power - 1)
+    end
+  end
+
+  # Square the units of this quantity
+  # @example
+  #     4.meters.squared == Quantity.new(4.'m^2')
+  # @return [Quantity]
+  def squared
+    Quantity.new(@value, @unit * @unit)
+  end
+
+  # Cube the units of this quantity
+  # @example
+  #     4.meters.cubed == Quantity.new(4.'m^3')
+  # @return [Quantity]
+  def cubed
+    Quantity.new(@value, @unit * @unit * @unit)
+  end
+
+  # Mod
+  # @return [Quantity]
+  def %(other)
+    if (other.is_a?(Numeric))
+      Quantity.new(@value % other, @unit)
+    elsif(other.is_a?(Quantity) && self.measures == other.measures)
+      Quantity.new({:unit => @unit, :reference_value => @reference_value % other.reference_value})
+    else
+      raise ArgumentError, "Cannot modulo #{other} with #{self}"
+    end
+  end
+
+  # Both names for modulo
+  alias_method :modulo, :%
+
+  # Negation
+  # @return [Quantity]
+  def -@
+    Quantity.new({:unit => @unit, :reference_value => @reference_value * -1})
+  end
+
+  # Unary + (self)
+  # @return [Quantity]
+  def +@
+    self
+  end
+
+  # Integer representation
+  # @return [Fixnum]
+  def to_i
+    @value.to_i
+  end
+
+  # Float representation
+  # @return [Float]
+  def to_f
+    @value.to_f
+  end
+
+  # Round this value to the nearest integer
+  # @return [Quantity]
+  def round
+    Quantity.new(@value.round, @unit)
+  end
+
+  # Truncate this value to an integer
+  # @return [Quantity]
+  def truncate
+    Quantity.new(@value.truncate, @unit)
+  end
+
+  # Largest integer quantity less than or equal to this
+  # @return [Quantity]
+  def floor
+    Quantity.new(@value.floor, @unit)
+  end
+
+  # Smallest integer quantity greater than or equal to this
+  # @return [Quantity]
+  def ceil
+    Quantity.new(@value.ceil, @unit)
+  end
+
+  # Divmod
+  # @return [Quantity,Quantity]
+  def divmod(other)
+    if (other.is_a?(Numeric))
+      (q, r) = @value.divmod(other)
+      [Quantity.new(q,@unit),Quantity.new(r,@unit)]
+    elsif (other.is_a?(Quantity) && measures == other.measures)
+      (q, r) = @value.divmod(other.value)
+      [Quantity.new(q,@unit),Quantity.new(r,@unit)]
+    else
+      raise ArgumentError, "Cannot divmod #{other} with #{self}"
+    end
+  end
+
+  # Returns true if self has a zero value
+  # @return [Boolean]
+  def zero?
+    @value.zero?
+  end
+
+  # Convert to another unit of measurement.
+  # For most uses, Quantity#to_<unit> is what you want, but this can be handy
+  # for variable units.
+  # @param [Unit Symbol]
+  def convert(to)
+    Quantity.new({:unit => @unit.convert(to), :reference_value => @reference_value})
+  end
+
+  #
+  # :method to_unit
+  # Convert this quantity to another quantity.
+  # unit can be any unit that measures the same thing as this quantity, i.e. 
+  # 12.meters can call .to_feet, .to_centimeters, etc.  An error is raised with
+  # other types, i.e. 12.meters.to_grams
+  # @raises ArgumentError
+  # @return [Quantity]
+
+  # Developer-friendly string representation
+  # @return [String]
+  def inspect
+    to_s
+  end
+
+    # this creates the conversion methods of .to_* and .in_*
+    # @private
+    def method_missing(method, *args, &block)
+      if method.to_s =~ /(to_|in_)(.*)/
+        if (Unit.is_unit?($2.to_sym))
+          convert($2.to_sym)
+        else
+          raise ArgumentError, "Unknown target unit type: #{$2}"
+        end
+      else 
+        raise NoMethodError, "Undefined method `#{method}` for #{self}:#{self.class}"
+      end
+    end
+
+end
+
+# @private
+# Plug our constructors into Numeric
+class Numeric
+  alias_method :quantity_method_missing, :method_missing
+  def method_missing(method, *args, &block)
+    if Quantity::Unit.is_unit?(method)
+      Quantity.new(self,Quantity::Unit.for(method))
+    else
+      quantity_method_missing(method,*args, &block)
+    end
   end
 end