C0034 exact-units-plain-number¶
Rule: An index, a count, a sequence number or a duration carries what it counts in its type.
| Code | C0034 (stable, never reused) |
| Id | exact-units-plain-number |
| Category | units |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | warn |
an index of one table used for another, or a count of samples taken for bytes, is a bug no plain integer catches |
| units-paranoid | warn |
an index of one table used for another, or a count of samples taken for bytes, is a bug no plain integer catches |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
words |
list of strings | ["idx=Index<Of, T>", "index=Index<Of, T>", "pos=Index<Of, T>", "count=Fixed<Of, One, T>", "num=Fixed<Of, One, T>", "n=Fixed<Of, One, T>", "seq=Seq<Of, T>", "seqno=Seq<Of, T>", "samples=Fixed<Sample, One, T>", "frames=Fixed<Frame, One, T>", "packets=Fixed<Packet, One, T>", "items=Fixed<Item, One, T>", "cycles=Fixed<Cycle, One, T>", "ticks=Fixed<Second, Rational<1, TICK_HZ>, T>"] |
name words of positions and counts, matched anywhere in a name, with the type that holds them; Of is the thing counted, a unit of the crate made with counted! |
durations |
list of strings | ["Duration"] |
types of a time span that a Fixed of seconds holds in the bytes of its integer |
Why¶
An index into one table used for another table, a count of samples taken for a count of bytes, a sequence number compared without wrapping: each is a plain integer that the compiler cannot tell apart from any other. exact_units gives each its own type. An Index<Slot, u8> only indexes slots, a Fixed<Sample, One, u32> counts samples and does not add to bytes, and a Seq<Packet, u16> compares in serial number order.
This lint is the strict level, above exact-units-quantity. It reports plain numbers whose names say they are positions or counts, from the words in words: idx, index, count, num, n, seq, samples, ticks. It also reports std::time::Duration values. A Duration takes 12 or 16 bytes, while a Millis<u32> covers 49 days in 4 bytes and converts exactly.
pub struct Ring {
pub head_idx: u8, // reported: Index<Of, u8>
pub sample_count: u32, // reported: Fixed<Sample, One, u32>
pub poll: Duration, // reported: Fixed<Second, Milli, u32>
pub head: Index<Slot, u8>, // passes
}
Of in a suggestion is the thing counted. Declare it once per crate as a counted unit with exact_units::counted!, so that counts of different things stay different types.
How to fix¶
Replace the plain number with the suggested type and name the thing it counts. Where an assertion or a doc comment fixes the range, the suggestion includes the bounds: Index<Slot, u8, Range<0, 7>>. A len() and other names outside words are never reported. Remove a word from words when it means something else in your project.
Configure¶
[lints.exact-units-plain-number]
level = "deny"
words = ["idx=Index<Of, T>", "index=Index<Of, T>", "pos=Index<Of, T>", "count=Fixed<Of, One, T>", "num=Fixed<Of, One, T>", "n=Fixed<Of, One, T>", "seq=Seq<Of, T>", "seqno=Seq<Of, T>", "samples=Fixed<Sample, One, T>", "frames=Fixed<Frame, One, T>", "packets=Fixed<Packet, One, T>", "items=Fixed<Item, One, T>", "cycles=Fixed<Cycle, One, T>", "ticks=Fixed<Second, Rational<1, TICK_HZ>, T>"]
durations = ["Duration"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(exact-units-plain-number) <reason> (waivers); the code works there too, as in [lints.C0034].