navcore_signalk/

units.rs

//! A mariner's own display units, as `signalk-server`'s `unitpreferences`
//! feature states them.
//!
//! Signal K itself is SI on the wire and says nothing about how a value
//! should be shown -- that is what `unitpreferences` is for, a
//! `signalk-server` feature (not part of the core specification, the same
//! already-observed-convention standing this crate already gives
//! [`crate::AisTargetStatus`] and [`crate::NotificationSeverity`]) that
//! lets a mariner pick nautical miles, kilometres or statute miles for
//! distance, once, on the server, for every client to honour alike.
//!
//! # Why this does not read the server's own conversion formula
//!
//! `GET /signalk/v1/unitpreferences/active` answers with a `formula` and
//! `inverseFormula` per category -- a short expression, `"value * 1.94384"`,
//! meant to be evaluated. This crate deliberately never evaluates it: doing
//! so needs a small expression interpreter, which is new conversion math of
//! exactly the kind this workspace exists to avoid growing twice. Instead,
//! `conversions` below is a table of `(scale, offset)` pairs -- one row
//! per `target = value * scale + offset` -- computed once, by hand, from
//! every `formula` string `GET /signalk/v1/unitpreferences/definitions`
//! answered on a real `signalk-server` (confirmed live; see
//! `crates/signalk/testdata/unitpreferences.json`, the fixture this table
//! is checked against, and this module's own tests). What is read from a
//! server at runtime is only *which* row a mariner's preference names --
//! never a formula to evaluate.
//!
//! # What is not covered
//!
//! Every target unit `signalk-server` ships is in `conversions`, with two
//! exceptions, both left unread the same way an unrecognised path is
//! anywhere else in this crate -- skipped, not refused:
//!
//! - **Beaufort** (`m/s` -> `Bf`), the one target in the entire catalogue
//!   whose own formula is not affine -- `(value / 0.836)^(2/3)`, a power
//!   law. Modelling it would mean either a second kind of table entry for
//!   one row, or the interpreter this module exists to avoid; a mariner
//!   who picks Beaufort for wind speed gets the same "not a reading this
//!   crate understands" [`Preferences::convert`] already gives any other
//!   unrecognised target.
//! - **Duration formatters** (`s` -> `HH:MM:SS` and six siblings), which
//!   are not a numeric scale at all -- `formatDurationHMS(value)` turns a
//!   seconds count into a clock-formatted *string*, which is a formatting
//!   concern, not a unit conversion, and not this module's to grow into.
//!   The plain decimal ones (`s` -> `hour`, `minute`, `day`, ...) are
//!   ordinary affine conversions and are covered.
//!
//! Three base units are themselves formats rather than physical
//! quantities -- `RFC 3339 (UTC)` and `Epoch Seconds` (the `dateTime`/
//! `epoch` categories' own timestamp representations) and `bool` (the
//! `boolean` category) -- each with exactly one target, itself. The
//! `target-equals-base` rule [`Preferences::convert`] applies before ever
//! consulting `conversions` already answers that trivially and
//! correctly (the value passes through unchanged), without this module
//! needing to know or care that a category is not really a measurement.
//!
//! # The `target-equals-base` rule
//!
//! A preference whose `targetUnit` is exactly the category's own Signal K
//! base unit (`"m"` for `length`, `"K"` for `temperature`, ...) means "no
//! conversion" -- confirmed live: `signalk-server` sends that literal
//! string, not the differently-spelled identity row its own
//! `conversions` table happens to carry for some base units (`m`'s own
//! identity entry is named `"meter"`, never `"m"`; several base units --
//! `V`, `A`, `bool`, `tr`, the two timestamp formats -- carry no entry
//! *but* their own name at all). [`Preferences::convert`] checks this
//! before ever looking a target up in `conversions`, so every category
//! has a correct identity regardless of which, if either, spelling the
//! table itself happens to carry.

use std::collections::BTreeMap;

use serde_json::Value;

/// The Signal K base unit `category` (as `GET /signalk/v1/unitpreferences/categories`'s
/// own `categoryToBaseUnit` names it, confirmed live) reads its preference
/// out of, or `None` for a category this crate has never heard of.
fn category_base_unit(category: &str) -> Option<&'static str> {
    Some(match category {
        "speed" => "m/s",
        "temperature" => "K",
        "pressure" => "Pa",
        "distance" => "m",
        "depth" => "m",
        "angle" => "rad",
        "angleDegrees" => "deg",
        "angularVelocity" => "rad/s",
        "volume" => "m3",
        "voltage" => "V",
        "current" => "A",
        "power" => "W",
        "percentage" => "ratio",
        "frequency" => "Hz",
        "time" => "s",
        "charge" => "C",
        "volumeRate" => "m3/s",
        "length" => "m",
        "energy" => "J",
        "mass" => "kg",
        "area" => "m2",
        "dateTime" => "RFC 3339 (UTC)",
        "epoch" => "Epoch Seconds",
        "unitless" => "tr",
        "boolean" => "bool",
        "dataSize" => "B",
        _ => return None,
    })
}

