quantity 0.0.0 → 0.1.1

data/lib/quantity/systems/us.rb

@@ -0,0 +1,19 @@
+# Units for the most commonly used US units.  If you need to
+# worry about the minitae, such as the difference between a
+# fluid pint and a dry pint, pleases see the documentation
+# for the quantity/systems/us modules.
+class Quantity::Unit
+  add_unit :foot, :length, 304.8, :ft, :feet
+  add_unit :inch, :width, 25.4, :in, :inches
+  add_unit :yard, :length, 914.4, :yd, :yards
+  add_unit :mile, :length, 1_609_344, :miles
+
+  add_unit :pound, :mass, 453592.37, :pounds, :lb, :lbs
+  add_unit :ounce, :mass, 28349.5231, :ounces, :oz
+  add_unit :ton, :mass, 907184740, :tons
+
+  add_unit :fluid_ounce, :volume, 29.57, :floz, :ozfl
+  add_unit :pint, :volume, 473.18, :pint, :pints
+  add_unit :quart, :volume, 946.35, :qt, :quarts
+  add_unit :gallon, :volume, 3785.41, :gallons, :gal
+end

data/lib/quantity/unit.rb

@@ -1,28 +1,320 @@
 class Quantity
+  # A unit of measurement.
+  # 
+  # Units are a well-defined increment of a measurement domain.  Units
+  # measure a particular Dimension, which may be base or compound.
+  # Examples of units are meters and degrees celius.
+  #
+  # Units are not quantities, and their associated value only defines
+  # their relationship to their measurement domain.  For a representation
+  # of a given number of units, see Quantity.
+  #
+  # There is only one type of unit.  Units are simply denote a range on
+  # their measurement dimension, which may be compound and complicated.
+  #
+  # Units are implemented in terms of a reference unit for each dimension.
+  # The SI milli- unit for each of the base physical dimensions is the
+  # reference unit for each of the so-called base quantities.
+  #
+  # Units are known by a wide variety of abbreviations and names.  Each
+  # unit is only instantiated once, regardless of what name it is called
+  # by.  The cannonical name is used internally.  A client Quantity
+  # object is responsible for remembering which name a unit was originally
+  # called as.
+  #
   class Unit
-    autoload :Length,      'quantity/unit/length'
-    autoload :Mass,        'quantity/unit/mass'
-    autoload :Time,        'quantity/unit/time'
-    autoload :Current,     'quantity/unit/current'
-    autoload :Temperature, 'quantity/unit/temperature'
-    autoload :Luminosity,  'quantity/unit/luminosity'
-    autoload :Substance,   'quantity/unit/substance'
+    include Comparable
+   
+    # All known units
+    @@units = {}
 
