Skip to main content

hpr_flightdata/
xls.rs

1//! Excel's older binary format, `.xls`, as a bare worksheet stream: the records of one sheet, written
2//! on their own rather than inside the compound file Excel 97 and later save, as some loggers'
3//! programs write their exports.
4//!
5//! Like an `.xlsx` workbook ([`workbook`](crate::workbook)), the file isn't a layout of its own.
6//! [`sheets`] writes the sheet's cells out as comma-separated text, one line a row, and [`read`]
7//! gives the text to [`import::read`], which recognizes it as it would the file the sheet came
8//! from.
9//!
10//! **The records.** A BIFF stream is a run of records, each a 16-bit identifier, a 16-bit length
11//! and that many bytes, all little-endian. A worksheet's stream opens with a BOF record and closes
12//! with an EOF record (*OpenOffice.org's Documentation of the Microsoft Excel File Format*, Daniel
13//! Rentz, revision 1.42, 2008, §2.1, §4.1.1, §5.8 and §5.37; Microsoft's *[MS-XLS]* describes only
14//! BIFF8). The reader takes the stream when its first record is a BOF of any version (identifier
15//! `0009`, `0209`, `0409` or `0809`) for a worksheet (type `0010`), and reads these cell records,
16//! BIFF2's:
17//!
18//! | Record | Identifier | The cell | Written as |
19//! |---|---|---|---|
20//! | NUMBER (§5.71) | `0003` | a 64-bit IEEE 754 number | its shortest decimal that reads back as the same double, such as `0.005` |
21//! | INTEGER (§5.60) | `0002` | an unsigned 16-bit integer | its digits |
22//! | LABEL (§5.63) | `0004` | text, 8-bit, its length in one byte | its text |
23//! | BOOLERR (§5.10) | `0005` | a truth value, or an error such as `#DIV/0!` | `TRUE` or `FALSE`; an error is a gap |
24//! | BLANK (§5.7) | `0001` | a cell formatted but empty | nothing |
25//!
26//! Every other record, formats, fonts, column widths and the sheet's settings, is passed over. A
27//! record of a later version that holds a value (NUMBER `0203`, LABEL `0204`, RK, MULRK, LABELSST,
28//! RSTRING, BOOLERR `0205`) or a formula is refused by name rather than passed over, so no value is
29//! left out unsaid.
30//!
31//! **What a cell becomes.** A cell is written as the sheet stores it. Its format isn't read: each
32//! BIFF2 cell names one in its attributes (§2.5.13), and a number under one other than the first,
33//! `General`, is written as the number stored, with a note counting them, as such a number may be
34//! a date the sheet would show as one. Text is taken only in plain ASCII: a byte beyond it is in a
35//! code page the reader doesn't read, and the sheet is refused. A cell's text that holds a comma or
36//! a double quote is quoted, its quotes doubled; a line break inside it becomes a space, as an
37//! `.xlsx` sheet's does.
38//!
39//! **Rows and columns.** Cells are placed by their row and column. Every row is written as wide as
40//! the sheet's last column that holds a value; a row with no value is left out. A sheet with no
41//! value gives no text, and [`read`] says it has no data. A worksheet's stream names no sheet, so
42//! the sheet's name is empty.
43//!
44//! **Bounds.** The cells must come in order, row by row and, within a row, column by column, as
45//! Excel writes them, so that a cell can't be written twice; a column past `IV`, the 256th and last
46//! of a BIFF2 to BIFF5 sheet, is refused, as is a record longer than 8,224 bytes (BIFF8's limit,
47//! §2.1.2), one that runs past the end, a stream with no EOF, or bytes after it, where a second
48//! stream would be passed over. The text written is held to [`MAX_TEXT_BYTES`], each line counted
49//! before it is kept. A workbook of several sheets, as Excel 5 and later write inside a compound
50//! file, isn't read yet.
51//!
52//! ```
53//! use hpr_flightdata::xls;
54//!
55//! // An invented worksheet stream: BOF, a header of two labels, two rows of numbers, EOF.
56//! fn record(id: u16, data: &[u8]) -> Vec<u8> {
57//!     let mut bytes = id.to_le_bytes().to_vec();
58//!     bytes.extend((data.len() as u16).to_le_bytes());
59//!     bytes.extend(data);
60//!     bytes
61//! }
62//! fn cell(row: u16, column: u16) -> Vec<u8> {
63//!     let mut bytes = row.to_le_bytes().to_vec();
64//!     bytes.extend(column.to_le_bytes());
65//!     bytes.extend([0, 0, 0]); // the cell's attributes: format 0, General
66//!     bytes
67//! }
68//! let mut stream = record(0x0009, &[0, 0, 0x10, 0]);
69//! for (column, name) in ["Time (s)", "Altitude (m)"].iter().enumerate() {
70//!     let mut data = cell(0, column as u16);
71//!     data.push(name.len() as u8);
72//!     data.extend(name.as_bytes());
73//!     stream.extend(record(0x0004, &data));
74//! }
75//! for (row, values) in [[0.0f64, 0.0], [0.05, 1.5]].iter().enumerate() {
76//!     for (column, value) in values.iter().enumerate() {
77//!         let mut data = cell(row as u16 + 1, column as u16);
78//!         data.extend(value.to_le_bytes());
79//!         stream.extend(record(0x0003, &data));
80//!     }
81//! }
82//! stream.extend(record(0x000A, &[]));
83//!
84//! let sheets = xls::sheets(&stream)?;
85//! assert_eq!(sheets[0].text, "Time (s),Altitude (m)\n0,0\n0.05,1.5\n");
86//! let log = xls::read(&stream)?.remove(0).log?;
87//! // A table read by its header: each column a channel in its stated unit.
88//! assert!(log.channels.iter().any(|c| c.column == "Altitude (m)" && c.values == [0.0, 1.5]));
89//! # Ok::<(), hpr_flightdata::error::LogError>(())
90//! ```
91
92use crate::error::LogError;
93use crate::import;
94use crate::workbook::{Sheet, SheetLog, escaped, shortened};
95
96/// The most text taken from one stream, 256 MiB: [`workbook`](crate::workbook)'s bound.
97pub const MAX_TEXT_BYTES: usize = crate::workbook::MAX_TEXT_BYTES;
98
99/// The longest record's data, BIFF8's limit (§2.1.2; BIFF2 to BIFF5's is 2,080 bytes).
100const MAX_RECORD_BYTES: usize = 8_224;
101
102/// Columns `A` to `IV`, a BIFF2 to BIFF5 sheet's.
103const MAX_COLUMNS: u16 = 256;
104
105/// The BOF record's identifiers, BIFF2's to BIFF8's (§5.8).
106const BOF: [u16; 4] = [0x0009, 0x0209, 0x0409, 0x0809];
107
108/// A BOF's type for a worksheet (§5.8).
109const WORKSHEET: u16 = 0x0010;
110
111const EOF: u16 = 0x000A;
112const BLANK: u16 = 0x0001;
113const INTEGER: u16 = 0x0002;
114const NUMBER: u16 = 0x0003;
115const LABEL: u16 = 0x0004;
116const BOOLERR: u16 = 0x0005;
117
118/// Records of later versions that hold a cell's value, refused by name (§5.50, §5.65, §5.71,
119/// §5.63, §5.10, §5.87, §5.68, §5.89, §5.103).
120const NOT_READ: [(u16, &str); 13] = [
121    (0x0006, "FORMULA"),
122    (0x0206, "FORMULA"),
123    (0x0406, "FORMULA"),
124    (0x0007, "STRING"),
125    (0x0207, "STRING"),
126    (0x0203, "NUMBER (BIFF3 and later)"),
127    (0x0204, "LABEL (BIFF3 and later)"),
128    (0x0205, "BOOLERR (BIFF3 and later)"),
129    (0x027E, "RK"),
130    (0x00BD, "MULRK"),
131    (0x00FD, "LABELSST"),
132    (0x00D6, "RSTRING"),
133    (0x04BC, "SHRFMLA"),
134];
135
136const FORMAT: &str = "Excel `.xls` worksheet";
137
138/// Whether `bytes` open as a worksheet's BIFF stream: a BOF record of any version, whole, whose
139/// type is a sheet, a chart or a macro sheet, or a workbook's globals (§5.8). [`sheets`] reads only
140/// a worksheet's.
141pub fn recognizes(bytes: &[u8]) -> bool {
142    // The record's identifier and length, then the BOF's version and type.
143    let Some(header) = bytes.get(..8) else {
144        return false;
145    };
146    let id = u16::from_le_bytes([header[0], header[1]]);
147    let length = usize::from(u16::from_le_bytes([header[2], header[3]]));
148    let kind = u16::from_le_bytes([header[6], header[7]]);
149    BOF.contains(&id)
150        && (4..=20).contains(&length)
151        && bytes.len() >= 4 + length
152        && [0x0005, WORKSHEET, 0x0020, 0x0040].contains(&kind)
153}
154
155/// The sheet of a bare worksheet stream, read as a log by [`import::read`], as
156/// [`workbook::read`](crate::workbook::read) reads an `.xlsx` workbook's.
157///
158/// # Errors
159///
160/// As [`sheets`]; a sheet that doesn't read is not an error, but its [`SheetLog::log`].
161pub fn read(bytes: &[u8]) -> Result<Vec<SheetLog>, LogError> {
162    Ok(sheets(bytes)?
163        .into_iter()
164        .map(|sheet| {
165            let log = if sheet.text.is_empty() {
166                Err(LogError::NoData { format: FORMAT })
167            } else {
168                import::read(sheet.text.as_bytes()).map(|mut log| {
169                    let mut notes =
170                        vec!["read from an Excel `.xls` worksheet, its cells as stored".to_owned()];
171                    notes.extend(sheet.notes);
172                    notes.append(&mut log.notes);
173                    log.notes = notes;
174                    log
175                })
176            };
177            SheetLog {
178                name: sheet.name,
179                log,
180            }
181        })
182        .collect())
183}
184
185/// The sheet of a bare worksheet stream as text; [`sheets_within`] with [`MAX_TEXT_BYTES`].
186///
187/// # Errors
188///
189/// As [`sheets_within`].
190pub fn sheets(bytes: &[u8]) -> Result<Vec<Sheet>, LogError> {
191    sheets_within(bytes, MAX_TEXT_BYTES)
192}
193
194/// The sheet of a bare worksheet stream as text, keeping at most `max_text_bytes` of it: one
195/// sheet, as the stream holds one.
196///
197/// # Errors
198///
199/// [`LogError::NotThisFormat`] when the bytes don't open with a BOF record ([`recognizes`]);
200/// [`LogError::Workbook`] when the stream is a workbook's or a chart's rather than a worksheet's,
201/// a record runs past the end or past 8,224 bytes, a cell record is shorter than its fields, a
202/// record holds a value the reader doesn't read (a formula, or a later version's cell), cells
203/// come out of order or past column `IV`, a number isn't finite, a text cell holds a byte beyond
204/// ASCII, the stream has no EOF or holds bytes after it, or the text would pass
205/// `max_text_bytes`.
206pub fn sheets_within(bytes: &[u8], max_text_bytes: usize) -> Result<Vec<Sheet>, LogError> {
207    if !recognizes(bytes) {
208        return Err(LogError::NotThisFormat {
209            format: FORMAT,
210            message: "its bytes don't open with a BIFF stream's BOF record".to_owned(),
211        });
212    }
213    // Invariant: `recognizes` read the BOF's type, its data's bytes 2 and 3.
214    let kind = u16::from_le_bytes([bytes[6], bytes[7]]);
215    if kind != WORKSHEET {
216        return Err(refused(format!(
217            "it is a BIFF stream of type {kind:04X}h, a workbook's, a chart's or a macro sheet's: \
218             only a worksheet's stream, type 0010h, is read"
219        )));
220    }
221    // Two walks: the first checks the whole stream and finds how wide the rows are, the second
222    // writes them, so that no cell is held twice in memory.
223    let mut width = 0u16;
224    let mut counts = Counts::default();
225    walk(bytes, |cell| {
226        if cell.value.is_some() {
227            width = width.max(cell.column + 1);
228        }
229        match cell.value {
230            Some(Value::Number(_)) if cell.format != 0 => counts.formatted += 1,
231            None if cell.error => counts.errors += 1,
232            _ => {}
233        }
234        Ok(())
235    })?;
236    let mut text = String::new();
237    let mut row: Vec<Option<String>> = vec![None; usize::from(width)];
238    let mut current: Option<u16> = None;
239    let flush = |row: &mut Vec<Option<String>>, text: &mut String| -> Result<(), LogError> {
240        if row.iter().all(Option::is_none) {
241            return Ok(());
242        }
243        let line = row
244            .iter_mut()
245            .map(|cell| cell.take().unwrap_or_default())
246            .collect::<Vec<_>>()
247            .join(",");
248        if text.len() + line.len() + 1 > max_text_bytes {
249            return Err(refused(format!(
250                "its text would pass {max_text_bytes} bytes, the most taken from one sheet"
251            )));
252        }
253        text.push_str(&line);
254        text.push('\n');
255        Ok(())
256    };
257    walk(bytes, |cell| {
258        if current != Some(cell.row) {
259            flush(&mut row, &mut text)?;
260            current = Some(cell.row);
261        }
262        if let Some(value) = cell.value {
263            row[usize::from(cell.column)] = Some(value.text());
264        }
265        Ok(())
266    })?;
267    flush(&mut row, &mut text)?;
268    let mut notes = Vec::new();
269    if counts.formatted > 0 {
270        notes.push(format!(
271            "{} numbers under a number format other than `General` were kept as stored. The \
272             reader doesn't read a BIFF2 sheet's formats, so a date stays its serial number",
273            counts.formatted
274        ));
275    }
276    if counts.errors > 0 {
277        notes.push(format!(
278            "{} cells holding an error value, such as `#DIV/0!`, are gaps",
279            counts.errors
280        ));
281    }
282    Ok(vec![Sheet {
283        name: String::new(),
284        text,
285        notes,
286    }])
287}
288
289/// What [`sheets_within`] counts for its notes.
290#[derive(Default)]
291struct Counts {
292    formatted: usize,
293    errors: usize,
294}
295
296/// A cell's value, as the stream stores it.
297enum Value<'a> {
298    Number(f64),
299    Integer(u16),
300    Text(&'a str),
301    Bool(bool),
302}
303
304impl Value<'_> {
305    /// The value as the sheet's text writes it.
306    fn text(&self) -> String {
307        match self {
308            // Rust writes a double as the shortest decimal that reads back as the same double.
309            Value::Number(value) => value.to_string(),
310            Value::Integer(value) => value.to_string(),
311            Value::Text(text) => escaped(text).into_owned(),
312            Value::Bool(value) => if *value { "TRUE" } else { "FALSE" }.to_owned(),
313        }
314    }
315}
316
317/// A cell record, read: its place, its format's index and its value, `None` for a gap.
318struct Cell<'a> {
319    row: u16,
320    column: u16,
321    format: u8,
322    value: Option<Value<'a>>,
323    /// The cell holds an error value, written as a gap.
324    error: bool,
325}
326
327/// Walks the worksheet's records from its BOF to its EOF, giving `each` every cell in order.
328fn walk<'a>(
329    bytes: &'a [u8],
330    mut each: impl FnMut(Cell<'a>) -> Result<(), LogError>,
331) -> Result<(), LogError> {
332    let mut at = 0usize;
333    let mut last: Option<(u16, u16)> = None;
334    let mut first = true;
335    loop {
336        let Some(header) = bytes.get(at..at + 4) else {
337            return Err(refused(format!(
338                "it ends at byte {} with no EOF record, the end of a sheet's stream",
339                bytes.len()
340            )));
341        };
342        let id = u16::from_le_bytes([header[0], header[1]]);
343        let length = usize::from(u16::from_le_bytes([header[2], header[3]]));
344        if length > MAX_RECORD_BYTES {
345            return Err(refused(format!(
346                "the record {id:04X}h at byte {at} is {length} bytes long, past the 8,224 a \
347                 record may hold"
348            )));
349        }
350        let Some(data) = bytes.get(at + 4..at + 4 + length) else {
351            return Err(refused(format!(
352                "the record {id:04X}h at byte {at} runs past the end of the file"
353            )));
354        };
355        at += 4 + length;
356        if first {
357            // Checked by `recognizes`: a worksheet's BOF.
358            first = false;
359            continue;
360        }
361        if BOF.contains(&id) {
362            return Err(refused(format!(
363                "a second BOF record, at byte {}, opens a stream inside the sheet's",
364                at - 4 - length
365            )));
366        }
367        if id == EOF {
368            if at != bytes.len() {
369                return Err(refused(format!(
370                    "{} bytes follow the sheet's EOF record, where another stream could be",
371                    bytes.len() - at
372                )));
373            }
374            return Ok(());
375        }
376        if let Some((_, name)) = NOT_READ.iter().find(|(not_read, _)| *not_read == id) {
377            return Err(refused(format!(
378                "the record at byte {}, {name} ({id:04X}h), holds a value of a kind the reader \
379                 doesn't read. It reads BIFF2's NUMBER, INTEGER, LABEL and BOOLERR",
380                at - 4 - length
381            )));
382        }
383        let Some(cell) = cell(id, data, at - 4 - length)? else {
384            continue;
385        };
386        if cell.column >= MAX_COLUMNS {
387            return Err(refused(format!(
388                "a cell in row {} is in column {}, past `IV`, the last of a BIFF2 to BIFF5 sheet",
389                u32::from(cell.row) + 1,
390                u32::from(cell.column) + 1
391            )));
392        }
393        if last.is_some_and(|last| (cell.row, cell.column) <= last) {
394            return Err(refused(format!(
395                "the cell in row {}, column {}, comes after a cell at or past it: cells must come \
396                 in order, row by row",
397                u32::from(cell.row) + 1,
398                u32::from(cell.column) + 1
399            )));
400        }
401        last = Some((cell.row, cell.column));
402        each(cell)?;
403    }
404}
405
406/// The cell a BIFF2 cell record holds; `None` for any other record.
407fn cell(id: u16, data: &[u8], at: usize) -> Result<Option<Cell<'_>>, LogError> {
408    let fixed = match id {
409        BLANK => 7,
410        INTEGER => 9,
411        NUMBER => 15,
412        LABEL => 8,
413        BOOLERR => 9,
414        _ => return Ok(None),
415    };
416    if data.len() < fixed {
417        return Err(refused(format!(
418            "the cell record {id:04X}h at byte {at} holds {} bytes, fewer than its {fixed} fields",
419            data.len()
420        )));
421    }
422    let row = u16::from_le_bytes([data[0], data[1]]);
423    let column = u16::from_le_bytes([data[2], data[3]]);
424    // The cell's attributes: its format's index is the low 6 bits of the second byte (§2.5.13).
425    let format = data[5] & 0x3F;
426    let mut error = false;
427    let value = match id {
428        INTEGER => Some(Value::Integer(u16::from_le_bytes([data[7], data[8]]))),
429        NUMBER => {
430            let mut double = [0u8; 8];
431            double.copy_from_slice(&data[7..15]);
432            let value = f64::from_le_bytes(double);
433            if !value.is_finite() {
434                return Err(refused(format!(
435                    "the number in row {}, column {}, isn't finite",
436                    u32::from(row) + 1,
437                    u32::from(column) + 1
438                )));
439            }
440            Some(Value::Number(value))
441        }
442        LABEL => {
443            let length = usize::from(data[7]);
444            let Some(bytes) = data.get(8..8 + length) else {
445                return Err(refused(format!(
446                    "the text in row {}, column {}, runs past its record",
447                    u32::from(row) + 1,
448                    u32::from(column) + 1
449                )));
450            };
451            if !bytes.is_ascii() {
452                return Err(refused(format!(
453                    "the text in row {}, column {}, {:?}, holds a byte beyond ASCII, in a code \
454                     page the reader doesn't read",
455                    u32::from(row) + 1,
456                    u32::from(column) + 1,
457                    shortened(&String::from_utf8_lossy(bytes))
458                )));
459            }
460            // Invariant: ASCII, checked above, is UTF-8.
461            let text = std::str::from_utf8(bytes).unwrap_or_default();
462            (!text.is_empty()).then_some(Value::Text(text))
463        }
464        BOOLERR => {
465            // The value, then whether it is an error's code rather than a truth value (§5.10).
466            if data[8] == 0 {
467                Some(Value::Bool(data[7] != 0))
468            } else {
469                error = true;
470                None
471            }
472        }
473        _ => None,
474    };
475    Ok(Some(Cell {
476        row,
477        column,
478        format,
479        value,
480        error,
481    }))
482}
483
484fn refused(message: String) -> LogError {
485    LogError::Workbook { message }
486}
487
488#[cfg(test)]
489mod tests {
490    use super::*;
491
492    fn record(id: u16, data: &[u8]) -> Vec<u8> {
493        let mut bytes = id.to_le_bytes().to_vec();
494        bytes.extend(u16::try_from(data.len()).unwrap().to_le_bytes());
495        bytes.extend(data);
496        bytes
497    }
498
499    /// A cell record's place and attributes, `format` its format's index.
500    fn place(row: u16, column: u16, format: u8) -> Vec<u8> {
501        let mut bytes = row.to_le_bytes().to_vec();
502        bytes.extend(column.to_le_bytes());
503        bytes.extend([0, format, 0]);
504        bytes
505    }
506
507    fn number(row: u16, column: u16, value: f64) -> Vec<u8> {
508        let mut data = place(row, column, 0);
509        data.extend(value.to_le_bytes());
510        record(NUMBER, &data)
511    }
512
513    fn label(row: u16, column: u16, text: &[u8]) -> Vec<u8> {
514        let mut data = place(row, column, 0);
515        data.push(u8::try_from(text.len()).unwrap());
516        data.extend(text);
517        record(LABEL, &data)
518    }
519
520    /// A worksheet stream of `cells`, BOF and EOF around them: the BOF as the sample's writer has
521    /// it, BIFF5's identifier with 6 bytes of data.
522    fn stream(cells: &[Vec<u8>]) -> Vec<u8> {
523        let mut bytes = record(0x0809, &[0, 0, 0x10, 0, 0xBB, 0x0D]);
524        for cell in cells {
525            bytes.extend(cell);
526        }
527        bytes.extend(record(EOF, &[]));
528        bytes
529    }
530
531    fn message(result: Result<Vec<Sheet>, LogError>) -> String {
532        match result {
533            Err(LogError::Workbook { message }) => message,
534            other => panic!("expected a workbook refusal, got {other:?}"),
535        }
536    }
537
538    #[test]
539    fn each_cell_record_is_written_as_stored() {
540        let mut integer = place(1, 1, 0);
541        integer.extend(7u16.to_le_bytes());
542        let mut truth = place(1, 2, 0);
543        truth.extend([1, 0]);
544        let mut error = place(1, 3, 0);
545        error.extend([0x07, 1]);
546        let bytes = stream(&[
547            label(0, 0, b"a, \"b\""),
548            label(0, 1, b"two\r\nlines"),
549            number(1, 0, 461.629_999_999_859),
550            record(INTEGER, &integer),
551            record(BOOLERR, &truth),
552            record(BOOLERR, &error),
553            record(BLANK, &place(1, 4, 0)),
554            number(2, 0, -0.005),
555        ]);
556        let sheet = sheets(&bytes).unwrap().remove(0);
557        assert_eq!(sheet.name, "");
558        // The row is as wide as the last column holding a value, the truth value's: the error and
559        // the blank cell widen nothing.
560        assert_eq!(
561            sheet.text,
562            "\"a, \"\"b\"\"\",two lines,\n461.629999999859,7,TRUE\n-0.005,,\n"
563        );
564        assert_eq!(
565            sheet.notes,
566            ["1 cells holding an error value, such as `#DIV/0!`, are gaps"]
567        );
568    }
569
570    #[test]
571    fn rows_with_no_value_are_left_out_and_an_empty_sheet_has_no_data() {
572        let bytes = stream(&[record(BLANK, &place(0, 0, 0)), number(3, 1, 2.5)]);
573        assert_eq!(sheets(&bytes).unwrap()[0].text, ",2.5\n");
574        let empty = stream(&[record(BLANK, &place(0, 0, 0)), label(1, 0, b"")]);
575        assert_eq!(sheets(&empty).unwrap()[0].text, "");
576        assert!(matches!(
577            read(&empty).unwrap()[0].log,
578            Err(LogError::NoData { .. })
579        ));
580    }
581
582    #[test]
583    fn a_number_under_a_format_is_kept_as_stored_with_a_note() {
584        let mut dated = place(0, 0, 14);
585        dated.extend(45_000.25f64.to_le_bytes());
586        let sheet = sheets(&stream(&[record(NUMBER, &dated)]))
587            .unwrap()
588            .remove(0);
589        assert_eq!(sheet.text, "45000.25\n");
590        assert!(sheet.notes[0].starts_with("1 numbers under a number format other than"));
591    }
592
593    #[test]
594    fn a_later_versions_cell_record_or_a_formula_is_refused_by_name() {
595        for (id, name) in [
596            (0x0203, "NUMBER (BIFF3"),
597            (0x027E, "RK"),
598            (0x0006, "FORMULA"),
599        ] {
600            let refusal = message(sheets(&stream(&[record(id, &[0; 14])])));
601            assert!(refusal.contains(name), "{refusal}");
602        }
603    }
604
605    #[test]
606    fn cells_out_of_order_or_twice_are_refused() {
607        for cells in [
608            [number(1, 0, 1.0), number(0, 5, 2.0)],
609            [number(1, 1, 1.0), number(1, 0, 2.0)],
610            [number(1, 1, 1.0), number(1, 1, 2.0)],
611        ] {
612            let refusal = message(sheets(&stream(&cells)));
613            assert!(refusal.contains("must come in order"), "{refusal}");
614        }
615    }
616
617    #[test]
618    fn the_streams_bounds_are_held() {
619        // Column 256 is past `IV`; 255 is its last.
620        assert!(sheets(&stream(&[number(0, 255, 1.0)])).is_ok());
621        let refusal = message(sheets(&stream(&[number(0, 256, 1.0)])));
622        assert!(refusal.contains("past `IV`"), "{refusal}");
623        // No EOF, a record cut short, bytes after the EOF, a second BOF.
624        let whole = stream(&[number(0, 0, 1.0)]);
625        let refusal = message(sheets(&whole[..whole.len() - 4]));
626        assert!(refusal.contains("no EOF"), "{refusal}");
627        let refusal = message(sheets(&whole[..whole.len() - 6]));
628        assert!(refusal.contains("runs past the end"), "{refusal}");
629        let mut after = whole.clone();
630        after.push(0);
631        let refusal = message(sheets(&after));
632        assert!(refusal.contains("1 bytes follow"), "{refusal}");
633        let refusal = message(sheets(&stream(&[record(0x0009, &[0, 0, 0x10, 0])])));
634        assert!(refusal.contains("a second BOF"), "{refusal}");
635        // A record of 8,225 bytes.
636        let refusal = message(sheets(&stream(&[record(0x00EF, &[0; 8_225])])));
637        assert!(refusal.contains("past the 8,224"), "{refusal}");
638        // A cell record shorter than its fields, and text running past its record.
639        let refusal = message(sheets(&stream(&[record(NUMBER, &place(0, 0, 0))])));
640        assert!(refusal.contains("fewer than its 15 fields"), "{refusal}");
641        let mut long = place(0, 0, 0);
642        long.extend([5, b'a']);
643        let refusal = message(sheets(&stream(&[record(LABEL, &long)])));
644        assert!(refusal.contains("runs past its record"), "{refusal}");
645    }
646
647    #[test]
648    fn a_value_that_cant_be_written_faithfully_is_refused() {
649        let refusal = message(sheets(&stream(&[number(0, 0, f64::NAN)])));
650        assert!(refusal.contains("isn't finite"), "{refusal}");
651        let refusal = message(sheets(&stream(&[label(0, 0, b"\xb0C")])));
652        assert!(refusal.contains("beyond ASCII"), "{refusal}");
653    }
654
655    #[test]
656    fn the_text_is_held_to_its_bound() {
657        let bytes = stream(&[number(0, 0, 12.5), number(1, 0, 3.0)]);
658        // "12.5\n3\n" is 7 bytes.
659        assert_eq!(sheets_within(&bytes, 7).unwrap()[0].text, "12.5\n3\n");
660        let refusal = message(sheets_within(&bytes, 6));
661        assert!(refusal.contains("would pass 6 bytes"), "{refusal}");
662    }
663
664    #[test]
665    fn only_a_worksheets_stream_is_read() {
666        assert!(matches!(
667            sheets(b"PK\x03\x04"),
668            Err(LogError::NotThisFormat { .. })
669        ));
670        let mut globals = record(0x0809, &[0, 6, 0x05, 0, 0xBB, 0x0D, 0xCC, 0x07]);
671        globals.extend(record(EOF, &[]));
672        assert!(recognizes(&globals));
673        let refusal = message(sheets(&globals));
674        assert!(refusal.contains("type 0005h"), "{refusal}");
675        // A compound file isn't a bare stream.
676        assert!(!recognizes(&[
677            0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1
678        ]));
679    }
680}