Skip to main content

hpr_flightdata/
gpx.rs

1//! GPX files, the GPS Exchange Format, holding the tracks a GPS receiver, a phone app or a mapping
2//! tool recorded, in version 1.0 or 1.1 of the format Topografix publishes.
3//!
4//! GPX is XML. Its root element `gpx` states its `version` and the program that wrote it
5//! (`creator`), then holds waypoints (`wpt`), routes (`rte`, each a list of `rtept`) and tracks
6//! (`trk`). A track is a list of segments (`trkseg`), each a list of track points (`trkpt`):
7//!
8//! ```text
9//! <gpx version="1.1" creator="…" xmlns="http://www.topografix.com/GPX/1/1">
10//!   <trk><name>Flight 7</name>
11//!     <trkseg>
12//!       <trkpt lat="35.2000120" lon="-97.1000340">
13//!         <ele>402.0</ele><time>2031-07-14T17:04:04.000Z</time><sat>11</sat><hdop>0.8</hdop>
14//!       </trkpt>
15//!     </trkseg>
16//!   </trk>
17//! </gpx>
18//! ```
19//!
20//! **What the sources set.** Topografix's schemas, *GPX 1.0* (topografix.com/GPX/1/0/gpx.xsd) and
21//! *GPX 1.1* (topografix.com/GPX/1/1/gpx.xsd), and GPX 1.0's manual
22//! (topografix.com/gpx_manual.asp). GPX 1.0's schema holds types and no documentation, so the words
23//! quoted here are GPX 1.1's schema's; GPX 1.0's manual says the same of each element it describes.
24//! A point's `lat` and `lon` are in "Decimal degrees, WGS84 datum", the latitude from −90 to 90 and
25//! the longitude from −180 to 180 (both schemas' types: 1.1 leaves out 180 itself, 1.0 doesn't;
26//! this reader takes 180, the same meridian as −180). Its `ele` is the "Elevation (in meters) of
27//! the point", with no datum of its own. GPX 1.1's schema opens with "all coordinates are relative
28//! to the WGS84 datum", which could be read as heights above the WGS84 ellipsoid, but it doesn't
29//! say so of `ele`, nor does the manual, and neither says whether a writer's elevation is above
30//! that ellipsoid, above mean sea level or from a barometer. A point's `geoidheight` is the geoid's
31//! height above the WGS84 ellipsoid, "as defined in NMEA GGA message". A point's `time` is an XML
32//! Schema `dateTime`, and "Date and time in are in Univeral \[sic\] Coordinated Time (UTC), not
33//! local time!" `sat` is the "Number of satellites used to calculate the GPX fix", `hdop`, `vdop`
34//! and `pdop` its dilutions of precision, and a `fix` of "none means GPS had no fix". In GPX 1.0 a
35//! track point may also hold `course`, in "degrees, true", and `speed`, in "meters per second" (the
36//! manual); GPX 1.1 dropped both. A track segment "holds a list of Track Points which are logically
37//! connected in order. To represent a single GPS track where GPS reception was lost, or the GPS
38//! receiver was turned off, start a new Track Segment for each continuous span of track data."
39//!
40//! **Tracks and channels.** A GPX file holds tracks of positions, not an altimeter's record over
41//! time, so the record's primary track is empty and every value is a channel, with a note, as the
42//! GPS logs' decision, [ADR-254][adr-254] §2, has it. Each track segment is a GPS track, its
43//! channels named after its track's `name`, or `track` if it has none; the segments of a track
44//! with several are numbered, `<name> segment 2`, by their place in the track, and a name already
45//! used gains ` (2)`, ` (3)` …, so no two segments share a name:
46//!
47//! | Channel | Quantity | From |
48//! |---|---|---|
49//! | `<name> latitude`, `<name> longitude` | [`Quantity::Latitude`], [`Quantity::Longitude`] | `lat`, `lon` |
50//! | `<name> elevation` | [`Quantity::Altitude`], m | `ele`: an altitude whose datum the file doesn't state |
51//! | `<name> satellites` | [`Quantity::Number`] | `sat` |
52//! | `<name> HDOP`, `<name> VDOP`, `<name> PDOP` | [`Quantity::Number`] | `hdop`, `vdop`, `pdop` |
53//! | `<name> geoid height` | [`Quantity::Distance`], m | `geoidheight`: the geoid above the WGS84 ellipsoid, NMEA's geoid separation |
54//! | `<name> speed` | [`Quantity::Speed`], m/s | GPX 1.0's `speed` |
55//! | `<name> course` | [`Quantity::Angle`], ° from true north | GPX 1.0's `course` |
56//!
57//! A channel is there only if some point of its segment holds its element; a point that lacks it,
58//! or holds it empty, such as `<ele/>`, is a gap, `NaN`, the empty ones counted in a note. The
59//! rest of a point (`magvar`, `fix`, its names and descriptions, `extensions`, other namespaces'
60//! elements, and a waypoint's or route point's `geoidheight`) is counted in a note and not read.
61//! The elevation is [`Quantity::Altitude`], not [`Quantity::GnssAltitude`], whose altitude is
62//! above mean sea level as the receiver states it: a GPX file states neither the datum nor the
63//! sensor, so only the rise from one point to another means what it says.
64//!
65//! **What `ele` most likely holds** (sources read 2026-10-17 to 2026-10-23). A receiver's NMEA GGA
66//! sentence gives the antenna's altitude above mean sea level, the geoid, and the geoid's
67//! separation from the WGS84 ellipsoid (gpsd's NMEA notes, gpsd.gitlab.io/gpsd/NMEA.html; u-blox's
68//! M10 interface description, UBX-21035062 R03, GGA `alt`, "Altitude above mean sea level"). Phones
69//! differ: Android's `Location.getAltitude()` is above the WGS84 ellipsoid, iOS's
70//! `CLLocation.altitude` above mean sea level, and a handheld with a barometer may write the
71//! barometer's altitude. GPSLogger for Android wrote 7 of 10 GPX files with `geoidheight` opened on
72//! GitHub. Its sea-level option "subtracts the geoidheight from the reported altitude" (its FAQ,
73//! gpslogger.app), so with the option off it writes Android's ellipsoidal height; in three such
74//! files on clear terms, `ele` sits above SRTM's ground heights by about their `geoidheight`, and a
75//! fourth's is too small to tell (issue #645, 2026-10-20). The rocketry trackers checked export
76//! KML, CSV or NMEA, not GPX, and their manuals that state a datum say mean sea level (Missile
77//! Works' RTx/GPS manual, firmware 1.31; Featherweight's Swift manual, 2026-04-10). One Eggfinder
78//! track saved as GPX by MapSphere reads 6.7 to 7.4 m below the pad's terrain height as a sea-level
79//! height and 26 m above it as an ellipsoid's, so it most likely holds the GGA altitude, with
80//! moderate confidence ([a research note][eggfinder]). So `geoidheight` doesn't settle `ele`'s
81//! datum, and the reader's note says which writer does what. Either datum is off by an offset that
82//! barely changes over one flight: it moves the pad's elevation, not the height above the pad. A
83//! barometric `ele` would differ by an amount that grows with height.
84//!
85//! **Routes and waypoints** are places marked or planned, not flown, so they are kept apart from
86//! the tracks, as figures the file states ([`Stated::figures`]), each in the file's order: a
87//! waypoint's `waypoint <name> latitude`, `… longitude`, `… elevation` and `… time`, and a route
88//! point's `route <name> point <n> latitude` and so on, `<name>` the waypoint's or the route's
89//! `name`, or its place among the file's waypoints or routes, `waypoint 2`, if it has none. A time
90//! is in seconds from the log's zero, [`Quantity::Duration`]. No reading takes them for the flight.
91//!
92//! **Times.** A point's time is its `time`, in UTC: one that states an offset from UTC, such as
93//! `-04:00`, is moved to UTC; one that states no zone is read as UTC, as GPX 1.1's schema and
94//! GPX 1.0's manual say every time is, with a note counting them. The log's zero is the first
95//! time the file gives a track point, or, with none, a waypoint or route point, and a note names
96//! it. A track point with no time keeps its place with its time a gap, `NaN`. Times within a
97//! track go forward, segment to segment: one that goes back is refused by name, as such a track
98//! isn't one recording. Two tracks may run in any order, as a file holding two flights does. A
99//! second written 60, a leap second's, reads as the next minute's first, as in the KML reader;
100//! no sample holds one.
101//!
102//! **Refused by name.** A document type declaration, so that no entity can expand, and a reference
103//! to an entity XML doesn't define; a root that isn't `gpx`, or whose namespace or `version` isn't
104//! GPX 1.0's or 1.1's, or whose namespace and `version` disagree; a point with no `lat` or `lon`,
105//! or one off the globe (its latitude past ±90° or longitude past ±180°, once read to the nearest
106//! double); a value that isn't the schema's kind of number (`ele` and the rest are XML Schema
107//! `decimal`s, written with no exponent; `sat` is a whole number); a `course` outside 0° to
108//! 360°; a point holding one of the elements read twice; a `time` that isn't a date and time;
109//! and a time that goes back within a track. Each names what it found and its line: a
110//! point's, or the declaration's, the root's, or the line where the nesting passes the bound
111//! (a file of too many nodes is refused at line 1, as the parser gives that refusal no place).
112//!
113//! **Hostile input.** `roxmltree` parses the XML, with its default refusal of a document type
114//! declaration and a limit of [`MAX_NODES`] nodes. The parser descends the tree on the stack, so
115//! the text's nesting is counted first, as the KML reader's is ([`crate::kml`]), and a file
116//! nesting elements deeper than [`MAX_DEPTH`] is refused. At most [`MAX_TRACKS`] segments,
117//! [`MAX_POINTS`] track points and [`MAX_PLACES`] waypoints and route points are read, the rest
118//! counted in a note; names are cut to the length a note quotes, and the note listing what isn't
119//! read names at most [`MAX_UNREAD_NAMES`] elements.
120//!
121//! **Where this comes from, and how far to trust it.** The schemas and the manual as cited; no GPX
122//! reader was ported. No sample log in the project's collection is a GPX file, so the reader is
123//! checked on invented files only, every value against gpxpy 1.6.2 (Apache-2.0), run as an outside
124//! reader (`validation/oracles/gpx/gpxpy_read.py`). One real rocket track, read for the research
125//! note above, points to a sea-level `ele`, with moderate confidence (one app, one pad). No rocket
126//! flight's GPX with `geoidheight` has been seen, so the note on `geoidheight` rests on
127//! GPSLogger's documentation and files, none of them a flight.
128//!
129//! [adr-254]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/decisions/0254-gps-tracks-first-among-the-other-importers.md
130//! [eggfinder]: https://github.com/nrdptel/fusionspace-eridanus/blob/main/docs/research/forum-eggfinder-gpx-vs-baro.md
131
132use std::collections::{BTreeMap, HashMap, HashSet};
133
134use roxmltree::{Document, Node, ParsingOptions};
135
136use crate::error::LogError;
137use crate::kml::{self, Clock};
138use crate::log::{Channel, Figure, FlightLog, LogFormat, Quantity, Stated};
139use crate::table::short;
140
141/// The format's name in errors.
142const FORMAT: &str = "GPX";
143
144/// The namespace of GPX 1.0's elements.
145const NAMESPACE_10: &str = "http://www.topografix.com/GPX/1/0";
146
147/// The namespace of GPX 1.1's elements.
148const NAMESPACE_11: &str = "http://www.topografix.com/GPX/1/1";
149
150/// The most track segments read from one file, each a track; past it, the rest are counted in a
151/// note.
152pub const MAX_TRACKS: usize = 256;
153
154/// The most track points read from one file, over all its segments; past it, the rest are counted
155/// in a note.
156pub const MAX_POINTS: usize = 1_000_000;
157
158/// The most waypoints and route points read from one file, together; past it, the rest are
159/// counted in a note. Each gives up to four figures.
160pub const MAX_PLACES: usize = 10_000;
161
162/// The most XML nodes the parser builds for one file, so a file of many tiny elements can't fill
163/// memory. A track point with its elevation, time, satellite count and three dilutions of
164/// precision is about 21 nodes, its whitespace included, so this holds some 190,000 such points,
165/// more than two days of a receiver writing once a second.
166pub const MAX_NODES: u32 = 4_000_000;
167
168/// The deepest the XML may nest its elements, as the KML reader's bound ([`kml::MAX_DEPTH`]):
169/// `roxmltree` descends the tree on the stack, so the nesting is counted before the text is
170/// parsed. A track point's `extensions` sit 5 deep (`gpx`, `trk`, `trkseg`, `trkpt`,
171/// `extensions`), an app's own elements a few more.
172pub const MAX_DEPTH: usize = kml::MAX_DEPTH;
173
174/// The most names of elements not read that the note listing them names; the rest are counted.
175pub const MAX_UNREAD_NAMES: usize = 16;
176
177/// Nanoseconds in a second.
178const NS_PER_S: i64 = 1_000_000_000;
179
180/// Whether the text is a GPX document, judged from its content, never the file's name: its root
181/// element is `gpx`, after an optional byte-order mark, XML declaration, comments and document
182/// type declaration. A file with a document type declaration is recognized so that [`read`]
183/// refuses it by name.
184pub(crate) fn recognizes(text: &str) -> bool {
185    kml::root_is(text, "gpx")
186}
187
188/// Reads a GPX file's tracks into a flight record, its waypoints and routes as figures it states.
189///
190/// # Errors
191///
192/// [`LogError::Syntax`] if the XML isn't well formed, declares a document type, refers to an entity
193/// XML doesn't define, nests elements deeper than [`MAX_DEPTH`] or holds more than [`MAX_NODES`]
194/// nodes; if its `version` is missing, isn't 1.0 or 1.1, or disagrees with its namespace; or if a
195/// point is refused (the module's documentation lists why), naming the element and its line.
196/// [`LogError::NotThisFormat`] if its root element isn't `gpx`, or is in a namespace that is
197/// neither GPX 1.0's nor 1.1's. [`LogError::NoData`] if it holds no track point.
198pub fn read(text: &str) -> Result<FlightLog, LogError> {
199    read_within(text, MAX_NODES, MAX_POINTS)
200}
201
202/// [`read`], parsing at most `max_nodes` XML nodes and reading at most `max_points` track points.
203fn read_within(text: &str, max_nodes: u32, max_points: usize) -> Result<FlightLog, LogError> {
204    let document = parse(text, max_nodes)?;
205    let root = document.root_element();
206    let version = version(&document, root)?;
207    let mut reader = Reader::new(&document, root.tag_name().namespace(), version);
208    reader.max_points = max_points;
209    for node in root.children() {
210        match reader.own_name(node) {
211            Some("wpt") => reader.waypoint(node)?,
212            Some("rte") => reader.route(node)?,
213            Some("trk") => reader.track(node)?,
214            _ => {}
215        }
216    }
217    reader.finish(root)
218}
219
220/// A syntax error at a line.
221fn syntax(line: usize, message: String) -> LogError {
222    LogError::Syntax {
223        format: FORMAT,
224        line,
225        message,
226    }
227}
228
229/// The text parsed as XML, once its nesting is found no deeper than [`MAX_DEPTH`], with at most
230/// `nodes` nodes and no document type declaration.
231fn parse(text: &str, nodes: u32) -> Result<Document<'_>, LogError> {
232    let (deepest, line) = kml::nesting(text);
233    if deepest > MAX_DEPTH {
234        return Err(syntax(
235            line,
236            format!(
237                "the XML nests elements {deepest} deep, past the {MAX_DEPTH} this reader reads, \
238                 so that the parser can't exhaust its stack"
239            ),
240        ));
241    }
242    let options = ParsingOptions {
243        nodes_limit: nodes,
244        ..ParsingOptions::default()
245    };
246    Document::parse_with_options(text, options).map_err(|error| {
247        let mut line = usize::try_from(error.pos().row).unwrap_or(usize::MAX);
248        // The parser places this refusal at the text's start; its declaration's line is found.
249        if matches!(error, roxmltree::Error::DtdDetected)
250            && let Some(offset) = kml::doctype_offset(text)
251        {
252            line = 1 + text[..offset].matches('\n').count();
253        }
254        let message = match &error {
255            roxmltree::Error::DtdDetected => "the file declares a document type, which this \
256                 reader refuses so that no entity can expand"
257                .to_owned(),
258            roxmltree::Error::UnknownEntityReference(name, _) => format!(
259                "the file refers to the entity `&{};`, which XML doesn't define: this reader \
260                 expands no entity a file declares",
261                short(name)
262            ),
263            roxmltree::Error::NodesLimitReached => {
264                format!("the file holds more than {nodes} XML nodes")
265            }
266            error => format!("the XML isn't well formed: {}", short(&error.to_string())),
267        };
268        syntax(line, message)
269    })
270}
271
272/// The 1-based line a node starts on.
273fn line_of(document: &Document<'_>, node: Node<'_, '_>) -> usize {
274    usize::try_from(document.text_pos_at(node.range().start).row).unwrap_or(usize::MAX)
275}
276
277/// A GPX version.
278#[derive(Debug, Clone, Copy, PartialEq, Eq)]
279enum Version {
280    V10,
281    V11,
282}
283
284impl Version {
285    fn name(self) -> &'static str {
286        match self {
287            Self::V10 => "1.0",
288            Self::V11 => "1.1",
289        }
290    }
291}
292
293/// The file's GPX version, from its root's `version`, which its namespace, if it states one, must
294/// agree with.
295fn version(document: &Document<'_>, root: Node<'_, '_>) -> Result<Version, LogError> {
296    if root.tag_name().name() != "gpx" {
297        return Err(LogError::NotThisFormat {
298            format: FORMAT,
299            message: format!(
300                "its root element is `{}`, not `gpx`",
301                short(root.tag_name().name())
302            ),
303        });
304    }
305    let by_namespace = match root.tag_name().namespace() {
306        None => None,
307        Some(NAMESPACE_10) => Some(Version::V10),
308        Some(NAMESPACE_11) => Some(Version::V11),
309        Some(other) => {
310            return Err(LogError::NotThisFormat {
311                format: FORMAT,
312                message: format!(
313                    "its root element `gpx` is in the namespace `{}`, neither GPX 1.0's nor 1.1's",
314                    short(other)
315                ),
316            });
317        }
318    };
319    let line = line_of(document, root);
320    let stated = match root.attribute("version") {
321        Some("1.0") => Version::V10,
322        Some("1.1") => Version::V11,
323        Some(other) => {
324            return Err(syntax(
325                line,
326                format!(
327                    "the `gpx` element's `version` is `{}`: this reader reads GPX 1.0 and 1.1",
328                    short(other)
329                ),
330            ));
331        }
332        None => {
333            return Err(syntax(
334                line,
335                "the `gpx` element states no `version`, which GPX 1.0 and 1.1 both require"
336                    .to_owned(),
337            ));
338        }
339    };
340    if let Some(by_namespace) = by_namespace
341        && by_namespace != stated
342    {
343        return Err(syntax(
344            line,
345            format!(
346                "the `gpx` element's `version` is {} but its namespace is GPX {}'s",
347                stated.name(),
348                by_namespace.name()
349            ),
350        ));
351    }
352    Ok(stated)
353}
354
355/// What kind of point an element is.
356#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
357enum Kind {
358    TrackPoint,
359    Waypoint,
360    RoutePoint,
361}
362
363impl Kind {
364    /// The element's name.
365    fn element(self) -> &'static str {
366        match self {
367            Self::TrackPoint => "trkpt",
368            Self::Waypoint => "wpt",
369            Self::RoutePoint => "rtept",
370        }
371    }
372
373    /// What it is, for notes: `count` of them.
374    fn counted(self, count: usize) -> String {
375        counted(
376            count,
377            match self {
378                Self::TrackPoint => "track point",
379                Self::Waypoint => "waypoint",
380                Self::RoutePoint => "route point",
381            },
382        )
383    }
384}
385
386/// A point's time.
387#[derive(Debug, Clone)]
388struct Stamp {
389    /// Nanoseconds since 1970-01-01T00:00:00 UTC.
390    ns: i64,
391    /// Whether the file stated its zone.
392    zoned: bool,
393    /// As written, cut to the length a note quotes.
394    written: String,
395    /// The byte offset of its element, for a refusal's line.
396    at: usize,
397}
398
399/// A number and its text as written, cut to the length a note quotes.
400#[derive(Debug, Clone)]
401struct Written {
402    value: f64,
403    text: String,
404}
405
406/// One point read.
407#[derive(Debug, Clone, Default)]
408struct Point {
409    lat: Option<Written>,
410    lon: Option<Written>,
411    ele: Option<Written>,
412    time: Option<Stamp>,
413    sat: Option<f64>,
414    hdop: Option<f64>,
415    vdop: Option<f64>,
416    pdop: Option<f64>,
417    geoidheight: Option<f64>,
418    speed: Option<f64>,
419    course: Option<f64>,
420}
421
422/// A channel's value at a point, `None` where the point holds none.
423type Pick = fn(&Point) -> Option<f64>;
424
425/// One track segment read.
426struct Segment {
427    /// Its track's name, or `track`.
428    track: String,
429    /// Its 1-based place in its track, if the track has several.
430    number: Option<usize>,
431    points: Vec<Point>,
432}
433
434/// One waypoint or route point read.
435struct Place {
436    /// `waypoint <name>` or `route <name> point <n>`, before the names are made unique.
437    label: String,
438    point: Point,
439}
440
441/// What the reader gathers over the file.
442struct Reader<'a, 'input> {
443    document: &'a Document<'input>,
444    namespace: Option<&'a str>,
445    version: Version,
446    segments: Vec<Segment>,
447    places: Vec<Place>,
448    tracks: usize,
449    waypoints: usize,
450    routes: usize,
451    points: usize,
452    empty_segments: usize,
453    empty_tracks: usize,
454    segments_left_out: usize,
455    segment_points_left_out: usize,
456    points_left_out: usize,
457    places_left_out: usize,
458    no_fix: usize,
459    /// Elements not read, by the kind of point and the element's name, at most
460    /// [`MAX_UNREAD_NAMES`] of them; other namespaces' elements under one entry.
461    unread: BTreeMap<(Kind, String), usize>,
462    /// Elements not read whose names are past those listed.
463    unread_left_out: usize,
464    /// Elements read that hold no value, by the kind of point and the element's name.
465    empty: BTreeMap<(Kind, &'input str), usize>,
466    /// The most track points read, [`MAX_POINTS`] but in tests.
467    max_points: usize,
468}
469
470impl<'a, 'input> Reader<'a, 'input> {
471    /// A reader of the document, whose root's namespace is GPX's.
472    fn new(document: &'a Document<'input>, namespace: Option<&'a str>, version: Version) -> Self {
473        Self {
474            document,
475            namespace,
476            version,
477            segments: Vec::new(),
478            places: Vec::new(),
479            tracks: 0,
480            waypoints: 0,
481            routes: 0,
482            points: 0,
483            empty_segments: 0,
484            empty_tracks: 0,
485            segments_left_out: 0,
486            segment_points_left_out: 0,
487            points_left_out: 0,
488            places_left_out: 0,
489            no_fix: 0,
490            unread: BTreeMap::new(),
491            unread_left_out: 0,
492            empty: BTreeMap::new(),
493            max_points: MAX_POINTS,
494        }
495    }
496
497    /// A node's name if it is an element in GPX's namespace, the root's.
498    fn own_name(&self, node: Node<'_, 'input>) -> Option<&'input str> {
499        (node.is_element() && node.tag_name().namespace() == self.namespace)
500            .then(|| node.tag_name().name())
501    }
502
503    /// The 1-based line of a byte offset, found only for a refusal: it counts the lines from the
504    /// text's start, so finding it for every point would take time growing as the square of the
505    /// file's length.
506    fn line_at(&self, offset: usize) -> usize {
507        usize::try_from(self.document.text_pos_at(offset).row).unwrap_or(usize::MAX)
508    }
509
510    /// A child element's text, by its name, in GPX's namespace.
511    fn name_of(&self, node: Node<'_, 'input>) -> Option<String> {
512        node.children()
513            .find(|child| self.own_name(*child) == Some("name"))
514            .map(|child| clean(&all_text(child)))
515            .filter(|name| !name.is_empty())
516    }
517
518    /// Counts an element not read.
519    fn not_read(&mut self, kind: Kind, name: String) {
520        let key = (kind, name);
521        if let Some(count) = self.unread.get_mut(&key) {
522            *count += 1;
523        } else if self.unread.len() < MAX_UNREAD_NAMES {
524            self.unread.insert(key, 1);
525        } else {
526            self.unread_left_out += 1;
527        }
528    }
529
530    /// Reads a waypoint.
531    fn waypoint(&mut self, node: Node<'_, 'input>) -> Result<(), LogError> {
532        self.waypoints += 1;
533        if self.places.len() >= MAX_PLACES {
534            self.places_left_out += 1;
535            return Ok(());
536        }
537        let point = self.point(node, Kind::Waypoint)?;
538        let name = self
539            .name_of(node)
540            .unwrap_or_else(|| self.waypoints.to_string());
541        self.places.push(Place {
542            label: format!("waypoint {name}"),
543            point,
544        });
545        Ok(())
546    }
547
548    /// Reads a route's points.
549    fn route(&mut self, node: Node<'_, 'input>) -> Result<(), LogError> {
550        self.routes += 1;
551        let name = self
552            .name_of(node)
553            .unwrap_or_else(|| self.routes.to_string());
554        let mut number = 0;
555        for child in node.children() {
556            if self.own_name(child) != Some("rtept") {
557                continue;
558            }
559            number += 1;
560            if self.places.len() >= MAX_PLACES {
561                self.places_left_out += 1;
562                continue;
563            }
564            let point = self.point(child, Kind::RoutePoint)?;
565            self.places.push(Place {
566                label: format!("route {name} point {number}"),
567                point,
568            });
569        }
570        Ok(())
571    }
572
573    /// Reads a track's segments, holding its times to go forward from one point to the next.
574    fn track(&mut self, node: Node<'_, 'input>) -> Result<(), LogError> {
575        self.tracks += 1;
576        let name = self.name_of(node).unwrap_or_else(|| "track".to_owned());
577        let segments: Vec<_> = node
578            .children()
579            .filter(|child| self.own_name(*child) == Some("trkseg"))
580            .collect();
581        if segments.is_empty() {
582            self.empty_tracks += 1;
583        }
584        let several = segments.len() > 1;
585        let mut last: Option<Stamp> = None;
586        for (index, segment) in segments.into_iter().enumerate() {
587            let trkpts: Vec<_> = segment
588                .children()
589                .filter(|child| self.own_name(*child) == Some("trkpt"))
590                .collect();
591            if trkpts.is_empty() {
592                self.empty_segments += 1;
593                continue;
594            }
595            if self.segments.len() >= MAX_TRACKS {
596                self.segments_left_out += 1;
597                self.segment_points_left_out += trkpts.len();
598                continue;
599            }
600            let mut points = Vec::new();
601            for trkpt in trkpts {
602                if self.points >= self.max_points {
603                    self.points_left_out += 1;
604                    continue;
605                }
606                let point = self.point(trkpt, Kind::TrackPoint)?;
607                if let Some(stamp) = &point.time {
608                    if let Some(previous) = &last
609                        && stamp.ns < previous.ns
610                    {
611                        return Err(syntax(
612                            self.line_at(stamp.at),
613                            format!(
614                                "a time that goes back. Track `{name}`'s point is timed `{}`, \
615                                 before `{}`, the time of the point ahead of it at line {}. A \
616                                 track's times go forward, so this one isn't read as one \
617                                 recording",
618                                stamp.written,
619                                previous.written,
620                                self.line_at(previous.at)
621                            ),
622                        ));
623                    }
624                    last = Some(stamp.clone());
625                }
626                self.points += 1;
627                points.push(point);
628            }
629            if !points.is_empty() {
630                self.segments.push(Segment {
631                    track: name.clone(),
632                    number: several.then_some(index + 1),
633                    points,
634                });
635            }
636        }
637        Ok(())
638    }
639
640    /// Reads a point: its position, then each element it holds.
641    fn point(&mut self, node: Node<'_, 'input>, kind: Kind) -> Result<Point, LogError> {
642        let at = node.range().start;
643        let element = kind.element();
644        let mut point = Point::default();
645        for (attribute, latitude) in [("lat", true), ("lon", false)] {
646            let Some(text) = node.attribute(attribute) else {
647                return Err(syntax(
648                    self.line_at(at),
649                    format!(
650                        "a `{element}` has no `{attribute}`, which GPX requires of every point"
651                    ),
652                ));
653            };
654            let value = decimal(text)
655                .ok_or_else(|| not_a_number(self.line_at(at), element, attribute, text))?;
656            let on_globe = if latitude {
657                (-90.0..=90.0).contains(&value)
658            } else {
659                (-180.0..=180.0).contains(&value)
660            };
661            if !on_globe {
662                return Err(syntax(
663                    self.line_at(at),
664                    format!(
665                        "a point off the globe: a `{element}`'s `{attribute}` is {}, where a {} \
666                         is {}",
667                        short(trimmed(text)),
668                        if latitude { "latitude" } else { "longitude" },
669                        if latitude {
670                            "−90° to 90°"
671                        } else {
672                            "−180° to 180°"
673                        }
674                    ),
675                ));
676            }
677            let written = Some(Written {
678                value,
679                text: short(trimmed(text)),
680            });
681            if latitude {
682                point.lat = written;
683            } else {
684                point.lon = written;
685            }
686        }
687        let mut seen: Vec<&str> = Vec::new();
688        for child in node.children().filter(|child| child.is_element()) {
689            let Some(name) = self.own_name(child) else {
690                self.not_read(kind, "other namespaces' elements".to_owned());
691                continue;
692            };
693            let read_here = match name {
694                "ele" | "time" => true,
695                "sat" | "hdop" | "vdop" | "pdop" | "geoidheight" => kind == Kind::TrackPoint,
696                "course" | "speed" => kind == Kind::TrackPoint && self.version == Version::V10,
697                _ => false,
698            };
699            if !read_here {
700                if name == "fix" && kind == Kind::TrackPoint && all_text(child).trim() == "none" {
701                    self.no_fix += 1;
702                }
703                // A waypoint's `name` names its figures.
704                if !(name == "name" && kind == Kind::Waypoint) {
705                    self.not_read(kind, format!("`{}`", short(name)));
706                }
707                continue;
708            }
709            let child_at = child.range().start;
710            if seen.contains(&name) {
711                return Err(syntax(
712                    self.line_at(child_at),
713                    format!("a `{element}` holds two `{name}` elements, where GPX allows one"),
714                ));
715            }
716            seen.push(name);
717            let text = all_text(child);
718            // An empty element, such as `<ele/>`, states nothing: a gap, counted.
719            if trimmed(&text).is_empty() {
720                *self.empty.entry((kind, name)).or_insert(0) += 1;
721                continue;
722            }
723            if name == "time" {
724                let read = stamp(&text, child_at);
725                point.time = Some(read.ok_or_else(|| {
726                    syntax(
727                        self.line_at(child_at),
728                        format!(
729                            "a `{element}`'s `time` reads `{}`, not a date and time this reader \
730                             reads, such as `2031-07-14T17:04:04.250Z`",
731                            short(trimmed(&text))
732                        ),
733                    )
734                })?);
735                continue;
736            }
737            if name == "sat" {
738                let count = whole_number(&text)
739                    .ok_or_else(|| not_a_number(self.line_at(child_at), element, name, &text))?;
740                point.sat = Some(count);
741                continue;
742            }
743            let value = decimal(&text)
744                .ok_or_else(|| not_a_number(self.line_at(child_at), element, name, &text))?;
745            match name {
746                "ele" => {
747                    point.ele = Some(Written {
748                        value,
749                        text: short(trimmed(&text)),
750                    });
751                }
752                "hdop" => point.hdop = Some(value),
753                "vdop" => point.vdop = Some(value),
754                "pdop" => point.pdop = Some(value),
755                "geoidheight" => point.geoidheight = Some(value),
756                "speed" => point.speed = Some(value),
757                _ => {
758                    if !(0.0..=360.0).contains(&value) {
759                        return Err(syntax(
760                            self.line_at(child_at),
761                            format!(
762                                "a `{element}`'s `course` is {}°, outside the 0° to 360° GPX \
763                                 1.0 allows",
764                                short(trimmed(&text))
765                            ),
766                        ));
767                    }
768                    point.course = Some(value);
769                }
770            }
771        }
772        Ok(point)
773    }
774
775    /// The record: each segment's channels, the places as figures, the notes.
776    fn finish(self, root: Node<'_, '_>) -> Result<FlightLog, LogError> {
777        if self.segments.is_empty() {
778            return Err(LogError::NoData { format: FORMAT });
779        }
780        let creator = root.attribute("creator").map(clean).unwrap_or_default();
781        let mut notes = vec![
782            "the record's altitude track is empty: a GPX file holds tracks of positions, not an \
783             altimeter's record over time, so every value is a channel"
784                .to_owned(),
785            format!(
786                "read as GPX {}, its `version`: {}, {} with points, each read as a GPS track, {}",
787                self.version.name(),
788                counted(self.tracks, "track"),
789                counted(self.segments.len(), "segment"),
790                counted(self.points, "point")
791            ),
792        ];
793        let track_points = || self.segments.iter().flat_map(|segment| &segment.points);
794        let place_points = || self.places.iter().map(|place| &place.point);
795        if track_points().any(|point| point.ele.is_some()) {
796            notes.push(
797                "`ele` read in meters, from GPX 1.1's schema and GPX 1.0's manual, as an altitude \
798                 whose datum the file doesn't state. Both give the unit and no datum, so it may \
799                 be above mean sea level, above the WGS84 ellipsoid or above another zero"
800                    .to_owned(),
801            );
802        }
803        if track_points().any(|point| point.geoidheight.is_some()) {
804            notes.push(
805                "`geoidheight` read in meters as the geoid's height above the WGS84 ellipsoid, \
806                 as GPX 1.1's schema defines it from NMEA's GGA message. It doesn't say which \
807                 surface `ele` beside it is measured from: GPSLogger for Android, the commonest \
808                 writer of `geoidheight` found, writes the height above the ellipsoid unless its \
809                 sea-level option is on, and a receiver's GGA altitude is above mean sea level, the two apart by the \
810                 geoid height. Over one flight that offset barely changes, so it moves the pad's \
811                 elevation, not the height above the pad"
812                    .to_owned(),
813            );
814        }
815        let zero = track_points()
816            .find_map(|point| point.time.as_ref())
817            .map(|stamp| (stamp, "a track point"))
818            .or_else(|| {
819                place_points()
820                    .find_map(|point| point.time.as_ref())
821                    .map(|stamp| (stamp, "a waypoint or route point"))
822            });
823        let zero_ns = zero.map(|(stamp, _)| stamp.ns);
824        if let Some((stamp, of)) = zero {
825            notes.push(format!(
826                "the log's zero is `{}`, the first time the file gives {of}",
827                stamp.written
828            ));
829        }
830        let unzoned = track_points()
831            .chain(place_points())
832            .filter(|point| point.time.as_ref().is_some_and(|stamp| !stamp.zoned))
833            .count();
834        if unzoned > 0 {
835            notes.push(format!(
836                "times with no zone read as UTC, as GPX 1.1's schema and GPX 1.0's manual say \
837                 every time is. {unzoned} of the file's times state none"
838            ));
839        }
840        let untimed = track_points().filter(|point| point.time.is_none()).count();
841        if untimed > 0 {
842            notes.push(format!(
843                "track points with no `time` keep their places, their times gaps: {untimed} of \
844                 {}",
845                self.points
846            ));
847        }
848        if self.no_fix > 0 {
849            notes.push(format!(
850                "track points whose `fix` is `none`, where the receiver had no fix, kept as \
851                 written: {}",
852                self.no_fix
853            ));
854        }
855        if track_points().any(|point| point.speed.is_some() || point.course.is_some()) {
856            notes.push(
857                "`speed` read in meters per second and `course` in degrees from true north, from \
858                 GPX 1.0's manual"
859                    .to_owned(),
860            );
861        }
862        if !self.places.is_empty() {
863            notes.push(format!(
864                "waypoints and routes kept apart from the tracks, as figures the file states, as \
865                 places marked or planned, not flown: {}, {}, {} read",
866                counted(self.waypoints, "waypoint"),
867                counted(self.routes, "route"),
868                counted(self.places.len(), "place")
869            ));
870        }
871        if self.empty_tracks + self.empty_segments > 0 {
872            notes.push(format!(
873                "tracks and segments with no point, left out: {} with no segment, {} with no \
874                 point",
875                counted(self.empty_tracks, "track"),
876                counted(self.empty_segments, "segment")
877            ));
878        }
879        if !self.empty.is_empty() {
880            let listed: Vec<String> = self
881                .empty
882                .iter()
883                .map(|((kind, name), count)| format!("`{name}` in {}", kind.counted(*count)))
884                .collect();
885            notes.push(format!(
886                "elements with no value read as gaps: {}",
887                listed.join(", ")
888            ));
889        }
890        if !self.unread.is_empty() {
891            let mut listed: Vec<String> = self
892                .unread
893                .iter()
894                .map(|((kind, name), count)| format!("{name} in {}", kind.counted(*count)))
895                .collect();
896            if self.unread_left_out > 0 {
897                listed.push(format!(
898                    "and {} more of names past the {MAX_UNREAD_NAMES} listed",
899                    self.unread_left_out
900                ));
901            }
902            notes.push(format!(
903                "elements no reading uses, not read: {}",
904                listed.join(", ")
905            ));
906        }
907        let mut left_out = Vec::new();
908        if self.segments_left_out > 0 {
909            left_out.push(format!(
910                "{} past the {MAX_TRACKS} read, holding {}",
911                counted(self.segments_left_out, "segment"),
912                counted(self.segment_points_left_out, "track point")
913            ));
914        }
915        if self.points_left_out > 0 {
916            left_out.push(format!(
917                "{} past the {}",
918                counted(self.points_left_out, "track point"),
919                self.max_points
920            ));
921        }
922        if self.places_left_out > 0 {
923            left_out.push(format!(
924                "{} past the {MAX_PLACES}",
925                match self.places_left_out {
926                    1 => "1 waypoint or route point".to_owned(),
927                    n => format!("{n} waypoints and route points"),
928                }
929            ));
930        }
931        if !left_out.is_empty() {
932            notes.push(format!(
933                "more than this reader reads, left out: {}",
934                left_out.join(", ")
935            ));
936        }
937
938        let seconds = |stamp: Option<&Stamp>| match (stamp, zero_ns) {
939            // Within the reader's dates, late 1677 to early 2262, two times differ by less than
940            // 2⁶⁴ ns, and when they differ by less than 2⁵³ ns, 104 days, the difference converts
941            // exactly.
942            (Some(stamp), Some(zero)) => {
943                (i128::from(stamp.ns) - i128::from(zero)) as f64 / NS_PER_S as f64
944            }
945            _ => f64::NAN,
946        };
947        let mut names = Names::default();
948        let mut channels = Vec::new();
949        for segment in &self.segments {
950            let base = match segment.number {
951                Some(number) => format!("{} segment {number}", segment.track),
952                None => segment.track.clone(),
953            };
954            let name = names.unique(base);
955            let time_s: Vec<f64> = segment
956                .points
957                .iter()
958                .map(|point| seconds(point.time.as_ref()))
959                .collect();
960            let column = |pick: Pick| -> Option<Vec<f64>> {
961                segment
962                    .points
963                    .iter()
964                    .any(|point| pick(point).is_some())
965                    .then(|| {
966                        segment
967                            .points
968                            .iter()
969                            .map(|point| pick(point).unwrap_or(f64::NAN))
970                            .collect()
971                    })
972            };
973            let picks: [(&str, Quantity, Pick); 10] = [
974                ("latitude", Quantity::Latitude, |p| {
975                    p.lat.as_ref().map(|w| w.value)
976                }),
977                ("longitude", Quantity::Longitude, |p| {
978                    p.lon.as_ref().map(|w| w.value)
979                }),
980                ("elevation", Quantity::Altitude, |p| {
981                    p.ele.as_ref().map(|w| w.value)
982                }),
983                ("satellites", Quantity::Number, |p| p.sat),
984                ("HDOP", Quantity::Number, |p| p.hdop),
985                ("VDOP", Quantity::Number, |p| p.vdop),
986                ("PDOP", Quantity::Number, |p| p.pdop),
987                ("geoid height", Quantity::Distance, |p| p.geoidheight),
988                ("speed", Quantity::Speed, |p| p.speed),
989                ("course", Quantity::Angle, |p| p.course),
990            ];
991            for (suffix, quantity, pick) in picks {
992                if let Some(values) = column(pick) {
993                    channels.push(Channel {
994                        column: format!("{name} {suffix}"),
995                        quantity,
996                        time_s: time_s.clone(),
997                        values,
998                    });
999                }
1000            }
1001        }
1002
1003        let mut figures = Vec::new();
1004        let mut names = Names::default();
1005        for place in &self.places {
1006            let label = names.unique(place.label.clone());
1007            let point = &place.point;
1008            for (suffix, quantity, written) in [
1009                ("latitude", Quantity::Latitude, &point.lat),
1010                ("longitude", Quantity::Longitude, &point.lon),
1011                ("elevation", Quantity::Altitude, &point.ele),
1012            ] {
1013                if let Some(written) = written {
1014                    figures.push(Figure::new(
1015                        format!("{label} {suffix}"),
1016                        written.text.clone(),
1017                        Some(quantity),
1018                        vec![written.value],
1019                    ));
1020                }
1021            }
1022            if let Some(stamp) = &point.time {
1023                figures.push(Figure::new(
1024                    format!("{label} time"),
1025                    stamp.written.clone(),
1026                    Some(Quantity::Duration),
1027                    vec![seconds(Some(stamp))],
1028                ));
1029            }
1030        }
1031
1032        Ok(FlightLog {
1033            format: LogFormat::Gpx,
1034            logger: if creator.is_empty() {
1035                "GPX".to_owned()
1036            } else {
1037                creator
1038            },
1039            serial_number: None,
1040            firmware: None,
1041            flight_number: None,
1042            stated: Stated {
1043                figures,
1044                ..Stated::default()
1045            },
1046            time_s: Vec::new(),
1047            altitude_m: Vec::new(),
1048            vertical_speed_m_s: None,
1049            temperature_k: None,
1050            battery_v: None,
1051            channels,
1052            events: Vec::new(),
1053            notes,
1054        })
1055    }
1056}
1057
1058/// `count` of a thing, for notes: `1 track`, `2 tracks`.
1059fn counted(count: usize, one: &str) -> String {
1060    if count == 1 {
1061        format!("1 {one}")
1062    } else {
1063        format!("{count} {one}s")
1064    }
1065}
1066
1067/// The names given so far, and for each name given twice the next number to try, so n repeats
1068/// of one name cost n steps, not n².
1069#[derive(Default)]
1070struct Names {
1071    used: HashSet<String>,
1072    next: HashMap<String, usize>,
1073}
1074
1075impl Names {
1076    /// A name not yet used, gaining ` (2)`, ` (3)` … if it is; marks it used. A number below the
1077    /// name's next was taken when it was passed, and a taken name stays taken, so starting there
1078    /// gives the first free number.
1079    fn unique(&mut self, name: String) -> String {
1080        if !self.used.contains(&name) {
1081            self.used.insert(name.clone());
1082            return name;
1083        }
1084        let number = self.next.entry(name.clone()).or_insert(2);
1085        loop {
1086            let candidate = format!("{name} ({number})");
1087            *number += 1;
1088            if !self.used.contains(&candidate) {
1089                self.used.insert(candidate.clone());
1090                return candidate;
1091            }
1092        }
1093    }
1094}
1095
1096/// An element's text, its text and CDATA children joined.
1097fn all_text(node: Node<'_, '_>) -> String {
1098    node.children()
1099        .filter(|child| child.is_text())
1100        .filter_map(|child| child.text())
1101        .collect()
1102}
1103
1104/// A name as a channel's: its runs of whitespace one space, cut to the length a note quotes.
1105fn clean(name: &str) -> String {
1106    short(&name.split_whitespace().collect::<Vec<_>>().join(" "))
1107}
1108
1109/// Text with XML's whitespace (space, tab, carriage return, line feed) trimmed from its ends, as
1110/// XML Schema's numbers and times collapse it.
1111fn trimmed(text: &str) -> &str {
1112    text.trim_matches([' ', '\t', '\r', '\n'])
1113}
1114
1115/// An XML Schema `decimal`: an optional sign, digits with an optional point, and at least one
1116/// digit, no exponent; as the nearest `f64`, which must be finite. `None` if it isn't one.
1117fn decimal(text: &str) -> Option<f64> {
1118    let text = trimmed(text);
1119    let unsigned = text.strip_prefix(['+', '-']).unwrap_or(text);
1120    let (whole, fraction) = unsigned.split_once('.').unwrap_or((unsigned, ""));
1121    let digits = |part: &str| part.bytes().all(|byte| byte.is_ascii_digit());
1122    if whole.is_empty() && fraction.is_empty() || !digits(whole) || !digits(fraction) {
1123        return None;
1124    }
1125    text.parse::<f64>().ok().filter(|value| value.is_finite())
1126}
1127
1128/// An XML Schema `nonNegativeInteger`: an optional `+` and digits, below 2⁵³ so the `f64` is exact.
1129fn whole_number(text: &str) -> Option<f64> {
1130    let text = trimmed(text);
1131    let digits = text.strip_prefix('+').unwrap_or(text);
1132    if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
1133        return None;
1134    }
1135    let value: u64 = digits.parse().ok()?;
1136    // Exact: below 2⁵³ every integer is an f64.
1137    (value < 1 << 53).then_some(value as f64)
1138}
1139
1140/// A refusal of a value that isn't the schema's kind of number.
1141fn not_a_number(line: usize, element: &str, name: &str, text: &str) -> LogError {
1142    let kind = if name == "sat" {
1143        "a whole number"
1144    } else {
1145        "a decimal number, with no exponent"
1146    };
1147    syntax(
1148        line,
1149        format!(
1150            "a `{element}`'s `{name}` reads `{}`, not {kind}",
1151            short(trimmed(text))
1152        ),
1153    )
1154}
1155
1156/// A `time` as nanoseconds since 1970-01-01T00:00:00 UTC, read by the KML reader's parser of XML
1157/// Schema's `dateTime` ([`kml::when_ns`]): with `Z` or an offset, moved to UTC; with no zone, as
1158/// UTC. `None` if it isn't one; `at` is its element's byte offset.
1159fn stamp(text: &str, at: usize) -> Option<Stamp> {
1160    let written = trimmed(text);
1161    let (zoned, ns) = match kml::when_ns(written)? {
1162        (Clock::Utc, ns) => (true, ns),
1163        (Clock::Local, ns) => (false, ns),
1164        _ => return None,
1165    };
1166    Some(Stamp {
1167        ns,
1168        zoned,
1169        written: short(written),
1170        at,
1171    })
1172}
1173
1174#[cfg(test)]
1175mod tests {
1176    use super::*;
1177
1178    /// A GPX 1.1 file around one track segment's points.
1179    fn gpx(points: &str) -> String {
1180        format!(
1181            "<?xml version=\"1.0\"?>\n<gpx version=\"1.1\" creator=\"test\" \
1182             xmlns=\"http://www.topografix.com/GPX/1/1\">\n<trk><name>t</name><trkseg>\n{points}\
1183             \n</trkseg></trk>\n</gpx>\n"
1184        )
1185    }
1186
1187    /// The message of a syntax error, and its line.
1188    fn refusal(text: &str) -> (usize, String) {
1189        match read(text) {
1190            Err(LogError::Syntax { line, message, .. }) => (line, message),
1191            other => panic!("expected a syntax error, got {other:?}"),
1192        }
1193    }
1194
1195    #[test]
1196    fn a_document_type_is_refused_by_name_so_no_entity_expands() {
1197        let text = "<?xml version=\"1.0\"?>\n<!DOCTYPE gpx [<!ENTITY a \"aaaa\">]>\n\
1198                    <gpx version=\"1.1\"><trk><name>&a;</name></trk></gpx>";
1199        assert!(recognizes(text));
1200        let (line, message) = refusal(text);
1201        assert_eq!(line, 2);
1202        assert!(
1203            message.starts_with("the file declares a document type"),
1204            "{message}"
1205        );
1206        // Past a comment naming a document type, the declaration's own line.
1207        let later = "<?xml version=\"1.0\"?>\n<!-- <!DOCTYPE x> -->\n\n<!DOCTYPE gpx [\n]>\n\
1208                     <gpx version=\"1.1\"/>";
1209        assert_eq!(refusal(later).0, 4);
1210        let external = "<!DOCTYPE gpx SYSTEM \"file:///etc/passwd\"><gpx version=\"1.1\"/>";
1211        assert!(
1212            refusal(external)
1213                .1
1214                .starts_with("the file declares a document type")
1215        );
1216    }
1217
1218    #[test]
1219    fn an_undefined_entity_is_refused_by_name() {
1220        let text = gpx("<trkpt lat=\"1\" lon=\"2\"><name>&rocket;</name></trkpt>");
1221        let (line, message) = refusal(&text);
1222        assert_eq!(line, 4);
1223        assert!(
1224            message.starts_with("the file refers to the entity `&rocket;`"),
1225            "{message}"
1226        );
1227        // XML's own five entities and character references are text, not entities a file declares.
1228        let fine = gpx("<trkpt lat=\"1\" lon=\"2\"><name>a &amp; b &#65;</name></trkpt>");
1229        assert!(read(&fine).is_ok());
1230    }
1231
1232    #[test]
1233    fn a_point_off_the_globe_is_refused_by_name() {
1234        for (lat, lon, attribute) in [
1235            ("90.0000001", "0", "lat"),
1236            ("-91", "0", "lat"),
1237            ("0", "180.5", "lon"),
1238            ("0", "-181", "lon"),
1239        ] {
1240            let text = gpx(&format!("<trkpt lat=\"{lat}\" lon=\"{lon}\"/>"));
1241            let (line, message) = refusal(&text);
1242            assert_eq!(line, 4);
1243            assert!(
1244                message.starts_with(&format!(
1245                    "a point off the globe: a `trkpt`'s `{attribute}` is"
1246                )),
1247                "{message}"
1248            );
1249        }
1250        // The poles and the antimeridian are on it.
1251        for (lat, lon) in [("90", "180"), ("-90", "-180"), ("+0.0", "-0")] {
1252            let log = read(&gpx(&format!("<trkpt lat=\"{lat}\" lon=\"{lon}\"/>"))).unwrap();
1253            assert_eq!(log.channels.len(), 2);
1254        }
1255        // A waypoint off the globe too.
1256        let text = "<gpx version=\"1.0\" xmlns=\"http://www.topografix.com/GPX/1/0\">\
1257                    <wpt lat=\"95\" lon=\"0\"/></gpx>";
1258        assert!(
1259            refusal(text)
1260                .1
1261                .starts_with("a point off the globe: a `wpt`'s `lat`")
1262        );
1263    }
1264
1265    #[test]
1266    fn a_time_that_goes_back_within_a_track_is_refused_by_name() {
1267        let back = gpx(
1268            "<trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:05Z</time></trkpt>\n\
1269             <trkpt lat=\"1\" lon=\"2\"></trkpt>\n\
1270             <trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:04.999Z</time></trkpt>",
1271        );
1272        let (line, message) = refusal(&back);
1273        assert_eq!(line, 6);
1274        assert!(
1275            message.starts_with(
1276                "a time that goes back. Track `t`'s point is timed `2031-07-14T17:04:04.999Z`, \
1277                 before `2031-07-14T17:04:05Z`, the time of the point ahead of it at line 4"
1278            ),
1279            "{message}"
1280        );
1281        // A time written later in another zone can be earlier in UTC: 18:04:04+01:00 is 17:04:04Z.
1282        let zoned_back = gpx(
1283            "<trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:05Z</time></trkpt>\n\
1284             <trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T18:04:04+01:00</time></trkpt>",
1285        );
1286        assert!(refusal(&zoned_back).1.starts_with("a time that goes back"));
1287        // The same instant in another zone is no step back, and a repeated time is none either.
1288        let zones = gpx(
1289            "<trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:05Z</time></trkpt>\n\
1290             <trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T13:04:05-04:00</time></trkpt>\n\
1291             <trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T13:04:05.5-04:00</time></trkpt>",
1292        );
1293        let log = read(&zones).unwrap();
1294        assert_eq!(log.channels[0].time_s, [0.0, 0.0, 0.5]);
1295        // From one segment to the next of a track, too.
1296        let segments = "<gpx version=\"1.1\" xmlns=\"http://www.topografix.com/GPX/1/1\"><trk>\
1297                        <trkseg><trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:05Z</time>\
1298                        </trkpt></trkseg><trkseg><trkpt lat=\"1\" lon=\"2\">\
1299                        <time>2031-07-14T17:04:01Z</time></trkpt></trkseg></trk></gpx>";
1300        assert!(refusal(segments).1.starts_with("a time that goes back"));
1301        // But a second track may be earlier than the first.
1302        let tracks = "<gpx version=\"1.1\" xmlns=\"http://www.topografix.com/GPX/1/1\">\
1303                      <trk><trkseg><trkpt lat=\"1\" lon=\"2\"><time>2031-07-14T17:04:05Z</time>\
1304                      </trkpt></trkseg></trk><trk><trkseg><trkpt lat=\"1\" lon=\"2\">\
1305                      <time>2031-07-14T17:04:01Z</time></trkpt></trkseg></trk></gpx>";
1306        let log = read(tracks).unwrap();
1307        assert_eq!(log.channels[2].time_s, [-4.0]);
1308        assert_eq!(log.channels[2].column, "track (2) latitude");
1309    }
1310
1311    #[test]
1312    fn the_version_and_namespace_must_be_gpx_and_agree() {
1313        let missing = "<?xml version=\"1.0\"?>\n<gpx xmlns=\"http://www.topografix.com/GPX/1/1\"/>";
1314        assert_eq!(refusal(missing).0, 2);
1315        assert!(refusal(missing).1.contains("states no `version`"));
1316        let unknown = "<gpx version=\"1.2\"/>";
1317        assert!(refusal(unknown).1.contains("`version` is `1.2`"));
1318        let disagree = "<gpx version=\"1.0\" xmlns=\"http://www.topografix.com/GPX/1/1\"/>";
1319        assert!(
1320            refusal(disagree)
1321                .1
1322                .contains("`version` is 1.0 but its namespace is GPX 1.1's")
1323        );
1324        let other = "<gpx version=\"1.1\" xmlns=\"http://example.invalid/gpx\"/>";
1325        assert!(matches!(
1326            read(other),
1327            Err(LogError::NotThisFormat { message, .. }) if message.contains("`http://example.invalid/gpx`")
1328        ));
1329        assert!(matches!(
1330            read("<kml/>"),
1331            Err(LogError::NotThisFormat { message, .. }) if message.contains("`kml`, not `gpx`")
1332        ));
1333        // No track point: nothing flown.
1334        let empty = "<gpx version=\"1.1\"><wpt lat=\"1\" lon=\"2\"/><trk><trkseg/></trk></gpx>";
1335        assert!(matches!(read(empty), Err(LogError::NoData { .. })));
1336    }
1337
1338    #[test]
1339    fn values_not_the_schemas_numbers_are_refused_by_name() {
1340        for (inner, message) in [
1341            (
1342                "<ele>1e3</ele>",
1343                "a `trkpt`'s `ele` reads `1e3`, not a decimal number",
1344            ),
1345            (
1346                "<ele>NaN</ele>",
1347                "a `trkpt`'s `ele` reads `NaN`, not a decimal number",
1348            ),
1349            (
1350                "<ele>.</ele>",
1351                "a `trkpt`'s `ele` reads `.`, not a decimal number",
1352            ),
1353            (
1354                "<hdop>1,5</hdop>",
1355                "a `trkpt`'s `hdop` reads `1,5`, not a decimal number",
1356            ),
1357            (
1358                "<sat>7.0</sat>",
1359                "a `trkpt`'s `sat` reads `7.0`, not a whole number",
1360            ),
1361            (
1362                "<sat>-1</sat>",
1363                "a `trkpt`'s `sat` reads `-1`, not a whole number",
1364            ),
1365            (
1366                "<ele>1</ele><ele>2</ele>",
1367                "a `trkpt` holds two `ele` elements",
1368            ),
1369            (
1370                "<time>2031-07-14</time>",
1371                "a `trkpt`'s `time` reads `2031-07-14`, not a date",
1372            ),
1373            (
1374                "<time>yesterday</time>",
1375                "a `trkpt`'s `time` reads `yesterday`, not a date",
1376            ),
1377        ] {
1378            let text = gpx(&format!("<trkpt lat=\"1\" lon=\"2\">{inner}</trkpt>"));
1379            let (line, refused) = refusal(&text);
1380            assert_eq!(line, 4, "{inner}");
1381            assert!(refused.starts_with(message), "{inner}: {refused}");
1382        }
1383        let text = gpx("<trkpt lat=\"1e1\" lon=\"2\"/>");
1384        assert!(
1385            refusal(&text)
1386                .1
1387                .starts_with("a `trkpt`'s `lat` reads `1e1`")
1388        );
1389        let text = gpx("<trkpt lon=\"2\"/>");
1390        assert!(refusal(&text).1.starts_with("a `trkpt` has no `lat`"));
1391        // A course outside 0° to 360°, in GPX 1.0, where a track point holds one.
1392        let course = "<gpx version=\"1.0\" xmlns=\"http://www.topografix.com/GPX/1/0\"><trk>\
1393                      <trkseg><trkpt lat=\"1\" lon=\"2\"><course>360.5</course></trkpt>\
1394                      </trkseg></trk></gpx>";
1395        assert!(
1396            refusal(course)
1397                .1
1398                .starts_with("a `trkpt`'s `course` is 360.5°")
1399        );
1400    }
1401
1402    #[test]
1403    fn an_empty_value_is_a_gap_not_a_refusal() {
1404        let text = gpx(
1405            "<trkpt lat=\"1\" lon=\"2\"><ele>5</ele><time>2031-07-14T17:04:05Z</time>\
1406                        </trkpt>\n<trkpt lat=\"1\" lon=\"2\"><ele/><time> </time><sat></sat>\
1407                        </trkpt>",
1408        );
1409        let log = read(&text).unwrap();
1410        let elevation = &log.channels[2];
1411        assert_eq!(elevation.column, "t elevation");
1412        assert_eq!(elevation.values[0], 5.0);
1413        assert!(elevation.values[1].is_nan() && elevation.time_s[1].is_nan());
1414        // A satellite count no point states has no channel.
1415        assert_eq!(log.channels.len(), 3);
1416        assert!(log.notes.iter().any(|note| note
1417            == "elements with no value read as gaps: `ele` in 1 track point, `sat` in 1 track \
1418                point, `time` in 1 track point"));
1419        // An empty position is no position: refused.
1420        assert!(
1421            refusal(&gpx("<trkpt lat=\"\" lon=\"2\"/>"))
1422                .1
1423                .starts_with("a `trkpt`'s `lat` reads ``, not a decimal number")
1424        );
1425    }
1426
1427    #[test]
1428    fn the_xml_is_bounded_before_it_is_read() {
1429        let deep = format!(
1430            "<gpx version=\"1.1\">\n{}{}</gpx>",
1431            "<a>".repeat(MAX_DEPTH),
1432            "</a>".repeat(MAX_DEPTH)
1433        );
1434        let (line, message) = refusal(&deep);
1435        assert_eq!(line, 2);
1436        assert!(
1437            message.contains(&format!("nests elements {} deep", MAX_DEPTH + 1)),
1438            "{message}"
1439        );
1440        let text = gpx(&"<trkpt lat=\"1\" lon=\"2\"/>".repeat(10));
1441        assert!(read_within(&text, 1_000, MAX_POINTS).is_ok());
1442        let (line, message) = match read_within(&text, 10, MAX_POINTS) {
1443            Err(LogError::Syntax { line, message, .. }) => (line, message),
1444            other => panic!("{other:?}"),
1445        };
1446        assert_eq!(message, "the file holds more than 10 XML nodes");
1447        // The parser places no node count's refusal: it reads the text's first line.
1448        assert_eq!(line, 1);
1449    }
1450
1451    #[test]
1452    fn past_each_cap_the_rest_is_counted_and_left_out() {
1453        let note = |log: &FlightLog| {
1454            log.notes
1455                .iter()
1456                .find(|note| note.starts_with("more than this reader reads, left out: "))
1457                .cloned()
1458                .unwrap_or_default()
1459        };
1460        // Segments: one more than the cap, each of one point.
1461        let segments: String = (0..=MAX_TRACKS)
1462            .map(|_| "<trkseg><trkpt lat=\"1\" lon=\"2\"/></trkseg>")
1463            .collect();
1464        let text = format!("<gpx version=\"1.1\"><trk>{segments}</trk></gpx>");
1465        let log = read(&text).unwrap();
1466        assert_eq!(log.channels.len(), 2 * MAX_TRACKS);
1467        assert_eq!(
1468            note(&log),
1469            format!(
1470                "more than this reader reads, left out: 1 segment past the {MAX_TRACKS} read, \
1471                 holding 1 track point"
1472            )
1473        );
1474        // Track points: the cap lowered, as a million would make a slow test.
1475        let text = gpx(&"<trkpt lat=\"1\" lon=\"2\"/>".repeat(7));
1476        let log = read_within(&text, MAX_NODES, 5).unwrap();
1477        assert_eq!(log.channels[0].values.len(), 5);
1478        assert_eq!(
1479            note(&log),
1480            "more than this reader reads, left out: 2 track points past the 5"
1481        );
1482        // Waypoints and route points, together.
1483        let places: String = (0..MAX_PLACES)
1484            .map(|_| "<wpt lat=\"1\" lon=\"2\"/>")
1485            .chain(["<rte><rtept lat=\"1\" lon=\"2\"/></rte>"])
1486            .collect();
1487        let text = format!(
1488            "<gpx version=\"1.1\">{places}<trk><trkseg><trkpt lat=\"1\" lon=\"2\"/></trkseg>\
1489             </trk></gpx>"
1490        );
1491        let log = read(&text).unwrap();
1492        assert_eq!(log.stated.figures.len(), 2 * MAX_PLACES);
1493        assert_eq!(
1494            note(&log),
1495            format!(
1496                "more than this reader reads, left out: 1 waypoint or route point past the \
1497                 {MAX_PLACES}"
1498            )
1499        );
1500        // The names of elements not read: those past the cap are counted, not named.
1501        let names: String = (0..=MAX_UNREAD_NAMES).map(|n| format!("<x{n}/>")).collect();
1502        let log = read(&gpx(&format!(
1503            "<trkpt lat=\"1\" lon=\"2\">{names}{names}</trkpt>"
1504        )))
1505        .unwrap();
1506        let unread = log
1507            .notes
1508            .iter()
1509            .find(|note| note.starts_with("elements no reading uses"))
1510            .unwrap();
1511        assert_eq!(
1512            unread.matches(" in 2 track points").count(),
1513            MAX_UNREAD_NAMES
1514        );
1515        assert!(unread.ends_with(&format!(
1516            "and 2 more of names past the {MAX_UNREAD_NAMES} listed"
1517        )));
1518    }
1519
1520    #[test]
1521    fn decimals_read_as_xml_schema_writes_them() {
1522        assert_eq!(decimal(" +1.5\n"), Some(1.5));
1523        assert_eq!(decimal("-.25"), Some(-0.25));
1524        assert_eq!(decimal("7."), Some(7.0));
1525        assert!(decimal("-0").is_some_and(|zero| zero == 0.0 && zero.is_sign_negative()));
1526        for refused in ["", "+", "-.", "1e3", "inf", "0x10", "1 2", "١"] {
1527            assert_eq!(decimal(refused), None, "{refused}");
1528        }
1529        // A decimal too long for any double is refused, not read as infinity.
1530        assert_eq!(decimal(&"9".repeat(400)), None);
1531        assert_eq!(whole_number("+12"), Some(12.0));
1532        assert_eq!(whole_number(&(1u64 << 53).to_string()), None);
1533    }
1534
1535    #[test]
1536    fn names_are_made_unique_by_number() {
1537        let mut names = Names::default();
1538        let given: Vec<String> = ["a", "a", "a (2)", "a", "a (4)", "a", "a"]
1539            .into_iter()
1540            .map(|name| names.unique(name.to_owned()))
1541            .collect();
1542        assert_eq!(
1543            given,
1544            [
1545                "a",
1546                "a (2)",
1547                "a (2) (2)",
1548                "a (3)",
1549                "a (4)",
1550                "a (5)",
1551                "a (6)"
1552            ]
1553        );
1554        // Each repeat starts from the name's next number, not from 2, so naming the places' cap
1555        // of one name takes as many steps as there are names.
1556        assert_eq!(names.next.get("a"), Some(&7));
1557        let places: String = (0..MAX_PLACES)
1558            .map(|_| "<wpt lat=\"1\" lon=\"2\"><name>a</name></wpt>")
1559            .collect();
1560        let text = format!(
1561            "<gpx version=\"1.1\">{places}<trk><trkseg><trkpt lat=\"1\" lon=\"2\"/></trkseg>\
1562             </trk></gpx>"
1563        );
1564        let log = read(&text).unwrap();
1565        let last = &log.stated.figures[log.stated.figures.len() - 1];
1566        assert_eq!(last.name, format!("waypoint a ({MAX_PLACES}) longitude"));
1567    }
1568}