Imperial and US customary units¶

exact_units has a marker for every imperial, US customary and other non-SI unit still in use (feature customary, opt-in: not part of quantities or std, so an API without them pays nothing for them; ww_si's customary turns it on): inches, pounds, gallons, psi, Btu, horsepower, slugs, knots, mils. Each one's scale is the exact rational of SI its legal definition gives, with the source cited in its docs, so a value in pound-force seconds converts to newton seconds exactly, or doesn't convert at all.

use exact_units::{Fixed, prefix::{Milli, One, Pico}, units::{Newton, PoundForce, Second, Times}};

type LbfSeconds = Fixed<Times<PoundForce, Second>, Milli, i32>;

let impulse = LbfSeconds::new(2000); // 2 lbf·s
// 1 lbf·s is 4.4482216152605 N·s exactly
assert_eq!(
    impulse.convert::<Times<Newton, Second>, Pico, i64>(),
    Some(Fixed::new(8_896_443_230_521))
);
// 8.896443230521 N·s is not a whole number of mN·s: refused, not rounded
assert_eq!(impulse.convert::<Times<Newton, Second>, Milli, i64>(), None);

The markers are zero-size types, and convert costs what Fixed::to costs: its factor is worked out at compile time.

No bare ambiguous names¶

"Gallon", "ton", "ounce", "BTU" or "horsepower" each mean several units that differ by up to a fifth. None of them is a marker: there is GallonUs and GallonImperial, TonShort, TonLong and Tonne, BtuIt and BtuTh. A test checks that no marker is named by a word of the table below, and that every unit called after such a word is in its group. The one exception is Degree, the angle: SI names it so, and a temperature degree is always "degree Fahrenheit" or "degree Celsius".

just customary-docs writes the generated tables of this page from the catalogue; just test fails when they are stale.

Mass and force¶

A pound of mass and a pound of force are different dimensions, and so different types:

Fixed<PoundForce, ..>::convert::<PoundAvdp, ..>() doesn't compile, and a dynamic client refuses the same. A slug is a mass of about 32.174 lb (g_n in ft/s²), not a pound.

Temperatures¶

Degrees Fahrenheit and Rankine are points on a scale, not units: Point<Fahrenheit, Fixed<Kelvin, Rational<5, 9>, T>> and Point<Rankine, ..> (see points). A temperature difference in °F is a Fixed<Kelvin, Rational<5, 9>, T>.

Mercury, water, Btu and calories¶

A pressure in inches or millimetres of mercury or of water depends on the density of the liquid, which depends on its temperature. The markers say which one they are:

• conventional, a defined density and g_n: InchOfMercuryConventional (13 595.1 kg/m³, ISO 80000-4), MillimetreOfMercuryConventional (133.322 387 415 Pa), InchOfWaterConventional (1000 kg/m³); and Torr, 101 325/760 Pa, and the EU's legal MillimetreOfMercuryEu, 133.322 Pa;
• at a stated temperature, InchOfMercury32f, InchOfWater39f: measured.

The same for Btu and calories: the International Table and thermochemical ones are defined, those at a temperature or "mean" are measured. A measured unit's scale is the value NIST SP 811 prints, exact in this crate by convention only; UnitExpr::Named's provenance is Provenance::Conventional for them, Defined for every other unit. An API model carries it too (as ww_self::MarkerDef::ConventionalUnit, a unit with its source, while a defined unit stays a plain MarkerDef::Unit and pays nothing for it), for these and for an API crate's own unit! lines with conventional(..), so a client knows which scales are conventions:

The Mars Climate Orbiter case¶

In 1999 a ground program wrote thruster impulse in pound-force seconds where the navigation software expected newton seconds, and the orbiter was lost. With a unit in the type, a value either converts exactly or is refused; it is never read as another unit's number. Fixed::convert as above does it in Rust; with WireWeaver the unit is part of a device's API, so its dynamic clients and Python do the same (imperial and US customary units in WireWeaver).

Sources¶

Every definition is from one of these documents, each read in full; a unit's docs say which and where:

• Refinement of values for the yard and the pound, Federal Register 24 FR 5348 (1 Jul 1959), reprinted in NBS Misc. Publ. 233 (1960)
• NIST Special Publication 811, Guide for the Use of the International System of Units (SI), Appendix B
• NIST Handbook 44 (2026), Appendix C, General Tables of Units of Measurement
• Weights and Measures Act 1985 (c. 72), Schedule 1
• 3^rd CGPM (1901), Resolution 2
• BIPM, The International System of Units (SI), 8^th edition (2006)
• Federal Register 85 FR 62698 (5 Oct 2020), deprecation of the U.S. survey foot
• Council Directive 80/181/EEC of 20 December 1979 on units of measurement
• 21 CFR 101.9 Nutrition labeling of food

A few definitions are stated by no document above. SP 811 prints a matching value for most of them, which the tests check, but the defining relation is from ISO 80000, DIN or tradition: