quantify 3.1.3 → 3.1.4

data/README.md

@@ -3,67 +3,36 @@ Quantify
 
 A gem to support physical quantities and unit conversions in Ruby
 
-Licensed under the MIT license (See COPYING file for details)
-
 Author: Andrew Berkeley (andrew.berkeley.is@googlemail.com)
 
-Homepage: https://github.com/spatchcock/quantify
+Homepage: https://github.com/spatchcock/quantify 
 
 
 Quick introduction
 ------------------
+```ruby
+# Operating on quantities
 
-    # Operating on quantities
-
-    12.feet + 12.feet                   #=> "24.0 feet"
-
-    6.m ** 2                            #=> "36.0 m²"
-
-    100.km / 2.h                        #=> "50 kilometers per hour"
+12.feet + 12.feet                   #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "24.0 feet"
 
-    5000.L.to_bbl                       #=> "31.4490528488754 barrels"
+6.m ** 2                            #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "36.0 m²"
 
-    1.5.lb.to_si.round(2)               #=> "0.68 kg"
+100.km / 2.h                        #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "50 kilometers per hour"
 
-    Unit.ratio :kg, :ton                #=> "1016.047 kilograms per long ton"
+5000.L.to_bbl                       #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "31.4490528488754 barrels"
 
-Note: these results are string representations of the actual objects
-which result from these operations, using the Quantity#to_s method which
-renders quantities using either the unit name or symbol.
+1.5.lb.to_si.round(2)               #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "0.68 kg"
 
-    # Handling units
-
-    Unit.ton.name                       #=> "long ton"
-
-    Unit.ton.label                      #=> "ton_uk"
-
-    Unit.ton.measures                   #=> "mass"
-
-    Unit.ton.alternatives :name         #=> [ "kilogram",
-                                              "gram",
-                                              "carat",
-                                              "electron mass",
-                                              "grain",
-                                              "hundredweight long",
-                                              "hundredweight short",
-                                              "ounce",
-                                              "pennyweight",
-                                              "pound",
-                                              "short ton",
-                                              "stone",
-                                              "tonne",
-                                              "unified atomic mass" ]
- 
-    Unit.ton.si_unit                    #=> 'kg'
-
-    Unit.ton.dimensions                 #=> <Quantify::Dimensions:0xb75467c8 ... >
-
-    Unit.ton.dimensions.describe        #=> "mass"
-
-    Unit.ton.dimensions.mass            #=> 1
-
-    Unit.ton.dimensions.length          #=> nil
+1.kg < 1.g                          #=> false
 
+Unit.ratio(:kg, :ton)               #=> <Quantify::Quantity:0xb7332bbc ... >
+_.to_s                              #=> "1016.047 kilograms per long ton"
+```
     
 General introduction
 --------------------
@@ -78,74 +47,126 @@ Quantities can be manipulated and operated on, in all of the ways that might be
 In all cases the results of operations are a changes to the Quantity instance or a new instance of a Quantity object. The new value or unit can be accessed using the #value and #unit attributes, or the #to_s method which renders the quantity in string form.
 
 There are several ways to initialize a quantity object