/// Every base unit this crate converts out of, and the target units
/// reachable from it as `(scale, offset)` pairs -- see this module's own
/// top doc for where these numbers come from and what is left out.
/// `crates/signalk/testdata/unitpreferences.json` is the fixture this
/// table is checked against.
fn conversions(base_unit: &str) -> &'static [(&'static str, f64, f64)] {
    match base_unit {
        "m" => &[
            ("mm", 1000.0, 0.0),
            ("cm", 100.0, 0.0),
            ("fathom", 0.5467468562055768, 0.0),
            ("angstrom", 10000000000.0, 0.0),
            ("AU", 6.684585813036146e-12, 0.0),
            ("datamile", 0.0005468066491688539, 0.0),
            ("foot", 3.280839895013124, 0.0),
            ("furlong", 0.004970178926441352, 0.0),
            ("inch", 39.37007874015748, 0.0),
            ("league", 0.0002071251035625518, 0.0),
            ("light-minute", 5.5594008077809377e-11, 0.0),
            ("light-second", 3.3356404846685622e-09, 0.0),
            ("light-year", 1.0570234557732929e-16, 0.0),
            ("meter", 1.0, 0.0),
            ("kilometer", 0.001, 0.0), // km
            ("mile", 0.000621371192237334, 0.0),
            ("naut-mile", 0.0005399568034557236, 0.0), // nmi
            ("parsec", 3.2407788498994385e-17, 0.0),
            ("pica", 236.22047262694525, 0.0),
            ("point", 2834.645667505735, 0.0),
            ("redshift", 7.67593433391696e-27, 0.0),
            ("rod", 0.1988466892026248, 0.0),
            ("yard", 1.0936132983377078, 0.0),
        ],
        "m/s" => &[
            ("kn", 1.94384, 0.0),
            ("km/h", 3.6, 0.0),
            ("mph", 2.2369362920544025, 0.0),
            ("fps", 3.280839895013124, 0.0),
        ],
        "K" => &[
            ("C", 1.0, -273.15),  // °C
            ("F", 1.8, -459.67), // °F
        ],
        "Pa" => &[
            ("hPa", 0.01, 0.0),
            ("mbar", 0.01, 0.0),
            ("bar", 1e-05, 0.0),
            ("psi", 0.0001450376807894691, 0.0),
            ("inHg", 0.00029529987601298443, 0.0),
            ("mmHg", 0.0075006168507298, 0.0),
            ("atm", 9.869232667160129e-06, 0.0),
            ("cmh2o", 0.0101974428892211, 0.0),
            ("inh2o", 0.004014741294968937, 0.0),
            ("torr", 0.0075006168507298, 0.0),
        ],
        "m3" => &[
            ("beerbarrel", 8.521679072308338, 0.0),
            ("beerbarrel-imp", 6.110256897196883, 0.0),
            ("bushel", 28.37759178221265, 0.0),
            ("cup", 4226.752810932216, 0.0),
            ("fluid-ounce", 33814.02254462713, 0.0),
            ("fluid-ounce-imp", 35195.07972785405, 0.0),
            ("gallon", 264.1720512415585, 0.0),
            ("gallon-imp", 219.9692482990878, 0.0),
            ("liter", 1000.0, 0.0),
            ("oilbarrel", 6.289810770432104, 0.0),
            ("pint-imp", 1759.7539863927022, 0.0),
            ("quart", 1056.688204966234, 0.0),
            ("tablespoon", 67628.04531793189, 0.0),
            ("teaspoon", 202884.1355421759, 0.0),
        ],
        "m3/s" => &[
            ("L/h", 3600000.0, 0.0),
            ("L/min", 60000.0, 0.0),
            ("gal/h", 264.17205236, 0.0),
            ("gal-imp/h", 219.9692483, 0.0),
        ],
        "kg" => &[
            ("AMU", 6.0221412901167415e+26, 0.0),
            ("carat", 5000.0, 0.0),
            ("dalton", 6.0221412901167415e+26, 0.0),
            ("dram", 564.3833897001838, 0.0),
            ("grain", 15432.358352941434, 0.0),
            ("gram", 1000.0, 0.0),
            ("kilogram", 1.0, 0.0),
            ("metric-ton", 0.001, 0.0),
            ("ounce", 35.27396198068672, 0.0),
            ("pound", 2.2046226218487757, 0.0),
            ("short-ton", 0.001102311310924388, 0.0),
            ("slug", 0.0685217660314843, 0.0),
            ("stone", 0.15747304441776971, 0.0),
        ],
        "J" => &[
            ("btu", 0.0009478169879134378, 0.0),
            ("calorie", 0.2390057361376673, 0.0),
            ("Calorie", 0.00023900573613766727, 0.0),
            ("electronvolt", 6.241509074460763e+18, 0.0),
            ("erg", 10000000.0, 0.0),
            ("therm-US", 9.480434279733487e-09, 0.0),
            ("Wh", 0.0002777777777777778, 0.0),
        ],
        "W" => &[
            ("kW", 0.001, 0.0),
            ("horsepower", 0.0013410220888438076, 0.0),
            ("watt", 1.0, 0.0),
        ],
        "rad" => &[
            ("arcminute", 3437.746770784939, 0.0),
            ("arcsecond", 206264.8062470964, 0.0),
            ("degree", 57.29577951308231, 0.0), // °
            ("gradian", 63.66197723675812, 0.0),
            ("radian", 1.0, 0.0),
            ("rotation", 0.1591549430918954, 0.0),
        ],
        "deg" => &[
            ("arcminute", 60.00000000000001, 0.0),
            ("arcsecond", 3600.000000000001, 0.0),
            ("degree", 1.0, 0.0), // °
            ("gradian", 1.111111111111111, 0.0),
            ("radian", 0.0174532925199433, 0.0),
            ("rotation", 0.0027777777777777783, 0.0),
        ],
        "rad/s" => &[
            ("deg/s", 57.2958, 0.0), // °/s
            ("rpm", 9.549296585513723, 0.0),
        ],
        "Hz" => &[
            ("rpm", 60.0, 0.0),
            ("hertz", 1.0, 0.0),
        ],
        "C" => &[
            ("Ah", 0.0002777777777777778, 0.0),
            ("mAh", 0.277778, 0.0),
        ],
        "ratio" => &[
            ("percent", 100.0, 0.0), // %
        ],
        "s" => &[
            ("MM.xx", 0.016666666666666666, 0.0),   // min
            ("HH.xx", 0.0002777777777777778, 0.0),  // hr
            ("DD.xx", 1.1574074074074073e-05, 0.0), // days
            ("century", 3.168876461541279e-10, 0.0),
            ("day", 1.1574074074074073e-05, 0.0),
            ("decade", 3.1688764615412793e-09, 0.0),
            ("fortnight", 8.26719576719577e-07, 0.0),
            ("hour", 0.0002777777777777778, 0.0),
            ("minute", 0.016666666666666666, 0.0),
            ("second", 1.0, 0.0),
            ("week", 1.653439153439154e-06, 0.0),
            ("year", 3.168876461541279e-08, 0.0),
        ],
        "m2" => &[
            ("acre", 0.0002471053816137119, 0.0),
            ("hectare", 0.0001, 0.0),
            ("sqft", 10.7639, 0.0),
        ],
        "B" => &[
            ("KB", 0.001, 0.0),
            ("MB", 1e-06, 0.0),
            ("GB", 1e-09, 0.0),
            ("TB", 1e-12, 0.0),
            ("KiB", 0.0009765625, 0.0),
            ("MiB", 9.5367431640625e-07, 0.0),
            ("GiB", 9.313225746154785e-10, 0.0),
            ("TiB", 9.094947017729282e-13, 0.0),
        ],
        // V, A: signalk-server lists only their own identity conversion,
        // which the target-equals-base check in `resolve` already answers.
        _ => &[],
    }
}

