Expand description
Binary records read by a layout the caller states: a team’s flight computer that writes each
sample as a fixed run of bytes, such as a u32 clock in milliseconds then 24 f32 readings,
with nothing in the file to say so.
No maker documents these files, and their bytes carry no names: a record of a clock and two
readings looks like any other 12 bytes. So the reader takes the layout from the caller, each
field’s name and type in the record’s order (RecordLayout), and never guesses one. The
names do the work a table’s header does: the records are written out as a table, the names its
header and one row a record, and the table is read by generic::read, which reads a column
in a unit only where its name states one, such as timestamp__ms or Time (ms), and keeps
every other as written. A layout whose names state no clock is refused; table gives the
text, for a caller who would rather read it by a column mapping (generic::read_with).
Records. The file is records end to end, from its first byte, each the layout’s fields with
no gap between them, in little-endian byte order unless the layout says big. A field is an
unsigned or signed integer of 8, 16, 32 or 64 bits, or an IEEE 754 binary32 or binary64 float
(FieldKind). A float that isn’t finite (a NaN or an infinity) is written as an empty cell,
which the table’s reader keeps as a gap, and counted in a note.
Erased flash. A logger that saves to flash memory leaves the memory it never wrote erased,
every byte 0xFF, and a dump of the memory may run past its last record into it. A run of
records each wholly 0xFF at the file’s end is that memory, not samples: it is dropped, and a
note counts it. So are bytes past the last whole record if every one is 0xFF. Any other bytes
past the last whole record are refused, as a layout that doesn’t fit the file. An erased record
with a written one after it is read as written: its unsigned integers at their largest, its
signed ones −1, its floats NaN. So a file with a float clock is refused at such a record, its
clock no number; with an integer clock, the record’s time and values stay in the log, and a
column whose values it pushes past what its unit allows is kept as written.
Bounds. A layout has from 2 to MAX_FIELDS fields, each named with 1 to
MAX_NAME_CHARS characters, no two alike, none a number or holding a separator (a comma, a
semicolon or |), a quotation mark, a control character or spaces at its ends, and the first
not opening with #, sep= or a byte order mark. The table is refused once its text would pass MAX_TEXT_BYTES.
How far to trust it: the reader is exact for the bytes and types the caller states; whether the
layout is the logger’s is the caller’s statement. The project’s sample files are each held,
field by field, to the table the logger’s team decoded from the same bytes (cargo xtask logs, ADR-271).
use hpr_flightdata::records::{self, Field, FieldKind, RecordLayout};
// Two invented records: a clock in milliseconds and a pressure in kilopascals.
let mut bytes = Vec::new();
for (ms, kpa) in [(1000_u32, 101.3_f32), (1010, 101.2)] {
bytes.extend(ms.to_le_bytes());
bytes.extend(kpa.to_le_bytes());
}
let layout = RecordLayout::new(vec![
Field::new("time__ms", FieldKind::U32),
Field::new("pressure__kpa", FieldKind::F32),
]);
let log = records::read(&bytes, &layout)?;
assert_eq!(log.channels[0].time_s, [1.0, 1.01]);
assert_eq!(log.channels[0].values[0], f64::from(101.3_f32) * 1000.0); // pascalsStructs§
- Field
- One field of a record: its name, as a table’s header would write it, and its type.
- Record
Layout - How each record of a file is laid out: its fields, in order, with no gap between them.
- Table
- A file’s records written out as a table, by
table.
Enums§
Constants§
- MAX_
FIELDS - The most fields a layout may have: as many columns as a table may.
- MAX_
NAME_ CHARS - The most characters in a field’s name.
- MAX_
TEXT_ BYTES - The most bytes of text the records may be written out as: a bound on the memory a file can make the reader take, whatever its layout (a binary64 can write over 300 characters).
Functions§
- read
- Reads a file of binary records by the layout the caller states (module docs), as
LogFormat::BinaryRecords. - table
- The file’s records written out as a table (module docs);
table_withinwithMAX_TEXT_BYTES. - table_
within - The file’s records written out as a table of at most
max_text_bytes(module docs).