Skip to main content

hpr_flightdata/
perfectflite.rs

1//! PerfectFlite's `.pf2` flight logs, as its software writes a Pnut's, a StratoLogger's or a
2//! StratoLoggerCF's flights, the CSV and text exports it writes of them ([`read_export`]), and
3//! the older `.pfa` of an Alt15K/WD's flights ([`read_pfa`]). Every
4//! `.pf2` and `.pfa` among the project's sample logs reads, of all four models (`cargo xtask
5//! logs`).
6//!
7//! A `.pf2` is text: the logger's name on the first line, a preamble of `Key: value` lines, a
8//! `Data:` line naming the columns, then one row per sample, comma-separated, at about 20 Hz:
9//!
10//! ```text
11//! PerfectFlite Pnut
12//! Firmware: 1.0
13//! Apogee: 1280' AGL
14//! Ground Elevation: 600' MSL
15//! NumSamps: 3
16//! Flight Number: 2
17//! Data: (Time, Altitude, Velocity, Temperature (F), Voltage)
18//! 0.00, 0, 0, 70.00, 4.20
19//! 0.05, 0, 0
20//! 0.10, 1, 8, 70.00, 4.20
21//! ```
22//!
23//! Times are seconds, altitudes feet above the logger's reading on the pad, speeds feet per
24//! second, temperatures degrees Fahrenheit, voltages volts. A row may leave its last columns out
25//! (the temperature and voltage are logged less often); a column left out is a gap, `NaN`. The
26//! velocity is the logger's own, worked out from its barometric altitude: a PerfectFlite has no
27//! accelerometer.
28//!
29//! **Where this comes from.** PerfectFlite publishes no specification of the format. This reader
30//! follows the one in Debrief (`lib/parsers/perfectflite.ts`, MIT, the project owner's own; see
31//! `THIRD-PARTY-NOTICES.md`), which was written from exported files and cites no document; the
32//! units above are its reading, borne out by the Pnut fixture Debrief ships, whose preamble states
33//! its apogee with a foot mark. Where this reader departs from Debrief's: it takes the column order
34//! from the `Data:` line when there is one, where Debrief assumes it; and it refuses what Debrief
35//! passes over, naming the line: an empty or non-numeric cell, a time that doesn't increase, and a
36//! line that isn't a row once the rows have begun. A stated apogee or elevation in a unit other
37//! than feet is refused rather than guessed at. A byte-order mark is dropped, and lines may end
38//! in CR, LF or both.
39//!
40//! # The older `.pfa`
41//!
42//! A `.pfa` is what PerfectFlite's DataCap program (AltCapWD 1.10 on the Mac) saves of an
43//! Alt15K/WD's flight. It is text, its lines ending in CR, or CR LF: the logger's name, four
44//! `Key: value` lines, a blank line, a `**!!Data:` line, then one altitude a line, zero-padded to
45//! five digits, and nothing else. An invented flight's first lines:
46//!
47//! ```text
48//! PerfectFlite Alt15K/WD
49//! Ground: 1150
50//! Apogee: 274
51//! NumSamps: 24
52//! Comments:
53//!
54//! **!!Data:
55//! 00000
56//! 00002
57//! ```
58//!
59//! [`import::read`](crate::import::read) tells it from a `.pf2` by the `**!!` line: both open
60//! with a line naming PerfectFlite.
61//!
62//! **Units and clock.** The file states neither. The samples are feet above the logger's reading on
63//! the pad, 0.1 s apart, so the record's time is the sample's place in the file over 10, from the
64//! first sample:
65//!
66//! - *Alt15K/WD User's Manual* (PerfectFlite; archived 2013), p. 2: waiting on the pad, the logger
67//!   samples "every 100 milliseconds"; once a sample is 80 ft above the ground reading, it saves
68//!   "the previous 8 altitude samples" and adds one "every 100 milliseconds" for the rest of the
69//!   flight. It beeps the apogee in feet (p. 6).
70//! - The *A15K Data Sheet* (archived 2011) and the revision 2 specifications page (archived
71//!   2023): "10 samples per second"; the latter lets the launch-detect height be set from 40 to
72//!   250 ft, and keeps 2,304 samples a flight.
73//! - DataCap's own help: the samples are collected "at the rate of 10 samples per second"; the
74//!   `Apogee:` line is "the highest altitude encountered during the flight"; `NumSamps:` is "the
75//!   number of data points".
76//!
77//! The project's 25 sample `.pfa`s bear these out: in every one `NumSamps:` counts the samples and
78//! `Apogee:` is their highest, and each first reaches 40 or 80 ft at its eighth sample. Each record
79//! says where its units came from in a note, `` `Data` read in feet, 0.1 s apart, from the
80//! manual ``, which `cargo xtask logs` counts.
81//!
82//! **Time zero isn't liftoff.** DataCap's help: "Sampling begins at a point 0.7 seconds before the
83//! launch is detected", so the logger saw the launch at 0.7 s, liftoff came before that, and for a
84//! rocket slow off the pad before time zero too (the help: the data "may begin at an altitude
85//! greater than 0"). A note says so.
86//!
87//! **`Ground:` isn't the pad's elevation.** DataCap's help gives it as the site's elevation "when
88//! the ambient barometric pressure is 29.92" Hg at sea level": a pressure altitude, about 100 ft
89//! off the true elevation for every 0.1 inHg the day's sea-level pressure differs, "reported for
90//! interest only". It is kept in a note, never as
91//! [`Stated::ground_elevation_msl_m`](crate::log::Stated::ground_elevation_msl_m).
92//!
93//! **What else is checked.** A `NumSamps:` that differs from the samples read is noted, as is an
94//! `Apogee:` that isn't their highest. DataCap's help says a `NumSamps` of 2,200 (revision 2) or
95//! 2,400 (the original) likely means the logger lost power in flight, its memory then holding
96//! older flights after this one's: such a file reads, with a note. The comment, every line from
97//! `Comments:` to `**!!Data:`, is kept short in a note. A sample line that isn't a whole number of
98//! up to six digits, an empty line among the samples (it would move every time after it), a
99//! `**!!` line other than `**!!Data:`, or a `Ground:`, `Apogee:` or `NumSamps:` stated twice is
100//! refused, naming the line. Nothing is sized from `NumSamps:`.
101
102use crate::error::LogError;
103use crate::log::{Channel, FlightLog, LogFormat, Quantity, Stated};
104use crate::table::finite;
105
106/// The format's name in errors.
107const FORMAT: &str = ".pf2";
108
109/// Meters in a foot, exactly (the international foot).
110pub const FOOT_M: f64 = 0.3048;
111
112/// The columns a `.pf2` has when it has no `Data:` line: the order Debrief reads and the Pnut
113/// fixture's `Data:` line states.
114const DEFAULT_COLUMNS: [(Column, &str); 5] = [
115    (Column::Time, "Time"),
116    (Column::Altitude, "Altitude"),
117    (Column::Velocity, "Velocity"),
118    (
119        Column::Temperature(TemperatureUnit::Fahrenheit),
120        "Temperature (F)",
121    ),
122    (Column::Voltage, "Voltage"),
123];
124
125/// A column of the data rows.
126#[derive(Debug, Clone, Copy, PartialEq, Eq)]
127enum Column {
128    Time,
129    Altitude,
130    Velocity,
131    Temperature(TemperatureUnit),
132    Voltage,
133    /// A column the reader doesn't know, kept as written with a note.
134    Unknown,
135}
136
137#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138enum TemperatureUnit {
139    Fahrenheit,
140    Celsius,
141}
142
143impl TemperatureUnit {
144    fn kelvin(self, value: f64) -> f64 {
145        match self {
146            Self::Fahrenheit => (value - 32.0) * 5.0 / 9.0 + 273.15,
147            Self::Celsius => value + 273.15,
148        }
149    }
150}
151
152/// Reads a `.pf2` flight log from its text.
153///
154/// # Errors
155///
156/// [`LogError::NotThisFormat`] if the first line doesn't name PerfectFlite;
157/// [`LogError::Syntax`] for a row that isn't numbers, a time that doesn't increase, a
158/// temperature too large to convert to kelvin, or a `Data:` line without a time or an altitude
159/// column; [`LogError::Unit`] for a stated height that isn't
160/// in feet; [`LogError::NoData`] if there are no rows.
161pub fn read(text: &str) -> Result<FlightLog, LogError> {
162    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
163    let text = text.replace("\r\n", "\n").replace('\r', "\n");
164    let mut lines = text
165        .lines()
166        .enumerate()
167        .map(|(index, line)| (index + 1, line.trim()));
168    let logger = loop {
169        match lines.next() {
170            Some((_, "")) => {}
171            Some((_, line)) if line.to_ascii_lowercase().contains("perfectflite") => {
172                break line.to_owned();
173            }
174            Some((_, line)) => {
175                return Err(LogError::NotThisFormat {
176                    format: FORMAT,
177                    message: format!(
178                        "its first line, {:?}, doesn't name PerfectFlite",
179                        short(line)
180                    ),
181                });
182            }
183            None => {
184                return Err(LogError::NotThisFormat {
185                    format: FORMAT,
186                    message: "the file is empty".to_owned(),
187                });
188            }
189        }
190    };
191
192    let mut log = FlightLog {
193        format: LogFormat::PerfectFlitePf2,
194        logger,
195        serial_number: None,
196        firmware: None,
197        flight_number: None,
198        stated: Stated::default(),
199        time_s: Vec::new(),
200        altitude_m: Vec::new(),
201        vertical_speed_m_s: None,
202        temperature_k: None,
203        battery_v: None,
204        channels: Vec::new(),
205        events: Vec::new(),
206        notes: Vec::new(),
207    };
208    let mut notes = Notes::default();
209    let mut columns: Option<Vec<(Column, String)>> = None;
210    let mut rows: Vec<(usize, Vec<f64>)> = Vec::new();
211
212    for (number, line) in lines {
213        if line.is_empty() {
214            continue;
215        }
216        if is_data_row(line) {
217            rows.push((number, data_row(line, number)?));
218            continue;
219        }
220        if !rows.is_empty() {
221            return Err(syntax(
222                number,
223                format!(
224                    "{:?} after the data rows began isn't a row of numbers",
225                    short(line)
226                ),
227            ));
228        }
229        let Some((key, value)) = line.split_once(':') else {
230            notes.push(format!(
231                "line {number}, {:?}, isn't a `Key: value` line and was skipped",
232                short(line)
233            ));
234            continue;
235        };
236        let value = value.trim();
237        match key.trim().to_ascii_lowercase().as_str() {
238            "data" => columns = Some(data_columns(value, number, &mut notes)?),
239            "apogee" => log.stated.apogee_m = stated_feet(value, number, "apogee", &mut notes)?,
240            "ground elevation" => {
241                log.stated.ground_elevation_msl_m =
242                    stated_feet(value, number, "ground elevation", &mut notes)?;
243            }
244            "numsamps" => log.stated.samples = value.parse().ok(),
245            "flight number" => log.flight_number = value.parse().ok(),
246            "serial number" if !value.is_empty() => log.serial_number = Some(value.to_owned()),
247            "firmware" if !value.is_empty() => log.firmware = Some(value.to_owned()),
248            // The software version, comments and anything else describe the file, not the flight.
249            _ => {}
250        }
251    }
252
253    if rows.is_empty() {
254        return Err(LogError::NoData { format: FORMAT });
255    }
256    let columns = columns.unwrap_or_else(|| {
257        log.notes.push(
258            "the file has no `Data:` line; its columns were read as time, altitude, velocity, \
259             temperature (°F) and voltage"
260                .to_owned(),
261        );
262        DEFAULT_COLUMNS
263            .iter()
264            .map(|(column, name)| (*column, (*name).to_owned()))
265            .collect()
266    });
267    fill(&mut log, FORMAT, &columns, &rows)?;
268    if let Some(stated) = log.stated.samples
269        && stated != log.time_s.len()
270    {
271        log.notes.push(format!(
272            "the file states {stated} samples and holds {}",
273            log.time_s.len()
274        ));
275    }
276    // The file-wide notes above come first, then those about single lines.
277    log.notes.extend(notes.kept);
278    if notes.left_out > 0 {
279        log.notes.push(format!(
280            "and {} more notes about single lines, left out so that a broken file's list stays \
281             short",
282            notes.left_out
283        ));
284    }
285    Ok(log)
286}
287
288/// The CSV export's name in errors.
289const EXPORT_CSV: &str = "PerfectFlite CSV";
290/// The text export's name in errors.
291const EXPORT_TEXT: &str = "PerfectFlite text";
292
293/// The column names a PerfectFlite export writes, as the project's 17 sample exports with a
294/// header row write them (one names its temperature `Temp`, without the dot). A header row with
295/// any other name, or the same name in another case, is another logger's or a person's, such as
296/// the RRC3's `Time,Altitude,Pressure,…` or a bare `time,altitude`, whose units nothing states.
297const EXPORT_COLUMNS: [&str; 9] = [
298    "Time",
299    "Altitude",
300    "Velocity",
301    "Temperature (F)",
302    "Temperature (C)",
303    "Temp.",
304    "Temp",
305    "Voltage",
306    "Acceleration (calculated)",
307];
308
309/// The separator of a PerfectFlite export's header row: `Time`, `Altitude` and at least one more
310/// of the names an export writes ([`EXPORT_COLUMNS`]) and no other, by commas or tabs; `None` if
311/// the line isn't one.
312pub(crate) fn export_separator(header: &str) -> Option<char> {
313    [',', '\t'].into_iter().find(|separator| {
314        let names: Vec<&str> = header.split(*separator).map(str::trim).collect();
315        names.len() >= 3
316            && names[0] == "Time"
317            && names[1] == "Altitude"
318            && names.iter().all(|name| EXPORT_COLUMNS.contains(name))
319    })
320}
321
322/// The columns a tab-separated export with no header row holds, in order: the header row the
323/// text exports with one write.
324const HEADERLESS_COLUMNS: &str = "Time\tAltitude\tTemp.\tVoltage";
325
326/// Whether a line is the first row of a tab-separated export written with no header row: four
327/// cells, each a number, the third a temperature followed by its unit's letter, `F` or `C` in
328/// either case, as
329/// the text export with a header row writes its `Temp.` column (`58.7F`). No other layout HPR Sim
330/// knows writes a unit's letter after a number in a row of numbers.
331pub(crate) fn is_headerless_row(line: &str) -> bool {
332    let cells: Vec<&str> = line.split('\t').map(str::trim).collect();
333    let plain = |cell: &str| cell.parse::<f64>().is_ok_and(f64::is_finite);
334    let [time, altitude, temperature, voltage] = cells[..] else {
335        return false;
336    };
337    plain(time)
338        && plain(altitude)
339        && plain(voltage)
340        && temperature_suffix(temperature).is_some()
341        && plain(&temperature[..temperature.len() - 1])
342}
343
344/// Reads one of the exports PerfectFlite's software writes from a flight: comma-separated, with a
345/// header row such as `Time,Altitude,Velocity,Temperature (F),Voltage`, or tab-separated, with a
346/// header row such as `Time`, `Altitude`, `Temp.`, `Voltage` and temperatures written with their unit,
347/// such as `58.7F`.
348///
349/// A tab-separated export may have no header row: its rows are then the four cells the text
350/// export writes under `Time`, `Altitude`, `Temp.`, `Voltage`, and a row is recognized by its
351/// temperature's unit letter, as no other layout HPR Sim knows writes one. The record notes that
352/// the columns were taken so. Four of the project's sample logs are written this way; `cargo
353/// xtask logs` checks their altitudes' unit as it checks the other exports'.
354///
355/// The units are a `.pf2`'s: seconds, feet, feet per second, and the temperature's stated unit.
356/// The header doesn't state the altitude's. `cargo xtask logs` bears out feet on the project's
357/// sample exports: most peak at exactly the height of the `.pf2` saved beside them, and the rest
358/// climb, read in feet, as long as those do against a fall in vacuum from the peak (its report,
359/// `validation/reports/log-import.md`, gives the counts and ratios). An export doesn't name the
360/// logger's model, so the logger reads `PerfectFlite`. A column the reader doesn't know, such as
361/// `Acceleration (calculated)`, is kept as written.
362///
363/// # Errors
364///
365/// [`LogError::NotThisFormat`] if the first line isn't an export's header row;
366/// [`LogError::Syntax`] for a cell that isn't a number, a temperature in a unit other than its
367/// column's or too large to convert to kelvin, a row with more cells than the header, or a time
368/// that doesn't increase;
369/// [`LogError::NoData`] if there are no rows.
370pub fn read_export(text: &str) -> Result<FlightLog, LogError> {
371    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
372    let text = text.replace("\r\n", "\n").replace('\r', "\n");
373    let mut lines = text
374        .lines()
375        .enumerate()
376        .map(|(index, line)| (index + 1, line.trim()))
377        .filter(|(_, line)| !line.is_empty());
378    let Some((header_line, header)) = lines.next() else {
379        return Err(LogError::NotThisFormat {
380            format: EXPORT_CSV,
381            message: "the file is empty".to_owned(),
382        });
383    };
384    // A headerless export's first line is its first row, read under the columns it implies.
385    let headerless = export_separator(header).is_none() && is_headerless_row(header);
386    let first_row = headerless.then_some((header_line, header));
387    let (header_line, header) = if headerless {
388        (0, HEADERLESS_COLUMNS)
389    } else {
390        (header_line, header)
391    };
392    let Some(separator) = export_separator(header) else {
393        return Err(LogError::NotThisFormat {
394            format: EXPORT_CSV,
395            message: format!(
396                "its first line, {:?}, isn't a header row of `Time` then `Altitude`, nor a row \
397                 of a tab-separated export without one",
398                short(header)
399            ),
400        });
401    };
402    let (format, name) = if separator == ',' {
403        (LogFormat::PerfectFliteCsv, EXPORT_CSV)
404    } else {
405        (LogFormat::PerfectFliteText, EXPORT_TEXT)
406    };
407    let rows: Vec<(usize, Vec<&str>)> = first_row
408        .into_iter()
409        .chain(lines)
410        .map(|(number, line)| (number, line.split(separator).map(str::trim).collect()))
411        .collect();
412    if rows.is_empty() {
413        return Err(LogError::NoData { format: name });
414    }
415    let mut notes = Notes::default();
416    // A temperature column whose name states no unit takes the one its first cell is written in.
417    let names: Vec<&str> = header.split(separator).collect();
418    let cell_unit = names
419        .iter()
420        .position(|written| written.trim().to_ascii_lowercase().starts_with("temp"))
421        .and_then(|index| rows.iter().find_map(|(_, cells)| cells.get(index)))
422        .and_then(|cell| temperature_suffix(cell));
423    let columns = named_columns(names.into_iter(), cell_unit, &mut notes);
424    require_time_and_altitude(&columns, name, header_line, "header row", header)?;
425
426    let mut values = Vec::with_capacity(rows.len());
427    for (number, cells) in &rows {
428        let row = cells
429            .iter()
430            .zip(&columns)
431            .map(|(cell, (column, _))| export_cell(cell, *column, name, *number))
432            .collect::<Result<Vec<f64>, LogError>>()?;
433        if cells.len() > columns.len() {
434            return Err(LogError::Syntax {
435                format: name,
436                line: *number,
437                message: format!(
438                    "the row has {} values and the columns are {}",
439                    cells.len(),
440                    columns.len()
441                ),
442            });
443        }
444        values.push((*number, row));
445    }
446
447    let mut log = FlightLog {
448        format,
449        logger: "PerfectFlite".to_owned(),
450        serial_number: None,
451        firmware: None,
452        flight_number: None,
453        stated: Stated::default(),
454        time_s: Vec::new(),
455        altitude_m: Vec::new(),
456        vertical_speed_m_s: None,
457        temperature_k: None,
458        battery_v: None,
459        channels: Vec::new(),
460        events: Vec::new(),
461        notes: headerless
462            .then(|| {
463                "the file has no header row. Its four columns are taken as a text export's, \
464                 `Time`, `Altitude`, `Temp.`, `Voltage`, by the unit letter of its temperatures"
465                    .to_owned()
466            })
467            .into_iter()
468            .collect(),
469    };
470    fill(&mut log, name, &columns, &values)?;
471    log.notes.extend(notes.kept);
472    if notes.left_out > 0 {
473        log.notes.push(format!(
474            "and {} more notes about single lines, left out so that a broken file's list stays \
475             short",
476            notes.left_out
477        ));
478    }
479    Ok(log)
480}
481
482/// The unit a temperature cell is written in, such as `58.7F`; `None` for a bare number.
483fn temperature_suffix(cell: &str) -> Option<TemperatureUnit> {
484    match cell.trim().chars().last()? {
485        'F' | 'f' => Some(TemperatureUnit::Fahrenheit),
486        'C' | 'c' => Some(TemperatureUnit::Celsius),
487        _ => None,
488    }
489}
490
491/// An export's cell as a number in the file's unit: a temperature may carry its column's unit
492/// letter, and no other.
493fn export_cell(
494    cell: &str,
495    column: Column,
496    format: &'static str,
497    line: usize,
498) -> Result<f64, LogError> {
499    let digits = match (column, temperature_suffix(cell)) {
500        (_, None) => cell,
501        (Column::Temperature(unit), Some(written)) if unit == written => &cell[..cell.len() - 1],
502        _ => {
503            return Err(LogError::Syntax {
504                format,
505                line,
506                message: format!("{:?} carries a unit its column doesn't state", short(cell)),
507            });
508        }
509    };
510    digits
511        .trim()
512        .parse::<f64>()
513        .ok()
514        .filter(|value| value.is_finite())
515        .ok_or_else(|| LogError::Syntax {
516            format,
517            line,
518            message: format!("{:?} isn't a finite number", short(cell)),
519        })
520}
521
522/// The most notes about single lines a log keeps; past it, one more note counts the rest.
523const MAX_NOTES: usize = 20;
524
525/// Notes about single lines as the reader meets them: the first [`MAX_NOTES`] kept, the rest
526/// only counted, so a file of many broken lines can't fill memory with them.
527#[derive(Default)]
528struct Notes {
529    kept: Vec<String>,
530    left_out: usize,
531}
532
533impl Notes {
534    fn push(&mut self, note: String) {
535        if self.kept.len() < MAX_NOTES {
536            self.kept.push(note);
537        } else {
538            self.left_out += 1;
539        }
540    }
541}
542
543/// Whether a line is a data row: it starts with a number and has a comma, as Debrief tells them.
544fn is_data_row(line: &str) -> bool {
545    let first = line.trim_start_matches(['-', '+']);
546    first.starts_with(|c: char| c.is_ascii_digit() || c == '.') && line.contains(',')
547}
548
549fn syntax(line: usize, message: String) -> LogError {
550    LogError::Syntax {
551        format: FORMAT,
552        line,
553        message,
554    }
555}
556
557/// A data row's cells as numbers.
558fn data_row(line: &str, number: usize) -> Result<Vec<f64>, LogError> {
559    line.split(',')
560        .map(|cell| {
561            let cell = cell.trim();
562            cell.parse::<f64>()
563                .ok()
564                .filter(|value| value.is_finite())
565                .ok_or_else(|| syntax(number, format!("{:?} isn't a finite number", short(cell))))
566        })
567        .collect()
568}
569
570/// The columns a `Data:` line names, such as `(Time, Altitude, Velocity, Temperature (F), Voltage)`,
571/// each with its name as written.
572fn data_columns(
573    value: &str,
574    number: usize,
575    notes: &mut Notes,
576) -> Result<Vec<(Column, String)>, LogError> {
577    let inner = value.strip_prefix('(').unwrap_or(value);
578    let inner = inner.strip_suffix(')').unwrap_or(inner);
579    let columns = named_columns(inner.split(','), None, notes);
580    require_time_and_altitude(&columns, FORMAT, number, "`Data:` line", value)?;
581    Ok(columns)
582}
583
584/// Each column's meaning from its name, with the name as written. A temperature column whose name
585/// states no unit, such as the text export's `Temp.`, takes `cell_unit`, the unit its cells
586/// carry; without one it is kept as written.
587fn named_columns<'a>(
588    names: impl Iterator<Item = &'a str>,
589    cell_unit: Option<TemperatureUnit>,
590    notes: &mut Notes,
591) -> Vec<(Column, String)> {
592    names
593        .map(|written| {
594            let name = written.trim().to_ascii_lowercase();
595            let column = if name.starts_with("time") {
596                Column::Time
597            } else if name.starts_with("altitude") {
598                Column::Altitude
599            } else if name.starts_with("velocity") {
600                Column::Velocity
601            } else if name.starts_with("temp") && name.contains("(f)") {
602                Column::Temperature(TemperatureUnit::Fahrenheit)
603            } else if name.starts_with("temp") && name.contains("(c)") {
604                Column::Temperature(TemperatureUnit::Celsius)
605            } else if let (true, Some(unit)) = (name.starts_with("temp"), cell_unit) {
606                Column::Temperature(unit)
607            } else if name.starts_with("voltage") {
608                Column::Voltage
609            } else {
610                Column::Unknown
611            };
612            if column == Column::Unknown {
613                notes.push(format!(
614                    "the column {:?} isn't one this reader knows, and was kept as written",
615                    short(&name)
616                ));
617            }
618            (column, written.trim().to_owned())
619        })
620        .collect()
621}
622
623/// Refuses a list of columns without exactly one time and one altitude.
624fn require_time_and_altitude(
625    columns: &[(Column, String)],
626    format: &'static str,
627    line: usize,
628    what: &str,
629    written: &str,
630) -> Result<(), LogError> {
631    for required in [Column::Time, Column::Altitude] {
632        if columns
633            .iter()
634            .filter(|(column, _)| *column == required)
635            .count()
636            != 1
637        {
638            return Err(LogError::Syntax {
639                format,
640                line,
641                message: format!(
642                    "the {what} must name one {required:?} column: {:?}",
643                    short(written)
644                ),
645            });
646        }
647    }
648    Ok(())
649}
650
651/// A stated height, such as `1009' AGL`, in meters; `None`, with a note, for one that isn't a
652/// number HPR Sim can read, such as `PWRLOSS`, or that names no unit, such as `1009 AGL`. A number in
653/// a unit other than feet (`'`, `ft`, `feet`) is refused.
654fn stated_feet(
655    value: &str,
656    number: usize,
657    what: &str,
658    notes: &mut Notes,
659) -> Result<Option<f64>, LogError> {
660    let end = value
661        .find(|c: char| !(c.is_ascii_digit() || matches!(c, '.' | '-' | '+')))
662        .unwrap_or(value.len());
663    let (digits, rest) = value.split_at(end);
664    let Some(feet) = digits.parse::<f64>().ok().filter(|feet| feet.is_finite()) else {
665        notes.push(format!(
666            "the file states its {what} as {:?}, which isn't a height",
667            short(value)
668        ));
669        return Ok(None);
670    };
671    let rest = rest.trim_start();
672    let word: String = rest
673        .chars()
674        .take_while(char::is_ascii_alphabetic)
675        .collect::<String>()
676        .to_ascii_lowercase();
677    if rest.starts_with('\'') || word == "ft" || word == "feet" {
678        return Ok(Some(feet * FOOT_M));
679    }
680    // `AGL` and `MSL` say what the height is measured from, not its unit.
681    if word.is_empty() || word == "agl" || word == "msl" {
682        notes.push(format!(
683            "the file states its {what} as {:?}, with no unit HPR Sim can read",
684            short(value)
685        ));
686        return Ok(None);
687    }
688    Err(LogError::Unit {
689        format: FORMAT,
690        line: number,
691        message: format!(
692            "the {what} {:?} is in {:?}, not feet ('), the only unit this reader knows",
693            short(value),
694            short(&word)
695        ),
696    })
697}
698
699/// Text from the file as an error or note quotes it: cut to [`QUOTED_CHARS`] characters, so a
700/// binary file's "first line" doesn't fill the message.
701fn short(text: &str) -> String {
702    if text.chars().count() <= QUOTED_CHARS {
703        text.to_owned()
704    } else {
705        let mut cut: String = text.chars().take(QUOTED_CHARS - 1).collect();
706        cut.push('…');
707        cut
708    }
709}
710
711/// The most characters of the file an error or note quotes.
712const QUOTED_CHARS: usize = 80;
713
714/// Puts the rows' values into the log's channels, in SI.
715fn fill(
716    log: &mut FlightLog,
717    format: &'static str,
718    columns: &[(Column, String)],
719    rows: &[(usize, Vec<f64>)],
720) -> Result<(), LogError> {
721    let syntax = |line: usize, message: String| LogError::Syntax {
722        format,
723        line,
724        message,
725    };
726    let written: usize = rows.iter().map(|(_, cells)| cells.len()).sum();
727    if crate::log::too_sparse(columns.len(), rows.len(), written) {
728        return Err(syntax(
729            rows.first().map_or(1, |(number, _)| *number),
730            format!(
731                "{} rows hold {written} of the {} cells the {} columns name: too few for the \
732                 columns to be this file's",
733                rows.len(),
734                rows.len().saturating_mul(columns.len()),
735                columns.len()
736            ),
737        ));
738    }
739    // Every column's values, the time's included, row by row; a cell a row leaves out is NaN.
740    let mut values: Vec<Vec<f64>> = vec![Vec::with_capacity(rows.len()); columns.len()];
741    for (number, cells) in rows {
742        if cells.len() > columns.len() {
743            return Err(syntax(
744                *number,
745                format!(
746                    "the row has {} values and the columns are {}",
747                    cells.len(),
748                    columns.len()
749                ),
750            ));
751        }
752        let mut time = None;
753        let mut altitude = None;
754        for (index, (column, name)) in columns.iter().enumerate() {
755            let cell = cells.get(index).copied();
756            match column {
757                Column::Time => time = cell,
758                Column::Altitude => altitude = cell,
759                _ => {}
760            }
761            // °F to kelvin multiplies by 5 before it divides by 9, so a temperature near the
762            // largest `f64` is infinite in kelvin: refused on its row's line (ADR-258 §3).
763            let value = match cell {
764                Some(value) => finite(si(*column, value), format, *number, name)?,
765                None => f64::NAN,
766            };
767            values[index].push(value);
768        }
769        let (Some(time), Some(_)) = (time, altitude) else {
770            return Err(syntax(
771                *number,
772                "the row leaves out its time or its altitude".to_owned(),
773            ));
774        };
775        if let Some(&last) = log.time_s.last()
776            && time <= last
777        {
778            return Err(syntax(
779                *number,
780                format!("the time {time} s doesn't come after the row before's {last} s"),
781            ));
782        }
783        log.time_s.push(time);
784    }
785    for ((column, name), values) in columns.iter().zip(values) {
786        let quantity = match column {
787            Column::Time => continue,
788            Column::Altitude => {
789                log.altitude_m.clone_from(&values);
790                Quantity::AltitudeAboveGround
791            }
792            Column::Velocity => {
793                log.vertical_speed_m_s = Some(values.clone());
794                Quantity::Speed
795            }
796            Column::Temperature(_) => {
797                log.temperature_k = Some(values.clone());
798                Quantity::Temperature
799            }
800            Column::Voltage => {
801                log.battery_v = Some(values.clone());
802                Quantity::Voltage
803            }
804            Column::Unknown => Quantity::Unrecognized,
805        };
806        log.channels.push(Channel {
807            column: name.clone(),
808            quantity,
809            time_s: log.time_s.clone(),
810            values,
811        });
812    }
813    Ok(())
814}
815
816/// A cell's value in SI: feet to meters, temperatures to kelvin, the rest as written.
817fn si(column: Column, value: f64) -> f64 {
818    match column {
819        Column::Altitude | Column::Velocity => value * FOOT_M,
820        Column::Temperature(unit) => unit.kelvin(value),
821        Column::Time | Column::Voltage | Column::Unknown => value,
822    }
823}
824
825/// The `.pfa`'s name in errors.
826const PFA: &str = ".pfa";
827
828/// An Alt15K/WD's samples a second, fixed: it logs "every 100 milliseconds" (*Alt15K/WD User's
829/// Manual*, PerfectFlite, p. 2), "10 samples per second" (*A15K Data Sheet*; DataCap's help, as
830/// AltCapWD 1.10 shows it). A `.pfa` doesn't state it.
831const PFA_SAMPLES_PER_S: f64 = 10.0;
832
833/// How long before the logger detected the launch its first sample is, s: "Sampling begins at a
834/// point 0.7 seconds before the launch is detected" (DataCap's help), the 8 samples it keeps from
835/// before the detection (*Alt15K/WD User's Manual*, p. 2) spanning 7 steps of 0.1 s.
836const PFA_BEFORE_DETECTION_S: f64 = 0.7;
837
838/// The sample counts DataCap's help gives for an Alt15K/WD that has likely lost power in flight,
839/// its memory then holding older flights after this one's: 2,200 for the revision 2 logger and
840/// 2,400 for the original.
841const PFA_FULL_MEMORY_SAMPLES: [usize; 2] = [2_200, 2_400];
842
843/// The most digits a `.pfa` sample may have: DataCap writes five, and an Alt15K/WD works to
844/// 15,000 ft (*Alt15K/WD User's Manual*, p. 10); a sixth is let through, more is no height.
845const PFA_SAMPLE_DIGITS: usize = 6;
846
847/// The name the record gives the `.pfa`'s one channel, the `Data` its `**!!Data:` line names.
848const PFA_CHANNEL: &str = "Data";
849
850/// Reads a `.pfa` flight log, as PerfectFlite's DataCap saves an Alt15K/WD's flight, from its
851/// text: one altitude a line after a `**!!Data:` line, each 0.1 s after the one before, in feet
852/// above the pad. The layout and where its units come from are in the [module's
853/// documentation](self).
854///
855/// # Errors
856///
857/// [`LogError::NotThisFormat`] if the first line doesn't name PerfectFlite;
858/// [`LogError::Syntax`] for a sample line that isn't a whole number, an empty line among the
859/// samples, a `**!!` line other than `**!!Data:`, or a `Ground:`, `Apogee:` or `NumSamps:` line
860/// stated twice; [`LogError::NoData`] if there is no `**!!Data:` line or no sample after it.
861pub fn read_pfa(text: &str) -> Result<FlightLog, LogError> {
862    let text = text.strip_prefix('\u{feff}').unwrap_or(text);
863    let text = text.replace("\r\n", "\n").replace('\r', "\n");
864    let mut lines = text
865        .lines()
866        .enumerate()
867        .map(|(index, line)| (index + 1, line.trim()));
868    let logger = loop {
869        match lines.next() {
870            Some((_, "")) => {}
871            Some((_, line)) if line.to_ascii_lowercase().contains("perfectflite") => {
872                break line.to_owned();
873            }
874            Some((_, line)) => {
875                return Err(LogError::NotThisFormat {
876                    format: PFA,
877                    message: format!(
878                        "its first line, {:?}, doesn't name PerfectFlite",
879                        short(line)
880                    ),
881                });
882            }
883            None => {
884                return Err(LogError::NotThisFormat {
885                    format: PFA,
886                    message: "the file is empty".to_owned(),
887                });
888            }
889        }
890    };
891
892    let mut notes = Notes::default();
893    let mut ground_ft: Option<f64> = None;
894    let mut apogee_ft: Option<f64> = None;
895    let mut stated_samples: Option<usize> = None;
896    // The keys stated so far, to refuse one stated twice.
897    let mut seen: [Option<usize>; 3] = [None; 3];
898    // The comment, from its `Comments:` line to the `**!!Data:` line, cut short as it grows.
899    let mut comment: Option<String> = None;
900    let mut data_line = false;
901    for (number, line) in lines.by_ref() {
902        if let Some(rest) = line.strip_prefix("**!!") {
903            let rest = rest.trim();
904            let named = rest
905                .strip_prefix("Data:")
906                .or_else(|| rest.strip_prefix("data:"));
907            if named.is_none_or(|after| !after.trim().is_empty()) {
908                return Err(pfa_syntax(
909                    number,
910                    format!(
911                        "{:?} isn't the `**!!Data:` line the samples follow",
912                        short(line)
913                    ),
914                ));
915            }
916            data_line = true;
917            break;
918        }
919        if let Some(comment) = comment.as_mut() {
920            // Every line after `Comments:` is the comment's, up to the samples.
921            if !line.is_empty() && comment.chars().count() <= QUOTED_CHARS {
922                if !comment.is_empty() {
923                    comment.push(' ');
924                }
925                comment.push_str(&short(line));
926            }
927            continue;
928        }
929        if line.is_empty() {
930            continue;
931        }
932        let Some((key, value)) = line.split_once(':') else {
933            notes.push(format!(
934                "line {number}, {:?}, isn't a `Key: value` line and was skipped",
935                short(line)
936            ));
937            continue;
938        };
939        let value = value.trim();
940        let key = key.trim().to_ascii_lowercase();
941        let slot = match key.as_str() {
942            "ground" => 0,
943            "apogee" => 1,
944            "numsamps" => 2,
945            "comments" => {
946                comment = Some(short(value));
947                continue;
948            }
949            _ => {
950                notes.push(format!(
951                    "line {number}, {:?}, isn't a line this reader knows and was skipped",
952                    short(line)
953                ));
954                continue;
955            }
956        };
957        if let Some(first) = seen[slot] {
958            return Err(pfa_syntax(
959                number,
960                format!(
961                    "{:?} states the {key} line {first} stated already",
962                    short(line)
963                ),
964            ));
965        }
966        seen[slot] = Some(number);
967        match slot {
968            0 | 1 => {
969                let feet = value.parse::<f64>().ok().filter(|feet| feet.is_finite());
970                if feet.is_none() {
971                    notes.push(format!(
972                        "the file states its {key} as {:?}, which isn't a height in feet",
973                        short(value)
974                    ));
975                }
976                if slot == 0 {
977                    ground_ft = feet;
978                } else {
979                    apogee_ft = feet;
980                }
981            }
982            _ => {
983                stated_samples = value.parse().ok();
984                if stated_samples.is_none() {
985                    notes.push(format!(
986                        "the file states its sample count as {:?}, which isn't a count",
987                        short(value)
988                    ));
989                }
990            }
991        }
992    }
993    if !data_line {
994        return Err(LogError::NoData { format: PFA });
995    }
996
997    // One sample a line; an empty line is allowed only after the last.
998    let mut feet: Vec<f64> = Vec::new();
999    let mut empty_line: Option<usize> = None;
1000    for (number, line) in lines {
1001        if line.is_empty() {
1002            empty_line = empty_line.or(Some(number));
1003            continue;
1004        }
1005        if let Some(empty) = empty_line {
1006            return Err(pfa_syntax(
1007                empty,
1008                "an empty line among the samples. Each line is the sample 0.1 s after the one \
1009                 before, so a line left out would move every time after it"
1010                    .to_owned(),
1011            ));
1012        }
1013        feet.push(pfa_sample(line).ok_or_else(|| {
1014            pfa_syntax(
1015                number,
1016                format!(
1017                    "{:?} isn't a sample: a whole number of feet, up to {PFA_SAMPLE_DIGITS} \
1018                     digits, alone on its line",
1019                    short(line)
1020                ),
1021            )
1022        })?);
1023    }
1024    if feet.is_empty() {
1025        return Err(LogError::NoData { format: PFA });
1026    }
1027
1028    // The n-th sample's time is n / 10 s, divided rather than multiplied by 0.1 so that each time
1029    // is the double nearest its tenth.
1030    let time_s: Vec<f64> = (0..feet.len())
1031        .map(|index| index as f64 / PFA_SAMPLES_PER_S)
1032        .collect();
1033    let altitude_m: Vec<f64> = feet.iter().map(|feet| feet * FOOT_M).collect();
1034
1035    let mut file_notes = vec![
1036        "`Data` read in feet, 0.1 s apart, from the manual. The file states neither. The \
1037         Alt15K/WD manual logs a sample every 100 ms (p. 2) and beeps its apogee in feet (p. 6). \
1038         DataCap's help gives 10 samples a second and the `Apogee:` line as the highest \
1039         sample"
1040            .to_owned(),
1041        format!(
1042            "time zero is {PFA_BEFORE_DETECTION_S} s before the logger detected the launch, not \
1043             liftoff. DataCap's help starts the samples {PFA_BEFORE_DETECTION_S} s before the \
1044             detection. Liftoff therefore came before {PFA_BEFORE_DETECTION_S} s, and before time \
1045             zero if the rocket was slow off the pad"
1046        ),
1047    ];
1048    if let Some(ground) = ground_ft {
1049        file_notes.push(format!(
1050            "the file's `Ground:`, {ground} ft, is the pad's pressure altitude, not its \
1051             elevation. DataCap's help gives it as the site's height were sea-level pressure \
1052             29.92 inHg. It is about 100 ft off for every 0.1 inHg the day's differs. It is for \
1053             interest only, and isn't read as the ground elevation"
1054        ));
1055    }
1056    if let Some(full) = [stated_samples, Some(feet.len())]
1057        .into_iter()
1058        .flatten()
1059        .find(|count| PFA_FULL_MEMORY_SAMPLES.contains(count))
1060    {
1061        file_notes.push(format!(
1062            "the file holds {full} samples. DataCap's help gives that count for an Alt15K/WD that \
1063             likely lost power in flight (2200 for revision 2, 2400 for the original). The \
1064             samples after this flight's may be older flights'"
1065        ));
1066    }
1067    if let Some(stated) = stated_samples
1068        && stated != feet.len()
1069    {
1070        file_notes.push(format!(
1071            "the file states {stated} samples and holds {}",
1072            feet.len()
1073        ));
1074    }
1075    let peak_ft = feet.iter().copied().fold(f64::NEG_INFINITY, f64::max);
1076    if let Some(apogee) = apogee_ft
1077        && apogee != peak_ft
1078    {
1079        file_notes.push(format!(
1080            "the file states its apogee as {apogee} ft and its samples peak at {peak_ft} ft"
1081        ));
1082    }
1083    if let Some(comment) = comment.filter(|comment| !comment.is_empty()) {
1084        file_notes.push(format!("the file's comment: {:?}", short(&comment)));
1085    }
1086    // The file-wide notes above come first, then those about single lines.
1087    file_notes.extend(notes.kept);
1088    if notes.left_out > 0 {
1089        file_notes.push(format!(
1090            "and {} more notes about single lines, left out so that a broken file's list stays \
1091             short",
1092            notes.left_out
1093        ));
1094    }
1095
1096    Ok(FlightLog {
1097        format: LogFormat::PerfectFlitePfa,
1098        logger,
1099        serial_number: None,
1100        firmware: None,
1101        flight_number: None,
1102        stated: Stated {
1103            apogee_m: apogee_ft.map(|feet| feet * FOOT_M),
1104            // `Ground:` is a pressure altitude, not the site's elevation: in a note, not here.
1105            ground_elevation_msl_m: None,
1106            samples: stated_samples,
1107            figures: Vec::new(),
1108        },
1109        channels: vec![Channel {
1110            column: PFA_CHANNEL.to_owned(),
1111            quantity: Quantity::AltitudeAboveGround,
1112            time_s: time_s.clone(),
1113            values: altitude_m.clone(),
1114        }],
1115        time_s,
1116        altitude_m,
1117        vertical_speed_m_s: None,
1118        temperature_k: None,
1119        battery_v: None,
1120        events: Vec::new(),
1121        notes: file_notes,
1122    })
1123}
1124
1125/// A `.pfa` sample line's height, ft: a whole number of up to [`PFA_SAMPLE_DIGITS`] digits,
1126/// perhaps after a minus sign; `None` for anything else.
1127fn pfa_sample(line: &str) -> Option<f64> {
1128    let digits = line.strip_prefix('-').unwrap_or(line);
1129    if digits.is_empty()
1130        || digits.len() > PFA_SAMPLE_DIGITS
1131        || !digits.bytes().all(|byte| byte.is_ascii_digit())
1132    {
1133        return None;
1134    }
1135    // At most six digits, so the value is exact as an `i32` and as an `f64`.
1136    line.parse::<i32>().ok().map(f64::from)
1137}
1138
1139fn pfa_syntax(line: usize, message: String) -> LogError {
1140    LogError::Syntax {
1141        format: PFA,
1142        line,
1143        message,
1144    }
1145}
1146
1147#[cfg(test)]
1148mod tests {
1149    use super::*;
1150
1151    const HEAD: &str = "PerfectFlite Pnut\r\nFirmware: 1.0\r\nSerial Number: 17\r\n\
1152                        Apogee: 1280' AGL\r\nGround Elevation: 600' MSL\r\nNumSamps: 3\r\n\
1153                        Flight Number: 2\r\nComments: \r\n\r\n\
1154                        Data: (Time, Altitude, Velocity, Temperature (F), Voltage)\r\n";
1155
1156    /// A temperature in °F near the largest `f64` is finite as written and infinite in kelvin, as
1157    /// the conversion multiplies by 5 before it divides by 9: refused on its line, in the `.pf2`
1158    /// and in both exports (ADR-258 §3). Feet only shrink, so no height or speed can overflow.
1159    #[test]
1160    fn a_value_its_conversion_makes_infinite_is_refused() {
1161        let pf2 = format!("{HEAD}0.00, 0, 0, 32.00, 4.20\r\n0.05, 1, 10, -1.7e308, 4.2\r\n");
1162        assert_eq!(
1163            read(&pf2).unwrap_err().to_string(),
1164            ".pf2 line 12: the column Temperature (F) holds a value too large for its unit's \
1165             conversion to SI"
1166        );
1167        let csv = "Time,Altitude,Velocity,Temperature (F),Voltage\n0,0,0,70,9\n\
1168                   0.05,1,1,-1.7e308,9\n";
1169        assert_eq!(
1170            read_export(csv).unwrap_err().to_string(),
1171            "PerfectFlite CSV line 3: the column Temperature (F) holds a value too large for its \
1172             unit's conversion to SI"
1173        );
1174        let text = "Time\tAltitude\tTemp.\tVoltage\n0\t0\t70F\t9\n0.05\t1\t-1.7e308F\t9\n";
1175        assert_eq!(
1176            read_export(text).unwrap_err().to_string(),
1177            "PerfectFlite text line 3: the column Temp. holds a value too large for its unit's \
1178             conversion to SI"
1179        );
1180    }
1181
1182    /// Every value in SI, a short row's missing cells gaps, and the preamble's statements read.
1183    #[test]
1184    fn reads_the_preamble_and_rows_in_si() {
1185        let text =
1186            format!("{HEAD}0.00, 0, 0, 32.00, 4.20\r\n0.05, -1, 10\r\n0.10, 10, 20, 212, 4.1\r\n");
1187        let log = read(&text).unwrap();
1188        assert_eq!(log.format, LogFormat::PerfectFlitePf2);
1189        assert_eq!(log.logger, "PerfectFlite Pnut");
1190        assert_eq!(log.serial_number.as_deref(), Some("17"));
1191        assert_eq!(log.firmware.as_deref(), Some("1.0"));
1192        assert_eq!(log.flight_number, Some(2));
1193        assert_eq!(log.stated.apogee_m, Some(1280.0 * 0.3048));
1194        assert_eq!(log.stated.ground_elevation_msl_m, Some(600.0 * 0.3048));
1195        assert_eq!(log.stated.samples, Some(3));
1196        assert_eq!(log.time_s, [0.0, 0.05, 0.10]);
1197        assert_eq!(log.altitude_m, [0.0, -0.3048, 3.048]);
1198        assert_eq!(
1199            log.vertical_speed_m_s.as_deref(),
1200            Some(&[0.0, 3.048, 6.096][..])
1201        );
1202        let temperature = log.temperature_k.unwrap();
1203        assert_eq!(temperature[0], 273.15);
1204        assert!(temperature[1].is_nan());
1205        assert!((temperature[2] - 373.15).abs() < 1e-12);
1206        let battery = log.battery_v.unwrap();
1207        assert_eq!((battery[0], battery[2]), (4.2, 4.1));
1208        assert!(battery[1].is_nan());
1209        assert!(log.notes.is_empty(), "{:?}", log.notes);
1210    }
1211
1212    /// The columns come from the `Data:` line, in its order; a column it doesn't know is noted
1213    /// and left out; without the line, Debrief's order is assumed and noted.
1214    #[test]
1215    fn columns_follow_the_data_line() {
1216        let text = "PerfectFlite StratoLogger\nData: (Altitude, Time, Pressure)\n100, 0.5, 9\n";
1217        let log = read(text).unwrap();
1218        assert_eq!((log.time_s[0], log.altitude_m[0]), (0.5, 30.48));
1219        assert!(log.vertical_speed_m_s.is_none() && log.temperature_k.is_none());
1220        assert!(log.notes[0].contains("\"pressure\""), "{:?}", log.notes);
1221
1222        let log = read("PerfectFlite Pnut\n0.0, 5, 1, 50, 4\n").unwrap();
1223        assert_eq!(log.altitude_m, [5.0 * 0.3048]);
1224        assert!(log.notes[0].contains("no `Data:` line"), "{:?}", log.notes);
1225    }
1226
1227    /// `PWRLOSS` is no height, and `1009 AGL` names no unit: both noted, not refused. A height in
1228    /// another unit is refused.
1229    #[test]
1230    fn stated_heights_are_feet_or_nothing() {
1231        let log = read("PerfectFlite Pnut\nApogee: PWRLOSS\n0, 0, 0\n").unwrap();
1232        assert_eq!(log.stated.apogee_m, None);
1233        assert!(
1234            log.notes.iter().any(|note| note.contains("PWRLOSS")),
1235            "{:?}",
1236            log.notes
1237        );
1238        let error = read("PerfectFlite Pnut\nApogee: 390 m AGL\n0, 0, 0\n").unwrap_err();
1239        assert!(
1240            matches!(&error, LogError::Unit { line: 2, message, .. } if message.contains("\"390 m AGL\" is in \"m\"")),
1241            "{error}"
1242        ); // `AGL` names the height's zero, not its unit: noted, and the flight still reads.
1243        let log = read("PerfectFlite Pnut\nApogee: 1009 AGL\n0, 0, 0\n").unwrap();
1244        assert_eq!(log.stated.apogee_m, None);
1245        assert!(
1246            log.notes.iter().any(|note| note.contains("no unit")),
1247            "{:?}",
1248            log.notes
1249        );
1250    }
1251
1252    /// A header of many unreadable lines keeps a short list of notes, the file-wide one first,
1253    /// and counts the 980 it left out of the 1,000 skipped lines.
1254    #[test]
1255    fn notes_stay_few() {
1256        let text = format!("PerfectFlite Pnut\n{}0, 0, 0\n", "x\n".repeat(1000));
1257        let log = read(&text).unwrap();
1258        assert_eq!(log.notes.len(), MAX_NOTES + 2);
1259        assert!(log.notes[0].contains("no `Data:` line"), "{:?}", log.notes);
1260        assert!(
1261            log.notes[MAX_NOTES + 1].starts_with("and 980 more notes"),
1262            "{:?}",
1263            log.notes
1264        );
1265    }
1266
1267    /// A file that isn't text is refused with a short quote of it, not the whole of it.
1268    #[test]
1269    fn a_long_line_is_quoted_short() {
1270        let junk = "\u{fffd}".repeat(100_000);
1271        let error = read(&junk).unwrap_err().to_string();
1272        assert!(error.len() < 400, "{} bytes", error.len());
1273        assert!(error.contains('…'), "{error}");
1274    }
1275
1276    /// A byte-order mark is dropped; CR-only line ends read as lines; `ft` is feet; a height
1277    /// hpr can't read, such as one with a thousands comma, is noted and left out.
1278    #[test]
1279    fn marks_line_ends_and_odd_heights() {
1280        let log = read(
1281            "\u{feff}PerfectFlite Pnut\rApogee: 1,009' AGL\rGround Elevation: 600 ft\r0, 0, 0\r",
1282        )
1283        .unwrap();
1284        assert_eq!(log.logger, "PerfectFlite Pnut");
1285        assert_eq!(log.time_s.len(), 1);
1286        assert_eq!(log.stated.apogee_m, None);
1287        assert!(
1288            log.notes.iter().any(|note| note.contains("\"1,009' AGL\"")),
1289            "{:?}",
1290            log.notes
1291        );
1292        assert_eq!(log.stated.ground_elevation_msl_m, Some(600.0 * FOOT_M));
1293    }
1294
1295    /// Each refusal names its line and what is wrong.
1296    #[test]
1297    fn malformed_files_are_refused_where_they_go_wrong() {
1298        let cases = [
1299            ("", "the file is empty"),
1300            ("Time, Altitude\n0, 0\n", "doesn't name PerfectFlite"),
1301            ("PerfectFlite Pnut\nApogee: 5'\n", "no data rows"),
1302            (
1303                "PerfectFlite Pnut\n0, 0, 0\n0, 1, 0\n",
1304                "line 3: the time 0 s doesn't come after",
1305            ),
1306            (
1307                "PerfectFlite Pnut\n0, 0, x\n",
1308                "line 2: \"x\" isn't a finite number",
1309            ),
1310            (
1311                "PerfectFlite Pnut\n0, 0, 0\nEnd\n",
1312                "line 3: \"End\" after the data rows",
1313            ),
1314            (
1315                "PerfectFlite Pnut\n0, 0, 0, 1, 2, 3\n",
1316                "line 2: the row has 6 values",
1317            ),
1318            ("PerfectFlite Pnut\n0\n", "no data rows"),
1319            (
1320                "PerfectFlite Pnut\nData: (Time, Velocity)\n0, 0\n",
1321                "line 2: the `Data:` line",
1322            ),
1323            (
1324                "PerfectFlite Pnut\nData: (Time, Altitude)\n0.5\n",
1325                "no data rows",
1326            ),
1327            (
1328                "PerfectFlite Pnut\nData: (Time, Altitude)\n0.5,\n",
1329                "line 3: \"\" isn't",
1330            ),
1331            (
1332                "PerfectFlite Pnut\n0, inf, 0\n",
1333                "line 2: \"inf\" isn't a finite number",
1334            ),
1335        ];
1336        for (text, expected) in cases {
1337            let error = read(text).unwrap_err().to_string();
1338            assert!(error.contains(expected), "{text:?}: {error}");
1339        }
1340        // A short row that stops before the altitude's column leaves it out.
1341        let error =
1342            read("PerfectFlite Pnut\nData: (Time, Velocity, Altitude)\n0, 5\n").unwrap_err();
1343        assert!(
1344            error.to_string().contains("line 3: the row leaves out"),
1345            "{error}"
1346        );
1347    }
1348
1349    /// A stated sample count the rows don't match is noted.
1350    #[test]
1351    fn a_sample_count_that_differs_is_noted() {
1352        let log = read("PerfectFlite Pnut\nNumSamps: 3\n0, 0, 0\n0.05, 0, 0\n").unwrap();
1353        assert_eq!(
1354            log.notes.last().unwrap(),
1355            "the file states 3 samples and holds 2"
1356        );
1357    }
1358
1359    /// An invented `.pfa`'s preamble, CR-separated as DataCap writes most.
1360    const PFA_HEAD: &str =
1361        "PerfectFlite Alt15K/WD\rGround: 1150\rApogee: 30\rNumSamps: 4\rComments: \r\r**!!Data: \r";
1362
1363    /// Each sample is 0.1 s after the one before, from 0, and feet above the pad in meters; the
1364    /// stated apogee and count read, and `Ground:` stays out of the ground elevation.
1365    #[test]
1366    fn a_pfa_reads_a_sample_every_tenth_of_a_second() {
1367        let log = read_pfa(&format!("{PFA_HEAD}00000\r00004\r00030\r00012\r")).unwrap();
1368        assert_eq!(log.format, LogFormat::PerfectFlitePfa);
1369        assert_eq!(log.logger, "PerfectFlite Alt15K/WD");
1370        assert_eq!(log.time_s, [0.0, 0.1, 0.2, 0.3]);
1371        assert_eq!(
1372            log.altitude_m,
1373            [0.0, 4.0 * FOOT_M, 30.0 * FOOT_M, 12.0 * FOOT_M]
1374        );
1375        assert_eq!(log.stated.apogee_m, Some(30.0 * FOOT_M));
1376        assert_eq!(log.stated.samples, Some(4));
1377        assert_eq!(log.stated.ground_elevation_msl_m, None);
1378        assert_eq!(log.channels.len(), 1);
1379        assert_eq!(log.channels[0].column, "Data");
1380        assert_eq!(log.channels[0].quantity, Quantity::AltitudeAboveGround);
1381        assert_eq!(log.channels[0].values, log.altitude_m);
1382        assert_eq!(log.channels[0].time_s, log.time_s);
1383        // The unit decision, the clock's zero and `Ground:`, and nothing more.
1384        assert_eq!(log.notes.len(), 3, "{:?}", log.notes);
1385        assert!(
1386            log.notes[0].starts_with("`Data` read in feet, 0.1 s apart, from the manual. "),
1387            "{:?}",
1388            log.notes
1389        );
1390        assert!(log.notes[1].starts_with("time zero is 0.7 s before the logger detected"));
1391        assert!(log.notes[2].starts_with("the file's `Ground:`, 1150 ft, is the pad's pressure"));
1392    }
1393
1394    /// The thousandth sample's time is the double nearest 99.9 s, not 999 × 0.1's sum or product.
1395    #[test]
1396    fn a_pfa_time_is_the_nearest_double_to_its_tenth() {
1397        let samples = "00001\r".repeat(1000);
1398        let log = read_pfa(&format!("PerfectFlite Alt15K/WD\r**!!Data:\r{samples}")).unwrap();
1399        assert_eq!(log.time_s[999], 99.9);
1400        assert_eq!(log.time_s[3], 0.3);
1401    }
1402
1403    /// The count DataCap's help names for a logger that lost power is noted, stated or read;
1404    /// another large count isn't.
1405    #[test]
1406    fn a_pfa_at_a_full_memory_count_is_noted() {
1407        for (count, noted) in [(2_200, true), (2_400, true), (2_304, false), (2_199, false)] {
1408            let samples = "00010\r".repeat(count);
1409            let text = format!("PerfectFlite Alt15K/WD\r**!!Data:\r{samples}");
1410            let log = read_pfa(&text).unwrap();
1411            let note = format!("the file holds {count} samples. DataCap's help gives that count");
1412            assert_eq!(
1413                log.notes.iter().any(|n| n.starts_with(&note)),
1414                noted,
1415                "{count}: {:?}",
1416                log.notes
1417            );
1418        }
1419        // Stated, though the file holds fewer: noted, beside the count that differs.
1420        let log =
1421            read_pfa("PerfectFlite Alt15K/WD\rNumSamps: 2400\r**!!Data:\r00001\r00002\r").unwrap();
1422        assert!(
1423            log.notes
1424                .iter()
1425                .any(|n| n.starts_with("the file holds 2400 samples"))
1426        );
1427        assert!(
1428            log.notes
1429                .iter()
1430                .any(|n| n == "the file states 2400 samples and holds 2")
1431        );
1432    }
1433
1434    /// A huge stated count costs nothing: nothing is sized from it.
1435    #[test]
1436    fn a_pfa_huge_count_allocates_nothing() {
1437        let log = read_pfa(&format!(
1438            "PerfectFlite Alt15K/WD\rNumSamps: {}\r**!!Data:\r00001\r",
1439            usize::MAX
1440        ))
1441        .unwrap();
1442        assert_eq!(log.stated.samples, Some(usize::MAX));
1443        assert_eq!(log.time_s.len(), 1);
1444    }
1445
1446    /// An apogee that isn't the samples' highest, a value that isn't a height and a comment over
1447    /// several lines are noted; `Ground:` that isn't a height leaves no `Ground:` note.
1448    #[test]
1449    fn a_pfa_preamble_is_checked_against_its_samples() {
1450        let text = "PerfectFlite Alt15K/WD\rGround: n/a\rApogee: 31\rNumSamps: lots\r\
1451                    Comments: first line\rsecond: line\r\r**!!Data:\r00000\r00030\r";
1452        let log = read_pfa(text).unwrap();
1453        let notes = &log.notes;
1454        assert!(
1455            notes.contains(
1456                &"the file states its apogee as 31 ft and its samples peak at 30 ft".to_owned()
1457            ),
1458            "{notes:?}"
1459        );
1460        assert!(notes.contains(&"the file's comment: \"first line second: line\"".to_owned()));
1461        assert!(notes.iter().any(|n| n.contains("its ground as \"n/a\"")));
1462        assert!(notes.iter().any(|n| n.contains("sample count as \"lots\"")));
1463        assert!(!notes.iter().any(|n| n.contains("pressure altitude")));
1464        assert_eq!(log.stated.samples, None);
1465        // A comment of any length is quoted short.
1466        let long = format!(
1467            "PerfectFlite Alt15K/WD\rComments: {}\r**!!Data:\r00001\r",
1468            "word ".repeat(10_000)
1469        );
1470        let log = read_pfa(&long).unwrap();
1471        let comment = log
1472            .notes
1473            .iter()
1474            .find(|n| n.starts_with("the file's comment"))
1475            .unwrap();
1476        assert!(comment.chars().count() < 2 * QUOTED_CHARS, "{comment}");
1477    }
1478
1479    /// Each refusal names its line and what is wrong.
1480    #[test]
1481    fn a_malformed_pfa_is_refused_where_it_goes_wrong() {
1482        let cases = [
1483            ("", "the file is empty"),
1484            ("Ground: 5\r**!!Data:\r00001\r", "doesn't name PerfectFlite"),
1485            ("PerfectFlite Alt15K/WD\rApogee: 5\r", "no data rows"),
1486            ("PerfectFlite Alt15K/WD\r**!!Data:\r\r", "no data rows"),
1487            (
1488                "PerfectFlite Alt15K/WD\r**!!Data:\r00001\r0001x\r",
1489                "line 4: \"0001x\" isn't a sample",
1490            ),
1491            (
1492                "PerfectFlite Alt15K/WD\r**!!Data:\r00001\r12.5\r",
1493                "line 4: \"12.5\" isn't a sample",
1494            ),
1495            (
1496                "PerfectFlite Alt15K/WD\r**!!Data:\r00001\r00001, 00002\r",
1497                "line 4: \"00001, 00002\" isn't a sample",
1498            ),
1499            (
1500                "PerfectFlite Alt15K/WD\r**!!Data:\r1234567\r",
1501                "line 3: \"1234567\" isn't a sample",
1502            ),
1503            (
1504                "PerfectFlite Alt15K/WD\r**!!Data:\r-\r",
1505                "line 3: \"-\" isn't a sample",
1506            ),
1507            (
1508                "PerfectFlite Alt15K/WD\r**!!Data:\r00001\r\r00002\r",
1509                "line 4: an empty line among the samples",
1510            ),
1511            (
1512                "PerfectFlite Alt15K/WD\r**!!Data:\r00001\r**!!Data:\r00002\r",
1513                "line 4: \"**!!Data:\" isn't a sample",
1514            ),
1515            (
1516                "PerfectFlite Alt15K/WD\r**!!Info:\r00001\r",
1517                "line 2: \"**!!Info:\" isn't the `**!!Data:` line",
1518            ),
1519            (
1520                "PerfectFlite Alt15K/WD\r**!!Data: 00001\r",
1521                "line 2: \"**!!Data: 00001\" isn't the `**!!Data:` line",
1522            ),
1523            (
1524                "PerfectFlite Alt15K/WD\rApogee: 5\rApogee: 6\r**!!Data:\r00001\r",
1525                "line 3: \"Apogee: 6\" states the apogee line 2 stated already",
1526            ),
1527        ];
1528        for (text, expected) in cases {
1529            let error = read_pfa(text).unwrap_err().to_string();
1530            assert!(error.contains(expected), "{text:?}: {error}");
1531            assert!(error.contains(".pfa"), "{text:?}: {error}");
1532        }
1533        // A negative sample, below the pad, reads; so do trailing empty lines.
1534        let log = read_pfa("PerfectFlite Alt15K/WD\r**!!Data:\r-0003\r00001\r\r\r").unwrap();
1535        assert_eq!(log.altitude_m, [-3.0 * FOOT_M, FOOT_M]);
1536    }
1537
1538    /// Unknown preamble lines are noted, and only so many of them.
1539    #[test]
1540    fn a_pfa_keeps_its_notes_few() {
1541        let text = format!(
1542            "PerfectFlite Alt15K/WD\r{}**!!Data:\r00001\r",
1543            "Odd: line\r".repeat(500)
1544        );
1545        let log = read_pfa(&text).unwrap();
1546        assert_eq!(log.notes.len(), 2 + MAX_NOTES + 1, "{:?}", log.notes);
1547        assert!(log.notes.last().unwrap().starts_with("and 480 more notes"));
1548    }
1549
1550    proptest::proptest! {
1551        /// Any text is read or refused as a `.pfa`, never a panic; what is read has times 0.1 s
1552        /// apart from 0 and as many altitudes.
1553        #[test]
1554        fn any_pfa_text_is_read_or_refused(
1555            text in "(PerfectFlite Alt15K/WD\r)?([-0-9 A-Za-z:*!]{0,12}\r){0,6}(\\*\\*!!Data:\r)?([-0-9 ]{0,7}\r){0,12}"
1556        ) {
1557            if let Ok(log) = read_pfa(&text) {
1558                proptest::prop_assert_eq!(log.time_s.len(), log.altitude_m.len());
1559                for (index, time) in log.time_s.iter().enumerate() {
1560                    proptest::prop_assert_eq!(*time, index as f64 / 10.0);
1561                }
1562            }
1563        }
1564    }
1565
1566    proptest::proptest! {
1567        /// Any text is read or refused, never a panic; what is read has increasing finite times.
1568        #[test]
1569        fn any_text_is_read_or_refused(text in "(PerfectFlite Pnut\n)?([-0-9., A-Za-z:'()]{0,20}\n){0,12}") {
1570            if let Ok(log) = read(&text) {
1571                proptest::prop_assert!(log.time_s.windows(2).all(|pair| pair[1] > pair[0]));
1572                proptest::prop_assert_eq!(log.time_s.len(), log.altitude_m.len());
1573            }
1574        }
1575    }
1576}