/// One category's own resolved preference: the fixed factor from its
/// Signal K base unit into whatever a mariner asked for, and the label to
/// show beside the converted figure.
#[derive(Debug, Clone, PartialEq)]
struct Resolved {
    scale: f64,
    offset: f64,
    /// The label to show, when the server stated one.
    ///
    /// `None`, not empty, when the server states none -- confirmed live:
    /// its own `/active` endpoint only merges one in for a `targetUnit`
    /// its unit definitions have a `conversions` entry for, and omits it
    /// outright for the target-equals-base identity (`length`'s own `m`,
    /// on every built-in preset but the two imperial ones). A caller
    /// distinguishes this from a category Signal K never mentioned at all
    /// -- the unit to convert into is still read, only the word for it is
    /// not -- and falls back to its own default label either way.
    symbol: Option<String>,
}

/// What a server's `unitpreferences` states, as far as this crate reads
/// it -- every category `category_base_unit` names a Signal K base unit
/// for, present once the server has stated a target unit this crate
/// converts (see this module's own top doc for the two kinds of target
/// that leaves out), absent otherwise. [`Default`] is every category
/// absent, which is exactly the state a caller should fall back to its
/// own default unit for -- the same value [`Self::parse`] returns for an
/// unreadable answer.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct Preferences {
    resolved: BTreeMap<String, Resolved>,
}

