Provided by: units-filter_4.2-4_amd64 bug

NAME

       units-filter - a parser for physical and chemical quantities

SYNOPSIS

       units-filter [-s]  [-o]  [-l]

DESCRIPTION

       units-filter is a basic standalone parser written in C language, flex and bison. It inputs
       strings like "1.5e3 nN.m.s^-1" (it could be the time growth ratio of a torque) and outputs
       the value in standard SI unit, followed by the physical dimension of this value.

OPTIONS

       -s     Like Significant.

              Takes  in  account  the  number of significant digits. For example 1.0 m contains 2
              significant digits, while 0.00100 contains 3 significant digits. It is possible  to
              enforce  the  number  of  significant  digits  by  using  a  special  syntax  :  if
              units-filter parses the input "1.0m#6", it interprets it as a value with exactly  6
              significant digits, like "1.00000 m". The number following the # sign is the forced
              number of significant digits. The number of significant digits appears just  before
              the  last  zero in the output of the command (this zero is a placeholder for future
              extensions).

       -o     Like Output.

              Outputs a correct representation of the physical quantity with its physical unit in
              the  International  System  notation.  There  may be some simplification with usual
              units. For example, a newton will  be  represented  by  the  unit  N  in  place  of
              m.kg.s^-2.  The  value  is expressed as a floating number with one digit before the
              decimal point, and as many digits in the mantissa as necessary to fit  the  desired
              number  of significant digits (see an example below). It is possible to enforce the
              output unit : just add a colon and the desired unit at the end  of  the  input.  If
              this unit is homogeneous with the former one, it will be used to format the output.

       -l     Like LaTeX.

              Outputs a correct representation of the physical quantity with its physical unit in
              the International System notation, in LaTeX language.

SUPPORTED SYNTAX

       The simplest syntax for a physical quantity  to  be  passed  by  units-filter  is:  <float
       number> <physical unit>, for instance: "1e-3 m" stands for one millimeter.

       For  compound  units, the product of two base units is built with a dot "."  and each unit
       can be put at an integer power, with the symbol "^".   For  instance,  the  velocity  unit
       meter  per  second  is  "m.s^-1",  and  the  physical quantity "3e8 m.s^-1" stands for the
       velocity of light.

       One can use the star character "*" instead of the dot "." to mean a multiplication.

       Instead of building compound units with dots and negative powers, one can also use "/"  as
       a separator. For instance, "1 m/s" and "1 m.s^-1", "1 m/s^2" and "1 m.s^-2" are synonyms.

       This simple syntax can be enriched by modifiers.

   The modifier #
       This  modifier  allows  one  to  specify the number of significant digits which apply to a
       physical quantity. For instance, "1e-3m #2" stands for 1.0 mm, i.e.  one  millimeter  with
       two  significant  digits.  The same can be achieved with the input "1.0 mm" or "0.0010 m".
       This modifier is taken in account only if  one  calls  units-filter  -s  to  activate  the
       "Significant"  option.  It  is  also honoured when an output in ordinary text format or in
       LaTeX source format is requested (when one runs units-filter -o or units-filter -l.

       The output of units-filter -s provides the effective number of significant digits, as  the
       ninth  field, hence permitting to make some scripting around. All strings "1e-3m #2", "1.0
       mm" or "0.0010 m" will yield the same output when parsed by units-filter -s.

       Please notice that  this  modifier  allows  one  to  artificially  reduce  the  number  of
       significant   digits,   hence   forcing   some   rounding.   For   instance,   the  string
       "299792458m.s^-1#1", when processed by units-filter -o will yied 3e8 m.s^-1,  which  is  a
       less precise value of the speed of light.

       Much  effort  has been put in the rounding mechanism, in order to overcome limitations due
       to float numbers in base two. The calculations are internally carried as decimal  numbers,
       so  the  general rule to round <integer>+0.5 to the integer immediately above is honoured.
       However, beware: if the value to be rounded comes from  an  external  program  which  uses
       calculation  with ordinary float numbers, a value 3/2 processed by an external program and
       later processed by units-filter, with one single significative number, will not always  be
       rounded to 2 as expected.

   The modifier ~
       This  modifier  allows  one  to  express a given precision, as a percentage.  For example,
       "1kV~2" stands for one kilovolt plus or minus two percent.  This option  is  honoured  wen
       one  runs  units-filter  -o  or  units-filter  -l, that is, when one requests an output in
       ordinary text format or in LaTeX source format.

   The modifier :
       This modifier allows one to specify a non-standard unit for the text or LaTeX output.  For
       instance,  "1800C:A.h"  will  be  rendered  as  half  of  an ampere.hour; This modifier is
       honoured when one runs units-filter -o or units-filter -l, that is, when one  requests  an
       output in ordinary text format or in LaTeX source format.

OUTPUT

       When  units-filter  is run with no option switch, it parses its standard input, and if the
       syntax is recognized, it prints one float number and nine integers. The  meaning  of  this
       output is:

   float value
       The physical quantity's value, given in the basic International System unit.

   integers #1 to #7
       Those  integers  express the powers of the base units of International System used for the
       physical quantity's unit.

   integer #8
       This integer is non-zero only when one calls units-filter with the -s option, to  take  in
       account  significative  numbers  of the value, either given implicitly or given explicitly
       after a modifier (see The modifier "#" above).

   integer #9
       Not used currently. May be used by future versions of units-filter.

       When units-filter is run with the switch -s, the output is the same as  when  units-filter
       is  run  with no option, except for the eighth integer, which is always positive and means
       the number of significant digits (hence the precision) of the value.

       When units-filter is run with the switch -o, the output is a physical quantity, written in
       a  canonical  format.  One  can notice that units-filter -o is reentrant, i.e. when called
       twice in a pipe, the output is the same than when it is called only once.

       When units-filter is run with the switch -l, the output is a physical quantity, written as
       LaTeX  source  code.  In order to get something useful, one must embed the output inside a
       well-shaped LaTeX document and run a LaTeX compiler.

   Compound units
       units-filter can parse physical quantities like "1 h 1 min 1 s", which yields the same  as
       "3661  s".  This  syntax  is honored if and only if the units are compatible together, and
       given in order of decreasing importance.  For example "1m 1mm" makes sense, whereas  "1  C
       1A.h" would trigger an error, and "1A.h 1C" would be accepted.

ERROR OUTPUT

       When the syntax of the input cannot be parsed properly by units-filter, it sends a message
       like ERROR at xx : syntax error, where xx is  a  column  number,  to  the  standard  error
       stream.  The number xx allows one to know how many characters of the input could be parsed
       successfully before the failure. Additionally, the return code of the program is non-zero.

LIST OF PHYSICAL UNITS

       Here is the list of physical units which are automatically recognized by units-filter:
          h: one hour = 3600 s

          min: one minute = 60 s

          m:  meter

          g:  one gram = 1e-3 kg

          s: second

          A: ampere

          K: kelvin

          mol: mole

          cd: candela

          Hz: one hertz = 1 s^-1

          N: newton

          Pa: pascal

          J: joule

          W: watt

          C: coulomb

          V: volt

          ohm: ohm; variant: Ohm

          S: Siemens (the inverse of one ohm)

          F: farad (the electric capacity unit, not the faraday)

          T: tesla

          Wb: weber

          H: henry

          lm: lumen (1 lumen = 1 lux)

          lx: lux

          Bq: becquerel (1 Bq = 1 Hz)

          Gy: gray

          Sv: sievert

          rad: radian (1 rad = 1 no_unit, where no_unit has the units exponents { 0, 0, 0, 0,  0,
          0, 0})

          sr: steradian (1 sr = 1 no_unit)

          nothing:  no_unit;  a  number  with  no unit can be considered as written in radian for
          example

          °: angular degree (1° = pi/180)

          ': angular minute (1' = pi/10800)

          '': angular second (1'' = pi/648000)

          tr: turn (1 tr = 2*pi)

          rpm: revolution per minute (1 rpm = pi/30 Hz)

          b: barn (1b = 1e-28 m^2)

          a: are (1a = 100 m^2)

          L: liter

          t: ton (1 ton = 1e3 kg)

          bar: bar (1 bar = 1e5 Pa)

          eV: electron-volt (1eV = 1.60218e-19 J)

          uma: atomic mass unit (1 uma = 1.66054e-27 kg)

          °A: ångström (1 ångström = 1e-10 m)

