units(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

units 💅

okay bestie, welcome to units(3tcl) — the Tcl manual page that's literally just "Convert and manipulate quantities with units" and honestly? iconic. 🌈

✨ NAME ✨

units — unit conversion, and yes that's the whole name, she's mysterious like that 🎀

🦋 SYNOPSIS 🦋

package require Tcl 8.5 9

package require units ?2.2.3?

::units::convert value targetUnits

::units::reduce unitString

::units::new name baseUnits

💖 DESCRIPTION 💖

okay so listen. this library is a conversion facility, and what she does is take a whole buffet of scientific and engineering shorthand notations and turn them into floating point numbers. that's it, that's the job. and it means application devs can just... convert values with different units into uniformly scaled numbers without losing their minds. slay. 💅

she can also convert between compatible units — like, if your app is expecting a value in ohms (Resistance, yes capital R, she's fancy) and the user rolls up specifying milliwebers/femtocoulomb, the conversion routine will handle it appropriately. bestie is competent. but — and hear me on this — if you attempt an incorrect conversion, an error gets generated. no cap, she will not do it. 🙅

the way she does it is by dimensional analysis. both the value units and the target units get reduced into primitive units plus a scale factor. units get checked for compatibility, and then the scale factors are applied by multiplication and division. this technique is extremely flexible and quite robust — literally built different. 🔥

and you can define new units and new unit abbreviations in terms of the existing ones! you can even define a brand new primitive unit, although honestly that'll probably be unnecessary. most commonly you'd define new units to accommodate non-SI measurement systems — like, say, defining the unit inch as 2.54 cm. periodt.

👑 COMMANDS 👑

  • ::units::convert value targetUnits — takes that value string and turns it into a floating point number, scaled to the targetUnits you specified. the value string may contain a number and units. if units are specified, they've gotta be compatible with targetUnits. if units are not specified for the value, then it just gets scaled to the target units. like:
% ::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 — hands you back a unit string made 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) which means the remaining subunits are chillin' in the denominator. if the unitString is invalid she generates an error, no mercy 💀
% ::units::reduce pascal
1000.0 gram / meter second second
  • ::units::new name baseUnits — creates a new unit conversion with the specified name. heads up: the new unit name must be only alphabetic (upper or lower case) letters. the baseUnits string can consist of any valid units conversion string — constant factors, numerator and denominator parts, units with prefixes, exponents, the whole menu. baseUnits may contain any number of subunits, but it must reduce to primitive units. baseUnits could also be the string -primitive to represent a whole 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. go off i guess?? 🌟
% ::units::new furlong "220 yards"
% ::units::new fortnight "14 days"
% ::units::convert 100m/s furlongs/fortnight
601288.475303

🌸 UNIT STRING FORMAT 🌸

the value and unit string format is quite flexible. you can define virtually any combination of units, prefixes, and powers. but valid unit strings must conform to these rules, bestie, so let's go:

  • 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 it may or may not be separated from the subunits. also the scale factor could be negative. yes, negative. she said what she said. 🙈
  • subunits are separated from each other by one or more separator characters, which are space (" "), hyphen ("-"), asterisk ("*"), and forward-slash ("/"). and yeah, 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, and honestly? that's the vibe check that matters. 😌
  • the forward-slash separator ("/") means that the following subunits are in the denominator. and there can be at most one forward-slash separator. one. uno. don't push it. 💀
  • subunits can be floating point scale factors, but with the exception of the leading scale factor, they must be surrounded by valid separators. and subunit scale factors cannot be negative. (remember that the hyphen is a unit separator. yes i'm saying it again. it's important.) 🫶
  • 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 an integer, after the unit name (or the plural suffix, if there is one). negative exponents are not allowed. (and again — remember that the hyphen is a unit separator.) 🎀

🧚 EXAMPLE VALID UNIT STRINGS 🧚

so here's the glow-up: every unit string on the left reduces to the unit string on the right. obsessed.

  • 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 ✨

okay so the standard SI units are pre-defined according to NIST Special Publication 330. 💖 We've got standard units for both SI Base Units (Table 1) and SI Derived Units with Special Names (Tables 3a and 3b) right here for reference. Every standard unit name and abbreviation is included in this package. no cap. ✨

✨ SI BASE UNITS ✨

these are the base units, the main characters of the SI system. 👑

  • Length — unit name meter, abbreviation m
  • Mass — unit name kilogram, abbreviation kg
  • Time — unit name second, abbreviation s
  • Current — unit name ampere, abbreviation A
  • Temperature — unit name kelvin, abbreviation K
  • Amount — unit name mole, abbreviation mol
  • Luminous Intensity — unit name candela, abbreviation cd

✨ SI DERIVED UNITS WITH SPECIAL NAMES ✨

these are the derived units that got their own special names, and they're iconic. 💅

  • plane angle — radian (rad), units: m/m, base units: m/m
  • solid angle — steradian (sr), units: m^2/m^2, base units: m^2/m^2
  • frequency — hertz (Hz), units: (none), base units: /s
  • force — newton (N), units: (none), base units: m-kg/s^2
  • pressure — pascal (Pa), units: N/m^2, base units: kg/m-s^2
  • energy, work — joule (J), units: N-m, base units: m^2-kg/s^2
  • power, radiant flux — watt (W), units: J/s, base units: m^2-kg/s^3
  • electric charge — coulomb (C), units: (none), base units: s-A
  • electric potential — volt (V), units: W/A, base units: m^2-kg/s^3-A
  • capacitance — farad (F), units: C/V, base units: s^4-A^2/m^2-kg
  • electric resistance — ohm (no abbreviation), units: V/A, base units: m^2-kg/s^3-A^2
  • electric conductance — siemens (S), units: A/V, base units: s^3-A^2/m^2-kg
  • magnetic flux — weber (Wb), units: V-s, base units: m^2-kg/s^2-A
  • magnetic flux density — tesla (T), units: Wb/m^2, base units: kg/s^2-A
  • inductance — henry (H), units: Wb/A, base units: m^2-kg/s^2-A^2
  • luminous flux — lumen (lm), units: (none), base units: cd-sr
  • illuminance — lux (lx), units: lm/m^2, base units: cd-sr/m^2
  • activity (of a radionuclide) — becquerel (Bq), units: (none), base units: /s
  • absorbed dose — gray (Gy), units: J/kg, base units: m^2/s^2
  • dose equivalent — sievert (Sv), units: J/kg, base units: m^2/s^2
lowkey important: the SI unit kilograms is actually implemented as grams because 1e-6 kilogram = 1 milligram, not 1 microkilogram. Also, the abbreviation for Electric Resistance (ohms), which is the omega character, is not supported. sorry bestie, no omega here. 💀
and no, there's no support for Celsius or Farenheit temperature. 😭 The units conversion routines can only scale values with multiplication and division, so you can't convert from thermodynamic temperature (kelvins) to absolute degrees Celsius or Farenheit. But conversion of thermodynamic quantities, like thermal expansion (per unit temperature), is easy to add to the units library. so it's not all bad. 🫶

SI units can have a multiple or sub-multiple prefix. The prefix or its abbreviation goes before the unit, no spaces allowed. Compound prefixes? Not allowed. A prefix should never be used alone. These prefixes are defined in Table 5 of Special Publication 330. periodt. 💅

✨ SI PREFIXES ✨

  • yotta — abbreviation Y, factor 1e24
  • zetta — abbreviation Z, factor 1e21
  • exa — abbreviation E, factor 1e18
  • peta — abbreviation P, factor 1e15
  • tera — abbreviation T, factor 1e12
  • giga — abbreviation G, factor 1e9
  • mega — abbreviation M, factor 1e6
  • kilo — abbreviation k, factor 1e3
  • hecto — abbreviation h, factor 1e2
  • deka — abbreviation da, factor 1e1
  • deca — (no abbreviation), factor 1e1
  • deci — abbreviation d, factor 1e-1
  • centi — abbreviation c, factor 1e-2
  • milli — abbreviation m, factor 1e-3
  • micro — abbreviation u, factor 1e-6
  • nano — abbreviation n, factor 1e-9
  • pico — abbreviation p, factor 1e-12
  • femto — abbreviation f, factor 1e-15
  • atto — abbreviation a, factor 1e-18
  • zepto — abbreviation z, factor 1e-21
  • yocto — abbreviation y, factor 1e-24
we define the same prefix with both the USA (deka) and non-USA (deca) spellings. and we take the liberty of allowing micro to be typed as a u instead of the Greek character mu. so you can just type u and it's fine. iykyk. 😉

✨ NON-SI UNITS ✨

so many non-SI units are used in apps and stuff. Appendix B.8 of NIST Special Publication 811 lists a ton of non-SI conversion factors. We can't include all possible unit definitions in this package. sometimes there are many different conversion factors for a given unit depending on context. (the appendix lists over 40 conversions for British thermal units! 🤯) You can always add application specific conversions using the new command, but we've included some well known and often used ones here. 💖

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

✨ QUANTITIES AND DERIVED UNITS WITH SPECIAL NAMES ✨

so this units conversion package is specifically limited to unit reduction, comparison, and scaling. It does not consider any of the quantity names for either base or derived units. A similar implementation or an extension in a typed or object-oriented language might introduce user defined types for the quantities. Quantity type checking could be used, for example, to make sure all length values properly reduce to meters, or that all velocity values properly reduce to meters/second. vibe check. ✨

A C implementation of this package has been created to work with the Simplified Wrapper Interface Generator (http://www.swig.org/). That package (units.i) uses 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 they're applied to any unit-less quantity strings. slay. 💅

A units system enhanced with quantity type checking might benefit from including other derived types expressed in terms of special 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 International System of Units (SI). Both of these publications are available (as of December 2000) from http://physics.nist.gov/cuu/Reference/contents.html. 💖

The ideas behind the implementation of this package are 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/. iconic. 👑

✨ AUTHORS ✨

Robert W. Techentin — the legend. 🙌

✨ 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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. bestie, we wanna hear from you. 🫶

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. no cap. 💅

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk. ✨

✨ KEYWORDS ✨

angle, constants, conversion, distance, radians, unit

Copyright (c) 2000-2005 Mayo Foundation. 💖

and that's the tea, bestie! this page is from tcllib version 2.2.3, units(3tcl). stay slay, and remember: unit conversions are literally just fancy math. periodt. 💅✨

📦 where this page comes from