Bovnar — Unit & Currency Reference

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

Spec version: 1.1 Status: Normative — the unit and currency registry the parser validates against Scope: Physical units, currency codes, prefix rules, disambiguation, C/Python APIs, and validation.

Table of Contents

1. Overview
   • 1.1 Design Principles
2. Syntax — Annotation as a Type Parameter
   • 2.1 Parameter Ordering Flexibility
   • 2.2 Inline Unit Suffix
   • 2.3 Applicable Type Families
3. Physical Base Units
   • 3.1 SI Base Units
   • 3.2 Named SI-Derived Units
   • 3.3 Non-SI Units Accepted for Use with SI
   • 3.4 Imperial and US Customary Units
   • 3.5 Pressure Units
   • 3.6 Energy Units
   • 3.7 Power Units
   • 3.8 Force Units
   • 3.9 Speed and Rotational Frequency Units
   • 3.10 Volume Units
   • 3.11 Area Units
   • 3.12 Angle Units
   • 3.13 CGS Units
   • 3.14 Radiation Units
   • 3.15 Logarithmic Units
   • 3.16 Electrical Power Units
   • 3.17 Digital Units
   • 3.18 Textile Linear Density
   • 3.19 US Apothecary / Dry Volume
   • 3.20 Old German Units
   • 3.21 Additional Length Units
   • 3.22 Additional Mass Units
   • 3.23 Acceleration
   • 3.24 Signal Rate
   • 3.25 Ratio and Proportion Units
   • 3.26 Named Speed Units
   • 3.27 Acidity
   • 3.28 Water Hardness
   • 3.29 Conductivity and Dissolved Solids
   • 3.30 Turbidity and Salinity
   • 3.31 Sentinel Value
   • 3.32 Units the Unit Profiles Needed
4. Prefixes
   • 4.1 SI Prefixes
   • 4.2 IEC Binary Prefixes
   • 4.3 Compact Prefix Form
5. Unit Notation Grammar
   • 5.1 Simple Units
   • 5.2 Compound Units
   • 5.3 Separators
   • 5.4 Denominator Semantics
6. Exponents
   • 6.1 Unicode Superscript Form
   • 6.2 ASCII Caret Form
   • 6.3 Exponent Edge Cases
7. The no_unit Keyword
8. Constraints and Limits
9. Currency Codes
   • 9.1 The $ Sigil Rule
   • 9.2 ISO 4217 Fiat Currencies and Precious Metals
   • 9.3 Cryptocurrencies
   • 9.4 Prefix Rules for Currency Units
   • 9.5 Compound Currency Expressions
   • 9.6 Compatibility Rules
   • 9.7 Type Pairing Recommendations
10. Symbol Disambiguation
    • 10.1 The Namespace Rule as Disambiguator
    • 10.2 Exhaustive Conflict Table
    • 10.3 The CUP Case in Detail
    • 10.4 The Mandatory Currency Sigil
11. C Data Model
    • 11.1 Enumerations
    • 11.2 Structures
    • 11.3 Convenience Macros
12. C API Functions
    • 12.1 Parsing a Unit String
    • 12.2 Serializing a Unit
    • 12.3 Prefix Factor and Exponent Queries
    • 12.4 SI Conversion API
    • 12.5 Currency API
    • 12.6 Unit Profile API (under implementation)
    • 12.7 Python API
13. Integration with the Parser Event Stream
    • 13.1 Full event sequence — physical unit
    • 13.2 Full event sequence — currency unit
    • 13.3 Inline unit suffix — event stream view
    • 13.4 Practical callback
14. Validation Errors
15. Annotated Examples
    • 15.1 Physical Quantities
    • 15.2 Digital Storage
    • 15.3 Compound SI Quantities
    • 15.4 Currency Amounts and Rates
    • 15.5 Error Cases
    • See also

1. Overview

The Bovnar quantity annotation system is an optional, per-value annotation that attaches a physical unit or currency denomination to any numeric field. It is part of the type annotation (<family:width,_base,unit>) and applies to the uint, sint, float, float_fix, and float_dec type families.

Two distinct namespaces share the annotation slot:

• Physical units — 264 named base units covering SI, Imperial, CGS, radiation, surveying, culinary, Old German, and digital storage quantities.
• Currency codes — 216 monetary denominations: 166 ISO 4217 alphabetic codes (including precious-metal X-codes; 4 are historical — HRK retired 2023-01-01, SLL replaced by SLE 2022, ZWL superseded by ZWG 2024, BGN retired 2026-01-01 — and ANG coexists with its successor XCG, which inherited its numeric code 532; see §9.2) and 50 cryptocurrency tickers.

Both namespaces are syntactically unified: the same grammar, the same ~ prefix separator, the same compound-unit operators (·, *, /), and the same value_unit_t data model apply to both. They are separated purely by a token-classification rule described in §9.1 and §10.

Annotations are descriptive, not prescriptive: the validator checks form and type, and never rejects a document because its units do not add up. The library does provide dimensional analysis and unit conversion as an explicit, opt-in service — bvn_units_compatible, bvn_unit_convert_factor, bvn_unit_convert_value and the exact-rational bvn_unit_convert_rational (§12.4), plus the reader's want_unit hook, which converts at read time (§1.10 of the read/write API). None of that runs unless you ask for it. Exchange-rate arithmetic is the one thing the library genuinely does not do: currencies carry no conversion table, and a cross-currency conversion is always refused rather than guessed (§9.6).

1.1 Design Principles

• SI-first. All SI base units, all 22 BIPM-2019 named derived units, and all 24 current SI prefixes (quecto … quetta) are supported.
• Binary-prefix aware. IEC 80000-13 binary prefixes (kibi … yobi) are supported for digital storage quantities, plus Ri/Qi (robi, quebi) as a forward-looking extension — those two are a proposal, not part of IEC 80000-13, which stops at yobi.
• Compound units. Derived quantities (m/s, kg·m/s², USD/oz_t) are expressed inline without separate schema definitions.
• Two exponent notations. Unicode superscript (m², s⁻²) and ASCII caret (m^2, s^-2) are accepted equivalently.
• Currency as a first-class unit. ISO 4217 and cryptocurrency codes participate in all unit composition rules — prefixes, compound expressions, and the value_unit_t representation — with no special-case parsing.
• Dimensionless values. The keyword no_unit is the canonical representation of a dimensionless quantity.

2. Syntax — Annotation as a Type Parameter

The unit or currency code occupies the third positional parameter class of a type annotation, after the optional bit-width and optional base. Parameter classes are identified by their content, not by position:

type-spec       = param-type [ ":" type-param-list ]
type-param-list = type-param { "," type-param }
type-param      = width-param   (* plain decimal integer, e.g. 32    *)
                | base-param    (* "_" + decimal integer,  e.g. _16  *)
                | unit-param    (* everything else,        e.g. m/s  *)

A unit may also be written in a foreign notation. A name: namespace hands the parameter to a unit profile, which translates it into the same value_unit_t this document describes — so <float_dec:64,ucum:mm[Hg]> and <float_dec:64,mmHg> are the same unit to every part of the library. Seven namespaces are defined — ucum, unece, qudt, qudt-qk, udunits, om and cf; everything in this reference applies to the result unchanged. The notation is under implementation — it is not part of a published specification, and a document must opt in with a #!bovnar 1.2 directive that this build does not itself advertise. A native unit is unaffected in every version. See Unit Profiles.

2.1 Parameter Ordering Flexibility

.val = <uint:32,_10,no_unit> 42;
#      <uint:_10,no_unit,32>        — identical (parameter order is free)
#      <uint:no_unit,_10,32>        — identical

2.2 Inline Unit Suffix

A unit may be written directly after a scalar value literal, between the value and the terminating ;:

.distance  = 1500 m;            # inline physical unit
.speed     = 9.81 m/s;          # compound inline unit
.price     = 19.99 $USD;        # inline currency (mandatory $ sigil)
.gold_rate = 2351.40 $USD/oz_t; # inline compound currency/unit
.ratio     = 3.14 no_unit;      # explicit dimensionless

The inline unit uses the same character set and same semantic parser (bvn_parse_unit) as the type-annotation unit parameter. It is terminated by ASCII whitespace, # (comment), or ;.

A native unit contains no whitespace, in either position. Inline, whitespace ends the token, so 1.0 k g is a value with a stray token after it (error_unexpected_input_byte). In a type annotation, whitespace is legal only beside a separator — the family :, a , between parameters, the closing > — and inside a native unit parameter it is error_type_param_whitespace (spec §5.3). <float:64,k g> used to be accepted as k~g, which made it the one place in the format where a wrong unit was produced silently instead of refused.

