1use crate::error::LogError;
93use crate::import;
94use crate::workbook::{Sheet, SheetLog, escaped, shortened};
95
96pub const MAX_TEXT_BYTES: usize = crate::workbook::MAX_TEXT_BYTES;
98
99const MAX_RECORD_BYTES: usize = 8_224;
101
102const MAX_COLUMNS: u16 = 256;
104
105const BOF: [u16; 4] = [0x0009, 0x0209, 0x0409, 0x0809];
107
108const 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
118const 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
138pub fn recognizes(bytes: &[u8]) -> bool {
142 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
155pub 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
185pub fn sheets(bytes: &[u8]) -> Result<Vec<Sheet>, LogError> {
191 sheets_within(bytes, MAX_TEXT_BYTES)
192}
193
194pub 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 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 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#[derive(Default)]
291struct Counts {
292 formatted: usize,
293 errors: usize,
294}
295
296enum Value<'a> {
298 Number(f64),
299 Integer(u16),
300 Text(&'a str),
301 Bool(bool),
302}
303
304impl Value<'_> {
305 fn text(&self) -> String {
307 match self {
308 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
317struct Cell<'a> {
319 row: u16,
320 column: u16,
321 format: u8,
322 value: Option<Value<'a>>,
323 error: bool,
325}
326
327fn 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 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
406fn 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 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 let text = std::str::from_utf8(bytes).unwrap_or_default();
462 (!text.is_empty()).then_some(Value::Text(text))
463 }
464 BOOLERR => {
465 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 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 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 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 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 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 let refusal = message(sheets(&stream(&[record(0x00EF, &[0; 8_225])])));
637 assert!(refusal.contains("past the 8,224"), "{refusal}");
638 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 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 assert!(!recognizes(&[
677 0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1
678 ]));
679 }
680}