std.units

import std.units as u provides the SI base dimensions, named derived dimensions, units, physical constants and functions over the built-in Quantity[T, D]. The module is ordinary embedded Plenty: dimensions are pub dimension declarations and units are pub const quantities. Nothing in it allocates.

import std.units as u
from std.units import Velocity, km, hour, m, s

def main() -> Result[(), IoError | AllocError]:
    speed: Quantity[f64, Velocity] = 90.0 * km / hour
    braking = 6.0 * m / (s * s)
    distance = speed * speed / (2.0 * braking)
    print(speed, speed.to(u.knot))?
    print(f"{distance.to(m):.1f} m, {(speed / braking).to(s):.2f} s"?)?
    Ok(())

25.0 m/s 48.59611231101511
52.1 m, 4.17 s

Every unit is a Quantity[f64, D] holding its size in the coherent SI unit, so km stores 1000.0. Construction multiplies by the unit and to divides by it; both are folded at compile time when the operands are constants. A conversion between two non-coherent units divides two rounded values, so it can round: u.foot.to(u.inch) is 12.000000000000002. The stored values themselves are the nearest f64 to each exact definition.

Printing shows the coherent value and SI symbols in SI order (kg, m, s, A, K, mol, cd), so a newton prints as kg*m/s^2; see formatting.

Dimensions

Derived dimensions are aliases; each names a different dimension, so diagnostics can name it:

SI gives some different kinds of quantity one dimension. Energy also describes torque, Frequency also describes activity in becquerels, and SpecificEnergy also describes absorbed and equivalent dose. A program that needs to keep such kinds apart declares its own base dimension.

Units

SI units, their prefixed forms, eV and Wh use their symbols. Other units use names. Micro is written u: um, us, uF.

There is no milliohm constant, because mohm could be read as milli or mega; write 1e-3 * u.ohm. Angles are dimensionless, as in SI, so u.degree is Quantity[f64, One] holding π/180. calorie is the thermochemical calorie (4.184 J), btu the International Table BTU, horsepower the mechanical horsepower (550 ft·lbf/s), mmHg the conventional millimetre of mercury and year 365 days. Celsius and Fahrenheit are not units here; see temperature.

std.units.catalogue adds every SI prefix on every SI unit and the other named units of NIST SP 811. It is a separate module so that only programs importing it pay for its 768 constants.

Constants

Functions

Every argument is a copied quantity, except sum and mean, which borrow the list. Functions built on std.math take f64 storage, as std.math does. abs takes integer storage and abs_float floating storage, as in std.math; clamp accepts any storage. The generic std.math functions min, max, min_all and max_all already accept quantities, so this module does not repeat them. math.sum and math.prod take plain integers and math.abs a plain integer, so they do not accept quantities. A square or cube root whose dimension is not whole is a compile error at the call that needs it:

import std.units as u
import std.math as math

def main() -> Result[(), math.MathError]:
    side = u.sqrt(2.0 * u.litre)?
    Ok(())

`Root[Pow[std.units.Length, 3], 2]`: not a whole dimension

A root derives its dimension, so a formula’s result is checked. Falling through a tunnel across a uniform-density Earth is simple harmonic motion: the trip to the centre takes a quarter period, (π/2)·sqrt(R/g), and the speed there is sqrt(g·R):

import std.units as u
from std.units import km, m, s, minute
import std.math as math

def main() -> Result[(), IoError | AllocError | math.MathError]:
    radius = 6371.0 * km
    to_centre = f64.PI / 2.0 * u.sqrt(radius / u.g_n)?
    top_speed = u.sqrt(u.g_n * radius)?
    print(f"{to_centre.to(minute):.1f} min, {top_speed.to(km / s):.2f} km/s"?)?
    Ok(())

21.1 min, 7.90 km/s

Dimensionless results stay quantities, so an angle or a ratio combines with other quantities without .get():

import std.units as u
from std.units import m
import std.math as math

def main() -> Result[(), IoError | AllocError | math.MathError]:
    rise = 3.0 * m
    run = 4.0 * m
    angle = u.atan2(rise, run)?
    slope = u.hypot(rise, run)
    print(f"{angle.to(u.degree):.2f} degrees, {slope}"?)?
    print(slope * u.cos(angle)?, u.sqrt(rise * run)?)?
    lengths = [rise, run, slope]?
    print(u.sum(&lengths), u.mean(&lengths))?
    Ok(())

36.87 degrees, 5.0 m
4.0 m 3.4641016151377544 m
12.0 m Option[Quantity[f64, std.units.Length]].Some(Quantity[f64, std.units.Length](4.0))

Lists

Use these at the boundary with code that produces or expects plain numbers. Both are infallible and run in constant time: a quantity row is stored exactly as its f64, so the conversion replaces only the list’s type descriptor. No element is read or copied, and nothing is allocated; see representation. D is given explicitly to wrap_list and inferred by strip_list:

import std.units as u
from std.units import Length, km

def main() -> Result[(), IoError | AllocError]:
    laps = u.wrap_list[Length]([400.0, 400.0, 1609.344]?)
    total = u.sum(&laps)
    print(f"{total.to(km):.3f} km"?)?
    metres = u.strip_list(laps)
    print(metres)?
    Ok(())

2.409 km
[400.0, 400.0, 1609.344]

Temperature and time

Celsius and Fahrenheit have offset zeros, so they are not multiplicative units. They convert at the boundary to an absolute temperature; a temperature difference in degrees Celsius has the same size as one in kelvin. Going through Celsius keeps whole Celsius values exact: from_fahrenheit(212.0) is 373.15 K.

A std.time.Duration counts nanoseconds as u64. from_duration converts whole seconds and the remainder separately, but the result is still an f64: spans longer than about 104 days (2^53 nanoseconds) no longer resolve single nanoseconds.

import std.units as u
import std.time as time

def main() -> Result[(), IoError | RangeError]:
    boil = u.from_fahrenheit(212.0)
    print(boil, u.to_celsius(boil), u.to_fahrenheit(u.from_celsius(-40.0)))?
    timeout = u.to_duration(1.5 * u.minute)?
    print(timeout.as_seconds(), u.from_duration(&time.milliseconds(250)))?
    print(u.to_duration(-1.0 * u.s).is_err())?
    Ok(())

373.15 K 100.0 -40.0
90 0.25 s
True

Limits

• Units and functions use f64 storage. A quantity with f32 storage converts with Quantity[f32, D].from(q).
• wrap_list and strip_list take f64 storage only.
• Named units are not printed: a joule prints as kg*m^2/s^2.

Acknowledgements

• Exact unit definitions are from the SI Brochure (9th edition) and NIST SP 811, appendix B.
• Measured constants are the CODATA 2022 recommended values.
• misu and Frink informed the choice of units; Frink’s samples suggested the tunnel example.