quantify 1.0.3 → 1.0.4

data/README

@@ -3,6 +3,83 @@ Licensed under the MIT license (See COPYING file for details)
 Author: Andrew Berkeley (andrew.berkeley.is@googlemail.com)
 Homepage: https://github.com/spatchcock/quantify
 
+Quick introduction
+
+  # Quantity operations
+
+  12.feet + 12.feet                   => "24.0 feet"
+
+  6.m ** 2                            => "36.0 m^2"
+
+  100.km / 2.h                        => "50 kilometers per hour"
+
+  5000.L.to_bbl                       => "31.4490528488754 barrels"
+
+  1.5.lb.to_si.round(2)               => "0.68 kg"
+
+  Unit.ratio :kg, :ton                => "1.016047 kilograms per long ton"
+
+  # 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.
+
+  # 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
+
+  
+General introduction
+
+Quantify represents physical quantities using the Quantify::Quantity class.
+
+A Quantity object holds both a value (Numeric) and a unit (of the class
+Quantify::Unit::Base), for example a Quantity object might represent 12 kgs
+(value, 12; unit, kilogram).
+
+Quantities can be manipulated and operated on, in all of the ways that might be
+required for real physical quantities. Operations include, addition, subtraction,
+multiplying and dividing by scalar values or other quantities, raising to powers,
+converting into alternative unit representations (e.g. kgs to lbs, miles per hour
+to metres per second), and rounding of values. Quantify handles the converting of
+both values and units so that the result is a an accurate representation of the
+operation. For example, multiplying 10 metres by 10 metres will result in a quanity
+of square metres, whereas dividing, say, 10 metres by 2 seconds will result in a
+quantity in metres per second.
+
+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 ... >
@@ -30,62 +107,57 @@ Quantity object attributes
 
 Convert a quantity to a different unit
 
-  energy = 100.kWh                      => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s(:name)                    => "100 kilowatt hours"
+  energy = 100.kWh                      => "100 kilowatt hours"
 
-  energy = quantity.to_megajoules       => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s                           => "360.0 MJ"
+  new_energy = energy.to_megajoules     => "360.0 MJ"
 
-  energy = quantity.to_MJ               => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s                           => "360.0 MJ"
+  new_energy = energy.to_MJ             => "360.0 MJ"
 
-  energy = quantity.to(:MJ)             => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s                           => "360.0 MJ"
+  new_energy = energy.to(:MJ)           => "360.0 MJ"
 
   # Initialize a unit object and pass as conversion argument
   unit = Unit.MJ                        => <Quantify::Unit::SI:0xb75c9718 ... >
-  energy = quantity.to(unit)            => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s                           => "360.0 MJ"
+  new_energy = energy.to(unit)          => "360.0 MJ"
 
-  # Single line conversion of litres to barrels, returning only the value
-  5000.L.to_bbl.value                   => 31.4490528488754
+  # Note: all of the above results are string representations of the actual 
+  # objects which result from these operations.
 
 Convert the units of a quantity with a compound unit
 
-  speed = 70.mi/1.h                     => <Quantify::Quantity:0xb7332bbc ... >
-  speed.to_s                            => "70.0 mi h^-1"
+  speed = 70.mi/1.h                     => "70.0 mi h^-1"
 
-  speed_in_kms = speed.to_km            => <Quantify::Quantity:0xb7332bbc ... >
-  speed_in_kms.to_s                     => "112.65408 km h^-1"
+  speed_in_kms = speed.to_km            => "112.65408 km h^-1"
 
-  speed_in_mins = speed_in_kms.to_min   => <Quantify::Quantity:0xb7332bbc ... >
-  speed_in_mins.to_s                    => "1.877568 km min^-1"
+  speed_in_mins = speed_in_kms.to_min   => "1.877568 km min^-1"
+
+  # Note: all of the above results are string representations of the actual
+  # objects which result from these operations.
 
 Convert a quantity to the corresponding SI unit
 
-  energy = 100.kWh                      => <Quantify::Quantity:0xb7332bbc ... >
-  energy.to_s                           => "100 kWh"
-  si = quantity.to_si                   => <Quantify::Quantity:0x4j4j9sbc ... >
-  si.to_s                               => "360000000.0 J"
+  energy = 100.kWh                      => "100 kWh"
+  si = quantity.to_si                   => "360000000.0 J"
+
+  # Note: all of the above results are string representations of the actual
+  # objects which result from these operations.
 
 Operate on a quantity
 
-  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 :name                       => 100.0 square metres
+  area = 10.m * 10.m                    => "100.0 square metres"
 
-  speed = 250.mi / 3.h                  => <Quantify::Quantity:0xb7332bbc ... >
-  speed.to_s(:name)                     => 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
+  distance.to_s                         => "35.0 mi"
+
+  # Note: all of the above results are string representations of the actual
+  # objects which result from these operations.
 
 Additional operations
 The result of quantity operations is commonly a new quantity with a compound unit.
@@ -165,3 +237,5 @@ Initialize a unit object
   square = last_unit ** 2                => <Quantify::Unit::Compound:0xb446f12f ... >
   square.symbol                          => 'm^2'
   square.measures                        => 'area'
+
+

data/lib/quantify/unit/compound_unit.rb

@@ -318,4 +318,4 @@ module Quantify
 
     end
   end
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: quantify
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 31
   prerelease: 
   segments: 
   - 1
   - 0
-  - 3
-  version: 1.0.3
+  - 4
+  version: 1.0.4
 platform: ruby
 authors: 
 - Andrew Berkeley