impl Preferences {
    /// Reads `GET /signalk/v1/unitpreferences/active`'s own JSON body.
    ///
    /// Never fails: an answer this crate cannot make sense of -- the
    /// wrong shape, every category naming a target unit it does not know,
    /// or a category it has never heard of -- reads the same as no
    /// preference stated at all, since a caller reacts to both by falling
    /// back to its own default unit regardless of which it was.
    #[must_use]
    pub fn parse(value: &Value) -> Self {
        let empty = Value::Object(serde_json::Map::new());
        let categories = value.get("categories").unwrap_or(&empty);

        let mut resolved = BTreeMap::new();
        let Some(categories) = categories.as_object() else {
            return Self { resolved };
        };
        for (category, entry) in categories {
            let Some(base_unit) = category_base_unit(category) else {
                continue;
            };
            let Some(target) = entry.get("targetUnit").and_then(Value::as_str) else {
                continue;
            };
            let Some((scale, offset)) = resolve(base_unit, target) else {
                continue;
            };
            // Absent and empty read the same -- see `Resolved::symbol`'s
            // own doc.
            let symbol = entry
                .get("symbol")
                .and_then(Value::as_str)
                .filter(|symbol| !symbol.is_empty())
                .map(str::to_owned);
            resolved.insert(category.clone(), Resolved { scale, offset, symbol });
        }
        Self { resolved }
    }

    /// `si_value`, in `category`'s own Signal K base unit (its own SI
    /// unit for everything but [`Self::distance_nm`]'s and its three
    /// siblings' own nautical-mile/knot/metre convention -- see
    /// `category_base_unit` for which is which), converted into
    /// whatever a mariner's preference asks for, with the label to show
    /// beside it. `None` when `category` names nothing
    /// `category_base_unit` recognises, or nothing was stated (or
    /// understood) for it -- the same two cases [`Self::parse`]'s own doc
    /// gives.
    ///
    /// This is the one path every category not among nav-core's own four
    /// canonical units goes through -- a mariner's chosen pressure unit,
    /// say, has no `pressure_pa` accessor of its own here for the same
    /// reason `nav-math` itself never grew a pressure type: nothing in
    /// this workspace holds a pressure reading yet. A future one that
    /// does calls this directly rather than this crate growing an
    /// accessor speculatively.
    #[must_use]
    pub fn convert(&self, category: &str, si_value: f64) -> Option<(f64, Option<&str>)> {
        let resolved = self.resolved.get(category)?;
        Some((si_value * resolved.scale + resolved.offset, resolved.symbol.as_deref()))
    }

    /// The label `category` converts to, when a preference states one
    /// this crate reads *and* the server put a word to it -- see
    /// `Resolved::symbol`'s own doc for why the two are not the same
    /// question.
    #[must_use]
    pub fn symbol(&self, category: &str) -> Option<&str> {
        self.resolved.get(category)?.symbol.as_deref()
    }

    /// `nm` in the preferred distance unit, or unchanged with no
    /// preference stated -- nautical miles already being `nav-math`'s own
    /// unit, that is a caller's correct fallback regardless. Also what a
    /// closest point of approach converts through: a CPA is a distance.
    #[must_use]
    pub fn distance_nm(&self, nm: f64) -> f64 {
        self.convert("distance", nm * nav_math::METRES_PER_NM).map_or(nm, |(value, _)| value)
    }

    /// The distance unit's own symbol -- see [`Self::symbol`]'s own doc
    /// for exactly when this is `None`.
    #[must_use]
    pub fn distance_symbol(&self) -> Option<&str> {
        self.symbol("distance")
    }

    /// `kn` in the preferred speed unit, or unchanged with no preference.
    #[must_use]
    pub fn speed_kn(&self, kn: f64) -> f64 {
        // A knot is a nautical mile per hour: the same seam `distance_nm`
        // crosses, over an hour.
        let metres_per_second = kn * nav_math::METRES_PER_NM / 3600.0;
        self.convert("speed", metres_per_second).map_or(kn, |(value, _)| value)
    }

    /// The speed unit's own symbol -- see [`Self::symbol`]'s own doc for
    /// exactly when this is `None`.
    #[must_use]
    pub fn speed_symbol(&self) -> Option<&str> {
        self.symbol("speed")
    }

    /// `metres` in the preferred length unit, or unchanged with no
    /// preference -- metres already being the wire's own unit for a
    /// length or a depth, and this crate's own throughout.
    #[must_use]
    pub fn length_m(&self, metres: f64) -> f64 {
        self.convert("length", metres).map_or(metres, |(value, _)| value)
    }

    /// The length unit's own symbol -- see [`Self::symbol`]'s own doc for
    /// exactly when this is `None`.
    #[must_use]
    pub fn length_symbol(&self) -> Option<&str> {
        self.symbol("length")
    }