+    # The unit for a given symbol or string description of a compound unit
+    # @param [Symbol String Unit] to
+    # @return [Unit]
+    def self.for(to)
+      to.is_a?(Unit) ? to : @@units[to]
+    end
+
+    # Whether or not the given symbol or string refers to an existing unit
+    # @param [Symbol String Unit] to
+    # @return [Boolean]
+    def self.is_unit?(to)
+      to.is_a?(Unit) || @@units.has_key?(to)
+    end
+
+    # Register a unit with the given symbols
+    # @param [Unit] unit
+    # @param [*names]
+    def self.add_alias(unit,*names)
+      unit = Unit.for(unit) unless unit.is_a? Unit
+      names.each do |name|
+        @@units[name] = unit
+      end
+    end
+
+    # Add a unit to the system
+    # @param [Dimension] dimension
+    # @param [Symbol] name 
+    # @param [Numeric] value
+    # @param [[String Symbol]] *aliases
+    def self.add_unit(name,dimension,value,*names)
+      new_unit = Unit.new({ :name => name,:dimension => Quantity::Dimension.for(dimension),:value => value})
+      names.each do | name |
+        add_alias new_unit, name
+      end
+    end
+    class << self ; alias_method :add, :add_unit; end
+
+    # Add a number of units to the system
+    # @example
+    #     length = Quantity::Dimension.for(:length)
+    #     Quantity::Unit.add_units do
+    #       add :meter length 1000
+    #       add :mm :length 1
+    #     end
+    def self.add_units(&block)
+      self.class_eval(&block)
+    end
+
+    ### Instance-level methods/vars
+    attr_reader :name, :value, :dimension, :aliases
+    
+    # All the known aliases for this Unit, i.e. name + aliases
+    # @return [[Symbol String]]
+    def names
+      [@name] + @aliases
+    end
+
+    # Can this unit be converted into the target unit?
+    # @param [Symbol String Unit]
+    # @return [Boolean]
+    def can_convert_to?(to)
+      Unit.for(to).dimension == @dimension
+    end
+
+    # Return the unit this unit will convert to.
+    # It's sometimes necessary to let the unit decide, in case a conversion such as
+    # meters^2 -> feet is requested, for which feet^2 should be returned.
+    # @param [Symbol String Unit]
+    # @return [Unit]
+    def convert(to)
+      Unit.for(to)
+    end
+
+    # Return a proc that will perform conversion from this unit to the given one
+    # @param [Symbol String Unit]
+    # @return [Unit]
+    def convert_proc(to)
+      to = convert(to)
+      #to = Unit.for(to)
+      raise ArgumentError, "Unable to find unit #{to}" unless to
+      unless (to.dimension == self.dimension)
+        raise ArgumentError, "Cannot convert #{self.dimension} to #{to.dimension}"
+      end
+      if defined?(Rational) && (@value.is_a?(Fixnum)) && (to.value.is_a?(Fixnum))
+        lambda do | from |
+          from * Rational(@value, to.value) 
+        end
+      elsif defined?(Rational) && (@value.is_a?(Rational)) && (to.value.is_a?(Rational))
+        lambda do | from |
+          from * @value / to.value
+        end
+      else
+        lambda do | from |
+          from * (@value / to.value.to_f)
+        end
+      end
+    end
+
+    # The value for a given reference value.
+    # @example
+    #     Unit.add_unit :meter, :length, :1000
+    #     Unit.for(:meter).value_for(5000) = 5
+    # @param [Numeric] value
+    # @return [Numeric]
+    def value_for(reference_value)
+      if defined?(Rational) && (reference_value.is_a?(Fixnum)) && (@value.is_a?(Fixnum))
+        Rational(reference_value, @value)
+      elsif defined?(Rational) && (reference_value.is_a?(Rational) || reference_value.is_a?(Fixnum)) && (@value.is_a?(Rational))
+        reference_value / @value #Rational(reference_value, @value)
+      else
+        reference_value / @value.to_f
+      end
+    end
+
+    # A string representation of this unit at the given value
+    # @param [Any] value
     # @return [String]
-    attr_reader :name
+    def s_for(value)
+      "#{value} #{@name.to_s}"
+    end
 
-    alias_method :to_s, :name
+    def inspect
+      "<Unit #{@name} (#{@object_id}), value #{@value}, dimension #{@dimension}>"
+    end
 