-
-    mass = Quantity.new(100,:lb)          #=> <Quantify::Quantity:0xb7332bbc ... >
-    mass = Quantity.new(100,'pound')      #=> <Quantify::Quantity:0xb7332bbc ... >
-    mass = 100.lb                         #=> <Quantify::Quantity:0xb7332bbc ... >
-    mass = 100.pound                      #=> <Quantify::Quantity:0xb7332bbc ... >
-    mass = Quantity.parse "100 lb"        #=> <Quantify::Quantity:0xb7332bbc ... >
-    mass = "100 lb".to_q                  #=> <Quantify::Quantity:0xb7332bbc ... >
+```ruby
+long_text = "I travelled 220 miles driving my car and using 0.13 UK gallons per mile of diesel"
+
+mass = Quantity.new(100,:lb)          #=> <Quantify::Quantity:0xb7332bbc ... >
+mass = Quantity.new(100,'pound')      #=> <Quantify::Quantity:0xb7332bbc ... >
+mass = 100.lb                         #=> <Quantify::Quantity:0xb7332bbc ... >
+mass = 100.pound                      #=> <Quantify::Quantity:0xb7332bbc ... >
+mass = Quantity.parse "100 lb"        #=> [<Quantify::Quantity:0xb7332bbc ... >]
+mass = Quantity.parse long_text       #=> [<Quantify::Quantity:0xb7332bbc ... >, <Quantify::Quantity:0xc564321c ... >]
+mass = "100 lb".to_q                  #=> [<Quantify::Quantity:0xb7332bbc ... >]
+```
 
 Quantity object can be insterrogated for a range of attributes
+```ruby
+mass = 100.pound                      #=> <Quantify::Quantity:0xb7332bbc ... >
+
+mass.value                            #=> 100.0
+mass.unit                             #=> <Quantify::Unit::NonSI:0xb7332b08 ... >
+mass.unit.name                        #=> "pound"
+mass.unit.symbol                      #=> "lb"
+
+mass.unit.label                       #=> "lb" # unique identifier, follows JScience
+mass.unit.pluralized_name             #=> "pounds"
+mass.to_s                             #=> "100 lb"
+mass.to_s(:name)                      #=> "100 pounds"
+
+mass.represents                       #=> "mass" # Describe the physical quantity represented by the quantity
+mass.unit.measures                    #=> "mass" # Describe the physical quantity described by the unit
+
+mass.unit.alternatives(:name)         #=> [ "kilogram",
+                                      #     "gram",
+                                      #     "carat",
+                                      #     "electron mass",
+                                      #     "grain",
+                                      #     "hundredweight long",
+                                      #     "hundredweight short",
+                                      #     "ounce",
+                                      #     "pennyweight",
+                                      #     "pound",
+                                      #     "short ton",
+                                      #     "stone",
+                                      #     "tonne",
+                                      #     "unified atomic mass" ]
+ 
+mass.unit.si_unit                     #=> 'kg'
 
-    mass.value                            #=> 100.0
-    mass.unit                             #=> <Quantify::Unit::NonSI:0xb7332b08 ... >
-    mass.unit.name                        #=> "pound"
-    mass.unit.symbol                      #=> "lb"
-
-    # unique identifier, follows JScience
-    mass.unit.label                       #=> "lb"
-    mass.unit.pluralized_name             #=> "pounds"
-    mass.to_s                             #=> "100 lb"
-    mass.to_s(:name)                      #=> "100 pounds"
-
-    # Describe the physical quantity represented by the quantity
-    mass.represents                       #=> "mass"
+mass.unit.dimensions                  #=> <Quantify::Dimensions:0xb75467c8 ... >
+mass.unit.dimensions.describe         #=> "mass"
+mass.unit.dimensions.mass             #=> 1  # index of base dimension 'mass'
+```
 
 Convert a quantity to a different unit