    /// `metres` in the preferred depth unit, or unchanged with no
    /// preference -- see [`Self::length_m`]'s own doc, and this module's
    /// own for why depth is not simply `length_m` under another name.
    #[must_use]
    pub fn depth_m(&self, metres: f64) -> f64 {
        self.convert("depth", metres).map_or(metres, |(value, _)| value)
    }

    /// The depth unit's own symbol -- see [`Self::symbol`]'s own doc for
    /// exactly when this is `None`.
    #[must_use]
    pub fn depth_symbol(&self) -> Option<&str> {
        self.symbol("depth")
    }
}

/// `symbol` in `lang`'s own words, when this crate knows one -- `symbol`
/// unchanged otherwise, the same "unrecognised passes through" discipline
/// [`Preferences::parse`] itself already keeps. `signalk-server` states
/// every symbol in English regardless of who is reading it (confirmed
/// live: a mariner's own distance preference set to nautical miles comes
/// back with `"symbol":"nmi"` whatever locale the request was made
/// under) -- this is the one place that turns it into something else.
///
/// Deliberately not part of [`Preferences`] itself: a caller already has
/// this crate's own English symbol, from [`Preferences::symbol`] or one
/// of its four named accessors, and reaches for this only when it wants
/// a mariner's own words instead, which not every caller does -- one
/// happy with English survives this table changing without needing to
/// call anything differently.
///
/// `lang` is a BCP-47 language tag, `"de"` or `"de-DE"` alike -- only its
/// own primary language subtag is read, via [`language_tags`], rather
/// than this crate learning to split locale strings by hand. An
/// unparseable `lang` reads the same as a language this crate has
/// nothing for: `symbol` unchanged. Reading a mariner's own chosen
/// language at all is not this crate's job, the same "not this crate's
/// job" boundary [`Preferences`] itself already draws for where a token
/// lives on disk or which GSettings key a discovery preference is in.
#[must_use]
pub fn localized_symbol<'a>(symbol: &'a str, lang: &str) -> &'a str {
    let Ok(tag) = language_tags::LanguageTag::parse(lang) else {
        return symbol;
    };
    translation(tag.primary_language(), symbol).unwrap_or(symbol)
}

/// `symbol`'s own word in `lang`, when this crate carries one.
///
/// Scoped to the base units [`Preferences`] itself names accessors for
/// (`m`, `m/s`) rather than every symbol `signalk-server` can ever send
/// (mass, volume, energy, ... -- see `category_base_unit`'s own list):
/// nothing in this workspace shows those yet, the same "add an accessor
/// where it is first wanted" restraint [`Preferences::convert`]'s own
/// doc already states for the categories beyond nav-core's four
/// canonical units. Of what is here, `"nmi"`, `"mile"` and `"foot"` are
/// confirmed live -- the three symbols a real `signalk-server`'s own
/// nautical and imperial presets actually send for distance/depth/length
/// (`GET /signalk/v1/unitpreferences/definitions`, checked directly
/// against a running server rather than its shipped config file, which
/// turned out to disagree with an older version of this same table:
/// `"foot"`/`"mile"` spelled out in full, not the `"ft"`/`"mi"` an
/// earlier `signalk-server` used to send). `"meter"`, `"inch"` and
/// `"fathom"` are not live-confirmed the same way, but are unambiguous,
/// standard German words for the identical `m`-based unit, worth having
/// ready for a custom preset that picks one of them.
fn translation(lang: &str, symbol: &str) -> Option<&'static str> {
    match lang {
        "de" => Some(match symbol {
            "nmi" => "sm",
            "mile" => "Meile",
            "foot" => "Fuß",
            "meter" => "Meter",
            "inch" => "Zoll",
            "fathom" => "Faden",
            _ => return None,
        }),
        _ => None,
    }
}