-    ##
-    # @param  [String] name
-    def initialize(name = nil)
-      @name = name || self.class.name.split(':').last.downcase
+    def <=>(other)
+      if other.is_a?(Unit) && other.dimension == @dimension
+        @value <=> other.value
+      elsif other.is_a?(Unit)
+        @name <=> other.name
+      else
+        nil
+      end
+    end
+
+    # Exponentiation
+    # @param other [Numeric]
+    # @return [Unit]
+    def **(other)
+      if other.is_a?(Fixnum) && other > 0
+        other == 1 ? self : self * self**(other-1)
+      else
+        raise ArgumentError, "#{self} cannot be raised to #{other} power."
+      end
+    end
+
+    # Unit multiplication.
+    # @param [Unit] other
+    # @return [Unit]
+    def *(other)
+      if other.is_a?(Unit)
+        units = other.units || { other.dimension => other }
+        units.merge!(@units || { @dimension => self })
+        dim = @dimension * other.dimension
+        existing = Unit.for(Unit.string_form(dim,units).to_sym)
+        existing ||= Unit.new({ :dimension => dim, :units => units }) 
+      else
+        raise ArgumentError, "Cannot multiply #{self} with #{other}"
+      end
+    end
+
+    # Unit division.
+    # @param [Unit] other
+    # @return [Unit]
+    def /(other)
+      if other.is_a?(Unit)
+        units = other.units || { other.dimension => other }
+        units.merge!(@units || { @dimension => self })
+        dim = @dimension / other.dimension
+        existing = Unit.for(Unit.string_form(dim,units).to_sym)
+        existing ||= Unit.new({ :dimension => dim, :units => units }) 
+        existing
+      else
+        raise ArgumentError, "Cannot multiply #{self} with #{other}"
+      end
+    end
+
+    # Convert a portion of this compound to another unit.
+    # This one is tricky, because a lot of things can be happening.
+    # It's valid to convert m^2 to ft^2 and to feet (ft^2), but not 
+    # really valid to convert to ft^3.
+    # @param [Symbol Unit] to
+    # @return [Unit]
+    def convert(target)
+      to = Unit.from_string_form(target)
+      if (to.dimension == @dimension)
+        to
+      elsif @units && @units[to.dimension]
+        units = @units.merge({ to.dimension => to })
+        unit = Unit.for(Unit.string_form(@dimension,units).to_sym)
+        unit ||= Unit.new({ :dimension => @dimension, :units => units }) 
+        unit 
+      else
+        raise ArgumentError, "Cannot convert #{self} to #{target}"
+      end
+    end
+
+    # Parse a string representation of a unit, such as foot^2/time^2, and return
+    # a compound object representing it.
+    def self.from_string_form(to)
+      if Unit.for(to)
+        Unit.for(to)
+      else
+        dimension_string = to.to_s.dup
+        units = {}
+        to.to_s.split(/(\^|\/|\*)/).each do | name |
+          next if name =~ /(\^|\/|\*)/ || name =~ /^\d$/
+          unit = Unit.for(name.to_sym) || Unit.for(name)
+          dimension_string.gsub!(name,unit.dimension.name.to_s)
+          units[unit.dimension] = unit
+        end
+        dimension = Dimension.for(dimension_string.to_sym)
+        raise ArgumentError, "Couldn't create Unit for #{to}" unless dimension && units
+        unit = Unit.new({ :dimension => dimension, :units => units })
+        add_alias(unit,unit.name.to_sym)
+        unit
+      end
+    end
+    
+
+    # Higher-order units have a set of units to reference each aspect of the dimension they
+    # measure.  This is unused in basic units.
+    attr_reader :units
+
+    # A new compound unit.  There are two modes of operation.  One provides a way to add units with
+    # a DSL.  The other provides an options hash a little better for programming.  The last provides
+    # a way to create a unit for a given dimension--useful for reference units.
+    #
+    # @overload initialize(opts = {})
+    #   @param opts [String Symbol]  :name
+    #   @param opts [[Unit]]  :units
+    #   @param opts [Dimension] :dimension
+    # @return [Unit]
+    def initialize(opts)
+      @units = opts[:units]
+      @dimension = opts[:dimension]
+      @value = opts[:value] || calculate_value
+      if @dimension.nil?
+        raise ArgumentError, "Adding invalid unit with nil dimension (#{name} - #{dimension})"
+      end
+      unless opts[:name] || !@dimension.is_base?
+        raise ArgumentError, "Single-order units must be uniquely named (#{name} - #{dimension})"
+      end
+      @name = opts[:name] || string_form
+      self.class.add_alias(self,@name.to_sym)
+      raise ArgumentError, "Creating new unit with no value" unless @value
+    end
+
+    # calculate this unit's value compared to the reference unit
+    def calculate_value
+      value = defined?(Rational) ? Rational(1) : 1.0
+      @dimension.numerators.each do | component |
+        component.power.times do 
+          # we might have a unit for a compound dimension, such as liters for length^3.
+          value *= @units[Quantity::Dimension.for(component.dimension)].value
+        end
+      end
+      @dimension.denominators.each do | component |
+        component.power.times do 
+          value /= @units[Quantity::Dimension.for(component.dimension)].value
+        end
+      end
+      @value = value
+    end
+
+    # A vaguely human-readable form for this unit
+    # @return [String]
+    def string_form
+      self.class.string_form(@dimension,@units)
+    end
+
+    # a vaguely human-readable format for a compound unit 
+    # @param [Dimension] dimension
+    # @param [{}] units
+    # @return [String]
+    def self.string_form(dimension,units)
+      string = dimension.string_form
+      units.each do | dimension, unit |
+        string = string.gsub(dimension.name.to_s, unit.name.to_s)
+      end
+      string
     end
 