-
-    energy = 100.kWh                      #=> "100 kilowatt hours"
+```ruby
+energy = 100.kWh                      #=> <Quantify::Quantity:0xb7332bbc ... >
+energy.to_s                           #=> "100 kilowatt hours"
   
-    new_energy = energy.to_megajoules     #=> "360.0 MJ"
+new_energy = energy.to_megajoules     #=> <Quantify::Quantity:0xb7332bbc ... >
+new_energy.to_s                       #=> "360.0 MJ"
   
-    new_energy = energy.to_MJ             #=> "360.0 MJ"
+new_energy = energy.to_MJ             #=> <Quantify::Quantity:0xb7332bbc ... >
+new_energy.to_s                       #=> "360.0 MJ"
   
-    new_energy = energy.to(:MJ)           #=> "360.0 MJ"
+new_energy = energy.to(:MJ)           #=> <Quantify::Quantity:0xb7332bbc ... >
+new_energy.to_s                       #=> "360.0 MJ"
 
-    # Initialize a unit object and pass as conversion argument
-    unit = Unit.MJ                        #=> <Quantify::Unit::SI:0xb75c9718 ... >
-    new_energy = energy.to(unit)          #=> "360.0 MJ"
+# Initialize a unit object and pass as conversion argument
+unit = Unit.MJ                        #=> <Quantify::Unit::SI:0xb75c9718 ... >
+new_energy = energy.to(unit)          #=> <Quantify::Quantity:0xb7332bbc ... >
+new_energy.to_s                       #=> "360.0 MJ"
+```
 
 Convert the units of a quantity with a compound unit
+```ruby
+speed = 70.mi/1.h                     #=> <Quantify::Quantity:0xb7332bbc ... >
+speed.to_s                            #=> "70.0 mi/h"
 
-    speed = 70.mi/1.h                     #=> "70.0 mi/h"
-
-    speed_in_kms = speed.to_km            #=> "112.65408 km/h"
+speed_in_kms = speed.to_km            #=> <Quantify::Quantity:0xb7332bbc ... >
+speed_in_kms.to_s                     #=> "112.65408 km/h"
 
-    speed_in_mins = speed_in_kms.to_min   #=> "1.877568 km/min"
+speed_in_mins = speed_in_kms.to_min   #=> <Quantify::Quantity:0xb7332bbc ... >
+speed_in_mins.to_s                    #=> "1.877568 km/min"
+```
 
 Convert a quantity to the corresponding SI unit
+```ruby
+energy = 100.kWh                      #=> <Quantify::Quantity:0xb7332bbc ... >
+energy.to_s                           #=> "100 kWh"
 
-    energy = 100.kWh                      #=> "100 kWh"
-    si = quantity.to_si                   #=> "360000000.0 J"
+si = quantity.to_si                   #=> <Quantify::Quantity:0xb7332bbc ... >
+si.to_s                               #=> "360000000.0 J"
+```
 
 Operate on a quantity
+```ruby
+mass = 10.kg * 3                      #=> <Quantify::Quantity:0xb7332bbc ... >
+mass.to_s                             #=> "30.0 kg"
 
-    mass = 10.kg * 3                      #=> "30.0 kg"
+distance = 100.light_years / 20       #=> <Quantify::Quantity:0xb7332bbc ... >
+distance.to_s                         #=> "5.0 ly"
 
-    distance = 100.light_years / 20       #=> "5.0 ly"
+area = 10.m * 10.m                    #=> <Quantify::Quantity:0xb7332bbc ... >
+area.to_s                             #=> "100.0 square metres"
 
-    area = 10.m * 10.m                    #=> "100.0 square metres"
+speed = 250.mi / 3.h                  #=> <Quantify::Quantity:0xb7332bbc ... >
+speed.to_s                            #=> "83.3333333333333 miles per hour"
 
-    speed = 250.mi / 3.h                  #=> "83.3333333333333 miles per hour"
+speed = 70.mi/1.h                     #=> <Quantify::Quantity:0xb7332bbc ... >
+time = 0.5.h                          #=> <Quantify::Quantity:3xf3472hjc ... >
+distance = speed * time               #=> <Quantify::Quantity:7d7f8g9d5g ... >
+distance.to_s                         #=> "35.0 mi"
+```
 
-    speed = 70.mi/1.h                     #=> <Quantify::Quantity:0xb7332bbc ... >
-    time = 0.5.h                          #=> <Quantify::Quantity:3xf3472hjc ... >
-    distance = speed * time               #=> <Quantify::Quantity:7d7f8g9d5g ... >
-    distance.to_s                         #=> "35.0 mi"
+Compare quantities
+```ruby
+1.kg < 1.g                          #=> false
+1.kg > 1.g                          #=> true
 
-Note: all of the above results are string representations of the actual
-objects which result from these operations.
+# Comparisons only valid if quantities are of same dimension
+1.kg < 1.m                          #=> <Quantify::Exceptions::InvalidArgumentError ... >
+```
 
 Additional operations
 ---------------------