A parameter carrying a profile namespace is the exception: there whitespace is kept verbatim and the vocabulary decides what it means, because UDUNITS multiplies with a space and udunits:kg m-2 s-1 is the commonest spelling of a flux in CF metadata. That is a property of the foreign notation, not of the native one — see doc/11 §13.2.

Constraints

When both are present, equality is checked after parsing via bvn_unit_equal, a structural comparison of the parsed value_unit_t values: the two units must have the same number of components and the same set of components (matching base, exponent, and prefix). The comparison is order-insensitive — unit multiplication is commutative, so components are matched as multisets and reordered spellings such as N·m and m·N (or m·s⁻¹ and m/s) compare as equal. (It is not a raw memcmp, which would wrongly reject reordered components.)

.v = <float:64,m/s> 9.81 m·s⁻¹;   # OK: both parse to m/s
.v = <float:64,m> 1.0 s;           # ERROR: error_unit_mismatch

2.3 Applicable Type Families

3. Physical Base Units

Bovnar supports 264 physical base units. Currency codes are a separate namespace and are covered in §9.

Reading this section: The Symbol column gives the canonical serialized form. Long forms are accepted on input but never produced on output. Enum value is the value_base_unit_t constant used in the C API.

3.1 SI Base Units

Note on the kilogram: Bovnar uses g (gram) as the base unit symbol so that the k~ (kilo) prefix can be attached explicitly: k~g = kilogram. This is consistent with how the SI formally defines the kilogram as a prefixed gram.

3.2 Named SI-Derived Units

Photometry: the steradian is carried, not dropped. lm, lx and ph are defined through the steradian, so they carry its quantity kind (§3.12 and §11 of Unit Ambiguities); cd and sb do not. The SI dimension vector cannot tell them apart — every photometric unit reduces to candela in base dimensions — so without the kind the library both refused lm ↔ cd·sr and converted lm ↔ cd at factor 1, which is the same claim with the sr silently dropped. What holds now:

Converts	Refused
lm ↔ cd·sr, lx ↔ lm/m² ↔ cd·sr/m², ph ↔ lx, sb ↔ cd/m²	lm ↔ cd (flux vs intensity), lx ↔ cd/m² and ph ↔ sb (illuminance vs luminance)

3.3 Non-SI Units Accepted for Use with SI

3.4 Imperial and US Customary Units

Length

Thou vs mil: Both thou and mil are accepted for 1/1000 of an inch (25.4 µm). The canonical output form is thou. Note that mil does not mean milliradian; milliradians are written m~rad.

Mass

The apothecary dram is 2.2× the avoirdupois dr and the two are a classic near miss; the apothecary POUND, by contrast, is the troy pound (twelve apothecary ounces, and an apothecary ounce is a troy ounce), so both spellings are one unit. The SHORT hundredweight is exactly 100 lb, which the prefix mechanism already spells h~lb, so it has no unit of its own.

Temperature

Kelvin (K) is the SI base unit (§3.1). Ra not R — R is reserved for the röntgen (bu_roentgen).

Temperature Differences

Every unit above is a scale: 25 °C is 298.15 K, and Bovnar converts it that way. A difference of 25 degrees is 25 K, and these are the units that say so.

Six rows, eight spellings. The degree Celsius interval is the kelvin (SI Brochure 9th ed. §2.3.1) and the Rankine degree is the Fahrenheit degree, so Δ°C and Δ°Ra are aliases rather than units of their own — two units that had to compare equal and convert by exactly 1 would be a distinction with no content.

They are ratio scales. .affine = false, .offset = 0.0. That is what lets them compose where the scales cannot: Δ°F/k~m is a lapse rate and Δ°Re^-1 an expansion coefficient, while °F/k~m and °Re^-1 have no SI meaning at all (§9.4 — an affine scale is meaningful only alone at exponent 1).

They carry their own quantity kind, so:

ΔK   → K       error_unit_mismatch      the whole point
°C   → Δ°C     error_unit_mismatch      a reading is not an interval, and only
                                        the author can decide which one it was
Δ°C  → ΔK      factor 1                 the same unit
Δ°F  → ΔK      factor 5/9               exact; lossless only for multiples of 9
Δ°De → ΔK      factor −2/3              Delisle runs backwards
--si on 25 Δ°C                          25 ΔK, not 298.15 K
[<float:64,K> 1.0, <float:64,ΔK> 2.0]   error_array_element_type_mismatch

A bare array is homogeneous in its unit (spec §7.4), so the last line needs no rule of its own.

Inside a compound the distinction does not arise, and is not made. W/(m²·ΔK) and W/(m²·K) are the same unit, as are ΔK/k~m and K/k~m, and ΔK^-1 and K^-1. The reason is the one above: an affine scale cannot appear in a compound at all, so a K there was already an interval and there is nothing to separate. The quantity kind is therefore significant only for a lone unit at exponent 1 — precisely where the affine offset was the hazard. Every U-value written before these units existed keeps its meaning.

Δ is U+0394 (0xCE 0x94); every unit has ASCII spellings, formed as delta_ plus the scale's own short form. There is deliberately no bare delta_C or delta_F: those read as a delta coulomb and a delta farad, and the scales themselves do not alias bare C or F either. delta_K is unambiguous because K is the kelvin and nothing else.

3.5 Pressure Units

mH2O takes prefixes, so the spellings people actually write fall out of it: c~mH2O (or the compact cmH2O) is the centimetre of water a ventilator is set in, and m~mH2O the millimetre. The value is the conventional column — water at 1000 kg/m³ under standard gravity — the same kind of convention that fixes mmHg at exactly 133.322387415 Pa. A column measured at a stated temperature (UDUNITS' water_4C, QUDT's IN_H2O) is a different unit and is refused, not rounded onto this one.

3.6 Energy Units

Two calories and two BTUs, and the pairs cross over. cal is the THERMOCHEMICAL calorie and Btu the INTERNATIONAL TABLE BTU, which is not an inconsistency but the two vocabularies' own defaults: UCUM's unqualified cal is thermochemical and its unqualified [Btu] is too, while UDUNITS' unqualified calorie is the IT one. Each pair is 0.067 % apart — dimensionally identical and numerically wrong if confused — so both members of both pairs are carried and every profile code lands on the one its own vocabulary says it means. Both BTUs are one pound of water raised one degree Fahrenheit, i.e. the corresponding calorie × 453.59237 g/lb × 5/9; that terminates for the IT calorie and does not for the thermochemical one, which is why Btu_th states an exact rational rather than a decimal.

BTU alias note: BTU (all uppercase, three characters) is a valid alias for bu_btu. Because currencies require the $ sigil, the bare token BTU is a physical-unit lookup and resolves to bu_btu; Btu and btu are also accepted. See §10.2 for the complete look-alike table.

3.7 Power Units

3.8 Force Units

3.9 Speed and Rotational Frequency Units

kn has dimension m·s⁻¹. rpm has dimension s⁻¹ (rotational frequency, not linear speed); it is grouped here by convention.

3.10 Volume Units

US Liquid Volume

cup disambiguation: The canonical symbol for the US cup volume unit is cup (all lowercase). The Cuban Peso (ISO 4217 code 192) is written with the mandatory currency sigil as $CUP; the bare uppercase token CUP is error_unit_illegal. The two cannot be confused. See §10.3 for full details.

UK Imperial Volume

3.11 Area Units

3.12 Angle Units

Angle is one shared quantity kind, so ° → rad works and only the factor is irrational. What the kind stops is an angle drifting into a plain count: rev/min is an angular rate and rpm a cycle rate, and they differ by exactly 2π. sr carries the kind at weight 2, because a steradian is rad² — and so do the photometric units built on it (lm = cd·sr, lx = lm/m², ph = lm/cm²; see the note under §3.2).

3.13 CGS Units

sb and ph are not the same quantity, though the SI dimension vector says they are: both reduce to cd·m⁻² and both are 10⁴ of their SI counterpart. The stilb is a luminance (cd/cm²), the phot an illuminance (lm/cm²), and a lumen is a candela-steradian. Bovnar carries that steradian as a quantity kind, so ph converts with lx and sb with cd/m², and neither converts with the other — see §3.12 and the note under §3.2.

3.14 Radiation Units

3.15 Logarithmic Units

Neper and decibel do not convert into each other. bvn_units_compatible reports false for the pair, and every conversion entry point refuses it.

