C0033 exact-units-quantity¶
Rule: A number that holds a physical or dimensionless quantity carries its unit in its type.
| Code | C0033 (stable, never reused) |
| Id | exact-units-quantity |
| Category | units |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
a unit in a name is checked by no one; in the type the compiler checks every use. Names only, so a warning |
| small-workspace | warn |
a unit in a name is checked by no one; in the type the compiler checks every use. Names only, so a warning |
| medium | warn |
a unit in a name is checked by no one; in the type the compiler checks every use. Names only, so a warning |
| big | warn |
a unit in a name is checked by no one; in the type the compiler checks every use. Names only, so a warning |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
units |
list of strings | ["ns=Fixed<Second, Nano, T>", "nanos=Fixed<Second, Nano, T>", "us=Fixed<Second, Micro, T>", "micros=Fixed<Second, Micro, T>", "ms=Fixed<Second, Milli, T>", "millis=Fixed<Second, Milli, T>", "s=Fixed<Second, One, T>", "sec=Fixed<Second, One, T>", "secs=Fixed<Second, One, T>", "seconds=Fixed<Second, One, T>", "min=Fixed<Minute, One, T>", "mins=Fixed<Minute, One, T>", "minutes=Fixed<Minute, One, T>", "h=Fixed<Hour, One, T>", "hours=Fixed<Hour, One, T>", "days=Fixed<Day, One, T>", "hz=Fixed<Hertz, One, T>", "khz=Fixed<Hertz, Kilo, T>", "mhz=Fixed<Hertz, Mega, T>", "ghz=Fixed<Hertz, Giga, T>", "rpm=Fixed<Per<Turn, Minute>, One, T>", "v=Fixed<Volt, One, T>", "mv=Fixed<Volt, Milli, T>", "uv=Fixed<Volt, Micro, T>", "ma=Fixed<Ampere, Milli, T>", "ua=Fixed<Ampere, Micro, T>", "ohm=Fixed<Ohm, One, T>", "ohms=Fixed<Ohm, One, T>", "kohm=Fixed<Ohm, Kilo, T>", "uf=Fixed<Farad, Micro, T>", "nf=Fixed<Farad, Nano, T>", "pf=Fixed<Farad, Pico, T>", "uh=Fixed<Henry, Micro, T>", "mw=Fixed<Watt, Milli, T>", "mj=Fixed<Joule, Milli, T>", "c=Point<Celsius, Fixed<Kelvin, One, T>>", "degc=Point<Celsius, Fixed<Kelvin, One, T>>", "celsius=Point<Celsius, Fixed<Kelvin, One, T>>", "mdegc=Point<Celsius, Fixed<Kelvin, Milli, T>>", "kelvin=Fixed<Kelvin, One, T>", "mm=Fixed<Meter, Milli, T>", "um=Fixed<Meter, Micro, T>", "cm=Fixed<Meter, Centi, T>", "km=Fixed<Meter, Kilo, T>", "mg=Fixed<Gram, Milli, T>", "kg=Fixed<Gram, Kilo, T>", "pa=Fixed<Pascal, One, T>", "hpa=Fixed<Pascal, Hecto, T>", "kpa=Fixed<Pascal, Kilo, T>", "deg=Fixed<Degree, One, T>", "degrees=Fixed<Degree, One, T>", "mdeg=Fixed<Degree, Milli, T>", "rad=Fixed<Radian, One, T>", "mrad=Fixed<Radian, Milli, T>", "bytes=Fixed<Byte, One, T>", "kib=Fixed<Byte, Kibi, T>", "mib=Fixed<Byte, Mebi, T>", "gib=Fixed<Byte, Gibi, T>", "kb=Fixed<Byte, Kilo, T>", "mb=Fixed<Byte, Mega, T>", "gb=Fixed<Byte, Giga, T>", "bits=Fixed<Bit, One, T>", "bps=Fixed<Per<Bit, Second>, One, T>", "baud=Fixed<Per<Bit, Second>, One, T>", "percent=Fixed<Ratio, Centi, T>", "pct=Fixed<Ratio, Centi, T>", "permille=Fixed<Ratio, Milli, T>", "ppm=Fixed<Ratio, Micro, T>", "ppb=Fixed<Ratio, Nano, T>", "q15=Q15", "q31=Q31", "db=Fixed<Decibel, P, T>"] |
unit words, matched as the last word of a name (before a qualifier), with the type that holds them; T stands for the number's own type |
words |
list of strings | ["voltage=Fixed<Volt, P, T>", "vbat=Fixed<Volt, P, T>", "vref=Fixed<Volt, P, T>", "frequency=Fixed<Hertz, P, T>", "freq=Fixed<Hertz, P, T>", "temperature=Point<Celsius, Fixed<Kelvin, P, T>>", "temp=Point<Celsius, Fixed<Kelvin, P, T>>", "pressure=Fixed<Pascal, P, T>", "power=Fixed<Watt, P, T>", "energy=Fixed<Joule, P, T>", "resistance=Fixed<Ohm, P, T>", "capacitance=Fixed<Farad, P, T>", "inductance=Fixed<Henry, P, T>", "angle=Fixed<Turn, P, T>", "speed=Fixed<Speed, P, T>", "velocity=Fixed<Speed, P, T>", "timeout=Fixed<Second, P, T>", "delay=Fixed<Second, P, T>", "interval=Fixed<Second, P, T>", "period=Fixed<Second, P, T>", "latency=Fixed<Second, P, T>", "elapsed=Fixed<Second, P, T>", "ttl=Fixed<Second, P, T>", "backoff=Fixed<Second, P, T>", "deadline=Fixed<Second, P, T>", "size=Fixed<Byte, P, T>", "duty=Fixed<Ratio, P, T>", "gain=Fixed<Ratio, P, T>", "ratio=Fixed<Ratio, P, T>", "percent=Fixed<Ratio, Centi, T>", "percentage=Fixed<Ratio, Centi, T>"] |
quantity words, matched anywhere in a name without a unit word, with the type that holds them; P is the scale to choose |
untyped-units |
list of strings | ["ticks", "cycles", "words", "pages", "sectors", "blocks", "count", "items", "entries", "elements", "chars", "lines", "samples", "frames", "packets", "px", "pt", "lsb", "b"] |
unit words with no type in the units table: a name that ends in one says its unit and passes the quantity words |
qualifiers |
list of strings | ["max", "min", "limit", "nominal", "typ", "default", "target", "threshold", "step", "lo", "hi"] |
words that may follow the unit at the end of a name (latency_ms_max) |
Why¶
A plain integer named timeout_ms relies on every reader and every caller to honour the _ms. Nothing stops a value in microseconds from being passed in, or a voltage in millivolts from being added to one in volts. The compiler sees two u32 values and accepts both mistakes.
exact_units puts the unit, the scale and the storage into the type. A Fixed<Second, Milli, u32> has the same bytes as the u32 it replaces, but adding it to a value in microseconds converts exactly or does not compile. Dimensionless quantities belong here too: a percentage, a ppm offset, a duty cycle or a gain is a Fixed<Ratio, ..>, so a duty in percent cannot be read as one in permille.
What the lint reads¶
The lint looks at struct and enum fields, constants, statics, function parameters and function results whose type is a plain number, an Option, a Vec, an array or a slice of one. It reports a name in one of two ways:
- The name ends in a unit word from
units(timeout_ms,vbat_mv,latency_ms_max, wheremaxis a qualifier). The message names the type that holds that unit. - The name holds a quantity word from
words(timeout,voltage,gain) but no unit. The message names the type, with the scalePleft for you to choose.
A name that ends in a unit with no type in the table, such as frame_size_px, passes. Trait implementations are skipped, because the trait owns their signatures; so are extern functions and FFI declarations. The lint reads names only, so each finding is an estimate.
pub struct Config {
pub timeout_ms: u32, // reported: Fixed<Second, Milli, u32>
pub fan_duty_pct: u8, // reported: Fixed<Ratio, Centi, u8>
pub voltage: u16, // reported: Fixed<Volt, P, u16>
pub timeout: Millis<u32>, // passes
}
When the crate gives the value a range, the suggestion carries it as bounds. A range comes from a doc comment (0 to 100), an assertion, an early return, or a clamp assignment; see exact-units-bounds.
How to fix¶
- Add
exact_unitsto the crate's dependencies, with the feature of the unit group (time,electrical,dimensionless). - Replace the plain type with the suggested one, and drop the unit word from the name:
timeout: Millis<u32>. - Where the suggestion leaves
P, pick the scale the value is stored in:One,Milli,Micro, or aRationalfor a register step.
A project that keeps units in names instead turns this lint off. Then unit-suffix runs and checks that each name carries its unit.
Configure¶
[lints.exact-units-quantity]
level = "deny"
units = ["ns=Fixed<Second, Nano, T>", "nanos=Fixed<Second, Nano, T>", "us=Fixed<Second, Micro, T>", "micros=Fixed<Second, Micro, T>", "ms=Fixed<Second, Milli, T>", "millis=Fixed<Second, Milli, T>", "s=Fixed<Second, One, T>", "sec=Fixed<Second, One, T>", "secs=Fixed<Second, One, T>", "seconds=Fixed<Second, One, T>", "min=Fixed<Minute, One, T>", "mins=Fixed<Minute, One, T>", "minutes=Fixed<Minute, One, T>", "h=Fixed<Hour, One, T>", "hours=Fixed<Hour, One, T>", "days=Fixed<Day, One, T>", "hz=Fixed<Hertz, One, T>", "khz=Fixed<Hertz, Kilo, T>", "mhz=Fixed<Hertz, Mega, T>", "ghz=Fixed<Hertz, Giga, T>", "rpm=Fixed<Per<Turn, Minute>, One, T>", "v=Fixed<Volt, One, T>", "mv=Fixed<Volt, Milli, T>", "uv=Fixed<Volt, Micro, T>", "ma=Fixed<Ampere, Milli, T>", "ua=Fixed<Ampere, Micro, T>", "ohm=Fixed<Ohm, One, T>", "ohms=Fixed<Ohm, One, T>", "kohm=Fixed<Ohm, Kilo, T>", "uf=Fixed<Farad, Micro, T>", "nf=Fixed<Farad, Nano, T>", "pf=Fixed<Farad, Pico, T>", "uh=Fixed<Henry, Micro, T>", "mw=Fixed<Watt, Milli, T>", "mj=Fixed<Joule, Milli, T>", "c=Point<Celsius, Fixed<Kelvin, One, T>>", "degc=Point<Celsius, Fixed<Kelvin, One, T>>", "celsius=Point<Celsius, Fixed<Kelvin, One, T>>", "mdegc=Point<Celsius, Fixed<Kelvin, Milli, T>>", "kelvin=Fixed<Kelvin, One, T>", "mm=Fixed<Meter, Milli, T>", "um=Fixed<Meter, Micro, T>", "cm=Fixed<Meter, Centi, T>", "km=Fixed<Meter, Kilo, T>", "mg=Fixed<Gram, Milli, T>", "kg=Fixed<Gram, Kilo, T>", "pa=Fixed<Pascal, One, T>", "hpa=Fixed<Pascal, Hecto, T>", "kpa=Fixed<Pascal, Kilo, T>", "deg=Fixed<Degree, One, T>", "degrees=Fixed<Degree, One, T>", "mdeg=Fixed<Degree, Milli, T>", "rad=Fixed<Radian, One, T>", "mrad=Fixed<Radian, Milli, T>", "bytes=Fixed<Byte, One, T>", "kib=Fixed<Byte, Kibi, T>", "mib=Fixed<Byte, Mebi, T>", "gib=Fixed<Byte, Gibi, T>", "kb=Fixed<Byte, Kilo, T>", "mb=Fixed<Byte, Mega, T>", "gb=Fixed<Byte, Giga, T>", "bits=Fixed<Bit, One, T>", "bps=Fixed<Per<Bit, Second>, One, T>", "baud=Fixed<Per<Bit, Second>, One, T>", "percent=Fixed<Ratio, Centi, T>", "pct=Fixed<Ratio, Centi, T>", "permille=Fixed<Ratio, Milli, T>", "ppm=Fixed<Ratio, Micro, T>", "ppb=Fixed<Ratio, Nano, T>", "q15=Q15", "q31=Q31", "db=Fixed<Decibel, P, T>"]
words = ["voltage=Fixed<Volt, P, T>", "vbat=Fixed<Volt, P, T>", "vref=Fixed<Volt, P, T>", "frequency=Fixed<Hertz, P, T>", "freq=Fixed<Hertz, P, T>", "temperature=Point<Celsius, Fixed<Kelvin, P, T>>", "temp=Point<Celsius, Fixed<Kelvin, P, T>>", "pressure=Fixed<Pascal, P, T>", "power=Fixed<Watt, P, T>", "energy=Fixed<Joule, P, T>", "resistance=Fixed<Ohm, P, T>", "capacitance=Fixed<Farad, P, T>", "inductance=Fixed<Henry, P, T>", "angle=Fixed<Turn, P, T>", "speed=Fixed<Speed, P, T>", "velocity=Fixed<Speed, P, T>", "timeout=Fixed<Second, P, T>", "delay=Fixed<Second, P, T>", "interval=Fixed<Second, P, T>", "period=Fixed<Second, P, T>", "latency=Fixed<Second, P, T>", "elapsed=Fixed<Second, P, T>", "ttl=Fixed<Second, P, T>", "backoff=Fixed<Second, P, T>", "deadline=Fixed<Second, P, T>", "size=Fixed<Byte, P, T>", "duty=Fixed<Ratio, P, T>", "gain=Fixed<Ratio, P, T>", "ratio=Fixed<Ratio, P, T>", "percent=Fixed<Ratio, Centi, T>", "percentage=Fixed<Ratio, Centi, T>"]
untyped-units = ["ticks", "cycles", "words", "pages", "sectors", "blocks", "count", "items", "entries", "elements", "chars", "lines", "samples", "frames", "packets", "px", "pt", "lsb", "b"]
qualifiers = ["max", "min", "limit", "nominal", "typ", "default", "target", "threshold", "step", "lo", "hi"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(exact-units-quantity) <reason> (waivers); the code works there too, as in [lints.C0033].