EXAMPLES

          Establish the SI value and unit exponent of a quantity in the mksa system:

          ~$ echo 1.5e3 nN.m.s^-1 | units-filter

          1.5e-6 2 1 -3 0 0 0 0

          which means : 1.5e-6 (SI unit) m^2.kg.s^-3

          Compare different physical quantities:

          ~$ e1=$(echo "1.2e-3 V" | units-filter)

          ~$ e2=$(echo "1200e3 nWb/s"| units-filter

          ~$ if [ "$e1" = "$e2" ]; then echo ok; else echo ko; fi

          ok

          ... which emphasizes that webers by time unit are the same as volts.

          Playing with the number of significant digits:

          ~$ echo "0.00100m" | src/units-filter -s

          0.001 1 0 0 0 0 0 0 3 0

          ~$ echo "0.00100m #2" | src/units-filter -s

          0.001 1 0 0 0 0 0 0 2 0

          Giving a value for the relative precision:

          ~$ echo "1kV~2" | units-filter -o

          1e+03 V +-2%

          Turning on the LaTeX output:

          ~$ echo "1kohm+-2%" | units-filter -l

          1\times 10^{+03}\, \Omega \pm 2\,\%

          Turning on the output of a canonical physical notation:

          ~$ echo "1.0 m.kg.s^-2 #7" | units-filter -o

          1.000000e+00N

          Choosing a non-standard unit for the output:

          ~$ echo 1800C:A.h| units-filter -o

          5.000e-01 A.h
                 because 3600 coulomb is one ampere.hour

          ~$ echo 1 g:uma | units-filter -o

          6e23 uma
                 This last result reminds that Avogadro's constant is near 6e23 mol^-1.

KNOWN BUGS

          Few units out of the mksa system are successfully parsed.

          Compound units yield inconsistent results, when parsed by units-filter -o, because this
          process  will  take  the  first  mentioned  unit as the unit wanted for the result, and
          consider that the first value gives the number of wanted significant digits.

AUTHOR

       Georges Khaznadar <georgesk@debian.org>

COPYRIGHT

       2009-2018, Georges Khaznadar

       Permission is granted to copy, distribute and/or modify this document under the  terms  of
       the  GNU General Public License, Version 2 or (at your option) any later version published
       by the Free Software Foundation.

       On Debian systems, the complete text of the GNU General Public License  can  be  found  in
       /usr/share/common-licenses/GPL.