A logarithmic level is not a linear quantity: 20 dB is a ratio of 100, not twice the ratio 10 dB names. Relating two logarithmic scales is a change of base, which the multiply-by-a-factor model every conversion entry point is built on cannot express — so bovnar gives Np, dB and pH a quantity kind each and refuses every pair, rather than applying a factor that is only ever right by coincidence.

ISO 80000-3 does state 1 Np = 8.685889… dB, for a level referred consistently to the same kind of quantity. Two things stop that from being a conversion this library can perform. It is a relation between levels, so it does not compose with the exponents and prefixes a value_unit_t carries; and dB is written in practice against both the power convention (10·log₁₀) and the field convention (20·log₁₀), with nothing in the annotation recording which — so the number a reader would need is not determined by the unit alone.

The same reasoning keeps a level out of a plain number: dB → dimensionless is refused too.

3.16 Electrical Power Units

Watt, var, and VA: All three carry the same SI dimensional signature (kg·m²·s⁻³). bvn_units_compatible returns true when comparing them. They are kept as distinct base units because they represent distinct AC power interpretations.

3.17 Digital Units

Bit and byte do not convert into each other. They are separate quantity kinds, so b → B is refused rather than divided by eight. A byte is eight bits on the wire, but a value annotated in bytes and one annotated in bits are usually not the same measurement — a link rate quoted in M~b/s and a file size in M~B — and silently trading one for the other is the class of error this format exists to prevent. Convert explicitly in the application if that is genuinely what you mean.

Prefixes still work within each: Ki~B → B is 1024, M~b → k~b is 1000. Both units take IEC binary prefixes as well as SI ones, and SI prefixes on them are restricted to kilo and above (§6.3).

3.18 Textile Linear Density

3.19 US Apothecary / Dry Volume

minim (not min, which is the minute) avoids ambiguity.

3.20 Old German Units

Old German units fall into metric-compatible units (still in use in DACH regions) and historical pre-metric Prussian units. The prefix pr is reserved for Prussian symbols. No German unit accepts any non-trivial SI or IEC prefix; bvn_prefix_unit_valid rejects any non-si_none/iec_none prefix for every unit from bu_pfund through bu_scheffel.

Metric-Compatible German Units — Mass

Historical German Units — Length (Prussian)

Historical German Units — Area (Prussian)

Historical German Units — Volume (Prussian)

Every Prussian unit here reproduces its historical definition from the 1816 Fuß (0.313853 m): Zoll = Fuß/12, Linie = Zoll/12, Rute = 12 Fuß, Klafter = 6 Fuß, Elle = 25½ Zoll, Morgen = 180 square Ruten. test_unit_factors_derived.py checks each of them against that definition.

The German units carry ids 100133–100145, inside the native unit block like every other physical unit — see §12.1 for the block layout. They used to sit at 348–360, appended past the whole currency range, because the id space was one flat counter and the currencies had been dropped into the middle of it. The space is blocked now, so a unit's id no longer says anything about when it was added.

3.21 Additional Length Units

ftUS (US survey foot) differs from ft (international foot, 0.3048 m exactly) by about 2 ppm. Used in US geodetic surveying.

3.22 Additional Mass Units

3.23 Acceleration

3.24 Signal Rate

3.25 Ratio and Proportion Units

Dimensionless scaling factors. A value carrying one of these units reduces to the numeric value multiplied by the factor in the canonical (dimensionless) base representation — e.g. 5 % ≡ 0.05, 250 ppm ≡ 0.00025. Like the other dimensionless ratios they carry an empty dimension vector, but unlike rad/sr they do not accept SI or IEC prefixes (a prefixed % is meaningless).

Why pptr and not ppt. Two independent reasons, and either alone would settle it. ppt already resolved — as the compact form of p~pt, the picopint — so claiming it as an alias would have taken a spelling away from the unit that held it, which §4.3's guarantee forbids and gen_units.py refuses at build time. And ppt is ambiguous in the field: parts per thousand in some industries, parts per trillion in atmospheric chemistry, a factor of 10⁹ apart. UCUM splits the same ambiguity the same way — [ppth] for per thousand, [pptr] for per trillion — so the symbol here is borrowed rather than invented. The compact token ppt is refused outright (§4.3); write pptr, ‰, or p~pt if the picopint really is what you meant.

pptv and ppqv, the "by volume" spellings, are accepted as aliases because UDUNITS-2 defines them as the same 10⁻¹² and 10⁻¹⁵. Both profiles that name these units — UCUM's [pptr] and UDUNITS' ppt/pptv/ppq/ppqv — were refused for want of a native target until these rows existed.

3.26 Named Speed Units

Speeds people write as one token. mi/h and k~m/h express the same quantities as compounds and remain valid; these are separate base units, not shorthands the parser expands, so an annotation of mph does not reconcile with an inline mi/h (the comparison is structural — see §2.2). Neither accepts a prefix: they already carry one, or have no meaningful prefixed form. kn (the knot, §3.9) belongs to the same family.

3.27 Acidity

The pH scale: dimensionless by construction, being a negative decimal logarithm of hydrogen-ion activity. It carries a factor of 1 and accepts no prefix — a milli-pH is not a quantity. It is modelled for the same reason dB and Np are: a logarithmic scale is still a statement about what the number means, and 7.2 alone is not.

Because the scale is logarithmic, the value is a label, not something to sum or average — the same caveat that applies to dB and Np.

pH vs p~H: the two differ by one character and by seven orders of dimension. pH is the acidity scale; p~H is the picohenry. Case matters too: ph is the phot (§3.13). This is exactly why acidity had to become a unit — without it, pH resolves as a compact prefixed henry.

3.28 Water Hardness

Six scales for one physical quantity: the concentration of dissolved alkaline-earth ions (Ca²⁺, Mg²⁺). Each is defined as a mass of a reference compound per litre, but the scales use different compounds — °dH counts CaO, most of the others CaCO₃, °rH counts Ca — so mass concentration is not their common ground. Amount concentration is: every scale carries mol·m⁻³ (which is exactly mmol·L⁻¹), converts into every other, and into m~mol/L.

None of them takes a prefix. Millimoles per litre needs no unit of its own — it is the compound m~mol/L (or mmol/L).

Reading across, with 1 mmol·L⁻¹ as the reference:

gpg is a unit, gr/gal is a compound, and they are not the same thing. gpg is an amount concentration and converts with the other hardness scales; gr/gal (grain per US gallon) is a mass concentration and deliberately does not. Both spellings stay valid.

val is the equivalent as water analysis uses it. The ions counted are divalent, so one equivalent is half a mole and m~val/L = 0.5 mmol/L, which is what the hardness tables state. An equivalent of a monovalent species is one mole — Bovnar cannot know the species from the unit, so for that case write the amount directly (m~mol/L). There is deliberately no generic eq / equivalent alias.

Exactness. Every degree is derived from a molar mass (IUPAC 2021: Ca 40.078, C 12.011, O 15.999 g·mol⁻¹), so the factors are measurement-derived rather than exact rationals. They carry .exact = false, which means a read-time lossless conversion (want_unit, §1.10 of the read/write API) refuses them with error_unit_inexact (47) rather than inventing precision — the same answer it gives for a π-based angle. bvn_unit_convert_value and bvn_unit_to_si_factor, which work in double precision, convert normally.

mval/L and meq/L are one unit. eq is an accepted spelling of val, so the German and English conventions both work and both carry the divalent caveat above.

dH is not °dH. Without the degree sign the token is the decihenry, and it stays that way. Likewise water chemistry writes the American scale as "ppm"; Bovnar's ppm is the dimensionless 10⁻⁶ and is not interchangeable with °aH. See 07_bovnar_unit_ambiguities.md.

3.29 Conductivity and Dissolved Solids

Two quantities that water data quotes constantly and that need no unit of their own — the existing tables already say them exactly.

One quantity does get a unit of its own, because the hydroponic scale is a rescaling nothing else in the table expresses:

CF carries the dimensions of conductivity, so unlike the turbidity scales below it does convert: 1 CF = 0.1 mS/cm = 100 µS/cm, exactly, and into S/m and dS/m with it. Only the uppercase spelling is the conductivity factor — cF is the centifarad.

"ppm" for TDS. Water data writes TDS in "ppm", meaning milligrams per litre. Bovnar's ppm is the dimensionless 10⁻⁶ — for a dilute aqueous solution at 1 kg/L the two are numerically the same, so writing ppm is defensible here in a way it is not for hardness (§3.28), but the dimensions differ: ppm is a ratio, mg/L is a concentration, and they do not convert into one another. Pick the one you mean.

