units man page on Ubuntu

Man page or keyword search:  
man Server   6591 pages
apropos Keyword Search (all sections)
Output format
Ubuntu logo
[printable version]

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::reduce unitString

       ::units::new name baseUnits

_________________________________________________________________

DESCRIPTION
       This  library  provides	a conversion facility from a variety of scien‐
       tific and engineering shorthand notations into floating point  numbers.
       This  allows  application developers to easily convert values with dif‐
       ferent units into uniformly scaled numbers.

       The units conversion facility is also able to convert between  compati‐
       ble 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 anal‐
       ysis.  Both the value units and the target units are reduced into prim‐
       itive 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	exist‐
       ing units and abbreviations.  It is also possible to define a new prim‐
       itive 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.

COMMANDS
       ::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	repre‐
	      sent  a  new kind of quantity which cannot be derived from other
	      units.  But you probably would not do that unless you have  dis‐
	      covered 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	float‐
	      ing  point number, and may or may not be separated from the sub‐
	      units.  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 sub‐
	      units 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 STRINGS
       Unit String		Reduced Unit String
       ------------------------------------------------------------
       meter			1.0 meter
       kilometer		1000.0 meter
       km			1000.0 meter
       km/s			1000.0 meter / second
       /microsecond		1000000.0 / second
       /us			1000000.0 / second
       kg-m/s^2			1000.0 gram meter / second second
       30second			30.0 second
       30 second		30.0 second
       30 seconds		30.0 second
       200*meter/20.5*second	9.75609756098 meter / second

SI UNITS
       The standard SI units are predefined according to NIST Special Publica‐
       tion 330.  Standard units for both SI  Base  Units  (Table  1)  and  SI
       Derived	Units  with Special Names (Tables 3a and 3b) are included here
       for reference.  Each standard unit name and abbreviation	 are  included
       in this package.

   SI BASE UNITS
       Quantity		       Unit Name    Abbr.
       ---------------------------------------------
       Length		       meter	    m
       Mass		       kilogram	    kg
       Time		       second	    s
       Current		       ampere	    A
       Temperature	       kelvin	    K
       Amount		       mole	    mol
       Luminous Intensity      candela	    cd

   SI DERIVED UNITS WITH SPECIAL NAMES
       Quantity		       Unit Name    Abbr.   Units     Base Units
       --------------------------------------------------------------------
       plane angle	       radian	   rad	   m/m	     m/m
       solid angle	       steradian   sr	   m^2/m^2   m^2/m^2
       frequency	       hertz	   Hz		     /s
       force		       newton	   N		     m-kg/s^2
       pressure		       pascal	   Pa	   N/m^2     kg/m-s^2
       energy, work	       joule	   J	   N-m	     m^2-kg/s^2
       power, radiant flux     watt	   W	   J/s	     m^2-kg/s^3
       electric charge	       coulomb	   C		     s-A
       electric potential      volt	   V	   W/A	     m^2-kg/s^3-A
       capacitance	       farad	   F	   C/V	     s^4-A^2/m^2-kg
       electric resistance     ohm		   V/A	     m^2-kg/s^3-A^2
       electric conductance    siemens	   S	   A/V	     s^3-A^2/m^2-kg
       magnetic flux	       weber	   Wb	   V-s	     m^2-kg/s^2-A
       magnetic flux density   tesla	   T	   Wb/m^2    kg/s^2-A
       inductance	       henry	   H	   Wb/A	     m^2-kg/s^2-A^2
       luminous flux	       lumen	   lm		     cd-sr
       illuminance	       lux	   lx	   lm/m^2    cd-sr/m^2
       activity (of a
       radionuclide)	       becquerel   Bq		     /s
       absorbed dose	       gray	   Gy	   J/kg	     m^2/s^2
       dose equivalent	       sievert	   Sv	   J/kg	     m^2/s^2

       Note  that  the	SI  unit  kilograms  is	 actually implemented as grams
       because 1e-6 kilogram = 1 milligram, not 1 microkilogram.  The abbrevi‐
       ation  for Electric Resistance (ohms), which is the omega character, is
       not supported.

       Also note that there is no support for Celsius  or  Farenheit  tempera‐
       ture.   The units conversion routines can only scale values with multi‐
       plication and division, so it is not possible to convert from thermody‐
       namic  temperature  (kelvins) to absolute degrees Celsius or Farenheit.
       Conversion of thermodynamic quantities, such as thermal expansion  (per
       unit temperature), however, are easy to add to the units library.

       SI Units can have a multiple or sub-multiple prefix.  The prefix or its
       abbreviation should appear before the unit, without  spaces.   Compound
       prefixes	 are  not  allowed,  and  a prefix should never be used alone.
       These prefixes are defined in Table 5 of Special Publication 330.

   SI PREFIXES
       Prefix Name     Abbr.   Factor
       ---------------------------------------
       yotta	       Y       1e24
       zetta	       Z       1e21
       exa	       E       1e18
       peta	       P       1e15
       tera	       T       1e12
       giga	       G       1e9
       mega	       M       1e6
       kilo	       k       1e3
       hecto	       h       1e2
       deka	       da      1e1
       deca		       1e1

       deci	       d       1e-1
       centi	       c       1e-2
       milli	       m       1e-3
       micro	       u       1e-6
       nano	       n       1e-9
       pico	       p       1e-12
       femto	       f       1e-15
       atto	       a       1e-18
       zepto	       z       1e-21
       yocto	       y       1e-24

       Note that we define the same prefix with both the USA ("deka") and non-
       USA ("deca") spellings.	Also note that we take the liberty of allowing
       "micro" to be typed as a "u" instead of the Greek character mu.

       Many non-SI units are commonly used in applications.  Appendix  B.8  of
       NIST  Special Publication 811 lists many non-SI conversion factors.  It
       is not possible to include all possible unit definitions in this	 pack‐
       age.   In  some	cases,	many  different conversion factors exist for a
       given unit, depending on the context. (The appendix lists over 40  con‐
       versions	 for British thermal units!)  Application specific conversions
       can always be added using the new command,  but	some  well  known  and
       often used conversions are included in this package.

   NON-SI UNITS
       Unit Name	    Abbr.    Base Units
       --------------------------------------------------
       angstrom			     1.0E-10 m
       astronomicalUnit	    AU	     1.495979E11 m
       atmosphere		     1.01325E5 Pa
       bar			     1.0E5 Pa
       calorie			     4.1868 J
       curie			     3.7E10 Bq
       day			     8.64E4 s
       degree			     1.745329E-2 rad
       erg			     1.0E-7 J
       faraday			     9.648531 C
       fermi			     1.0E-15 m
       foot		    ft	     3.048E-1 m
       gauss			     1.0E-4 T
       gilbert			     7.957747E-1 A
       grain		    gr	     6.479891E-5 kg
       hectare		    ha	     1.0E4 m^2
       hour		    h	     3.6E3 s
       inch		    in	     2.54E-2 m
       lightYear		     9.46073E15 m
       liter		    L	     1.0E-3 m^3
       maxwell		    Mx	     1.0E-8 Wb
       mho			     1.0 S
       micron			     1.0E-6 m
       mil			     2.54E-5 m
       mile		    mi	     1.609344E3 m
       minute		    min	     6.0E1 s
       parsec		    pc	     3.085E16 m
       pica			     4.233333E-3 m
       pound		    lb	     4.535924E-1 kg
       revolution		     6.283185 rad
       revolutionPerMinute  rpm	     1.047198E-1 rad/s
       yard		    yd	     9.144E-1 m
       year			     3.1536E7 s

   QUANTITIES AND DERIVED UNITS WITH SPECIAL NAMES
       This  units  conversion	package is limited specifically to unit reduc‐
       tion, comparison, and scaling.  This package does not consider  any  of
       the  quantity names for either base or derived units.  A similar imple‐
       mentation or an extension in a typed or object-oriented language	 might
       introduce  user defined types for the quantities.  Quantity type check‐
       ing could be used, for example, to ensure that all length values	 prop‐
       erly reduced to meters, or that all velocity values properly reduced to
       meters/second.

       A C implementation of this package has been created to work in conjunc‐
       tion	with	the    Simplified    Wrapper	Interface    Generator
       (http://www.swig.org/).	That package (units.i) exploits SWIG's typemap
       system  to  automatically convert script quantity strings into floating
       point quantities.  Function arguments are specified as  quantity	 types
       (e.g.,  typedef	float  Length),	 and  target  units (expected by the C
       application code) are specified in an associative array.	 Default units
       are  also  defined for each quantity type, and are applied to any unit-
       less quantity strings.

       A units system enhanced with quantity type checking might benefit  from
       inclusion  of  other derived types which are expressed in terms of spe‐
       cial units, as illustrated in Table 2 of	 NIST  Publication  330.   The
       quantity area, for example, could be defined as units properly reducing
       to meter^2, although the utility of defining a unit named square	 meter
       is arguable.

REFERENCES
       The  unit  names, abbreviations, and conversion values are derived from
       those published by the United States Department of Commerce  Technology
       Administration,	National  Institute of Standards and Technology (NIST)
       in NIST Special Publication 330: The International System of Units (SI)
       and  NIST  Special  Publication	811: Guide for the Use of the Interna‐
       tional System of Units (SI).  Both of these publications are  available
       (as  of	December 2000) from http://physics.nist.gov/cuu/Reference/con‐
       tents.html

       The ideas behind implementation of this package is  based  in  part  on
       code  written  in  1993	by  Adrian Mariano which performed dimensional
       analysis of unit strings using fixed size tables of C  structs.	 After
       going  missing  in the late 1990's, Adrian's code has reappeared in the
       GNU Units program at http://www.gnu.org/software/units/

AUTHORS
       Robert W. Techentin

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and  other problems.  Please report such in the category units of
       the	   Tcllib	  SF	     Trackers	       [http://source‐
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       angle, constants, conversion, distance, radians, unit

COPYRIGHT
       Copyright (c) 2000-2005 Mayo Foundation

units				      1.2			   units(3tcl)
[top]

List of man pages available for Ubuntu

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net