units(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay bestie, welcome to the manual page for units(n) — and yes it's literally just unit conversion. that's the whole vibe. 💅

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

so this library is literally a conversion facility, no cap. it takes all those scientific and engineering shorthand notations and turns them into floating point numbers. which means app devs can take values that are all wearing different unit outfits and scale them into one uniform number. iconic. 🎀

the units conversion facility can also convert between compatible units. like, say your app is expecting a value in ohms (Resistance), and the user rocks up with milliwebers/femtocoulomb — the conversion routine will handle it appropriately, because it's that girl. but if you try a conversion that doesn't actually work? an error gets generated. periodt. 🙈

values get scaled from one set of units to another by dimensional analysis. both the value units and the target units get reduced into primitive units plus a scale factor. then the units get checked for compatibility, and the scale factors get applied by multiplication and division. this technique is extremely flexible and quite robust, lowkey the main character of the whole page. ✨

you can also define new units and new unit abbreviations in terms of the existing units and abbreviations. it's even possible to define a brand new primitive unit, though honestly you probably won't need to. new units most commonly get defined to accommodate non-SI measurement systems — like defining the unit inch as 2.54 cm. slay. 🔥

💅 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. like:

% ::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, okay? no numbers, no nonsense. 👑

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. fr fr. 🌈

% ::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, bestie. it is possible to define virtually any combination of units, prefixes, and powers. but 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. (yes, negative. we said what we said.)
  • subunits are separated from 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. and honestly? the readability ate. 💖
  • the forward-slash separator ("/") 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, so this is not a drill 🚨)
  • 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 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 🌈

here's the glow-up chart, unit string on the left, reduced unit string on the right:

  • 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
💀 not me warning you again but: the hyphen is a unit separator. it multiplies. it does not subtract. iykyk.

✨ SI UNITS ✨

The standard SI units are predefined according to NIST Special Publication 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 🌸

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

  • plane angle — unit name radian, abbr. rad, units m/m, base units m/m
  • solid angle — unit name steradian, abbr. sr, units m^2/m^2, base units m^2/m^2
  • frequency — unit name hertz, abbr. Hz, units (none listed), base units /s
  • force — unit name newton, abbr. N, units (none listed), base units m-kg/s^2
  • pressure — unit name pascal, abbr. Pa, units N/m^2, base units kg/m-s^2
  • energy, work — unit name joule, abbr. J, units N-m, base units m^2-kg/s^2
  • power, radiant flux — unit name watt, abbr. W, units J/s, base units m^2-kg/s^3
  • electric charge — unit name coulomb, abbr. C, units (none listed), base units s-A
  • electric potential — unit name volt, abbr. V, units W/A, base units m^2-kg/s^3-A
  • capacitance — unit name farad, abbr. F, units C/V, base units s^4-A^2/m^2-kg
  • electric resistance — unit name ohm, abbr. (none listed), units V/A, base units m^2-kg/s^3-A^2
  • electric conductance — unit name siemens, abbr. S, units A/V, base units s^3-A^2/m^2-kg
  • magnetic flux — unit name weber, abbr. Wb, units V-s, base units m^2-kg/s^2-A
  • magnetic flux density — unit name tesla, abbr. T, units Wb/m^2, base units kg/s^2-A
  • inductance — unit name henry, abbr. H, units Wb/A, base units m^2-kg/s^2-A^2
  • luminous flux — unit name lumen, abbr. lm, units (none listed), base units cd-sr
  • illuminance — unit name lux, abbr. lx, units lm/m^2, base units cd-sr/m^2
  • activity (of a radionuclide) — unit name becquerel, abbr. Bq, units (none listed), base units /s
  • absorbed dose — unit name gray, abbr. Gy, units J/kg, base units m^2/s^2
  • dose equivalent — unit name sievert, abbr. Sv, units J/kg, base units 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 abbreviation for Electric Resistance (ohms), which is the omega character, is not supported.

Also note that there is no support for Celsius or Farenheit temperature. The units conversion routines can only scale values with multiplication and division, so it is not possible to convert from thermodynamic 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 💖

  • yotta — abbr. Y — factor 1e24
  • zetta — abbr. Z — factor 1e21
  • exa — abbr. E — factor 1e18
  • peta — abbr. P — factor 1e15
  • tera — abbr. T — factor 1e12
  • giga — abbr. G — factor 1e9
  • mega — abbr. M — factor 1e6
  • kilo — abbr. k — factor 1e3
  • hecto — abbr. h — factor 1e2
  • deka — abbr. da — factor 1e1
  • deca — abbr. (none listed) — factor 1e1
  • deci — abbr. d — factor 1e-1
  • centi — abbr. c — factor 1e-2
  • milli — abbr. m — factor 1e-3
  • micro — abbr. u — factor 1e-6
  • nano — abbr. n — factor 1e-9
  • pico — abbr. p — factor 1e-12
  • femto — abbr. f — factor 1e-15
  • atto — abbr. a — factor 1e-18
  • zepto — abbr. z — factor 1e-21
  • yocto — abbr. y — factor 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 package. In some cases, many different conversion factors exist for a given unit, depending on the context. (The appendix lists over 40 conversions 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 🌈

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

🧚 QUANTITIES AND DERIVED UNITS WITH SPECIAL NAMES 🧚

This units conversion package is limited specifically to unit reduction, comparison, and scaling. This package 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 ensure that all length values properly 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 conjunction 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 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 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 Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

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

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.

🔑 KEYWORDS 🔑

angle, constants, conversion, distance, radians, unit

Copyright (c) 2000-2005 Mayo Foundation

And that's the whole thing, bestie 💖 the footer says source/version tcllib 2.2.3 and manual units(n) — no date shown, but it's iconic anyway. periodt 🫶

📦 where this page comes from