TDS meter scales. A conductivity meter reading "TDS ppm" applies a conversion factor to EC (the 500/442/700 scales). That factor is a property of the instrument and the water, not of a unit — record the EC in µS/cm and the factor separately, or record the TDS as mg/L.

3.30 Turbidity and Salinity

Six scales defined by a measurement method rather than by a physical quantity. They are dimensionless, and each carries its own quantity kind, so none of them converts to another or to a plain number — the conversion a factor cannot express is refused instead of guessed.

None of the five turbidity scales converts to any other:

One kind per method, and that is the whole content of the table. The formazin-calibrated scales (NTU, FNU, FTU) are numerically equal on a formazin standard — which is exactly the trap. On real water white light and near-infrared respond differently to particle size and colour, so the number alone does not say what was measured; FTU says even less, since its geometry is unstated by definition. FAU is not the same optical quantity at all: it measures how much light the sample removes from the beam, not how much it scatters sideways, and it is the instrument of choice above ~40 FNU where nephelometry saturates. JTU is the visual candle method, whose published equivalence to formazin ("1 JTU ≈ 1 NTU") holds near 40 units and nowhere else, being nonlinear and sample-dependent. Bovnar refuses every one of these conversions rather than implying a factor exists — report the method.

NTU, FNU, FTU and FAU accept prefixes (m~NTU is real in ultrapure-water work). JTU does not: the candle method cannot resolve below roughly 25 JTU, so a milli-JTU is not a measurement.

Watch the case. fau is the femto-astronomical-unit, cF the centifarad — the turbidity and conductivity scales are uppercase only. See 07_bovnar_unit_ambiguities.md.

PSU is not per-mille. Practical salinity is a conductivity ratio, so it is dimensionless by construction and PSU is a label rather than a unit — SI-minded texts write S_P = 35 with no unit at all. It is not a mass fraction: S_P 35 corresponds to about 35.165 g/kg absolute salinity, so equating it with ‰ or g/kg is wrong by roughly half a percent. For absolute salinity write the mass fraction directly: g/k~g. The scale is bounded by construction, so it takes no prefix.

3.31 Sentinel Value

bu_none (value 0) is the internal representation of "no base unit", used for the no_unit keyword and as the default when no unit annotation is present.

3.32 Units the Unit Profiles Needed

Every unit in this section was, until it was added, the sole reason a run of UCUM, UDUNITS-2, QUDT, OM or UN/ECE codes had to be refused as error_unit_profile_unsupported: the publisher defines the unit, the value is exactly stateable, and there was no native unit to translate onto. None of them is new physics. All are exact — the ones whose value is not a terminating decimal in SI state a rational in units.bvnr rather than the repr of a double.

US survey lengths

bu_survey_foot (§3.21) has been in the registry all along and nothing was built on it, so every survey length above the foot had to be refused. Each below is an exact rational multiple of the survey foot's 1200/3937 m.

The survey foot is 2 ppm longer than the international foot, and the survey acre 4 ppm larger than the international acre — an area being a length squared. Small enough to ignore and never small enough to be right: on a section of land the acre difference is about ten square metres. The survey foot was withdrawn for new work at the end of 2022, which is a reason to read it carefully rather than to refuse it, since US land records, state-plane coordinates and a century of engineering drawings are written in it.

Typographic lengths

The symbols are deliberately not pt and ln. pt is the pint and has been since before these existed; a length answering to it would change what an existing spelling means, which §10 forbids and which gen_units.py now refuses at build time. UCUM's own bracketed spellings [pnt], [pca] and [lne] name them unambiguously, so the symbols follow those. The printer's point (0.013837 in) is a different unit and has a row of its own, pnt_pr, at the end of §3.32.

US dry volumes, and the trade measures built on feet

A dry quart is 16 per cent larger than the liquid quart qt. The peck (pk) and bushel (bsh) in §3.19 have always been the dry ones; the gallon, quart and pint were only the liquid ones, so a document that meant dry had no way to say so.

ac_ft is the acre-foot on the survey acre and foot, which is what UDUNITS, OM and every US water agency mean by it. The international acre-foot is ac·ft = 1233.48183754752 m³ — 5.8 ppm away, and a different unit rather than a rounding.

Permeability, energy, power, ozone and one very short time

darcy takes prefixes, so the millidarcy every reservoir report is written in is m~darcy (or compactly mdarcy). thm_ec is the therm European gas billing uses; native thm is the US therm, 0.24 per cent away, and no SI prefix reaches 10⁵ — which is why it needed a unit of its own rather than a prefixed Btu. shake exists for the same reason at the other end: there is no SI prefix at 10⁻⁸.

Nine more, from two and three vocabularies at once

Each was refused across UCUM, UDUNITS-2, QUDT and OM for one reason only — no native unit of the magnitude. One publisher naming a unit is a request; two or three naming it independently at the same value is evidence, and every factor below is one all of its publishers agree on to the last digit they state.

Each is a near neighbour of a unit already here, which is why it needed its own row rather than an alias. pnt is the DTP point (¹⁄₇₂ in) and pnt_pr the printer's point (0.013837 in), 0.37 % apart; hp is the mechanical horsepower, PS the metric one and hp_E the electric 746 W, while hp_B is thirteen times any of them; bsh is the US dry bushel and bsh_uk the imperial one, 3.2 % larger. Mapping any of these onto its neighbour is the error doc/11 §6.3 warns about — dimensionally perfect, inside anything a later check would notice, and wrong.

abV needed a unit rather than a prefix because there is no decade prefix at 10⁻⁸ and prefixes do not stack. AT and debye are stated as exact rationals: the assay ton is 175/6 g, chosen so that milligrams recovered from one assay ton read as troy ounces per short ton, and the debye has been exactly 10⁻²¹/c C·m since the 2019 SI fixed c. Their publishers state 7- and 6-digit roundings of those; the rational is what they are rounding.

And the thirty-five the same sweep found next