@@ -157,18 +178,21 @@ Units are not automatically cancelled or rationalized (made consistent). This is
 and the user may not necessarily prefer a conversion into consistent mass units (e.g. g/g or t/t). Therefore, the following methods are available...
 
 Where units representing the same physical quantity appear together, they can be made consistent by simply converting to the unit which is desired:
-    
-    area = 12.yd * 36.ft                  #=> <Quantify::Quantity:0xb7332bbc ... >
-    area.to_s                             #=> "432.0 yd ft"
-    area.to_yd
-    area.to_s                             #=> "144.0 yd²"
+```ruby
+area = 12.yd * 36.ft                  #=> <Quantify::Quantity:0xb7332bbc ... >
+area.to_s                             #=> "432.0 yd ft"
 
-Alternatively, all units within the numerator and denominator respectively can be standardized:
+area = area.to_yd                     #=> <Quantify::Quantity:0xb7332bbc ... >
+area.to_s                             #=> "144.0 yd²"
+```
 
-    quantity = (12.ft*8.mi)/(1.s*8.min)
-    quantity.to_s                         #=> 12.0 ft mi/s min
-    quantity.rationalize_units!
-    quantity.to_s                         #=> 1056.0 ft²/s²
+Alternatively, all units within the numerator and denominator respectively can be standardized:
+```ruby
+quantity = (12.ft*8.mi)/(1.s*8.min)   #=> <Quantify::Quantity:0xb7332bbc ... >
+quantity.to_s                         #=> "12.0 ft mi/s min"
+quantity.rationalize_units!
+quantity.to_s                         #=> "1056.0 ft²/s²"
+```
 
 A quantity with arbitrary cancelable units can be cancelled manually:
 
@@ -177,4 +201,22 @@ A quantity with arbitrary cancelable units can be cancelled manually:
     quantity.cancel_base_units! :m
     quantity.to_s                         #=> "746496.0 m^4"
 
-Note: there are more comprehensive and flexible methods for manupulating compound units available as part of of the class Unit::Compound. These can be used to convert a conpound unit into the precise form required. If such an approach is used, any quantity object can be converted to the new form by simply passing the new unit object into the Quantity#to method.
+Note: there are more comprehensive and flexible methods for manupulating compound units available as part of of the class Unit::Compound. These can be used to convert a conpound unit into the precise form required. If such an approach is used, any quantity object can be converted to the new form by simply passing the new unit object into the Quantity#to method.
+
+Contributing
+============
+
+If you find a bug or think that you improve on the code, feel free to contribute.
+
+You can:
+
+* Send the author a message (andrew.berkeley.is@googlemail.com)
+* Create an issue
+* Fork the project and submit a pull request.
+
+License
+=======
+
+© Copyright 2012 Andrew Berkeley.
+
+Licensed under the MIT license (See COPYING file for details)

data/VERSION

@@ -1 +1 @@
-3.1.3
+3.1.4

data/lib/quantify/quantity.rb

@@ -313,12 +313,15 @@ module Quantify
 
     def multiply_or_divide!(operator,other)
       if other.kind_of? Numeric
+        raise ZeroDivisionError if (other.to_f == 0.0 && operator == :/)
         @value = @value.send(operator,other)
+
         return self
       elsif other.kind_of? Quantity
         @unit = @unit.send(operator,other.unit).or_equivalent
         @unit.consolidate_base_units! if @unit.is_compound_unit? && Quantity.auto_consolidate_units?
         @value = @value.send(operator,other.value)
+        
         return self
       else
         raise Quantify::Exceptions::InvalidArgumentError, "Cannot multiply or divide a Quantity by a non-Quantity or non-Numeric object"

data/quantify.gemspec

@@ -5,18 +5,17 @@
 
 Gem::Specification.new do |s|
   s.name = "quantify"
-  s.version = "3.1.3"
+  s.version = "3.1.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andrew Berkeley"]
-  s.date = "2012-05-01"
+  s.date = "2012-10-30"
   s.description = "A gem to support physical quantities and unit conversions"
   s.email = "andrew.berkeley.is@googlemail.com"
   s.extra_rdoc_files = [
     "README.md"
   ]
   s.files = [
-    ".rvmrc",
     "COPYING",
     "Gemfile",
     "README.md",
@@ -54,7 +53,7 @@ Gem::Specification.new do |s|
   s.homepage = "https://github.com/spatchcock/quantify"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.17"
+  s.rubygems_version = "1.8.24"
   s.summary = "Support for handling physical quantities, unit conversions, etc"
 
   if s.respond_to? :specification_version then

data/spec/quantity_spec.rb

@@ -369,6 +369,18 @@ describe Quantity do
     (20.metre / 5).to_s.should == "4.0 m"
   end
 
+  it "should throw ZeroDivisionError error when dividing a quantity by '0'" do
+    lambda{2.kg / 0}.should raise_error ZeroDivisionError
+  end
+
+  it "should NOT throw ZeroDivisionError error when multiplying a quantity by '0'" do
+    lambda{2.kg * 0}.should_not raise_error ZeroDivisionError
+  end
+
+  it "should multiply a quantity by '0'" do
+    (2.kg * 0).to_s.should == "0.0 kg"
+  end
+
   it "should successfully divide a quantity by a scalar" do
     (2.kg / 0.5).round.to_s.should == "4 kg"
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: quantify
 version: !ruby/object:Gem::Version 
-  hash: 5
+  hash: 11
   prerelease: 
   segments: 
   - 3
   - 1
-  - 3
-  version: 3.1.3
+  - 4
+  version: 3.1.4
 platform: ruby
 authors: 
 - Andrew Berkeley
@@ -15,12 +15,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-05-01 00:00:00 Z
+date: 2012-10-30 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: activesupport
   prerelease: false
-  type: :runtime
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -31,11 +29,11 @@ dependencies:
         - 3
         - 0
         version: "3.0"
+  type: :runtime
+  name: activesupport
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: i18n
   prerelease: false
-  type: :runtime
   requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -45,11 +43,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  type: :runtime
+  name: i18n
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: bundler
   prerelease: false
-  type: :development
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -61,11 +59,11 @@ dependencies:
         - 0
         - 0
         version: 1.0.0
+  type: :development
+  name: bundler
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: jeweler
   prerelease: false
-  type: :development
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -77,11 +75,11 @@ dependencies:
         - 6
         - 4
         version: 1.6.4
+  type: :development
+  name: jeweler
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  type: :development
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -93,11 +91,11 @@ dependencies:
         - 6
         - 0
         version: 2.6.0
+  type: :development
+  name: rspec
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
-  name: rcov
   prerelease: false
-  type: :development
   requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -107,11 +105,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  type: :development
+  name: rcov
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
-  name: rdoc
   prerelease: false
-  type: :development
   requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -121,6 +119,8 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  type: :development
+  name: rdoc
   version_requirements: *id007
 description: A gem to support physical quantities and unit conversions
 email: andrew.berkeley.is@googlemail.com
@@ -131,7 +131,6 @@ extensions: []
 extra_rdoc_files: 
 - README.md
 files: 
-- .rvmrc
 - COPYING
 - Gemfile
 - README.md
@@ -194,7 +193,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Support for handling physical quantities, unit conversions, etc

data/.rvmrc

@@ -1 +0,0 @@
-rvm 1.8.7@quantify