Bovnar — Unit Ambiguities

Bovnar (BVNR) v1.1 documentation · Also available as Markdown and PDF.

Spec version: 1.1 Status: Reference — companion to the unit registry and the cheat sheet Scope: Every token that could plausibly mean two things — what Bovnar reads it as, and how to write the other meaning.

Companion to Unit & Currency Reference (the registry) and Unit & Currency Cheat Sheet (the symbol tables). Every row here was checked against the reference parser; where a token is refused, it really is error_unit_illegal.

Table of Contents

1. How a token is resolved
2. A bare unit outranks a prefixed reading
3. Two prefixed readings compete
4. Refused outright
5. Prefix symbol vs. base unit symbol
6. Case decides
7. Look-alike characters
8. Temperature scales vs. electrical units
9. Same dimension, different quantity
10. An affine scale inside a compound has no value
11. A named unit is not its compound
12. Unit vs. currency
13. Looks like a unit, is not one
14. Water hardness: six scales, one quantity
15. Same name, different definition
16. Quick index: if you mean X, write Y
17. The same spelling in another namespace

• See also

1. How a token is resolved

A unit component is resolved in this order. Knowing the order explains every table below.

Rule 2 is the load-bearing one: a token that is itself a unit is always that unit, never a prefixed reading of a shorter one. That is what made the compact form (kg for k~g) safe to introduce — it can only ever be accepted where the parser previously raised an error, so no document written before it existed changed meaning.

Rule 3's ~ is never wrong to write. When in doubt, or when a reader of your file might be in doubt, use it: m~in cannot be misread, min can be misremembered.

2. A bare unit outranks a prefixed reading

These 19 tokens are units in their own right. The prefixed reading a reader might expect is reachable only with the ~.

pH, mph and kph are the reason three quantities became units: while they were not in the table, the compact form resolved them as the picohenry and the milli-/kilophot. Naming the quantity is the durable fix — rule 2 then keeps the prefixed reading out on its own.

3. Two prefixed readings compete

When a token can be split in two places, rule 2 decides: the longer base symbol wins.

Both are deterministic, not ambiguous — but neither is guessable. Write d~at / da~t and d~au / da~u explicitly; the separated form is unambiguous in both directions.

4. Refused outright

Three tokens are error_unit_illegal on purpose, listed in .compact_exceptions in src/gendata/units.bvnr. Accepting them would turn a parse error into a quietly wrong unit.

kt is the harder case of the first two: both readings are units Bovnar models, so no table lookup can settle it. Reading a speed as a mass is exactly the failure this format exists to prevent, so the author is asked to say which.

ppt is the same argument twice over. The compact form resolved it as the picopint, so a dimensionless ratio read as a volume; and the two things a writer might have meant differ by 10⁹. Bovnar's parts per trillion is spelled pptr, following UCUM, which splits the same ambiguity the same way ([ppth] for per thousand, [pptr] for per trillion). Note the asymmetry with §2: ppt is not claimed by the new unit, because a bare alias would have taken the spelling away from p~pt — see the note in units.bvnr, and rule 2's guarantee that no existing document changes meaning. Making it an error takes nothing away silently.

5. Prefix symbol vs. base unit symbol

Eight symbols are both a prefix and a unit. Bare, they are always the unit; before another unit they are always the prefix.

da (deca) is a two-character prefix: dam = decametre, dag = decagram, das = decasecond. It is not related to Da (dalton) — case separates them (§6).

6. Case decides

Symbols are matched byte for byte. These pairs differ only in case and mean unrelated things; several are one keystroke apart in everyday data.

Start with the bare symbols, because the prefixed rows below are built from them and they are the three most common symbols in the whole table:

Then the prefixed pairs:

* not a valid token in that casing — listed because the valid neighbours are easy to mistype.

Common miscasings that are errors, not silent variants — K is the kelvin, not the kilo prefix:

7. Look-alike characters

Several symbols exist in more than one Unicode code point. Bovnar accepts the variants on input and always emits one canonical form.

A document that has been through Unicode normalisation (NFC/NFD/NFKC/NFKD) still parses: every variant above maps to the same unit, which the normalisation test sweep enforces over the whole table.

