Skip to main content

Module records

Module records 

Source
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); // pascals

Structs§

Field
One field of a record: its name, as a table’s header would write it, and its type.
RecordLayout
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§

ByteOrder
The order of a field’s bytes.
FieldKind
The type of one field of a record.

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_within with MAX_TEXT_BYTES.
table_within
The file’s records written out as a table of at most max_text_bytes (module docs).