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

• 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

Two 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: 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.

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 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 (factor 1) — the distinction is yours to keep:

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. The collapse folds a compound into the named unit it spells out (A·s → C); it never substitutes one named unit for another.

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 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 — the kelvin has no offset and the ambiguity disappears.

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

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

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).