README.md in ruby-units-1.3.2 vs README.md in ruby-units-1.4.0
- old
+ new
@@ -15,35 +15,32 @@
## 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("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')
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
+ 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
Unit#-() # Subtract. only works if units are compatible
Unit#*() # Multiply.
@@ -63,96 +60,112 @@
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
All Trig math functions (sin, cos, sinh, hypot...) can take a unit as their parameter. It will be converted to radians and then used if possible.
## Temperatures
Ruby-units makes a distinction between a temperature (which technically is a property) and degrees of temperature (which temperatures are measured in).
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
+ 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
- '100 tempC'.unit >> 'degC' #=> '100 degC'.unit
+ 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
+
\ No newline at end of file