/// `target`'s own `(scale, offset)` out of `base_unit`'s own base, or the
/// identity when `target` names the base unit itself -- see this module's
/// own "target-equals-base rule" doc for why that check comes first.
fn resolve(base_unit: &str, target: &str) -> Option<(f64, f64)> {
    if target == base_unit {
        return Some((1.0, 0.0));
    }
    conversions(base_unit).iter().find(|row| row.0 == target).map(|row| (row.1, row.2))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The live answer this module's own doc names, from a real
    /// `signalk-server` running the `nautical-metric` preset -- confirmed
    /// against `GET /signalk/v1/unitpreferences/active`.
    const NAUTICAL_METRIC: &str = r#"{"categories":{
        "distance":{"targetUnit":"naut-mile","symbol":"nmi"},
        "speed":{"targetUnit":"kn","symbol":"kn"},
        "length":{"targetUnit":"m"},
        "depth":{"targetUnit":"m"},
        "temperature":{"targetUnit":"C","symbol":"°C"}
    }}"#;

    #[test]
    fn a_live_nautical_metric_answer_is_read() {
        let preferences = Preferences::parse(&serde_json::from_str(NAUTICAL_METRIC).unwrap());
        assert_eq!(preferences.distance_symbol(), Some("nmi"));
        assert_eq!(preferences.speed_symbol(), Some("kn"));
        // Distance's own target-equals-base rule applies here ("naut-mile"
        // is `m`'s own identity spelling for distance), so it round-trips
        // exactly. Speed's does not: "kn" is a genuine target on the `m/s`
        // base, routed through the table like any other, which carries
        // signalk-server's own mildly rounded 1.94384 rather than the
        // exact 1852/3600 -- see this module's own dedicated test for that
        // factor. A mariner whose preference literally says "kn" sees this
        // same rounding in every other figure the server shows too, so
        // matching it here is the honest answer, not a looser one of ours.
        assert!((preferences.distance_nm(12.0) - 12.0).abs() < 1e-9);
        assert!((preferences.speed_kn(6.0) - 6.0).abs() < 1e-4);
    }

    #[test]
    fn depth_is_read_apart_from_length_even_when_the_two_agree() {
        let preferences = Preferences::parse(&serde_json::from_str(NAUTICAL_METRIC).unwrap());
        assert!((preferences.depth_m(4.0) - 4.0).abs() < 1e-9);
    }

    #[test]
    fn a_custom_preset_may_put_depth_and_length_in_different_units() {
        // Nothing built in ever does this, but a custom preset is free
        // to, and the two must not be read as if they had to agree.
        let value = serde_json::json!({"categories": {
            "length": {"targetUnit": "m"},
            "depth": {"targetUnit": "foot", "symbol": "foot"},
        }});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.length_symbol(), None);
        assert_eq!(preferences.depth_symbol(), Some("foot"));
        assert!((preferences.length_m(1.0) - 1.0).abs() < 1e-9);
        assert!((preferences.depth_m(1.0) - 3.280_839_895).abs() < 1e-6);
    }

    #[test]
    fn a_length_that_maps_to_the_base_units_own_name_is_read_with_no_symbol() {
        // Confirmed live: `signalk-server`'s own `/active` sends the
        // literal targetUnit "m" for "no conversion", not "meter" (the
        // spelling `conversions("m")` itself uses), and never a `symbol`
        // for it -- see this module's own "target-equals-base rule" doc.
        let preferences = Preferences::parse(&serde_json::from_str(NAUTICAL_METRIC).unwrap());
        assert_eq!(preferences.length_symbol(), None);
        assert!((preferences.length_m(2.0) - 2.0).abs() < 1e-9);
    }

    #[test]
    fn an_explicitly_blank_symbol_reads_the_same_as_none_stated() {
        let value = serde_json::json!({"categories": {
            "distance": {"targetUnit": "kilometer", "symbol": ""},
        }});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.distance_symbol(), None);
    }

    #[test]
    fn metric_converts_distance_to_kilometres_and_speed_to_kmh() {
        let value = serde_json::json!({"categories": {
            "distance": {"targetUnit": "kilometer", "symbol": "km"},
            "speed": {"targetUnit": "km/h", "symbol": "km/h"},
        }});
        let preferences = Preferences::parse(&value);
        // One nautical mile is 1.852 km, confirmed against the fixed
        // definition nav-math states.
        assert!((preferences.distance_nm(1.0) - 1.852).abs() < 1e-9);
        assert!((preferences.speed_kn(1.0) - 1.852).abs() < 1e-9);
    }

    #[test]
    fn imperial_uk_converts_distance_to_statute_miles_and_length_to_feet() {
        let value = serde_json::json!({"categories": {
            "distance": {"targetUnit": "mile", "symbol": "mile"},
            "length": {"targetUnit": "foot", "symbol": "foot"},
        }});
        let preferences = Preferences::parse(&value);
        // A nautical mile is about 1.15078 statute miles.
        assert!((preferences.distance_nm(1.0) - 1.150_779_45).abs() < 1e-6);
        // A metre is about 3.28084 feet.
        assert!((preferences.length_m(1.0) - 3.280_839_895).abs() < 1e-6);
    }

    #[test]
    fn a_speed_in_knots_matches_the_servers_own_slightly_rounded_factor_when_named_explicitly() {
        // Unlike the identity case above, spelling "kn" out as speed's
        // *target* on a base unit of m/s is read the same as any other
        // target, through the server's own shipped (and mildly rounded)
        // factor. This crate reproduces that factor exactly rather than a
        // more precise one of its own, because matching what the
        // mariner's own server actually computes is the point, not being
        // more accurate than it. Checked through `convert` directly, not
        // `speed_kn`, whose own identity fast path this is deliberately
        // not exercising.
        let value = serde_json::json!({"categories": {
            "speed": {"targetUnit": "kn", "symbol": "kn"},
        }});
        let preferences = Preferences::parse(&value);
        let (converted, _) = preferences.convert("speed", 10.0).expect("a reading");
        // 10 m/s at the server's own 1.94384 (not the exact 1.9438444...).
        assert!((converted - 19.4384).abs() < 1e-9);
    }

    #[test]
    fn an_unrecognised_target_unit_leaves_the_category_absent() {
        let value = serde_json::json!({"categories": {
            "distance": {"targetUnit": "smoot", "symbol": "smoot"},
        }});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.distance_symbol(), None);
        // The caller's own fallback: unchanged, in nav-math's own unit.
        assert!((preferences.distance_nm(5.0) - 5.0).abs() < 1e-9);
    }

    #[test]
    fn beaufort_is_not_a_reading_this_crate_understands() {
        let value = serde_json::json!({"categories": {"speed": {"targetUnit": "Bf", "symbol": "Bf"}}});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.speed_symbol(), None);
        assert!((preferences.speed_kn(4.0) - 4.0).abs() < 1e-9);
    }

    #[test]
    fn a_duration_formatter_is_not_a_reading_this_crate_understands() {
        let value = serde_json::json!({"categories": {"time": {"targetUnit": "HH:MM:SS"}}});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.convert("time", 3661.0), None);
    }

    #[test]
    fn an_answer_with_no_categories_at_all_is_every_preference_absent() {
        let preferences = Preferences::parse(&serde_json::json!({}));
        assert_eq!(preferences, Preferences::default());
        assert_eq!(preferences.convert("distance", 5.0), None);
    }

    #[test]
    fn a_category_this_crate_does_not_recognise_converts_nothing() {
        let value = serde_json::json!({"categories": {"madeUpCategory": {"targetUnit": "x"}}});
        let preferences = Preferences::parse(&value);
        assert_eq!(preferences.convert("madeUpCategory", 1.0), None);
    }

    #[test]
    fn temperature_converts_kelvin_to_celsius_and_fahrenheit() {
        let celsius = Preferences::parse(&serde_json::json!({"categories": {
            "temperature": {"targetUnit": "C", "symbol": "°C"},
        }}));
        let (value, symbol) = celsius.convert("temperature", 300.0).expect("a reading");
        assert!((value - 26.85).abs() < 1e-9);
        assert_eq!(symbol, Some("\u{b0}C"));

        let fahrenheit = Preferences::parse(&serde_json::json!({"categories": {
            "temperature": {"targetUnit": "F", "symbol": "°F"},
        }}));
        let (value, _) = fahrenheit.convert("temperature", 300.0).expect("a reading");
        assert!((value - 80.33).abs() < 1e-9);
    }

    #[test]
    fn generic_convert_reaches_every_category_this_module_names_a_base_unit_for() {
        // Every entry `category_base_unit` answers is reachable through
        // the one generic path, at the identity, with no preference
        // stated -- the same fallback contract as the four named
        // accessors, without having to write one accessor per category.
        let preferences = Preferences::default();
        for category in [
            "speed", "temperature", "pressure", "distance", "depth", "angle", "angleDegrees",
            "angularVelocity", "volume", "voltage", "current", "power", "percentage", "frequency",
            "time", "charge", "volumeRate", "length", "energy", "mass", "area", "dateTime", "epoch",
            "unitless", "boolean", "dataSize",
        ] {
            assert_eq!(preferences.convert(category, 7.0), None, "{category}");
        }
    }

    #[test]
    fn the_conversion_table_matches_a_real_servers_own_answer_for_every_base_unit_it_covers() {
        // The fixture is `GET /signalk/v1/unitpreferences/definitions`'s
        // own answer, confirmed live -- see this module's own top doc.
        // This test is what notices signalk-server having added a target
        // unit this table does not yet have a row for: a new one shows up
        // in the fixture (once it is refreshed against a newer server --
        // see the crate's own README) and immediately fails here, named,
        // rather than silently being read as "unrecognised" forever.
        let fixture: Value = serde_json::from_str(include_str!("../testdata/unitpreferences.json")).unwrap();
        let definitions = fixture.get("definitions").and_then(Value::as_object).expect("a definitions object");

        // Every affine target this crate's own table does not carry is
        // named here, with the one word that makes it so -- checked
        // against, not merely trusted, so a fixture refresh that quietly
        // stopped naming one of these would fail loudly too.
        let unsupported = [
            ("m/s", "Bf"),
            ("s", "DD:HH:MM:SS"),
            ("s", "HH:MM:SS"),
            ("s", "HH:MM:SS.mmm"),
            ("s", "MM:SS"),
            ("s", "MM:SS.mmm"),
            ("s", "duration-verbose"),
            ("s", "duration-compact"),
        ];

        let mut missing = Vec::new();
        for (base, info) in definitions {
            let conversions = info.get("conversions").and_then(Value::as_object).expect("conversions");
            for (target, conversion) in conversions {
                if target == base {
                    continue; // the target-equals-base identity, not a table row
                }
                if unsupported.contains(&(base.as_str(), target.as_str())) {
                    continue;
                }
                let formula = conversion.get("formula").and_then(Value::as_str).unwrap_or_default();
                let Some((want_scale, want_offset)) = parse_affine_formula(formula) else {
                    missing.push(format!(
                        "{base} -> {target}: formula {formula:?} is not affine and is not on the unsupported list"
                    ));
                    continue;
                };
                match table_lookup(base, target) {
                    Some((scale, offset)) => {
                        assert!(
                            (scale - want_scale).abs() < 1e-9 && (offset - want_offset).abs() < 1e-9,
                            "{base} -> {target}: table has ({scale}, {offset}), fixture says ({want_scale}, {want_offset})"
                        );
                    }
                    None => missing.push(format!("{base} -> {target}: not in conversions(), and not on the unsupported list")),
                }
            }
        }
        assert!(missing.is_empty(), "signalk-server names targets this table does not:\n{}", missing.join("\n"));
    }

    /// The same `value * scale + offset` shape `conversions`' own rows
    /// are computed as, read back out of a live `formula` string -- used
    /// only by the fixture-coverage test above, to turn its ground truth
    /// into the same shape this module's own table already carries,
    /// never at runtime.
    fn parse_affine_formula(formula: &str) -> Option<(f64, f64)> {
        let formula = formula.trim();
        if formula == "value" {
            return Some((1.0, 0.0));
        }
        if let Some(factor) = formula.strip_prefix("value * ") {
            return factor.parse().ok().map(|scale| (scale, 0.0));
        }
        if let Some(divisor) = formula.strip_prefix("value / ") {
            return divisor.parse::<f64>().ok().map(|divisor| (1.0 / divisor, 0.0));
        }
        if let Some(subtrahend) = formula.strip_prefix("value - ") {
            return subtrahend.parse().ok().map(|offset: f64| (1.0, -offset));
        }
        // "(value - X) * Y + Z" -- Fahrenheit's own shape, the only one
        // of this form in the whole catalogue.
        let rest = formula.strip_prefix("(value - ")?;
        let (subtrahend, rest) = rest.split_once(") * ")?;
        let (scale, addend) = rest.split_once(" + ")?;
        let subtrahend: f64 = subtrahend.parse().ok()?;
        let scale: f64 = eval_simple_fraction(scale)?;
        let addend: f64 = addend.parse().ok()?;
        Some((scale, -subtrahend * scale + addend))
    }

    /// `"9/5"` or a bare number -- the only two shapes a `scale` in
    /// [`parse_affine_formula`] is ever written in.
    fn eval_simple_fraction(text: &str) -> Option<f64> {
        match text.split_once('/') {
            Some((num, den)) => Some(num.parse::<f64>().ok()? / den.parse::<f64>().ok()?),
            None => text.parse().ok(),
        }
    }

    /// `conversions`, read the same way [`Preferences::convert`] reads
    /// it -- `pub(crate)` would do, but the fixture test above is the
    /// only caller and lives in this same module.
    fn table_lookup(base: &str, target: &str) -> Option<(f64, f64)> {
        conversions(base).iter().find(|row| row.0 == target).map(|row| (row.1, row.2))
    }

    #[test]
    fn a_known_symbol_is_read_in_german() {
        assert_eq!(localized_symbol("nmi", "de"), "sm");
        assert_eq!(localized_symbol("mile", "de"), "Meile");
        assert_eq!(localized_symbol("foot", "de"), "Fuß");
    }

    #[test]
    fn a_full_locale_tag_reads_by_its_own_primary_language_alone() {
        assert_eq!(localized_symbol("nmi", "de-DE"), "sm");
        assert_eq!(localized_symbol("nmi", "de-AT"), "sm");
    }

    #[test]
    fn an_unrecognised_symbol_passes_through_unchanged() {
        // "kn" and "km/h" are already the same in German -- not because
        // this crate translated them, but because it was never asked to:
        // no entry means the original string, unrecognised is skipped,
        // not refused, the same discipline `Preferences::parse` keeps.
        assert_eq!(localized_symbol("kn", "de"), "kn");
        assert_eq!(localized_symbol("furlong", "de"), "furlong");
    }

    #[test]
    fn a_language_this_crate_has_nothing_for_passes_symbols_through() {
        assert_eq!(localized_symbol("nmi", "fr"), "nmi");
    }

    #[test]
    fn an_unparseable_locale_tag_is_treated_the_same_as_an_unknown_one() {
        assert_eq!(localized_symbol("nmi", "not a locale"), "nmi");
        assert_eq!(localized_symbol("nmi", ""), "nmi");
    }
}