ruby-units 1.3.2 → 1.4.0

data/CHANGELOG.txt

@@ -1,12 +1,30 @@
 Change Log for Ruby-units
 =========================
-2011-10-17	1.3.2	* deprecate some string helper functions (make the gem compatible with rails)
-					* tighten up some time helper functions so they don't make as many assumptions
-					* time helpers no longer attempt to convert strings to time/date objects
-2011-10-09			* Farads are not a base unit
-					* CFM added to default units
-					* multi specs run against ruby-1.9.3
-					* internally change Unit#to to Unit#convert_to, which is the preferred form
+2012-01-02  1.4.0   * Fix some definitions that were just wrong (amu, dalton)
+                    * Definition uses name of unit if no aliases provided
+                    * Refactor definition process.  New units are immediately available
+2011-12-31          * Define standard units in terms of base and other standard units -- more internally consistent 
+                      and less prone to round-off errors.
+                    * add 'poundal'
+                    * remove 'wtpercent'
+2011-12-30          * Bump version
+                    * Define compound units with base units for consistency
+                    * distinguish between a league and a nautical league
+                    * NOTE: the new unit definition DSL is not backwardly compatible with the old method
+                      (which is now deprecated).  
+                    * Fix issue #27
+2011-12-18          * Can define a display_name for units (fixes #26)
+2011-12-04          * Documentation improvements
+                    * Add DSL for defining/redefining units
+2011-11-24          * improve yard documentation
+                    * add 'tbsp' as an alias for tablespoon
+2011-10-17  1.3.2   * deprecate some string helper functions (make the gem compatible with rails)
+                    * tighten up some time helper functions so they don't make as many assumptions
+                    * time helpers no longer attempt to convert strings to time/date objects
+2011-10-09          * Farads are not a base unit
+                    * CFM added to default units
+                    * multi specs run against ruby-1.9.3
+                    * internally change Unit#to to Unit#convert_to, which is the preferred form
 
 2011-04-23  1.3.0.a * Some internal restructuring
                     * Implement specs for core behaviors

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2007 Kevin C. Olbrich
+Copyright (c) 2006-2012 Kevin C. Olbrich, Ph.D.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -17,21 +17,17 @@ This package may be installed using:  `gem install ruby-units`
   
 ## Usage:
     unit = Unit.new("1")             # constant only
-    unit = Unit.new("mm")            # unit only (defaults to a value of 1)
-    unit = Unit.new("1 mm")          # create a simple unit
-    unit = Unit.new("1 mm/s")        # a compound unit
-    unit = Unit.new("1 mm s^-1")     # in exponent notation
-    unit = Unit.new("1 kg*m^2/s^2")  # complex unit
-    unit = Unit.new("1 kg m^2 s^-2") # complex unit
+    unit = Unit("mm")                # unit only (defaults to a scalar of 1)
+    unit = Unit("1 mm")              # create a simple unit
+    unit = Unit("1 mm/s")            # a compound unit
+    unit = Unit("1 mm s^-1")         # in exponent notation
+    unit = Unit("1 kg*m^2/s^2")      # complex unit
+    unit = Unit("1 kg m^2 s^-2")     # complex unit
     unit = Unit("1 mm")              # shorthand
     unit = "1 mm".to_unit            # convert string object
     unit = object.to_unit            # convert any object using object.to_s
-    unit = U'1 mm'
-    unit = u'1 mm'
-    unit = '1 mm'.unit
-    unit = '1 mm'.u
-    unit = '1/4 cup'.unit            # Rational number 
-    unit = '1+1i mm'.unit            # Complex Number
+    unit = Unit('1/4 cup')           # Rational number 
+    unit = Unit('1+1i mm')           # Complex Number
 
 ## Rules:
 1. only 1 quantity per unit (with 2 exceptions... 6'5" and '8 lbs 8 oz')
@@ -41,7 +37,8 @@ This package may be installed using:  `gem install ruby-units`
 ## Unit compatability:
 Many methods require that the units of two operands are compatible.  Compatible units are those that can be easily converted into each other, such as 'meters' and 'feet'.
 
-    unit1 =~ unit2   #=> true if units are compatible
+    unit1 =~ unit2                  #=> true if units are compatible
+    unit1.compatible?(unit2)        #=> true if units are compatible
 
 ## Unit Math:
     Unit#+()      # Add. only works if units are compatible
@@ -65,61 +62,54 @@ This will work as expected so long as you start the formula with a Unit object.
 ## Conversions & comparisons
 Units can be converted to other units in a couple of ways.
 
-    unit1 = unit >> "ft"   # convert to 'feet'
-    unit >>= "ft"          # convert and overwrite original object
-    unit3 = unit1 + unit2  # resulting object will have the units of unit1
-    unit3 = unit1 - unit2  # resulting object will have the units of unit1
-    unit1 <=> unit2        # does comparison on quantities in base units, throws an exception if not compatible
-    unit1 === unit2        # true if units and quantity are the same, even if 'equivalent' by <=>
-    unit.to('ft')          # convert
-    unit1 + unit2 >> "ft"  # converts result of math to 'ft'
-    (unit1 + unit2).convert_to('ft') # converts result to 'ft'
+    unit1 = unit >> "ft"              # convert to 'feet'
+    unit >>= "ft"                     # convert and overwrite original object
+    unit3 = unit1 + unit2             # resulting object will have the units of unit1
+    unit3 = unit1 - unit2             # resulting object will have the units of unit1
+    unit1 <=> unit2                   # does comparison on quantities in base units, throws an exception if not compatible
+    unit1 === unit2                   # true if units and quantity are the same, even if 'equivalent' by <=>
+    unit.convert_to('ft')             # convert
+    unit1 + unit2 >> "ft"             # converts result of math to 'ft'
+    (unit1 + unit2).convert_to('ft')  # converts result to 'ft'
  
 Any object that defines a 'to_unit' method will be automatically coerced to a unit during calculations.
  
 ## Text Output
-Units will display themselves nicely based on the preferred abbreviation for the units and prefixes.
+Units will display themselves nicely based on the display_name for the units and prefixes.
 Since Unit implements a Unit#to_s, all that is needed in most cases is:
     
     "#{Unit('1 mm')}"  #=> "1 mm"
  
 The to_s also accepts some options.
 
-    Unit.new('1.5 mm').to_s("%0.2f")  # "1.50 mm".  Enter any valid format
+    Unit('1.5 mm').to_s("%0.2f")  # "1.50 mm".  Enter any valid format
                                       string.  Also accepts strftime format
-    U('1.5 mm').to_s("in")     # converts to inches before printing
-    U("2 m").to_s(:ft)         # returns 6'7"
-    U("100 kg").to_s(:lbs)     # returns 220 lbs, 7 oz
- 
+    Unit('1.5 mm').to_s("in")     # converts to inches before printing
+    Unit("2 m").to_s(:ft)         # returns 6'7"
+    Unit("100 kg").to_s(:lbs)     # returns 220 lbs, 7 oz
+
  
 ## Time Helpers
 Time, Date, and DateTime objects can have time units added or subtracted.
 
-    Time.now + "10 min".unit 
+    Time.now + Unit("10 min") 
 
 Several helpers have also been defined.
 Note: If you include the 'Chronic' gem, you can specify times in natural
       language.
 
       Unit('min').since(DateTime.parse('9/18/06 3:00pm'))
-      'min'.before('9/18/08 3:00pm')
-      'days'.until('1/1/07')
-      '5 min'.from(Time.now)
-      '5 min'.from_now
-      '5 min'.before_now
-      '5 min'.before(Time.now)
-      '10 min'.ago
 
 Durations may be entered as 'HH:MM:SS, usec' and will be returned in 'hours'.
 
-    '1:00'.unit #=> 1 h
-    '0:30'.unit #=> 0.5 h
-    '0:30:30'.unit #=> 0.5 h + 30 sec
+    Unit('1:00')     #=> 1 h
+    Unit('0:30')     #=> 0.5 h
+    Unit('0:30:30')  #=> 0.5 h + 30 sec
 
 If only one ":" is present, it is interpreted as the separator between hours and minutes.
 
 ## Ranges
-    [U('0 h')..U('10 h')].each {|x| p x}
+    [Unit('0 h')..Unit('10 h')].each {|x| p x}
 works so long as the starting point has an integer scalar
 
 ## Math functions
@@ -130,29 +120,52 @@ Ruby-units makes a distinction between a temperature (which technically is a pro
 
 Temperature units (i.e., 'tempK') can be converted back and forth, and will take into account the differences in the zero points of the various scales. Differential temperature (e.g., '100 degC'.unit) units behave like most other units.
 
-    '37 tempC'.unit >> 'tempF' #=> 98.6 tempF
+    Unit('37 tempC').convert_to('tempF')   #=> 98.6 tempF
 
 Ruby-units will raise an exception if you attempt to create a temperature unit that would fall below absolute zero.
 
 Unit math on temperatures is fairly limited.  
 
-    '100 tempC'.unit + '10 degC'.unit   # '110 tempC'.unit
-    '100 tempC'.unit - '10 degC'.unit   # '90 tempC'.unit
-    '100 tempC'.unit + '50 tempC'.unit  # exception  
-    '100 tempC'.unit - '50 tempC'.unit  # '50 degC'.unit
-    '50 tempC'.unit - '100 tempC'.unit  # '-50 degC'.unit
-    '100 tempC'.unit * [scalar]         # '100*scalar tempC'.unit
-    '100 tempC'.unit / [scalar]         # '100/scalar tempC'.unit
-    '100 tempC'.unit * [unit]           # exception
-    '100 tempC'.unit / [unit]           # exception
-    '100 tempC'.unit ** N               # exception
-
-    '100 tempC'.unit >> 'degC'          #=> '100 degC'.unit   
+    Unit('100 tempC') + Unit('10 degC')   # '110 tempC'.unit
+    Unit('100 tempC') - Unit('10 degC')   # '90 tempC'.unit
+    Unit('100 tempC') + Unit('50 tempC')  # exception  
+    Unit('100 tempC') - Unit('50 tempC')  # '50 degC'.unit
+    Unit('50 tempC')  - Unit('100 tempC') # '-50 degC'.unit
+    Unit('100 tempC') * [scalar]          # '100*scalar tempC'.unit
+    Unit('100 tempC') / [scalar]          # '100/scalar tempC'.unit
+    Unit('100 tempC') * [unit]            # exception
+    Unit('100 tempC') / [unit]            # exception
+    Unit('100 tempC') ** N                # exception
+
+    Unit('100 tempC').convert_to('degC')  #=> Unit('100 degC')   
 This conversion references the 0 point on the scale of the temperature unit 
 
-    '100 degC'.unit >> 'tempC'          #=> '-173 tempC'.unit
+    Unit('100 degC').convert_to('tempC')  #=> '-173 tempC'.unit
 These conversions are always interpreted as being relative to absolute zero.
 Conversions are probably better done like this...
     
-    '0 tempC'.unit + '100 degC'.unit #=> '100 tempC'.unit
+    Unit('0 tempC') + Unit('100 degC') #=> Unit('100 tempC')
+
+## Defininig Units
+
+It is possible to define new units or redefine existing ones.
+
+### Define New Unit
+
+The easiest approach is to define a unit in terms of other units.
+
+    Unit.define("foobar") do |foobar|
+      foobar.definition   = Unit("1 foo") * Unit("1 bar")   # anything that results in a Unit object
+      foobar.aliases      = %w{foobar fb}                   # array of synonyms for the unit
+      foobar.display_name = "Foobar"                        # How unit is displayed when output
+    end
+    
+### Redefine Existing Unit
+
+Redefining a unit allows the user to change a single aspect of a definition without having to re-create the entire definition.
+This is useful for changing display names, adding aliases, etc.
 
+    Unit.redefine!("cup") do |cup|
+      cup.display_name  = "cup"
+    end
+  

data/RakeFile

@@ -12,7 +12,8 @@ begin
     gem.authors = ["Kevin Olbrich, Ph.D."]
     gem.email = ["kevin.olbrich+ruby_units@gmail.com"]
     gem.homepage = "https://github.com/olbrich/ruby-units"
-    gem.files.exclude(".*")
+    gem.files.exclude(".*","test/**/*","spec/**/*","autotest/**/*", "Gemfile")
+    gem.license = "MIT"
 	gem.post_install_message = <<-EOS
 ====================
 Deprecation Warning
@@ -31,7 +32,7 @@ The extra functions mostly work the same, but will no longer properly handle cas
 
 Pass in a Date, Time, or DateTime object to get the expected result.
 
-They will probably go away completely in an upcoming release, so it would be a good idea to refactor your code
+They will go away completely in the next release, so it would be a good idea to refactor your code
 to avoid using them.  They will also throw deprecation warnings when they are used.
 EOS
   end
@@ -50,6 +51,16 @@ begin
 rescue LoadError
 end
 
+begin
+  require 'simplecov'
+  desc "code coverage report using simplecov (ruby 1.9+)"
+  task :simplecov do
+    ENV['COVERAGE']='true'
+    Rake::Task['spec'].invoke
+  end
+rescue LoadError
+end
+
 begin
   require 'rspec/core/rake_task'
 
@@ -80,29 +91,27 @@ task :specs => :spec
 desc "Run tests against several ruby versions, requires rvm"
 task :multitest do
   rubies = %w{
-      ruby-1.8.7@ruby-units
-      ruby-1.8.7@ruby-units-with-chronic
-      ruby-1.9.2@ruby-units
-      ruby-1.9.2@ruby-units-with-chronic
-      ruby-1.9.3@ruby-units
-      rbx@ruby-units
-      jruby-1.6.4@ruby-units
+      ruby-1.8.7-p352@ruby-units
+      ruby-1.8.7-p352@ruby-units-with-chronic
+      ruby-1.9.2-p290@ruby-units
+      ruby-1.9.2-p290@ruby-units-with-chronic
+      rbx-head@ruby-units
+      jruby-1.6.5@ruby-units
       }
-  exec "rvm #{rubies.join(',')} tests"
+  exec "rvm #{rubies.join(',')} do rake tests"
 end
 
 desc "Run specs against several ruby versions, requires rvm"
 task :multispec do
   rubies = %w{
-      ruby-1.8.7@ruby-units
-      ruby-1.8.7@ruby-units-with-chronic
-      ruby-1.9.2@ruby-units
-      ruby-1.9.2@ruby-units-with-chronic
-      ruby-1.9.3@ruby-units
-      rbx@ruby-units
-      jruby-1.6.4@ruby-units
+      ruby-1.8.7-p352@ruby-units
+      ruby-1.8.7-p352@ruby-units-with-chronic
+      ruby-1.9.2-p290@ruby-units
+      ruby-1.9.2-p290@ruby-units-with-chronic
+      rbx-head@ruby-units
+      jruby-1.6.5@ruby-units
       }
-  exec "rvm #{rubies.join(',')} specs"
+  exec "rvm #{rubies.join(',')} do rake spec"
 end
 
 task :default => :test

data/TODO

@@ -1,2 +1,3 @@
 2006-10-02  Currency handling remains to be implemented well
-2011-04-23  Refactor caching
+2011-04-23  Refactor caching
+2011-11-23  Perform all internal calculations in rational numbers to avoid round off problems

data/VERSION

@@ -1 +1 @@
-1.3.2
+1.4.0

data/lib/ruby-units.rb

@@ -1,5 +1,6 @@
 $LOAD_PATH << File.dirname(__FILE__)
 require "ruby_units/version"
+require "ruby_units/definition"
 require "ruby_units/cache"
 require 'ruby_units/array'
 require 'ruby_units/date'
@@ -8,7 +9,6 @@ require 'ruby_units/math'
 require 'ruby_units/numeric'
 require 'ruby_units/object'
 require 'ruby_units/string'
-require 'ruby_units/unit_definitions'
 require 'ruby_units/unit'
 require 'ruby_units/fixnum'
-
+require 'ruby_units/unit_definitions'

data/lib/ruby_units.rb

@@ -1,5 +1,6 @@
 $LOAD_PATH << File.dirname(__FILE__)
 require "ruby_units/version"
+require "ruby_units/definition"
 require "ruby_units/cache"
 require 'ruby_units/array'
 require 'ruby_units/date'
@@ -8,7 +9,6 @@ require 'ruby_units/math'
 require 'ruby_units/numeric'
 require 'ruby_units/object'
 require 'ruby_units/string'
-require 'ruby_units/unit_definitions'
 require 'ruby_units/unit'
 require 'ruby_units/fixnum'
-
+require 'ruby_units/unit_definitions'

data/lib/ruby_units/array.rb

@@ -1,6 +1,8 @@
-# make a unit from an array
-# [1, 'mm'].unit => 1 mm
 class Array
+  # Construct a unit from an array
+  # @example [1, 'mm'].to_unit => Unit("1 mm")
+  # @return (see Unit#initialize)
+  # @param [Object] other convert to same units as passed
   def to_unit(other = nil)
     other ? Unit.new(self).convert_to(other) : Unit.new(self)
   end

data/lib/ruby_units/date.rb

@@ -1,10 +1,11 @@
-# Allow date objects to do offsets by a time unit
-# Date.today + U"1 week" => gives today+1 week
-
 require 'date'
 
+# Allow date objects to do offsets by a time unit
+# Date.today + U"1 week" => gives today+1 week
 class Date
   alias :unit_date_add :+
+  # @param [Object] unit
+  # @return [Unit]
   def +(unit)
     case unit
     when Unit
@@ -14,9 +15,10 @@ class Date
       unit_date_add(unit)
     end
   end
-
  
   alias :unit_date_sub :-    
+  # @param [Object] unit
+  # @return [Unit]
   def -(unit)
     case unit
     when Unit 
@@ -27,27 +29,38 @@ class Date
     end
   end
   
+  # Construct a unit from a Date
+  # @example Date.today.to_unit => Unit
+  # @return (see Unit#initialize)
+  # @param [Object] other convert to same units as passed
   def to_unit(other = nil)
     other ? Unit.new(self).convert_to(other) : Unit.new(self)
   end
   alias :unit :to_unit
   
+  # :nocov_19:
   unless Date.instance_methods.include?(:to_time)
+    # @return [Time]
     def to_time
       Time.local(*ParseDate.parsedate(self.to_s))
     end
   end
+  # :nocov_19:
   
   alias :units_datetime_inspect :inspect
+  # @deprecated
   def inspect(raw = false)
     return self.units_datetime_inspect if raw
     self.to_s
   end
   
   unless Date.instance_methods.include?(:to_date)
+    # :nocov_19:
+    # @return [Date]
     def to_date
       Date.civil(self.year, self.month, self.day)
     end
+    # :nocov_19:
   end
   
 end

data/lib/ruby_units/definition.rb

@@ -0,0 +1,100 @@
+class Unit < Numeric
+
+  # Handle the definition of units
+  class Definition
+    
+    # @return [Array]
+    attr_writer :aliases
+    
+    # @return [Symbol]
+    attr_accessor :kind
+    
+    # @return [Numeric]
+    attr_accessor :scalar
+    
+    # @return [Array]
+    attr_accessor :numerator
+
+    # @return [Array]
+    attr_accessor :denominator
+    
+    # @return [String]
+    attr_accessor :display_name
+    
+    # @example Raw definition from a hash
+    #   Unit::Definition.new("rack-unit",[%w{U rack-U}, (6405920109971793/144115188075855872), :length, %w{<meter>} ])
+    # 
+    # @example Block form
+    #   Unit::Definition.new("rack-unit") do |unit|
+    #     unit.aliases = %w{U rack-U}
+    #     unit.definition = Unit("7/4 inches")
+    #   end
+    #
+    def initialize(_name, _definition = [], &block)
+      yield self if block_given?
+      self.name     ||= _name.gsub(/[<>]/,'')
+      @aliases      ||= (_definition[0] || [_name])
+      @scalar       ||= _definition[1]
+      @kind         ||= _definition[2]
+      @numerator    ||= _definition[3] || Unit::UNITY_ARRAY
+      @denominator  ||= _definition[4] || Unit::UNITY_ARRAY
+      @display_name ||= @aliases.first
+    end
+    
+    # name of the unit
+    # nil if name is not set, adds '<' and '>' around the name
+    # @return [String, nil]
+    # @todo refactor Unit and Unit::Definition so we don't need to wrap units with angle brackets
+    def name
+      "<#{@name}>" if (defined?(@name) && @name)
+    end
+    
+    # set the name, strip off '<' and '>'
+    # @param [String]
+    # @return [String]
+    def name=(_name)
+      @name = _name.gsub(/[<>]/,'')
+    end
+    
+    # alias array must contain the name of the unit and entries must be unique
+    # @return [Array]
+    def aliases
+      [[@aliases], @name].flatten.compact.uniq
+    end
+
+    # define a unit in terms of another unit
+    # @param [Unit] unit
+    # @return [Unit::Definition]
+    def definition=(unit)
+      _base         = unit.to_base
+      @scalar       = _base.scalar
+      @kind         = _base.kind
+      @numerator    = _base.numerator
+      @denominator  = _base.denominator
+      self
+    end
+
+    # is this definition for a prefix?
+    # @return [Boolean]
+    def prefix?
+      self.kind == :prefix
+    end
+    
+    # Is this definition the unity definition?
+    # @return [Boolean]
+    def unity?
+      self.prefix? && self.scalar == 1
+    end
+    
+    # is this a base unit?
+    # units are base units if the scalar is one, and the unit is defined in terms of itself.
+    # @return [Boolean]
+    def base?
+      (self.denominator     == Unit::UNITY_ARRAY) &&
+      (self.numerator       != Unit::UNITY_ARRAY) &&
+      (self.numerator.size  == 1) &&
+      (self.scalar          == 1) &&
+      (self.numerator.first == self.name)
+    end
+  end
+end