|units(3tcl)||Convert and manipulate quantities with units||units(3tcl)|
NAME¶units - unit conversion
SYNOPSIS¶package require Tcl 8.1
package require units?2.1?
::
|units(3tcl)||Convert and manipulate quantities with units||units(3tcl)|
NAME¶units - unit conversion
SYNOPSIS¶package require Tcl 8.1
package require units?2.1?
::units::convert value targetUnits
::units::new name baseUnits
DESCRIPTION¶This library provides a conversion facility from a variety of scientific and engineering shorthand notations into floating point numbers. This allows application developers to easily convert values with different units into uniformly scaled numbers.
The units conversion facility is also able to convert between compatible units. If, for example, a application is expecting a value in ohms (Resistance), and the user specifies units of milliwebers/femtocoulomb, the conversion routine will handle it appropriately. An error will be generated if an incorrect conversion is attempted.
Values are scaled from one set of units to another by dimensional analysis. Both the value units and the target units are reduced into primitive units and a scale factor. Units are checked for compatibility, and the scale factors are applied by multiplication and division. This technique is extremely flexible and quite robust.
New units and new unit abbreviations can be defined in terms of existing units and abbreviations. It is also possible to define a new primitive unit, although that will probably be unnecessary. New units will most commonly be defined to accommodate non-SI measurement systems, such as defining the unit inch as 2.54 cm.
- ::units::convert value targetUnits
- Converts the value string into a floating point number, scaled to the specified targetUnits. The value string may contain a number and units. If units are specified, then they must be compatible with the targetUnits. If units are not specified for the value, then it will be scaled to the target units. For example,
% ::units::convert "2.3 miles" km 3.7014912 % ::units::convert 300m/s miles/hour 671.080887616 % ::units::convert "1.0 m kg/s^2" newton 1.0 % ::units::convert 1.0 millimeter 1000.0
- ::units::reduce unitString
- Returns a unit string consisting of a scale factor followed by a space separated list of sorted and reduced primitive units. The reduced unit string may include a forward-slash (separated from the surrounding primitive subunits by spaces) indicating that the remaining subunits are in the denominator. Generates an error if the unitString is invalid.
% ::units::reduce pascal 1000.0 gram / meter second second
- ::units::new name baseUnits
- Creates a new unit conversion with the specified name. The new unit name must be only alphabetic (upper or lower case) letters. The baseUnits string can consist of any valid units conversion string, including constant factors, numerator and denominator parts, units with prefixes, and exponents. The baseUnits may contain any number of subunits, but it must reduce to primitive units. BaseUnits could also be the string -primitive to represent a new kind of quantity which cannot be derived from other units. But you probably would not do that unless you have discovered some kind of new universal property.
% ::units::new furlong "220 yards" % ::units::new fortnight "14 days" % ::units::convert 100m/s furlongs/fortnight 601288.475303
UNIT STRING FORMAT¶Value and unit string format is quite flexible. It is possible to define virtually any combination of units, prefixes, and powers. Valid unit strings must conform to these rules.
- A unit string consists of an optional scale factor followed by zero or more subunits. The scale factor must be a valid floating point number, and may or may not be separated from the subunits. The scale factor could be negative.
- Subunits are separated form each other by one or more separator characters, which are space (" "), hyphen ("-"), asterisk ("*"), and forward-slash ("/"). Sure, go ahead and complain about using a minus sign ("-") to represent multiplication. It just isn't sound mathematics, and, by rights, we should require everyone to use the asterisk ("*") to separate all units. But the bottom line is that complex unit strings like m-kg/s^2 are pleasantly readable.
- The forward-slash seperator ("/") indicates that following subunits are in the denominator. There can be at most one forward-slash separator.
- Subunits can be floating point scale factors, but with the exception of the leading scale factor, they must be surrounded by valid separators. Subunit scale factors cannot be negative. (Remember that the hyphen is a unit separator.)
- Subunits can be valid units or abbreviations. They may include a prefix. They may include a plural suffix "s" or "es". They may also include a power string denoted by a circumflex ("^"), followed by a integer, after the unit name (or plural suffix, if there is one). Negative exponents are not allowed. (Remember that the hyphen is a unit separator.)
EXAMPLE VALID UNIT STR