Skip to main content

utz_common/
lib.rs

1//! This crate holds the types and utilities shared across the workspace:
2//! the asset codec identifiers, the payload header record that both the
3//! encoder and the reader serialize through, and the deterministic LCG
4//! behind every reproducible test/bench sampler.
5#![no_std]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7
8use scroll::{Pread, Pwrite};
9
10pub mod presets;
11
12#[cfg(feature = "alloc")]
13extern crate alloc;
14
15#[cfg(feature = "alloc")]
16use alloc::vec::Vec;
17
18/// The magic bytes every `.utz` asset starts with. The bytes are ASCII on
19/// purpose ("μ" is 2 bytes in UTF-8 and byte literals reject non-ASCII):
20/// the project brands itself as μTZ, and the container as uTZ1.
21pub const MAGIC: [u8; 4] = *b"uTZ1";
22/// The container-format version this workspace reads and writes; a reader
23/// refuses any other value.
24pub const VERSION: u8 = 11;
25
26/// The byte length of the container prologue, which is `MAGIC` (4),
27/// `VERSION` (1), and 3 reserved bytes. The prologue is the only part of
28/// the format whose layout is frozen across versions; everything after it
29/// is [`VERSION`]-specific.
30pub const PROLOGUE_LEN: usize = 8;
31
32/// [`PayloadHeader`]'s serialized size. The section blob starts at
33/// `PROLOGUE_LEN + PAYLOAD_HEADER_LEN`.
34pub const PAYLOAD_HEADER_LEN: usize = 64;
35
36/// The primary grid table's "no zone covers this cell" marker (all 15 id
37/// bits set). Zone/feature ids stay strictly below it; the u16's high bit
38/// flags a border cell carrying a candidate-list index instead.
39pub const NO_ZONE: u16 = 0x7FFF;
40
41/// A primary-grid cell's border flag: the u16's high bit set means the
42/// low 15 bits index a candidate list instead of naming a zone.
43pub const BORDER_FLAG: u16 = 0x8000;
44
45/// The mask selecting a primary-grid cell's 15-bit value, a zone id or
46/// (under [`BORDER_FLAG`]) a candidate-list index. Zone ids and list
47/// indices stay strictly below [`NO_ZONE`], the all-bits-set sentinel.
48pub const CELL_ID_MASK: u16 = 0x7FFF;
49
50/// One decoded primary-grid cell. The wire form is the u16 the
51/// constants above describe; this decoder is shared by the runtime
52/// lookup, the format validator, and the encoder's measurement tools,
53/// so the tag layout is interpreted in exactly one place.
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub enum CellTag {
56    /// No zone covers the cell.
57    Empty,
58    /// A single zone covers the cell; a lookup answers without any
59    /// point-in-polygon test.
60    Zone(u16),
61    /// A zone boundary passes through the cell; the value indexes the
62    /// cell's candidate list.
63    Border(u16),
64}
65
66impl CellTag {
67    /// Decodes a primary-table cell value.
68    #[must_use]
69    pub const fn from_cell(cell: u16) -> CellTag {
70        if cell & BORDER_FLAG != 0 {
71            CellTag::Border(cell & CELL_ID_MASK)
72        } else if cell == NO_ZONE {
73            CellTag::Empty
74        } else {
75            CellTag::Zone(cell)
76        }
77    }
78}
79
80/// Meters per degree of latitude (and of longitude at the equator):
81/// the workspace's one flat conversion between tolerances in meters
82/// (`epsilon_m`) and coordinate degrees.
83pub const METERS_PER_DEG: f64 = 111_320.0;
84
85/// Kilometers per degree, [`METERS_PER_DEG`] scaled; area math uses
86/// `KM_PER_DEG²` (with a latitude cosine) for km² per square degree.
87pub const KM_PER_DEG: f64 = METERS_PER_DEG / 1000.0;
88
89/// The half-range of an `i{bits}` quantization grid (`2^(bits-1) - 1`).
90#[must_use]
91#[expect(
92    clippy::cast_precision_loss,
93    reason = "qmax = 2^(bits-1)-1 ≤ 2^31-1, exact in f64"
94)]
95pub const fn qmax_for(bits: u32) -> f64 {
96    ((1u64 << (bits - 1)) - 1) as f64
97}
98
99/// Rounds half away from zero via the truncating cast: `core` has no
100/// `f64::round`, and the encoder shares this exact expression with the
101/// reader's lookup quantizer so the two stay bit-identical.
102#[expect(
103    clippy::cast_possible_truncation,
104    reason = "callers bound |value| below i32::MAX; float as saturates"
105)]
106fn round_q(value: f64) -> i32 {
107    (value + if value >= 0.0 { 0.5 } else { -0.5 }) as i32
108}
109
110/// Quantizes a longitude onto a grid with half-range `qmax` (see
111/// [`qmax_for()`]).
112#[must_use]
113pub fn q_lon(lon: f64, qmax: f64) -> i32 {
114    round_q(lon / 180.0 * qmax)
115}
116
117/// Quantizes a latitude onto a grid with half-range `qmax`.
118#[must_use]
119pub fn q_lat(lat: f64, qmax: f64) -> i32 {
120    round_q(lat / 90.0 * qmax)
121}
122
123/// Dequantizes a longitude from a grid with half-range `qmax`, the
124/// inverse of [`q_lon()`]. The input is `f64` so fractional grid
125/// positions (e.g. ring intersection points) dequantize too; stored
126/// coordinates pass through `f64::from`.
127#[must_use]
128pub fn dq_lon(value: f64, qmax: f64) -> f64 {
129    value / qmax * 180.0
130}
131
132/// Dequantizes a latitude from a grid with half-range `qmax`, the
133/// inverse of [`q_lat()`].
134#[must_use]
135pub fn dq_lat(value: f64, qmax: f64) -> f64 {
136    value / qmax * 90.0
137}
138
139/// The primary-grid cell containing a lon/lat position, as `(row, col)`:
140/// truncate toward zero, then clamp into the grid. The encoder's
141/// rasterizer, the runtime reader, and the measurement tools all share
142/// this one formula, so what a lookup probes is exactly what the grid
143/// indexed.
144#[must_use]
145pub fn grid_cell(lon: f64, lat: f64, deg: f64, ncols: usize, nrows: usize) -> (usize, usize) {
146    #[expect(
147        clippy::cast_possible_truncation,
148        clippy::cast_sign_loss,
149        clippy::cast_possible_wrap,
150        reason = "cast saturates, then the clamp keeps the index in grid range"
151    )]
152    let cell = (
153        (((lat + 90.0) / deg) as i64).clamp(0, nrows as i64 - 1) as usize,
154        (((lon + 180.0) / deg) as i64).clamp(0, ncols as i64 - 1) as usize,
155    );
156    cell
157}
158
159/// The container's one fixed header record, which carries everything the
160/// reader needs to locate every section. It sits in PLAINTEXT right after
161/// the outer header (only the section blob after it is compressed), so
162/// any container is inspectable and validated before decompression. The
163/// encoder `Pwrite`s it, the reader `Pread`s it (both little-endian);
164/// field order is the wire order; all offsets are relative to the section
165/// blob that follows.
166///
167/// The section blob is laid out as the zone-string offsets and pool, the
168/// geometry-dependent sections at the stored offsets, the grid tables, and
169/// the TZBB release string at `release_off`.
170#[derive(Debug, Clone, Copy, PartialEq, Pread, Pwrite)]
171pub struct PayloadHeader {
172    /// The offset of the arc store (geom 0/1) or of the `FullRings`
173    /// coordinates (geom 2, 4-aligned).
174    pub arcs_off: u32,
175    /// The offset of the poly→feature parent table (plus the ring records
176    /// for geom 0/1).
177    pub rings_off: u32,
178    /// The offset of the grid tables, which hold the primary cells
179    /// followed by the CSR list offsets and ids.
180    pub grid_off: u32,
181    /// The offset of the TZBB release string (`release_len` bytes at the
182    /// payload tail).
183    pub release_off: u32,
184    /// The eager-cache reservation counts, which give exact Vec sizes for
185    /// `preload()` (the coords count is Σ referenced-arc vertex counts and
186    /// may only over-estimate).
187    pub eager_coords: u32,
188    pub eager_rings: u32,
189    pub eager_polys: u32,
190    /// The arc count (geom 0/1), which is zero when there is no arc store.
191    pub n_arcs: u32,
192    /// The section blob's decompressed size (so readers allocate once).
193    pub raw_len: u32,
194    /// The grid cell size in degrees; fractional sizes (e.g. 0.5) are
195    /// allowed.
196    pub grid_deg: f32,
197    /// The simplification tolerance the asset was built with (provenance).
198    pub epsilon_m: f32,
199    pub n_features: u16,
200    /// The grid's column count.
201    pub ncols: u16,
202    /// The grid's row count.
203    pub nrows: u16,
204    /// The number of distinct border-cell candidate lists (CSR).
205    pub uniq: u16,
206    pub release_len: u16,
207    /// This field is reserved and must be zero (room for future format
208    /// flags).
209    pub flags: u16,
210    pub dataset: Dataset,
211    pub quant_bits: QuantBits,
212    pub simplify_algorithm: SimplifyAlgorithm,
213    pub geom: GeomEncoding,
214    /// The section blob's compression codec.
215    pub codec: Codec,
216    /// The population-density weight floor in fixed-point 1e-4, where 0
217    /// means unweighted and 10000 means 1.0. Like `epsilon_m`, it is
218    /// provenance for the density-weighted simplification knob.
219    pub density_weight_floor_e4: u16,
220    /// This byte is reserved and must be zero (it pads the header to 64
221    /// bytes).
222    pub reserved: u8,
223}
224
225impl PayloadHeader {
226    /// Parses the plaintext header out of a complete asset, checking the
227    /// prologue first (magic + [`VERSION`]). The result is `None` if the
228    /// bytes are too short, not a μTZ asset, or a different format
229    /// version. The parse reads only the first
230    /// `PROLOGUE_LEN + PAYLOAD_HEADER_LEN` bytes, which makes it cheap
231    /// provenance sniffing without decompression.
232    #[must_use]
233    pub fn from_asset(bytes: &[u8]) -> Option<PayloadHeader> {
234        if bytes.len() < PROLOGUE_LEN + PAYLOAD_HEADER_LEN
235            || bytes[..4] != MAGIC
236            || bytes[4] != VERSION
237        {
238            return None;
239        }
240        bytes.pread_with(PROLOGUE_LEN, scroll::LE).ok()
241    }
242}
243
244/// The coordinate quantization width, which is how many bits each stored
245/// coordinate occupies (the wire value IS the bit count).
246#[derive(Debug, Clone, Copy, PartialEq, Eq, Pread, Pwrite)]
247#[repr(u8)]
248pub enum QuantBits {
249    Bits16 = 16,
250    Bits24 = 24,
251    Bits32 = 32,
252}
253
254impl QuantBits {
255    /// The width in bits.
256    #[must_use]
257    pub const fn bits(self) -> u32 {
258        self as u32
259    }
260
261    /// The number of bytes per stored coordinate (2 / 3 / 4).
262    #[must_use]
263    pub const fn bytes(self) -> usize {
264        (self as usize) / 8
265    }
266
267    /// The width a header byte names, if any.
268    #[must_use]
269    pub const fn from_byte(byte: u8) -> Option<QuantBits> {
270        match byte {
271            16 => Some(QuantBits::Bits16),
272            24 => Some(QuantBits::Bits24),
273            32 => Some(QuantBits::Bits32),
274            _ => None,
275        }
276    }
277}
278
279/// The geometry encoding, which decides how an asset stores its polygons
280/// and how lookups read them.
281///
282/// The three polygon encodings answer bit-identically; they trade storage
283/// for lookup speed. `Coarse` alone trades precision instead: it drops the
284/// polygons and answers at grid-cell precision.
285///
286/// The measured cost/speed ladder lives here. Every other doc site links
287/// back to this table rather than restating numbers. Size columns are
288/// whole assets relative to the `VarintArcs` build of the same preset;
289/// lookup speed is the flash-XIP (execute-in-place, zero RAM) leg of the
290/// embedded bench, against the same baseline.
291///
292/// | encoding         | geometry section                          |        raw | best-compressed | XIP lookup      |
293/// |------------------|-------------------------------------------|-----------:|----------------:|-----------------|
294/// | `VarintArcs`     | shared arcs, delta + zigzag-varint coords |         1× |              1× | 1×              |
295/// | `FixedWidthArcs` | shared arcs, absolute quant-width coords  |   1.4–1.7× |   1.15–1.3× (xz) | 1.3–1.5×        |
296/// | `FullRings`      | whole rings, absolute quant-width coords  |   2.1–3.2× |    1.4–2.1× (xz) | 2.0–3.3×        |
297/// | `Coarse`         | none (grid only)                          | 0.05–0.33× |     0.01–0.14× | grid probe only |
298///
299/// Narrow-quant `FullRings` XIP even outran the RAM preload cache on the
300/// embedded bench. On fixed-width payloads the codec ranking flips: xz
301/// overtakes brotli at every preset. `Coarse` shrinks with preset fineness
302/// twice over: the grid is all it keeps, and grids compress extremely well.
303///
304/// The size columns come from `utz_dev_cli whittle --extended` (2026-07,
305/// TZBB 2026c), measuring full assets per preset recipe against the
306/// `VarintArcs` build. The XIP
307/// lookup column is from the 2026-07 bench-firmware runs against earlier
308/// payload revisions; read it as a relative ladder.
309// TODO(verify): re-run the XIP lookup column on target against the
310// current payload revisions (last measured 2026-07 on earlier ones).
311#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Pread, Pwrite)]
312#[repr(u8)]
313pub enum GeomEncoding {
314    /// This encoding stores shared arcs as delta + zigzag-varint streams;
315    /// it is the default, for minimal storage size.
316    #[default]
317    VarintArcs = 0,
318    /// This encoding stores shared arcs as absolute fixed-width
319    /// (quant-width) coordinates, so streaming lookups no longer decode a
320    /// varint per vertex, the dominant lookup cost on embedded targets. It
321    /// reaches near-eager speed with no RAM cache and suits uncompressed
322    /// `-static` assets read in place from memory-mapped flash, at a
323    /// storage cost (table above).
324    FixedWidthArcs = 1,
325    /// This encoding stores each ring in full: coordinates are flattened
326    /// per ring as quant-width pairs plus ring/poly index tables, 4-byte
327    /// aligned; it is the preload cache serialized. Slice kernels read it
328    /// in place: from memory-mapped flash via `from_static()`
329    /// (eager-lookup speed with no RAM cache and no preload pass at boot)
330    /// or from the decompressed buffer via `from_slice()`. There is no arc
331    /// store, so borders shared between zones are duplicated per ring,
332    /// making this the largest encoding (table above). It works on
333    /// little-endian hosts only.
334    FullRings = 2,
335    /// A grid-only asset carrying the header, tzid pool, parent table,
336    /// and grid, with no geometry at all. `lookup()` answers at cell
337    /// precision, the same answer `lookup_coarse()` gives; precision is a
338    /// property of the asset, like `epsilon_m`. It is by far the smallest
339    /// storage (table above) and works on any endianness, and a reader
340    /// built only for coarse assets compiles no point-in-polygon code.
341    Coarse = 3,
342}
343
344impl GeomEncoding {
345    /// The canonical CLI name (`varint-arcs`, `fixed-width-arcs`,
346    /// `full-rings`, or `coarse`), a spelling
347    /// [`from_name()`](GeomEncoding::from_name) accepts.
348    #[must_use]
349    pub const fn name(self) -> &'static str {
350        match self {
351            GeomEncoding::VarintArcs => "varint-arcs",
352            GeomEncoding::FixedWidthArcs => "fixed-width-arcs",
353            GeomEncoding::FullRings => "full-rings",
354            GeomEncoding::Coarse => "coarse",
355        }
356    }
357
358    /// The encoding a name selects, the inverse of
359    /// [`name()`](GeomEncoding::name).
360    #[must_use]
361    pub fn from_name(name: &str) -> Option<GeomEncoding> {
362        match name {
363            "varint-arcs" => Some(GeomEncoding::VarintArcs),
364            "fixed-width-arcs" => Some(GeomEncoding::FixedWidthArcs),
365            "full-rings" => Some(GeomEncoding::FullRings),
366            "coarse" => Some(GeomEncoding::Coarse),
367            _ => None,
368        }
369    }
370
371    /// The encoding a header byte names, if any.
372    #[must_use]
373    pub const fn from_byte(byte: u8) -> Option<GeomEncoding> {
374        match byte {
375            0 => Some(GeomEncoding::VarintArcs),
376            1 => Some(GeomEncoding::FixedWidthArcs),
377            2 => Some(GeomEncoding::FullRings),
378            3 => Some(GeomEncoding::Coarse),
379            _ => None,
380        }
381    }
382}
383
384#[cfg_attr(
385    on_docsrs,
386    doc = "[`utz_simplify`]: https://docs.rs/utz_simplify/latest/utz_simplify/index.html"
387)]
388#[cfg_attr(on_docsrs, doc = "")]
389/// The simplification algorithm records which simplifier the encoder ran
390/// when the asset was generated. Each variant sketches its algorithm;
391/// guarantees, citations, and the density-weighted variants are
392/// documented in the [`utz_simplify`] crate.
393///
394/// RDP is the default because I had the best results with it when combined with
395/// the population density weighting. But your mileage may vary, so I kept the
396/// algorithms in for people to play with.
397///
398/// [`utz_simplify`]: ../utz_simplify/index.html
399#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Pread, Pwrite)]
400#[repr(u8)]
401pub enum SimplifyAlgorithm {
402    /// No simplification runs; the geometry is stored as sourced.
403    None = 0,
404    /// Ramer–Douglas–Peucker keeps every point within a maximum deviation
405    /// of ε. This is the default.
406    #[default]
407    Rdp = 1,
408    /// Visvalingam–Whyatt repeatedly drops the vertex spanning the
409    /// smallest triangle, trading RDP's deviation bound for a
410    /// cartographically smoother caricature; the ε-driven pipeline
411    /// derives its area threshold as ε², matching the viewer.
412    Visvalingam = 2,
413    /// Imai–Iri produces provably minimum vertices for the same ε bound
414    /// as RDP, at a slower encode. Measured against RDP on full-planet
415    /// arcs it keeps 3.8% fewer vertices at ε = 100 m, rising to 18–19%
416    /// fewer at ε = 500–2000 m; a full-pipeline check at ε = 2000 m
417    /// produced a 12.6% smaller compressed asset for about four seconds
418    /// of extra encode time.
419    ImaiIri = 3,
420}
421
422impl SimplifyAlgorithm {
423    /// The canonical CLI name (`none|rdp|vw|ii`), a spelling
424    /// [`from_name()`](SimplifyAlgorithm::from_name) accepts.
425    #[must_use]
426    pub const fn name(self) -> &'static str {
427        match self {
428            SimplifyAlgorithm::None => "none",
429            SimplifyAlgorithm::Rdp => "rdp",
430            SimplifyAlgorithm::Visvalingam => "vw",
431            SimplifyAlgorithm::ImaiIri => "ii",
432        }
433    }
434
435    /// The algorithm a name selects: the canonical names plus the long
436    /// `visvalingam` and `imai-iri` aliases.
437    #[must_use]
438    pub fn from_name(name: &str) -> Option<SimplifyAlgorithm> {
439        match name {
440            "none" => Some(SimplifyAlgorithm::None),
441            "rdp" => Some(SimplifyAlgorithm::Rdp),
442            "vw" | "visvalingam" => Some(SimplifyAlgorithm::Visvalingam),
443            "ii" | "imai-iri" => Some(SimplifyAlgorithm::ImaiIri),
444            _ => None,
445        }
446    }
447
448    /// The algorithm a header byte names, if any.
449    #[must_use]
450    pub const fn from_byte(byte: u8) -> Option<SimplifyAlgorithm> {
451        match byte {
452            0 => Some(SimplifyAlgorithm::None),
453            1 => Some(SimplifyAlgorithm::Rdp),
454            2 => Some(SimplifyAlgorithm::Visvalingam),
455            3 => Some(SimplifyAlgorithm::ImaiIri),
456            _ => None,
457        }
458    }
459}
460
461/// The dataset an asset was built from, naming a
462/// [timezone-boundary-builder] release as a zone set × ocean coverage
463/// pair. The zone set trades zone count for historical fidelity: `now`
464/// and `1970` merge zones whose rules are identical since that date,
465/// and `all` keeps every distinct tzid. Ocean coverage decides whether
466/// maritime timezones tile the rest of the planet or queries at sea
467/// return `None`. (The discriminants keep the wire bitfield: the zone
468/// set lives in bits 0–1, and a set bit 2 means land-only.)
469///
470/// [timezone-boundary-builder]: https://github.com/evansiroky/timezone-boundary-builder
471#[derive(Debug, Clone, Copy, PartialEq, Eq, Pread, Pwrite)]
472#[repr(u8)]
473pub enum Dataset {
474    /// Zones whose rules are identical from today onward are merged and
475    /// the oceans are covered. This is the smallest set, and the preset
476    /// default.
477    Now = 0,
478    /// Zones identical since 1970 are merged and the oceans are covered,
479    /// which is enough to resolve any post-1970 civil time correctly.
480    Since1970 = 1,
481    /// Every distinct tzid is kept and the oceans are covered, giving
482    /// full historical fidelity; this is the largest set.
483    All = 2,
484    /// This is `Now` without maritime zones, so queries at sea return
485    /// `None`.
486    NowLandOnly = 4,
487    /// This is `Since1970` without maritime zones.
488    Since1970LandOnly = 5,
489    /// This is `All` without maritime zones.
490    AllLandOnly = 6,
491}
492
493impl Dataset {
494    /// Returns the canonical dataset name (`now`, `1970`, or `all`, with
495    /// a `land-` prefix for the land-only variants), the spelling the
496    /// builder's dataset parser accepts.
497    #[must_use]
498    pub const fn name(self) -> &'static str {
499        match self {
500            Dataset::Now => "now",
501            Dataset::Since1970 => "1970",
502            Dataset::All => "all",
503            Dataset::NowLandOnly => "land-now",
504            Dataset::Since1970LandOnly => "land-1970",
505            Dataset::AllLandOnly => "land-all",
506        }
507    }
508
509    /// The zone-set half of the name (`"now"`, `"1970"`, or `"all"`),
510    /// which picks how aggressively zones with identical rules are
511    /// merged.
512    #[must_use]
513    pub const fn zone_set(self) -> &'static str {
514        match self {
515            Dataset::Now | Dataset::NowLandOnly => "now",
516            Dataset::Since1970 | Dataset::Since1970LandOnly => "1970",
517            Dataset::All | Dataset::AllLandOnly => "all",
518        }
519    }
520
521    /// Whether maritime timezones cover the oceans (`false` names the
522    /// `land-` releases).
523    #[must_use]
524    pub const fn oceans(self) -> bool {
525        matches!(self, Dataset::Now | Dataset::Since1970 | Dataset::All)
526    }
527
528    /// The dataset a name selects (`[land-]now|1970|all`; `full` and
529    /// `comprehensive`, TZBB's own word for the unsuffixed release, are
530    /// accepted for `all`). This is the inverse of
531    /// [`name()`](Dataset::name), kept beside it so the two spellings
532    /// cannot drift apart.
533    #[must_use]
534    pub fn from_name(name: &str) -> Option<Dataset> {
535        let (land_only, rest) = match name.strip_prefix("land-") {
536            Some(stripped) => (true, stripped),
537            None => (false, name),
538        };
539        match (rest, land_only) {
540            ("now", false) => Some(Dataset::Now),
541            ("now", true) => Some(Dataset::NowLandOnly),
542            ("1970", false) => Some(Dataset::Since1970),
543            ("1970", true) => Some(Dataset::Since1970LandOnly),
544            ("all" | "full" | "comprehensive", false) => Some(Dataset::All),
545            ("all" | "full" | "comprehensive", true) => Some(Dataset::AllLandOnly),
546            _ => None,
547        }
548    }
549
550    /// The dataset a header byte names, if any.
551    #[must_use]
552    pub const fn from_byte(byte: u8) -> Option<Dataset> {
553        match byte {
554            0 => Some(Dataset::Now),
555            1 => Some(Dataset::Since1970),
556            2 => Some(Dataset::All),
557            4 => Some(Dataset::NowLandOnly),
558            5 => Some(Dataset::Since1970LandOnly),
559            6 => Some(Dataset::AllLandOnly),
560            _ => None,
561        }
562    }
563}
564
565/// The compression applied to an asset's payload. The encoder picks one
566/// codec; loading the asset needs the matching decoder compiled in.
567#[derive(Clone, Copy, PartialEq, Eq, Debug, Pread, Pwrite)]
568#[repr(u8)]
569pub enum Codec {
570    Uncompressed = 0,
571    Gzip = 1,
572    Zstd = 2,
573    Brotli = 3,
574    Xz = 4,
575}
576
577impl Codec {
578    /// The canonical CLI name (`none|gzip|zstd|brotli|xz`), a spelling
579    /// [`from_name()`](Codec::from_name) accepts.
580    #[must_use]
581    pub const fn name(self) -> &'static str {
582        match self {
583            Codec::Uncompressed => "none",
584            Codec::Gzip => "gzip",
585            Codec::Zstd => "zstd",
586            Codec::Brotli => "brotli",
587            Codec::Xz => "xz",
588        }
589    }
590
591    /// The codec a name selects: the canonical names plus the
592    /// `uncompressed` alias.
593    #[must_use]
594    pub fn from_name(name: &str) -> Option<Codec> {
595        match name {
596            "none" | "uncompressed" => Some(Codec::Uncompressed),
597            "gzip" => Some(Codec::Gzip),
598            "zstd" => Some(Codec::Zstd),
599            "brotli" => Some(Codec::Brotli),
600            "xz" => Some(Codec::Xz),
601            _ => None,
602        }
603    }
604
605    /// The codec a header byte names, if any.
606    #[must_use]
607    pub const fn from_byte(byte: u8) -> Option<Codec> {
608        match byte {
609            0 => Some(Codec::Uncompressed),
610            1 => Some(Codec::Gzip),
611            2 => Some(Codec::Zstd),
612            3 => Some(Codec::Brotli),
613            4 => Some(Codec::Xz),
614            _ => None,
615        }
616    }
617}
618
619/// Knuth's MMIX LCG multiplier (TAOCP vol. 2, 3rd ed., §3.3.4 table 1).
620pub const MMIX_MUL: u64 = 0x5851_F42D_4C95_7F2D; // 6_364_136_223_846_793_005
621/// Knuth's MMIX LCG increment.
622pub const MMIX_ADD: u64 = 0x1405_7B7E_F767_814F; // 1_442_695_040_888_963_407
623
624/// A minimal MMIX LCG for reproducible test/bench data (not for
625/// cryptography). Callers keep their own seeds so historical sequences
626/// stay bit-identical.
627pub struct Lcg(pub u64);
628
629impl Lcg {
630    #[must_use]
631    pub fn new(seed: u64) -> Self {
632        Self(seed)
633    }
634
635    /// Advances and returns the full 64-bit state.
636    pub fn next_u64(&mut self) -> u64 {
637        self.0 = self.0.wrapping_mul(MMIX_MUL).wrapping_add(MMIX_ADD);
638        self.0
639    }
640
641    /// Returns a uniform value in [0, 1) via a 53-bit mantissa
642    /// construction.
643    #[expect(
644        clippy::cast_precision_loss,
645        reason = "53-bit mantissa construction: state>>11 < 2^53 and 2^53 are both exact"
646    )]
647    pub fn unit_f64(&mut self) -> f64 {
648        (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64
649    }
650}
651
652/// The workspace-wide seed for `gen_pts()` point sampling. Every bench
653/// and measurement command draws the same point sequence from it, so
654/// lookup numbers stay comparable across tools.
655pub const POINT_SEED: u64 = 0x1234_5678;
656
657/// The workspace-wide seed for pseudo-random payload bytes in codec
658/// roundtrip tests (ASCII `uztrip`).
659pub const PAYLOAD_SEED: u64 = 0x757a_7472_6970;
660
661/// Generates `count` uniform world points `(lon, lat)` from `seed`. This
662/// is the shared sampler behind the measurement commands and benches: the
663/// same seed gives the same points, so numbers stay comparable across
664/// tools.
665#[cfg(feature = "alloc")]
666#[must_use]
667pub fn gen_pts(seed: u64, count: usize) -> Vec<(f64, f64)> {
668    let mut lcg = Lcg::new(seed);
669    (0..count)
670        .map(|_| {
671            (
672                lcg.unit_f64() * 360.0 - 180.0,
673                lcg.unit_f64() * 180.0 - 90.0,
674            )
675        })
676        .collect()
677}
678
679#[cfg(test)]
680mod tests {
681    use scroll::{LE, Pread, Pwrite};
682
683    use super::{
684        Codec, Dataset, GeomEncoding, PAYLOAD_HEADER_LEN, PayloadHeader, QuantBits,
685        SimplifyAlgorithm,
686    };
687
688    #[test]
689    fn enum_names_round_trip_through_from_name() {
690        for dataset in [
691            Dataset::Now,
692            Dataset::Since1970,
693            Dataset::All,
694            Dataset::NowLandOnly,
695            Dataset::Since1970LandOnly,
696            Dataset::AllLandOnly,
697        ] {
698            assert_eq!(Dataset::from_name(dataset.name()), Some(dataset));
699        }
700        for codec in [
701            Codec::Uncompressed,
702            Codec::Gzip,
703            Codec::Zstd,
704            Codec::Brotli,
705            Codec::Xz,
706        ] {
707            assert_eq!(Codec::from_name(codec.name()), Some(codec));
708        }
709        for algorithm in [
710            SimplifyAlgorithm::None,
711            SimplifyAlgorithm::Rdp,
712            SimplifyAlgorithm::Visvalingam,
713            SimplifyAlgorithm::ImaiIri,
714        ] {
715            assert_eq!(
716                SimplifyAlgorithm::from_name(algorithm.name()),
717                Some(algorithm)
718            );
719        }
720        for geom in [
721            GeomEncoding::VarintArcs,
722            GeomEncoding::FixedWidthArcs,
723            GeomEncoding::FullRings,
724            GeomEncoding::Coarse,
725        ] {
726            assert_eq!(GeomEncoding::from_name(geom.name()), Some(geom));
727        }
728        assert_eq!(
729            Dataset::from_name("land-1970"),
730            Some(Dataset::Since1970LandOnly)
731        );
732        assert_eq!(Dataset::from_name("nowhere"), None);
733        // pre-publish legacy spellings are gone
734        assert_eq!(Dataset::from_name("osm"), None);
735        assert_eq!(Dataset::from_name("osm1970"), None);
736        assert_eq!(GeomEncoding::from_name("eager"), None);
737        assert_eq!(GeomEncoding::from_name("varint"), None);
738    }
739
740    #[test]
741    fn payload_header_round_trips_at_declared_length() {
742        let header = PayloadHeader {
743            arcs_off: 1,
744            rings_off: 2,
745            grid_off: 3,
746            release_off: 4,
747            eager_coords: 5,
748            eager_rings: 6,
749            eager_polys: 7,
750            n_arcs: 8,
751            raw_len: 14,
752            grid_deg: 0.5,
753            epsilon_m: 50.0,
754            n_features: 9,
755            ncols: 10,
756            nrows: 11,
757            uniq: 12,
758            release_len: 13,
759            flags: 0,
760            dataset: Dataset::Now,
761            quant_bits: QuantBits::Bits24,
762            simplify_algorithm: SimplifyAlgorithm::Rdp,
763            geom: GeomEncoding::FixedWidthArcs,
764            codec: Codec::Brotli,
765            density_weight_floor_e4: 200,
766            reserved: 0,
767        };
768        let mut bytes = [0u8; PAYLOAD_HEADER_LEN];
769        let written = bytes
770            .pwrite_with(header, 0, LE)
771            .expect("buffer sized to the declared length");
772        assert_eq!(written, PAYLOAD_HEADER_LEN);
773        let read: PayloadHeader = bytes
774            .pread_with(0, LE)
775            .expect("round-trip read of a full buffer");
776        assert_eq!(read, header);
777    }
778
779    #[test]
780    fn invalid_header_byte_fails_the_read() {
781        let header = PayloadHeader {
782            arcs_off: 0,
783            rings_off: 0,
784            grid_off: 0,
785            release_off: 0,
786            eager_coords: 0,
787            eager_rings: 0,
788            eager_polys: 0,
789            n_arcs: 0,
790            raw_len: 0,
791            grid_deg: 1.0,
792            epsilon_m: 0.0,
793            n_features: 0,
794            ncols: 0,
795            nrows: 0,
796            uniq: 0,
797            release_len: 0,
798            flags: 0,
799            dataset: Dataset::Now,
800            quant_bits: QuantBits::Bits16,
801            simplify_algorithm: SimplifyAlgorithm::None,
802            geom: GeomEncoding::VarintArcs,
803            codec: Codec::Uncompressed,
804            density_weight_floor_e4: 0,
805            reserved: 0,
806        };
807        let mut bytes = [0u8; PAYLOAD_HEADER_LEN];
808        bytes
809            .pwrite_with(header, 0, LE)
810            .expect("buffer sized to the declared length");
811        bytes[57] = 17; // quant_bits: no such width
812        assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
813        bytes[57] = 16;
814        bytes[56] = 3; // dataset: zone-set code 3 is unassigned
815        assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
816        bytes[56] = 0;
817        bytes[60] = 9; // codec: no such codec
818        assert!(bytes.pread_with::<PayloadHeader>(0, LE).is_err());
819    }
820}