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.
* Added CHANGELOG
* 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
* Added instructions on how to add custom units
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)'
* added time helper methods
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
|