The canonical output is deliberately not NFC. U+2126 (ohm) and U+212B (ångström) both have singleton NFC decompositions — to U+03A9 and U+00C5 — so a document this library writes is not Unicode-normalised, and running it through NFC changes its bytes. It still parses, and re-serialising returns U+2126/U+212B, so the round trip is a semantic fixed point but not a byte fixed point. That matters if you hash, sign or byte-diff bovnar output (the conformance suite's byte-for-byte comparison included): normalise before hashing, or do not normalise at all — but do not assume the two are the same file.

u is both the ASCII micro prefix and the bare symbol for the dalton — rule 2 keeps them apart: u alone is the dalton, us is a microsecond, uu is a micro-dalton.

8. Temperature scales vs. electrical units

The degree sign is not decoration: without it the token is a different quantity entirely.

ASCII aliases avoid the question: degC, degF, degRa, degN, degDe, degRe, degRo. K (kelvin) is absolute and needs no degree sign.

The temperature intervals (§9) prefix the same tokens with Δ (U+0394) and carry the same warning, resolved the same way — delta_degC, delta_degF, delta_degRa, delta_degN, delta_degDe, delta_degRe, delta_degRo, and delta_K for ΔK. There is deliberately no delta_C or delta_F: those read as a delta coulomb and a delta farad, exactly as the table above warns for C and F, so they are error_unit_illegal rather than aliases. delta_K is the one bare-letter form, and it is unambiguous because K is the kelvin and nothing else.

The water-hardness degrees carry the same warning, and one of them is genuinely dangerous:

Their ASCII long forms avoid the question entirely: german_hardness, english_hardness (or clark_degree), french_hardness, russian_hardness, american_hardness.

9. Same dimension, different quantity

The SI dimension vector cannot tell these apart — they are all dimensionally equal — yet they are not interchangeable in meaning. Bovnar's compatibility check is dimension-based, so it accepts conversions in the first group; the second group is protected by an explicit quantity-kind rule.

Dimensionally equal, and Bovnar will convert between them — the distinction is yours to keep:

The factor is not always 1, and that is the part to read twice. Each row above names the units that happen to be worth one of each other, but what the compatibility check actually accepts is the whole dimensional family — every native unit of that dimension converts to every other, at whatever factor relates them. Most of those conversions are exactly right: cal → J, Ci → Bq, hp → W. The ones that cross a quantity boundary Bovnar cannot see are right about the arithmetic and wrong about the quantity, and then the number changes too, so the result does not look like a relabelling:

The families, in full, are: Hz Bq Bd Ci rpm (s⁻¹); Gy Sv rem (m²·s⁻²); W var VA PS hp hp_E hp_B hp_W ton_ref (kg·m²·s⁻³); and the sixteen energy units J eV cal Btu erg thm ft_lb cal_IT Btu_th thm_ec cal_m cal_15 cal_20 Btu_59 Btu_60 Btu_m (kg·m²·s⁻²), which N·m joins as a compound.

Why these are not given quantity kinds, when b/B and lm/cd are. A kind works where the distinction is carried by a unit that appears in the definition: sr holds the photometric kind, so cd·sr inherits it and lm ↔ cd·sr keeps working while lm ↔ cd is refused. Nothing plays that part here — a dose weighting factor and a power factor are dimensionless and equal to 1 by convention. So a kind on Sv would have to refuse Sv ↔ J/kg as well, and one on VA would refuse VA ↔ V·A, which is what a volt-ampere is; leaving those accepted instead would make Gy ≡ J/kg ≡ Sv while Gy ≢ Sv, and code that screens targets with bvn_units_convertible would then depend on which spelling it was handed. The distinction belongs to a quantity-kind vocabulary rather than to a unit, which is where Bovnar carries it: qudt-qk maps QUDT's kinds to their coherent SI units, and that is what separates Torque from Work.

Offering the conversion is not the same as rewriting the annotation. BVN_UNIT_REDUCE leaves every unit in this table alone: a Sv serialises as Sv, never as Gy, and a Ci never becomes 3.7e10 Hz. The collapse folds a compound into the named unit it spells out (A·s → C); it never substitutes one named unit for another. Crossing one of these lines takes an explicit conversion request — a want_unit target, a unit policy, or --unit on the command line — so the risk is in what a consumer asks for, not in what a document says.

Dimensionless but not interchangeable — Bovnar refuses these conversions:

Water chemistry calls the American hardness scale "ppm" (milligrams of CaCO₃ per litre). Bovnar's ppm is the dimensionless 10⁻⁶ and the hardness scale is °aH, an amount concentration — the two carry different dimensions and do not convert into one another. If your source says "ppm hardness", write °aH.

The temperature-interval kind is the one that is scoped to a lone unit at exponent 1, and every other kind in the table is not. The reason is §10: an offset can only ever be applied to a lone bare temperature, so that is the only place a difference could have been misread as a reading. Inside a compound ΔK and K are the same unit — W/(m²·ΔK) is W/(m²·K), ΔK/k~m is K/k~m — because the K there was already an interval.

The logarithmic kinds are separate because no factor can relate them: 20 dB is a ratio of 100, not twice 10 dB, and a pH one unit lower is a tenfold concentration. rpm is a cycle rate and rev/min an angular rate — they differ by 2π and do not convert into one another either.

10. An affine scale inside a compound has no value

°C, °F, °De, °N, °Re and °Ro are offset scales: 0 is not nothing. That is fine for a lone temperature and meaningless in a product.

The annotation stays legal, because it is a reasonable thing to write — people do record a rate of change in °C/h. What it means is a temperature difference per hour, and the difference is what Bovnar cannot infer from the unit: 20 °C/h as a rate is 20 K/h, while 20 °C as a reading is 293.15 K. Rather than pick one, the library refuses to produce a number and leaves the components for a consumer that knows which was meant. Write ΔK/h when you mean the rate — or K/h, which is the same unit (§9) — and the ambiguity disappears.

The lone case now has a spelling too, and it did not before. <float:64,°C> 25.0 is a reading of 25 °C and converts to 298.15 K; if you meant a rise of 25 degrees, write <float:64,Δ°C> 25.0, which converts to 25 ΔK. This was the one place in the format where a wrong unit produced a wrong number silently — the two documents were byte-identical and there was no third spelling to disambiguate them. See doc/05 §3.4 and doc/temperature_difference.md.

11. A named unit is not its compound

A named unit is a single component; the compound that means the same thing is several. Both are valid and both convert to the same SI value, but annotation-vs-inline reconciliation is structural, so mixing the two spellings in one value is error_unit_mismatch.

Pick one spelling per document and stay with it. bvn_units_compatible and bvn_unit_convert_factor relate them, so a consumer can still convert freely.

12. Unit vs. currency

A currency is recognised only with the $ sigil, so the two namespaces cannot collide. The classic cases:

A prefix goes before the sigil, ~ optional: k~$EUR and k$EUR are both thousands of euro. kUSD is an error — the sigil is not optional.

13. Looks like a unit, is not one

Common abbreviations that are not in the table. All are error_unit_illegal, which is the point: a wrong unit is worse than a refused one.

Two that are accepted but rarely mean what the writer intended:

14. Water hardness: six scales, one quantity

All six measure the concentration of dissolved alkaline-earth ions, and Bovnar converts freely between them and m~mol/L. What differs is the reference compound each scale counts, which is why their mass-per-litre definitions are not comparable and the amount concentration is.

The traps, in order of how easily they bite:

Turbidity and salinity are instrument scales, and the trap is that they look interchangeable.

JTU and PSU take no prefix (the candle method cannot resolve below ~25 JTU; practical salinity is bounded by construction). The other turbidity scales do — m~NTU is real in ultrapure-water work.

Bovnar refuses every conversion in the "Not" column rather than implying a factor exists. CF is the exception in the other direction: it really is a conductivity, so 1 CF = 0.1 mS/cm = 100 µS/cm converts exactly.

Conductivity and dissolved solids need no units of their own, and that is the trap: people look for one.

For TDS the ppm question is softer than for hardness: at 1 kg/L, 1 mg/L is 1 ppm by mass, so ppm states a real (dimensionless) quantity. It simply is not the same dimension as mg/L, so the two never convert into one another. A meter's "TDS ppm" reading is EC times an instrument factor — record the EC and the factor, or the TDS as mg/L.

15. Same name, different definition

Not parser ambiguities — real-world ones. Bovnar keeps these distinct, and the distinction is usually where the money is.

16. Quick index: if you mean X, write Y

17. The same spelling in another namespace

Under implementation. The namespace:code notation is not part of a released specification and needs a #!bovnar 1.2 directive; see Unit Profiles.

Everything above is about one token read two ways inside Bovnar's own registry. A unit profile adds a second axis: the same letters mean different things in different vocabularies, and the namespace is what keeps them apart. This is the reason the namespace is mandatory rather than a fallback — there is no spelling a parser could try natively first and in UCUM second without sometimes being wrong.

Every row below was produced by the reference implementation.

Two rules make this tractable, and both are worth knowing before writing a profile code:

• A flat vocabulary's code is one whole token. unece:, qudt: and qudt-qk: recognise no operators and strip no prefixes, so a code either matches entire or is refused. unece:KGM/MTR and qudt:M/SEC are error_unit_illegal, not compounds.
• A whole atom beats a prefix in an expression vocabulary, exactly as it does natively. ucum:min is the minute rather than milli-inch, and udunits:cal the calorie rather than centi-al — the same longest-alias rule §6 describes for the native registry.

Where two vocabularies genuinely name the same quantity they land on the same unit, and that is checked: ucum:kg, unece:KGM, qudt:KiloGM, udunits:kg and qudt-qk:Mass all compare equal. The cross-vocabulary suite (doc/11 §14) verifies this pairwise across 64 concepts, and pins the rows above as pairs that must not compare equal.

See also

• Unit & Currency Reference — the registry these readings come from
• Unit & Currency Cheat Sheet — every symbol in one place
• Specification §11 — Units System — the normative unit rules
• FAQ §4 — Units — common unit questions
• Unit Profiles — the foreign vocabularies §17 draws on, and the suite that checks them against each other

Every claim in this document was verified against the reference implementation. If you find a token whose behaviour surprises you and it is not listed here, that is a documentation bug — please report it.

End of Bovnar — Unit Ambiguities (Bovnar spec 1.1).