Grouping every profile refusal by (dimension, value) turned up 35 groups two or more vocabularies define. The nine above were the first pass; these are the rest that name a real unit. What is left out is a constant rather than a unit (UCUM's [pi]), a value only one publisher states, or a dimensionless "relative permeability" that is a number.

Where the publishers disagree, the exact definition decides. The CGS-ESU units are built on c, which the 2019 SI fixed, so every one is an exact rational and the publishers' five- to seven-digit decimals are roundings of it — which is why statΩ is 22468879468420441/25000 here and 898 755 400 000, 898 755 200 000 and 898 760 000 000 in UDUNITS, OM and QUDT. The sidereal hour, minute and second are derived from the sidereal day rather than taken from the three slightly inconsistent decimals the publishers state for them, so the four stay consistent with each other. The π-based rows carry .exact = false, as the oersted and the parsec do: a value that is not a rational cannot be converted losslessly, and saying so is what that flag is for.

yr is still the Julian year and mo still a twelfth of it. Naming the others does not make the short spellings ambiguous — it gives the other calendars somewhere to go, which is what lets a UDUNITS or CF document that says year be read at all. It was refused outright before.

Calendar and sidereal time

CGS electrostatic (ESU)

Luminance

Water-vapour permeance

Heat conventions

And the singles

4. Prefixes

A prefix is attached to a base unit symbol either with the ~ separator — prefix~baseunit, the canonical form — or compactly, without it: kg is k~g, MiB is Mi~B. Both spellings parse to the same value_unit_t; the writer always emits the separated form, so a document that round-trips through the library comes back canonical. See §4.3 for what the compact form does and does not accept.

4.1 SI Prefixes

All 24 current SI prefixes are supported, from quecto (10⁻³⁰) to quetta (10³⁰).

Encoding note: µ is U+00B5 (MICRO SIGN), UTF-8: 0xC2 0xB5. U+03BC (GREEK SMALL LETTER MU) is a distinct code point but is also accepted on input; the canonical output form is always U+00B5. ASCII u is accepted as an input-only alias for µ (e.g. u~m parses as µ~m); the canonical output form is always µ. Note u is also the bare symbol for the dalton, but the two never collide: the base unit is whatever the longest alias suffix says, so u is the dalton and the u in um or u~m is the prefix.

Prefix–Symbol Ambiguities

Several prefix symbols overlap with base unit symbols. A base unit symbol is matched as the longest alias suffix of the component, so a bare unit always wins over a prefixed reading of the same token: min is the minute, never milli-inch, and cd is the candela, never centi-day. Where that is not the reading you want, the ~ separator states it: m~in is milli-inch, m~ introduces the milli prefix, bare m is the meter.

d~s = decisecond; d alone = day.

4.2 IEC Binary Prefixes

IEC 80000-13 binary prefixes are used for digital quantities (b and B only). The table below also lists Ri and Qi; the standard stops at Yi (2⁸⁰) and those two are an unratified extension.

Prefix–Unit Validity Constraints

• IEC prefixes (Ki…Qi) are only permitted on b and B. Ki~m → error_unit_illegal.
• SI sub-kilo prefixes (d, c, m, µ, n, p, f, a, z, y, r, q, da, h) are forbidden on b and B.
• German units (bu_pfund through bu_scheffel) accept only si_none/iec_none.
• Ratio units (%, ‰, ‱, pcm, ppm, ppb, pptr, ppq) likewise: a prefixed per-cent is meaningless. k~% → error_unit_illegal (§3.25).
• Scales that are already a scale — pH, mph, kph, the five water-hardness degrees, gpg, CF, PSU, JTU — take no prefix either. Each carries its reason in §3.26–§3.30; NTU, FNU, FTU and FAU do take one, because a milli-NTU is a real ultrapure-water measurement.
• Currency units accept SI prefixes of any magnitude (see §9.4). IEC prefixes are forbidden on all currency codes.

.valid1   = <uint:64,Ki~B>  8;     # OK: IEC prefix on byte
.valid2   = <uint:32,M~b>   100;   # OK: SI mega on bit
.valid3   = <float_dec:64,k~$USD> 250.0;  # OK: kilo on currency
.invalid1 = <uint:64,Ki~m>  1;     # ERROR: IEC prefix on meter
.invalid2 = <uint:32,m~B>   512;   # ERROR: SI milli on byte
.invalid3 = <float_dec:64,Ki~$USD> 1;     # ERROR: IEC prefix on currency

4.3 Compact Prefix Form

A prefixed physical unit may be written without the ~ separator, in the spelling the rest of the world already uses:

.mass      = <float:64,kg>   72.5;      # same unit as k~g
.distance  = <float:64,km>    1.5;      # k~m
.period    = <float:64,ms>   16.7;      # m~s
.frequency = <float:64,MHz> 2400.0;     # M~Hz
.pressure  = <float:64,hPa> 1013.25;    # h~Pa
.energy    = <float:64,MeV>   13.6;     # M~eV
.amount    = <float:64,mmol>   2.5;     # m~mol
.memory    = <uint:64,MiB>   512;       # Mi~B
.force     = <float:64,kg·m/s²> 9.81;   # compounds, exponents and groups too

Both spellings produce the same value_unit_t, so they reconcile against each other (<float:64,k~m> 1.5 km is valid) and against a stored annotation. The canonical output form is unchanged: bvn_unit_to_string emits k~g for either spelling, so a compact unit is an input convenience that never propagates into what the library writes.

The rules are exactly the rules of the separated form, with one addition:

• A bare unit alias always wins. The base symbol is the longest alias suffix, so min is the minute (not milli-inch), cd the candela (not centi-day), ft the foot (not femto-tonne), at the technical atmosphere (not atto-tonne), dB the decibel (not deci-byte). The separated form reaches the other reading: m~in, c~d, f~t.
• Where two prefixed readings compete, the longer base symbol wins — for the same reason. dat is deci-at (technical atmosphere), not deca-tonne; dau is deci-au, not deca-dalton. Write da~t / da~u for those.
• A prefix cannot be stacked. kkg and k~kg are both error_unit_illegal.
• Prefix–unit validity is unchanged. Kim fails for the same reason Ki~m does; so do mB, kPfd, kppm.
• A few compact spellings are refused by name. A token that is a well-known annotation for something else would otherwise become a valid — and quietly wrong — unit, which is the failure mode the format exists to prevent. These stay error_unit_illegal:

pH, mph and kph were on this list until the quantities they name became units of their own (§3.26, §3.27). A bare alias outranks any prefixed reading, so they now need no exception — and p~H, m~ph, k~ph still mean what they always did.

The last two rows are the harder cases. kt is a standard abbreviation for two units Bovnar does model — the kilotonne in climate and energy data, the knot in marine and aviation data — and reading a speed as a mass is precisely what this format exists to stop. ppt is worse: the compact rule makes it a volume, while every real use of the token is a dimensionless ratio, and the two ratios it might mean are 10⁹ apart. A token only the author can resolve is one the author has to resolve.

Note what is not done about ppt: the parts-per-trillion unit added in §3.25 does not claim the spelling. A bare alias outranks any prefixed reading (rule 2 above), so claiming it would take ppt away from p~pt and change what an existing document means — which the rule at the top of units.bvnr forbids and gen_units.py refuses at build time. The unit is spelled pptr, following UCUM's own [pptr], and the ambiguous token is refused instead.

The list lives in src/gendata/units.bvnr (.compact_exceptions) and applies to the compact spelling only — p~H is still picohenry, k~t still the kilotonne, p~pt still the picopint.

Because a compact spelling is only ever reached where the separated form would have been a parse error, no document that parsed before this existed can parse differently now.

For a token-by-token list of every spelling that could be read two ways — including case traps, look-alike characters and abbreviations that are deliberately not units — see 07_bovnar_unit_ambiguities.md.

Currencies take the compact prefix too — k$EUR is k~$EUR. The $ sigil already separates the prefix from the code (no prefix symbol and no currency code contains a $), so nothing is left for the ~ to resolve. What the sigil rule still requires is the sigil itself: kUSD is error_unit_illegal, because a bare code is never a currency (§10.4).

5. Unit Notation Grammar

5.1 Simple Units

unit-component = [ prefix [ "~" ] ] base-unit [ unit-exponent ]

The ~ separator is optional (km = k~m, k$USD = k~$USD; §4.3). The currency $ sigil is not.

.temperature = <float:64,K>      300.0;   # kelvin
.distance    = <float:64,k~m>    1.5;     # kilometer
.frequency   = <float:64,M~Hz>   2400;    # megahertz
.storage     = <uint:64,Ki~B>    1024;    # kibibytes
.altitude    = <float:64,km>     10.5;    # kilometer, compact spelling
.fund_nav    = <float_dec:64,k~$USD> 250.0; # $250,000

5.2 Compound Units

compound-unit  = "no_unit"
               | unit-component { unit-sep unit-component }

unit-sep       = "*" | "/" | "·"           (* · = U+00B7 MIDDLE DOT *)

unit-component = [ prefix [ "~" ] ] base-unit [ unit-exponent ]

unit-exponent  = [ exp-sign ] exp-digit { exp-digit }
               | "^" [ "-" | "+" ] ASCII-digit { ASCII-digit }

exp-sign       = "⁺" | "⁻"

exp-digit      = "⁰" | "¹" | "²" | "³" | "⁴" | "⁵"
               | "⁶" | "⁷" | "⁸" | "⁹"

An exponent is one or more digits in either notation — m¹⁰⁰ and m^100 are units, and this production is what §6 states in prose. ⁰ is a digit here only in a multi-digit exponent: it exists so m¹⁰⁰ can be written, and a leading m⁰ is still no unit (§6). At most three digits are scanned, so m^1000 fails as an unrecognised token rather than as an over-large exponent.

Currency codes participate in compound expressions using the same separators:

.gold_spot    = <float_dec:64,$USD/oz_t>   2351.40;  # $/troy oz
.rent         = <float_dec:64,$EUR/m²>       12.50;  # €/m²
.billing_rate = <float_dec:64,$EUR/h>       150.00;  # €/h
.eur_usd      = <float_dec:64,$USD/$EUR>      1.0842; # exchange rate

The sub-grammar is semantic, not lexical. The outer lexer captures the type-annotation body as a raw byte sequence; bvn_parse_unit parses the unit string portion after the lexer finishes.

5.3 Separators

· and * are semantically identical and may be mixed freely.

5.4 Denominator Semantics

The first / sets a latching "in-denominator" flag to true for all subsequent components. Additional / separators do not toggle back to the numerator. k~g·m/s² stores:

[0]: gram,   exp_linear,     si_kilo  ← numerator
[1]: meter,  exp_linear,     si_none  ← numerator
[2]: second, exp_neg_square, si_none  ← denominator (exponent negated)

Both k~g·m/s² and k~g·m·s⁻² parse to identical value_unit_t representations.

Parenthesised grouping

A (…) group is a sub-expression evaluated independently. Like any factor it obeys the latching denominator, so a / before a group negates the group's net component exponents as a whole. This makes the readable denominator form work and compose correctly:

.pressure = <float:64,k~g/(m·s²)> 101325;  # kg·m⁻¹·s⁻² — same as k~g/m·s²
.areal    = <float:64,(k~g/m)·s²> 1.0;     # kg·m⁻¹·s²  — grouping changes the s sign
.rate     = <float:64,m/(s·s)> 1.0;        # m·s⁻²

k~g/(m·s²) and k~g/m·s² therefore parse to the same value_unit_t (the canonical, parenless form is what the writer emits). Rules: an explicit separator is required before a group (m·(s), not m(s)); a group is not followed by its own exponent ((m·s)² is rejected — write m²·s²); parentheses must balance; empty groups (()) are rejected; nesting is bounded at 16. Unmatched or malformed groups raise error_unit_illegal.

6. Exponents

Exponents are integers in the range −100 … +100, with zero reserved: a component raised to zero is malformed, not dimensionless, so m^0 and m⁰ are not units. The bounds are BVN_EXPONENT_MIN and BVN_EXPONENT_MAX in include/bovnar.h.

The named enumerators of unit_exponent_t cover only ±1…±9 and are kept because that is what most units need and what existing source says. They are not the whole domain — any integer in the range is a valid exponent, so a switch over the type needs a default and code must not assume it can enumerate the values.

At most three digits are scanned, which is exactly what 100 needs. That is what makes an over-long exponent fail cleanly: m^1000 leaves a digit where the scan expects the ^, so no exponent is recognised at all and the whole token fails to resolve as a base symbol. A value that scans but lands outside the range — m^200 — is refused on the range check.

6.1 Unicode Superscript Form

Digits combine, most-significant first, so m¹⁰⁰ is the metre to the hundredth and s⁻¹² is a reciprocal twelfth power. Note that the glyphs are not one width — ¹ ² ³ are two UTF-8 bytes and ⁰ ⁴–⁹ are three — so ⁻¹⁰⁰ is eleven bytes, and a parser must consume one digit at a time rather than assume a stride.

⁰ is a digit only within a multi-digit exponent. A lone m⁰ is still not a unit, because zero is reserved.

6.2 ASCII Caret Form

Up to three ASCII digits are permitted after the caret — exactly what BVN_EXPONENT_MAX needs. m^1000 is not an out-of-range exponent but an unrecognised token: the scan stops after three digits, finds no ^, and the whole string fails to resolve.

6.3 Exponent Edge Cases

• exp_invalid (value 0): Zero-initialized sentinel. API functions that have an error output path reject it and signal an error. The two prefix query functions (bvn_unit_prefix_factor, bvn_unit_prefix_exponent) silently skip components with exp_invalid.
• exp_linear (value 1): Stored for both an explicit ¹/^1 and any component written without an exponent suffix.

7. The no_unit Keyword

The literal no_unit declares a value as explicitly dimensionless:

.ratio       = <float:64,no_unit> 0.95;
.count       = <uint:32,no_unit>  1000;

bvn_parse_unit detects no_unit via memcmp and returns BVN_UNIT_NONE (num_components = 0).

Omitting the unit parameter (e.g. <float:64>) yields BVN_UNIT_NO_PREFIX(bu_none) (num_components = 1, base == bu_none). Both forms are semantically equivalent — they compare as compatible via bvn_units_compatible and both serialize to "no_unit" — but they are structurally distinct internal states.

8. Constraints and Limits

a/b/c parses as a / (b·c) → components [a, b⁻¹, c⁻¹]. The "no toggle back" rule means / always adds to the denominator; it never re-enters the numerator.

An over-long unit in an annotation is error_type_too_long, not error_unit_too_long. Three 255-byte caps sit in front of the unit parser and the one that fires decides the code. The whole type-annotation body has its own cap, and it counts the family name, the width and the commas as well — so a unit parameter can never be the only thing over the line, and an annotated unit always reaches error_type_too_long first. An inline unit suffix has a buffer to itself and is the path that reaches error_unit_too_long. doc/11 §2.5 tabulates all three caps beside the profile grammar.

9. Currency Codes

Currency amounts are dimensional quantities in financial computing. $19.99 USD carries a denomination dimension just as 9.81 m/s² carries an acceleration dimension. Bovnar extends the unit system with 216 currency and cryptocurrency codes so that monetary data can be annotated and round-tripped with the same precision guarantees as physical measurements.

9.1 The $ Sigil Rule

As of spec 1.0 a currency is recognised only in its $-sigil form ($USD, $BTC, or prefixed k~$EUR / k$EUR). The sigil — and nothing else — dispatches a component to the currency table; see §10.4 for the full rules and rationale.

Classification happens at the lookup stage, per unit component:

1. A component introduced by $ (after any SI/IEC prefix and its ~) is looked up in the currency table. If the code is not found there, error_unit_illegal is raised — a $ introduces a currency and nothing else.
2. A component without a $ is looked up only in the physical unit table. A bare code such as USD or CUP is therefore never a currency; if it is not a physical unit it is error_unit_illegal.

Because the sigil is mandatory, a bare uppercase code can never collide with a physical-unit symbol — present or future — so the two namespaces are disjoint by construction. The collision cases this resolves are catalogued for reference in §10.

9.2 ISO 4217 Fiat Currencies and Precious Metals

166 ISO 4217 alphabetic codes are supported, including precious-metal X-codes. They occupy the front of block 90 of the value_base_unit_t id space (§12.1) — ids 900000 … 900165, alphabetical from AED to ZWL — and, unlike physical units, have no named bu_* enumerators: such a currency is resolved from its $-sigil code by bvn_parse_currency_str and carried as the numeric base value. The catalogue in bovnar_currency.c is index-aligned to the block, so a lookup is base - BVN_CURRENCY_FIRST.

The alphabetical order is a convenience, not a contract. Whether a currency is fiat or crypto is a column of the catalogue, read by bvn_unit_is_fiat / bvn_unit_is_crypto, not a sub-range of the ids — so a new currency of either kind appends at the end of currencies.bvnr and renumbers nothing. Before 2.0 it was a sub-range, which is why ZWG and XCG had to be stranded at 378–379 outside the currency range entirely; the block has 10 000 ids and they are ordinary rows now.

Four codes are historical and retained for compatibility: HRK (Croatian Kuna, retired 2023-01-01 when Croatia adopted the Euro), SLL (Sierra Leonean Leone (old), replaced by SLE in 2022), ZWL (Zimbabwean Dollar, superseded by ZWG Zimbabwe Gold in 2024), and BGN (Bulgarian Lev, retired 2026-01-01 when Bulgaria adopted the Euro); ANG (Netherlands Antillean Guilder) likewise coexists with its successor XCG (Caribbean Guilder, which inherits ANG's numeric code 532).

The minor_unit field carries the exponent N such that 1 major unit = 10^N minor units (e.g. 1 USD = 100 cents, N=2). Applications reading integer-annotated values (e.g. <uint:64,$KWD>) should call bvn_currency_minor_unit to determine the correct decimal shift. Minor units are bold below when they differ from 2. Num is the ISO 4217 numeric identifier.

CLF (Unidad de Fomento) is the only currency with 4 minor units in this catalogue. ISO 4217 also defines UYW with 4, but the catalogue omits the fund and bond codes (BOV CHE CHW COU MXV USN UYI UYW, XBA–XBD, XSU, XUA) and the no-currency code XXX: they denote accounting units and placeholders rather than money a value can be denominated in. The four historical codes HRK, SLL, ZWL, and BGN are retained for compatibility but should not be used for new data.

9.3 Cryptocurrencies

50 cryptocurrencies are supported, with 3- or 4-letter uppercase tickers. They occupy ids 900166 … 900215, after the fiat codes in the same block 90, and like them have no named bu_* enumerators — they are resolved by bvn_parse_currency_str and carried as the numeric base value. That they happen to follow the fiat run carries no meaning: bvn_unit_is_crypto reads the catalogue row, not the id (§9.2). The minor_unit field holds the canonical on-chain decimal places. numeric_code = 0 for all cryptocurrencies.

Min = minor_unit = on-chain decimal places. E.g. <uint:64,$BTC> stores satoshis; divide by 10⁸ to obtain whole BTC.

9.4 Prefix Rules for Currency Units

All SI prefixes are permitted on all currency units. k~$USD denotes "values in thousands of USD" — a common scale annotation in financial reporting. As with a physical unit (§4.3), the ~ is optional: k$USD is the same unit, because the $ sigil already separates the prefix from the code.

.fund_nav   = <float_dec:64,k~$USD>    250.0;   # $250,000
.gdp        = <float_dec:64,M$EUR>  42800.0;    # €42.8 billion — compact prefix
.eth_gwei   = <float_dec:64,G~$ETH>    35.0;    # 35 Gwei gas price

The sigil itself is not optional in either spelling: kUSD is error_unit_illegal, exactly as bare USD is.

IEC binary prefixes (Ki~, Mi~, …) are forbidden on all currency units, compact spelling included (Ki$USD is an error too). bvn_currency_prefix_valid() returns false for any IEC prefix; the parser raises error_unit_illegal.

9.5 Compound Currency Expressions

Currency codes participate in compound unit expressions using the existing separators:

.gold_spot    = <float_dec:64,$USD/oz_t>    2351.40;  # $/troy oz
.wheat        = <float_dec:64,$USD/bsh>        5.82;  # $/bushel
.rent         = <float_dec:64,$EUR/m²>        12.50;  # €/m²
.billing_rate = <float_dec:64,$EUR/h>         150.00; # €/h
.eur_usd      = <float_dec:64,$USD/$EUR>        1.0842; # exchange rate
.eth_btc      = <float_dec:64,$BTC/$ETH>       0.05610; # cross-crypto rate

Currency × currency compounds (USD·EUR) are syntactically valid and produce no error. Their financial interpretation is the application's responsibility.

Exchange Rate Timestamps

Bovnar annotates denomination; it does not store exchange rates or timestamps. The timestamp belongs in a separate field:

.snapshot = {
    .epoch    = <uint:64,s>              1716400000;
    .eur_usd  = <float_dec:64,$USD/$EUR>        1.0842;
};

9.6 Compatibility Rules

bvn_units_compatible() returns false for every unit containing a currency — including a currency against itself. It is dimension-based, and a currency deliberately has no SI conversion row, so bvn_unit_dimension_vector fails and the compatibility test fails with it. bvn_units_compatible($USD, $USD) is false.

Do not use it as the gate before converting money: it refuses the identity. Use the conversion functions directly — bvn_unit_convert_factor, bvn_unit_convert_value, bvn_unit_convert_rational — which carry their own currency path and report success or failure themselves.

What that path accepts is the same currency expression, differing at most in prefixes:

The mechanism is bvn_unit_prefix_only_delta in bovnar_si_units.c, consulted only after bvn_units_compatible has said no — so a unit that does have an SI row keeps taking the ordinary, fully general path.

9.7 Type Pairing Recommendations

float (binary floating-point) is discouraged for monetary amounts. Binary fractions cannot represent 0.10 USD exactly. Use float_dec for decimal-exact storage.

float_fix is wrong for monetary values. Q-format stores values as integer × 2^(-N) — a binary fractional resolution. No power of 2 equals a power of 10 (except 2⁰ = 10⁰ = 1), so no Q value exactly represents cents.

10. Symbol Disambiguation

This section documents how a physical-unit token and a currency token are kept apart. The mandatory $ currency sigil (§10.4) is the normative rule and resolves every potential collision; the look-alike tables that follow are retained for reference.

10.1 The Namespace Rule as Disambiguator

The mandatory $ sigil (§9.1, normative rule in §10.4) makes the two namespaces disjoint by construction: the sigil — and nothing else — selects the currency table, so a bare token is always a physical-unit lookup and can never be mistaken for a currency.

Because the lookup is sigil-driven rather than spelling-driven, case is no longer load-bearing for disambiguation: cup and CUP are both physical-unit lookups (the first matches bu_cup, the second is error_unit_illegal), and the Cuban Peso is written $CUP.

10.2 Exhaustive Conflict Table

Before the sigil, several uppercase tokens looked like they could be either a physical unit or a currency. The sigil removes the ambiguity outright; the table below is retained as a reference for the codes that previously needed disambiguation. In every row, the bare form is a physical-unit lookup and the currency is only ever the $-prefixed form.

Key finding: with the sigil, no token is simultaneously a valid bare physical-unit symbol and a valid currency — currencies live entirely under $, physical units entirely without it.

10.3 The CUP Case in Detail

CUP is the classic example because the ISO 4217 code for the Cuban Peso shares its letters with the English word for the culinary measure. Under the sigil rule the two are unambiguous:

.recipe_volume = <float_dec:32,cup>  2.0;    # 2 US cups (volume)
.balance       = <float_dec:64,$CUP> 15.00;  # 15 Cuban Pesos (currency)
# .bad         = <float_dec:64,CUP>  15.00;  # error_unit_illegal: bare 'CUP' is not a unit

Calling bvn_unit_to_si_factor on a $CUP unit returns *ok = false because bvn_find_si_conv skips currency enum values. Calling bvn_unit_is_currency on a cup unit returns false. The two are completely disjoint in both parsing and the conversion API — and, because the peso must be written $CUP, a user who writes the bare CUP intending the culinary cup gets an immediate error_unit_illegal (the correct spelling is lowercase cup) rather than a silently-accepted currency.

10.4 The Mandatory Currency Sigil

A currency code carries a mandatory $ sigil as of spec 1.0. This is the resolution of the CUP (Cuban Peso) vs cup (the physical cup) namespace collision: a currency is only recognised in its sigil form, so a bare code can never collide with a physical-unit symbol — present or future.

# Currencies — the '$' sigil is required:
.price   = <float_dec:64,$USD>      19.99;   # US Dollar
.btc     = <uint:64,$BTC>        54782000;   # Bitcoin (satoshis)
.fund    = <float_dec:64,k~$EUR>   250.0;    # kilo-Euro (prefix before the sigil)
.aum     = <float_dec:64,M$EUR>    42.8;     # mega-Euro, compact prefix (= M~$EUR)
.spot    = <float_dec:64,$USD/oz_t> 2351.40; # currency / physical-unit compound

# A bare code is no longer a currency:
.volume  = <float_dec:32,cup>        2.0;    # the physical 'cup', unambiguously
# .bad   = <float_dec:64,USD> 1.0;            # error_unit_illegal: bare 'USD' is not a unit (needs '$')

The sigil attaches directly before the currency code, after any SI/IEC prefix and its optional ~ (k~$EUR or k$EUR, M~$USDT or M$USDT; §4.3). It is accepted in inline units and type annotations alike, and the writer emits it on output so values round-trip. Because this breaks any document that used bare currency codes, it was made before the 1.0 freeze — afterwards it would be an incompatible change (see the Versioning & Stability section of the specification).

11. C Data Model

11.1 Enumerations

prefix_system_t

typedef enum prefix_system_e {
    prefix_si,      /* SI decimal prefixes (or no prefix) */
    prefix_iec      /* IEC binary prefixes                */
} prefix_system_t;

si_prefix_id_t

typedef enum si_prefix_id_e {
    si_none = 0,
    si_quecto, si_ronto, si_yocto, si_zepto, si_atto,
    si_femto,  si_pico,  si_nano,  si_micro, si_milli,
    si_centi,  si_deci,
    si_deca,   si_hecto, si_kilo,  si_mega,  si_giga,
    si_tera,   si_peta,  si_exa,   si_zetta, si_yotta,
    si_ronna,  si_quetta
} si_prefix_id_t;

iec_prefix_id_t

typedef enum iec_prefix_id_e {
    iec_none = 0,
    iec_kibi, iec_mebi, iec_gibi, iec_tebi, iec_pebi,
    iec_exbi, iec_zebi, iec_yobi, iec_robi, iec_quebi
} iec_prefix_id_t;

value_base_unit_t

A base unit's id is blocked, not a running counter: the leading two decimal digits name the vocabulary it comes from and the four digits after them its position within that vocabulary. Each block therefore holds 10 000 ids, and a vocabulary that grows shifts nothing outside itself.

bu_none is 0 and belongs to no block; every tag between the native units and the currencies is now taken, so a further vocabulary needs one outside 10–90. Blocks 40–80 currently contribute no ids at all: those vocabularies map every code onto a native unit, and the block tag reserves their room rather than filling it. Within block 10 the native units run contiguously from bu_bit = 100000 to bu_stattesla = 100263, in the order of units.bvnr; BVN_UNIT_NATIVE_FIRST, BVN_UNIT_NATIVE_LAST and BVN_UNIT_NATIVE_COUNT are generated beside the enum, so read the bounds from those rather than from this sentence. Currencies run contiguously from 900000 and — unlike every other block — have no named bu_* enumerators (see §9.2/§9.3): a currency is written by its ISO 4217 code behind a $ sigil, resolved by bvn_parse_currency_str and carried as the numeric base value. bvn_unit_is_currency(base) is a bounds check over block 90.

Only a vocabulary that contributes units of its own takes a block. A unit profile is a spelling for the unit slot, so most of its codes translate to native units and carry native ids; the ones that get a block id of their own are the opaque units — codes with no native equivalent and no dimension, such as UCUM's assay-defined [IU] or UN/ECE's package types — which need an identity precisely because nothing else can stand in for them.

Why blocks. One flat counter makes every vocabulary's ids a function of every other vocabulary's size, and that was not hypothetical. This space previously had physical units at 1–133 and again at 348–396 because the currencies had been dropped in between; two currencies stranded at 378–379, outside their own range, because that range had been frozen; and the profiles' units pinned above all of it. Adding a currency shifted units. The 2.0 renumbering ended that, and made an id self-describing: 200017 is UCUM's, whatever else the build contains.

The price is a sparse space, so do not index an array by a base unit id. The library's own tables are dense, one row per defined unit, indexed by bvni_unit_slot(); BVN_UNIT_SLOT_COUNT is that row count. A bounds check is no longer a membership test either — ask bvn_unit_valid on the unit, or bvn_unit_is_currency on the base.

typedef enum value_base_unit_e {
    bu_none = 0,            /* dimensionless / no unit; in no block */

    /* Digital — block 10 opens here */
    bu_bit = 100000, bu_byte,

    /* SI base */
    bu_second, bu_meter, bu_gram, bu_ampere, bu_kelvin,
    bu_mol, bu_candela,

    /* Named SI-derived */
    bu_hertz, bu_newton, bu_pascal, bu_joule, bu_watt,
    bu_volt,  bu_ohm,   bu_farad,  bu_coulomb, bu_siemens,
    bu_weber, bu_tesla, bu_henry,  bu_lumen,   bu_lux,
    bu_becquerel, bu_gray, bu_sievert, bu_katal,
    bu_liter, bu_minute, bu_hour, bu_day, bu_degree, bu_celsius,
    bu_radian, bu_steradian,
    bu_tonne, bu_bar,
    bu_electronvolt, bu_dalton, bu_astronomical_unit,
    bu_hectare, bu_week, bu_year,

    /* Imperial/US — length */
    bu_inch, bu_foot, bu_yard, bu_mile, bu_nautical_mile,
    bu_angstrom, bu_light_year, bu_parsec, bu_furlong, bu_fathom,

    /* Imperial/US — mass */
    bu_pound, bu_ounce, bu_grain, bu_stone, bu_short_ton,
    bu_long_ton, bu_troy_ounce, bu_carat,

    /* Temperature */
    bu_fahrenheit,

    /* Pressure */
    bu_atmosphere, bu_mmhg, bu_torr, bu_psi,

    /* Energy */
    bu_calorie, bu_btu, bu_erg, bu_therm,

    /* Power */
    bu_horsepower,

    /* Force */
    bu_pound_force, bu_dyne, bu_kip,

    /* Speed */
    bu_knot,

    /* Volume — US */
    bu_gallon, bu_gallon_uk, bu_quart, bu_pint, bu_cup,
    bu_fluid_ounce, bu_tablespoon, bu_teaspoon, bu_barrel,

    /* Area */
    bu_acre, bu_barn,

    /* Angle */
    bu_arcminute, bu_arcsecond, bu_grad,

    /* CGS */
    bu_poise, bu_stokes, bu_gauss, bu_maxwell, bu_oersted,
    bu_stilb, bu_phot, bu_galileo,

    /* Radiation */
    bu_curie, bu_roentgen, bu_rem,

    /* Logarithmic */
    bu_neper, bu_decibel,

    bu_rankine,             /* Temperature — absolute Fahrenheit scale */
    bu_slug,                /* Imperial mass */
    bu_thou,                /* Imperial length */

    /* Volume — UK imperial */
    bu_pint_uk, bu_fluid_ounce_uk, bu_quart_uk,

    /* Electrical power */
    bu_var, bu_volt_ampere,

    /* Force (additional) */
    bu_kilogram_force,

    /* Pressure (additional) */
    bu_inch_hg,

    /* Rotational frequency */
    bu_rpm,

    /* Energy (additional) */
    bu_foot_pound,

    /* Mass (additional) */
    bu_dram, bu_pennyweight,

    /* Length (additional) */
    bu_chain, bu_rod,

    /* Volume (additional) */
    bu_gill, bu_gill_uk,

    /* Acceleration / gravity */
    bu_standard_gravity,

    /* Power (additional) */
    bu_metric_horsepower,

    /* Angle (additional) */
    bu_revolution,

    /* Time (additional) */
    bu_month, bu_fortnight,

    /* Pressure (additional) */
    bu_atmosphere_technical,

    /* Textile */
    bu_tex, bu_denier,

    /* Apothecary / dry volume */
    bu_fluid_dram, bu_minim, bu_peck, bu_bushel,

    /* Old German */
    bu_pfund, bu_zentner, bu_doppelzentner, bu_lot,
    bu_prussian_line, bu_prussian_zoll, bu_prussian_fuss,
    bu_prussian_elle, bu_prussian_rute, bu_klafter,
    bu_german_mile, bu_morgen, bu_scheffel,

    /* Additional physical units */
    bu_survey_foot, bu_league, bu_cable, bu_hand,
    bu_quintal, bu_scruple, bu_baud,

    /* Historical temperature scales */
    bu_delisle, bu_newton_temp, bu_reaumur, bu_romer,

    /* Dimensionless ratio units */
    bu_percent, bu_per_mille, bu_per_myriad,
    bu_per_cent_mille, bu_ppm, bu_ppb,   /* bu_ppt and bu_ppq close
                                          * block 10 — see the note below */

    /* … the pH scale, the named speed units, the five water-hardness
     * degrees, the concentration units, and the turbidity and salinity
     * scales — then: */

    /* Temperature differences (Δ°C shares bu_delta_kelvin, Δ°Ra shares
     * bu_delta_fahrenheit — the same interval, so an alias not an id) */
    bu_delta_kelvin, bu_delta_fahrenheit, bu_delta_delisle,
    bu_delta_newton_temp, bu_delta_reaumur, bu_delta_romer,

    /* … the six units the profiles needed, the US survey lengths, the
     * typographic lengths, the US dry volumes and the trade measures, and
     * the rest of block 10 up to bu_horsepower_water = 100260. The whole run is
     * generated into include/bovnar_units.gen.h from
     * src/gendata/units.bvnr, in that file's order — read it there rather
     * than from this abridged listing. */

    /* Block 90 — the currencies — has NO named enumerators: a currency is
     * resolved by string via bvn_parse_currency_str and carried as the
     * numeric base value, and the catalogue in bovnar_currency.c is
     * index-aligned to BVN_CURRENCY_FIRST. */

    /* Blocks 20–80 — the profiles' opaque units — are generated into
     * include/bovnar_profiles.gen.h: bu_ucum_iu = 200000, bu_unece_one =
     * 300000, and so on. Only 20 and 30 contribute any today. */
} value_base_unit_t;

/* Not a member of the enum, and NOT a bound on it: the number of rows in the
 * dense tables the library indexes by bvni_unit_slot(). The id space is
 * sparse, so it has no "one past the end". */
/* #define BVN_UNIT_SLOT_COUNT 331 */

unit_exponent_t

#define BVN_EXPONENT_MIN    (-100)
#define BVN_EXPONENT_MAX    ( 100)

typedef enum unit_exponent_e {
    exp_range_min  = BVN_EXPONENT_MIN,
    exp_range_max  = BVN_EXPONENT_MAX,
    exp_invalid    =   0,
    exp_linear     =   1,  exp_square    =  2,  exp_cubic     =  3,
    exp_quartic    =   4,  exp_quintic   =  5,  exp_sextic    =  6,
    exp_septic     =   7,  exp_octic     =  8,  exp_nonic     =  9,
    exp_neg_linear =  -1,  exp_neg_square= -2,  exp_neg_cubic = -3,
    exp_neg_quartic=  -4,  exp_neg_quintic=-5,  exp_neg_sextic= -6,
    exp_neg_septic =  -7,  exp_neg_octic = -8,  exp_neg_nonic = -9,
} unit_exponent_t;