Skip to main content

Crate utz_common

Crate utz_common 

Source
Expand description

This crate holds the types and utilities shared across the workspace: the asset codec identifiers, the payload header record that both the encoder and the reader serialize through, and the deterministic LCG behind every reproducible test/bench sampler.

Modules§

presets
The canonical preset recipe table. Every preset asset the workspace ships is described here exactly once, as a Recipe constant; the builder presets (utz_build::Config), the gen-preset command, and the data crates’ recipe guards all consume this table instead of restating the numbers.

Structs§

Lcg
A minimal MMIX LCG for reproducible test/bench data (not for cryptography). Callers keep their own seeds so historical sequences stay bit-identical.
PayloadHeader
The container’s one fixed header record, which carries everything the reader needs to locate every section. It sits in PLAINTEXT right after the outer header (only the section blob after it is compressed), so any container is inspectable and validated before decompression. The encoder Pwrites it, the reader Preads it (both little-endian); field order is the wire order; all offsets are relative to the section blob that follows.

Enums§

CellTag
One decoded primary-grid cell. The wire form is the u16 the constants above describe; this decoder is shared by the runtime lookup, the format validator, and the encoder’s measurement tools, so the tag layout is interpreted in exactly one place.
Codec
The compression applied to an asset’s payload. The encoder picks one codec; loading the asset needs the matching decoder compiled in.
Dataset
The dataset an asset was built from, naming a timezone-boundary-builder release as a zone set × ocean coverage pair. The zone set trades zone count for historical fidelity: now and 1970 merge zones whose rules are identical since that date, and all keeps every distinct tzid. Ocean coverage decides whether maritime timezones tile the rest of the planet or queries at sea return None. (The discriminants keep the wire bitfield: the zone set lives in bits 0–1, and a set bit 2 means land-only.)
GeomEncoding
The geometry encoding, which decides how an asset stores its polygons and how lookups read them.
QuantBits
The coordinate quantization width, which is how many bits each stored coordinate occupies (the wire value IS the bit count).
SimplifyAlgorithm
The simplification algorithm records which simplifier the encoder ran when the asset was generated. Each variant sketches its algorithm; guarantees, citations, and the density-weighted variants are documented in the utz_simplify crate.

Constants§

BORDER_FLAG
A primary-grid cell’s border flag: the u16’s high bit set means the low 15 bits index a candidate list instead of naming a zone.
CELL_ID_MASK
The mask selecting a primary-grid cell’s 15-bit value, a zone id or (under BORDER_FLAG) a candidate-list index. Zone ids and list indices stay strictly below NO_ZONE, the all-bits-set sentinel.
KM_PER_DEG
Kilometers per degree, METERS_PER_DEG scaled; area math uses KM_PER_DEG² (with a latitude cosine) for km² per square degree.
MAGIC
The magic bytes every .utz asset starts with. The bytes are ASCII on purpose (“μ” is 2 bytes in UTF-8 and byte literals reject non-ASCII): the project brands itself as μTZ, and the container as uTZ1.
METERS_PER_DEG
Meters per degree of latitude (and of longitude at the equator): the workspace’s one flat conversion between tolerances in meters (epsilon_m) and coordinate degrees.
MMIX_ADD
Knuth’s MMIX LCG increment.
MMIX_MUL
Knuth’s MMIX LCG multiplier (TAOCP vol. 2, 3rd ed., §3.3.4 table 1).
NO_ZONE
The primary grid table’s “no zone covers this cell” marker (all 15 id bits set). Zone/feature ids stay strictly below it; the u16’s high bit flags a border cell carrying a candidate-list index instead.
PAYLOAD_HEADER_LEN
PayloadHeader’s serialized size. The section blob starts at PROLOGUE_LEN + PAYLOAD_HEADER_LEN.
PAYLOAD_SEED
The workspace-wide seed for pseudo-random payload bytes in codec roundtrip tests (ASCII uztrip).
POINT_SEED
The workspace-wide seed for gen_pts() point sampling. Every bench and measurement command draws the same point sequence from it, so lookup numbers stay comparable across tools.
PROLOGUE_LEN
The byte length of the container prologue, which is MAGIC (4), VERSION (1), and 3 reserved bytes. The prologue is the only part of the format whose layout is frozen across versions; everything after it is VERSION-specific.
VERSION
The container-format version this workspace reads and writes; a reader refuses any other value.

Functions§

dq_lat
Dequantizes a latitude from a grid with half-range qmax, the inverse of q_lat().
dq_lon
Dequantizes a longitude from a grid with half-range qmax, the inverse of q_lon(). The input is f64 so fractional grid positions (e.g. ring intersection points) dequantize too; stored coordinates pass through f64::from.
gen_ptsalloc
Generates count uniform world points (lon, lat) from seed. This is the shared sampler behind the measurement commands and benches: the same seed gives the same points, so numbers stay comparable across tools.
grid_cell
The primary-grid cell containing a lon/lat position, as (row, col): truncate toward zero, then clamp into the grid. The encoder’s rasterizer, the runtime reader, and the measurement tools all share this one formula, so what a lookup probes is exactly what the grid indexed.
q_lat
Quantizes a latitude onto a grid with half-range qmax.
q_lon
Quantizes a longitude onto a grid with half-range qmax (see qmax_for()).
qmax_for
The half-range of an i{bits} quantization grid (2^(bits-1) - 1).