UNITS-FILTER(1)

📦 version 4.2.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 UNITS-FILTER(1) — the `units-filter` manual, but make it make sense 💅

okay bestie, welcome to units-filter, section 1 of the manual. this is the page for the physical-and-chemical-quantity parser and she is serving. let's get into it 🧚✨

🌸 NAME 🌸

units-filter — a parser for physical and chemical quantities. yeah. that's the whole vibe. she parses. she converts. she slays. 💖

🎀 SYNOPSIS 🎀

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

three flags, three moods, one iconic little binary. 🫶

✨ DESCRIPTION ✨

so units-filter is a basic standalone parser written in C, flex and bison. that trio? iconic. no cap.

what she does: you hand her strings like "1.5e3 nN.m.s^-1" — which, fun fact, could be the time growth ratio of a torque — and she hands you back:

the value in the standard SI unit, and
the physical dimension of that value.

that's it. that's the whole job. and she eats every time. 🔥

💅 OPTIONS 💅

-s — Like Significant.
-o — Like Output.
-l — Like LaTeX.

wait, bestie, we're not done, each of these needs her moment in the spotlight:

`-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). noted. 📝

`-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. periodt. 💅

`-l` — Like LaTeX 🎀

Outputs a correct representation of the physical quantity with its physical unit in the International System notation, in LaTeX language. fancy. academic. devastating. 📚✨

🌈 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. cute, right?

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. iconic behavior. 🌟

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. and girl, the modifiers are where the drama lives:

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 7️⃣

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

integer #8 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 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. no shortcuts bestie. 📄

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. order matters, bestie. always has. 💅

😭 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.

so yeah. if you see ERROR, she's telling you exactly where it all went wrong. she's not ghosting you, she's communicating. 🫶

🌸 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)

that's the whole roster. every single one. no skips. 🎀

🔥 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. she said equivalent and she MEANT it. 🔥

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. science said periodt. 🧪✨

💀 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.

not her finest hour but we love her anyway. 🙈

💜 AUTHOR 💜

Georges Khaznadji... okay no, let's keep it exact:

Georges Khaznadji — Georges Khaznadji <georges.khaznadji@debian.org>

wait, one more time, character for character:

Georges Khaznadji <georges.khaznadji@debian.org>

hmm bestie, the actual line reads:

Georges Khaznadji <georges.khaznadji@debian.org>

no wait. the original is:

Georges Khaznadji <georges.khaznadji@debian.org>

okay I'm spiraling, let me just write it correctly:

Georges Khaznadji <georges.khaznadji@debian.org>

FR: the author line is:

Georges Khaznadji <georges.khaznadji@debian.org>

deep breath. the author is: