Notes:

### Release Name: ruby-units 0.2.1

```Notes:
=Ruby Units

Version: 0.2.1

Kevin C. Olbrich, Ph.D.

http://www.sciwerks.com

Project page: http://rubyforge.org/projects/ruby-units

==Introduction
Many technical applications make use of specialized calculations at some point.  Frequently, these calculations require unit conversions to ensure accurate results.  Needless to say, this is a pain to properly keep track of, and is prone to numerous errors.

==Solution
The 'Ruby units' gem is designed so simplify the handling of units for scientific calculations.  The units of each quantity are specified when a Unit object is created and the Unit class will handle all subsequent conversions and manipulations to ensure an accurate result.

==Installation:
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("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

==Rules:
1. only 1 quantity per unit (with 2 exceptions... 6'5" and '8 lbs 8 oz')
2. use SI notation when possible
3. avoid using spaces in unit names

==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

==Unit Math:

<b>Method</b>::  <b>Comment</b>
Unit#+()::       Add. only works if units are compatible
Unit#-()::       Subtract. only works if units are compatible
Unit#*()::       Multiply.
Unit#/()::       Divide.
Unit#**()::      Exponentiate.  Exponent must be an integer, can be positive,  negative, or zero
Unit#inverse:: Returns 1/unit
Unit#abs::     Returns absolute value of the unit quantity.  Strips off the  units
Unit#ceil::    rounds quantity to next highest integer
Unit#floor::   rounds quantity down to next lower integer
Unit#round::   rounds quantity to nearest integer
Unit#to_int::  returns the quantity as an integer

Unit will coerce other objects into a Unit if used in a formula.  This means that ..

Unit("1 mm") + "2 mm"  == Unit("3 mm")

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

==Text Output
Units will display themselves nicely based on the preferred abbreviation for the units and prefixes.
Since Unit implements a Unit#to_s, all that is needed in most cases is:
"#{Unit.new('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
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

==Time Helpers

Time, Date, and DateTime objects can have time units added or subtracted.

Time.now + "10 min".u

Several helpers have also been defined.

'min'.since('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

==Ranges

[U('0 h')..U('10 h')].each {|x| p x}
works so long as the starting point has an integer scalar

==Math functions
All Trig math functions (sin, cos, sinh, ...) can take a unit as their parameter.  It will be converted to radians and then used if possible.

Changes:
Change Log for Ruby-units
=========================
2006-08-22  0.1.0   * Initial Release

2006-08-22  0.1.1   * Added new format option "1 mm".to_unit("in") now
converts the result to the indicated units
* Fixed some naming issues so that the gem name matches
the require name.
* Improved test coverage (100% code coverage via RCov)
* fixed a bug that prevented units with a prefix in the
denominator from converting properly
* can use .unit method on a string to create a new unit
object
* can now coerce or define units from arrays, strings,
numerics.
"1 mm".unit + [1, 'mm'] === "2 mm".unit
[1,'mm','s'].unit === "1 mm/s".unit
2.5.unit === "2.5".unit

2006-08-28  0.2.0   * Added 'ruby_unit.rb' file so that requires will still
work if the wrong name is used
* Added 'to' as an alias to '>>' so conversions can be
done as '1 m'.unit.to('1 cm')
* Added ability to convert temperatures to absolute values
using the following syntax:
'37 degC'.unit.to('tempF')  #=> '98.6 degF'.unit
* Tweaked abbreviations a bit.  'ton' is now 'tn' instead
of 't'.  It was causing parse collisions with 'atm'.
* fixed a bug in term elimination routine
* fixed a bug in parsing of powers, and added support for
'm**2' format
* Added support for taking roots of units.  Just
exponentiate with a fraction (0.5, 1.0/3, 0.25)
* renamed 'quantity' to 'scalar'
* any type of Numeric can be used to initialize a Unit,
although this can't really be done with a string
* Units can not be forced to a float using to_f unless
they are unitless.  This prevents some math functions
from forcing the conversion.  To get the scalar, just
use 'unit.scalar'
* 'inspect' returns string representation
* better edge-case detection with math functions.
"0 mm".unit**-1 now throws a ZeroDivisionError exception
* Ranges can make a series of units, so long as the end
points have integer scalars.
* Fixed a parsing bug with feet/pounds and scientific
numbers
2006-09-17          * can now use the '%' format specifier like
'%0.2f' % '1 mm'.unit #=> '1.00 mm'
* works nicely with time now.
'1 week'.unit + Time.now => 1.159e+09 s
Time.at('1.159e+09 s'.unit)
=> Sat Sep 23 04:26:40 EDT 2006
"1.159e9 s".unit.time
=> Sat Sep 23 04:26:40 EDT 2006
* Time.now.unit => 1.159e9 s
* works well with 'Uncertain' numerics
(www.rubyforge.org/projects/uncertain)
* Improved parsing

2006-09-18  0.2.1   * Trig math functions (sin, cos, tan, sinh, cosh, tanh)
accept units that can be converted to radians
Math.sin("90 deg".unit) => 1.0
* Date and DateTime can be offset by a time unit
(Date.today + "1 day".unit) => 2006-09-19
Does not work with months since they aren't a consistent
size
* Tweaked time usage a bit
Time.now + "1 hr".unit => Mon Sep 18 11:51:29 EDT 2006
* can output time in 'hh:mm:ss' format by using
'unit.to_s(:time)'
ago,
since(Time/DateTime),
until(Time/DateTime),
from(Time/DateTime),
before(Time/DateTime), and
after(Time/DateTime)
* Time helpers also work on strings.  In this case they
are first converted to units
'5 min'.from_now
'1 week'.ago
'min'.since(time)
'min'.until(time)
'1 day'.from()
* Can pass Strings to time helpers and they will be parsed
with ParseDate
* Fixed most parsing bugs (I think)
* Can pass a strftime format string to to_s to format time
output
* can use U'1 mm' or '1 mm'.u to specify units now

```