-    ##
-    # @return [Symbol]
-    def to_sym
-      name.to_sym
+    # Reset the world.  Useful in testing.
+    # @private
+    def self.__reset!
+      @@units = {}
     end
   end
 end

data/lib/quantity/version.rb

@@ -1,7 +1,7 @@
 class Quantity
   module VERSION
     MAJOR = 0
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
     EXTRA = nil
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: quantity
 version: !ruby/object:Gem::Version 
-  version: 0.0.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Ben Lavender
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-29 00:00:00 +01:00
+date: 2010-01-05 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -33,7 +33,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 0.5.2
     version: 
-description: Units and quantities for Ruby.
+description: "    Quantity provides first-class quantities, units, and base quantities in pure ruby.\n    Things like 1.meter / 1.second == 1 meter/second.\n"
 email: blavender@gmail.com
 executables: []
 
@@ -46,13 +46,14 @@ files:
 - README
 - UNLICENSE
 - VERSION
-- lib/quantity/unit/current.rb
-- lib/quantity/unit/length.rb
-- lib/quantity/unit/luminosity.rb
-- lib/quantity/unit/mass.rb
-- lib/quantity/unit/substance.rb
-- lib/quantity/unit/temperature.rb
-- lib/quantity/unit/time.rb
+- lib/quantity/all.rb
+- lib/quantity/dimension/base.rb
+- lib/quantity/dimension.rb
+- lib/quantity/systems/enumerable.rb
+- lib/quantity/systems/imperial.rb
+- lib/quantity/systems/information.rb
+- lib/quantity/systems/si.rb
+- lib/quantity/systems/us.rb
 - lib/quantity/unit.rb
 - lib/quantity/version.rb
 - lib/quantity.rb

data/lib/quantity/unit/current.rb

@@ -1,9 +0,0 @@
-class Quantity
-  class Unit
-    ##
-    # @see http://en.wikipedia.org/wiki/Electric_current
-    class Current < Unit
-      # TODO
-    end
-  end
-end

data/lib/quantity/unit/length.rb

@@ -1,9 +0,0 @@
-class Quantity
-  class Unit
-    ##
-    # @see http://en.wikipedia.org/wiki/Length
-    class Length < Unit
-      # TODO
-    end
-  end
-end

data/lib/quantity/unit/luminosity.rb

@@ -1,9 +0,0 @@
-class Quantity
-  class Unit
-    ##
-    # @see http://en.wikipedia.org/wiki/Luminous_intensity
-    class Luminosity < Unit
-      # TODO
-    end
-  end
-end

data/lib/quantity/unit/mass.rb

@@ -1,9 +0,0 @@
-class Quantity
-  class Unit
-    ##
-    # @see http://en.wikipedia.org/wiki/Mass
-    class Mass < Unit
-      # TODO
-    end
-  end
-end