Skip to main content

sheetkit_core/
stream.rs

1//! Streaming worksheet writer.
2//!
3//! The [`StreamWriter`] writes row data directly to a temporary file instead of
4//! accumulating it in memory. This enables writing sheets with millions of rows
5//! without holding the entire worksheet in memory.
6//!
7//! Strings are written as inline strings (`<is><t>...</t></is>`) rather than
8//! shared string references, eliminating the need for SST index remapping and
9//! allowing each row to be serialized independently.
10//!
11//! Rows must be written in ascending order.
12//!
13//! # Example
14//!
15//! ```
16//! use sheetkit_core::stream::StreamWriter;
17//! use sheetkit_core::cell::CellValue;
18//!
19//! let mut sw = StreamWriter::new("Sheet1");
20//! sw.set_col_width(1, 20.0).unwrap();
21//! sw.write_row(1, &[CellValue::from("Name"), CellValue::from("Age")]).unwrap();
22//! sw.write_row(2, &[CellValue::from("Alice"), CellValue::from(30)]).unwrap();
23//! // StreamWriter data is applied to a workbook via apply_stream_writer().
24//! ```
25
26use std::fmt::Write as _;
27use std::io::{BufWriter, Write as _};
28
29use crate::cell::CellValue;
30use crate::error::{Error, Result};
31use crate::resource::{ResourceCategory, ResourceDimension, ResourceOperation, ResourceStage};
32use crate::save::{resource_limit, StreamLimits};
33use crate::utils::cell_ref::{cell_name_to_coordinates, coordinates_to_cell_name};
34use crate::utils::constants::{MAX_COLUMNS, MAX_ROWS, MAX_ROW_HEIGHT};
35
36use sheetkit_xml::worksheet::{Col, Cols, MergeCell, MergeCells, Pane, SheetView, SheetViews};
37
38/// Maximum outline level allowed by Excel.
39const MAX_OUTLINE_LEVEL: u8 = 7;
40
41/// Capacity of the buffered writer in front of the row temp file.
42const TEMP_FILE_BUFFER_BYTES: usize = 64 * 1024;
43
44/// Largest row XML buffer capacity retained between rows.
45const RETAINED_ROW_BUFFER_BYTES: usize = 1024 * 1024;
46
47/// Options for a streamed row.
48#[derive(Debug, Clone, Default)]
49pub struct StreamRowOptions {
50    /// Custom row height in points.
51    pub height: Option<f64>,
52    /// Row visibility (false = hidden).
53    pub visible: Option<bool>,
54    /// Outline level (0-7).
55    pub outline_level: Option<u8>,
56    /// Style ID for the row.
57    pub style_id: Option<u32>,
58}
59
60/// Internal column configuration beyond width.
61#[derive(Debug, Clone, Default)]
62struct StreamColOptions {
63    width: Option<f64>,
64    style_id: Option<u32>,
65    hidden: Option<bool>,
66    outline_level: Option<u8>,
67}
68
69/// Metadata for a streamed sheet stored in the workbook after applying.
70///
71/// Contains the temporary file with pre-serialized row XML and the
72/// configuration needed to compose the full worksheet XML on save.
73pub struct StreamedSheetData {
74    /// Temporary file containing `<row>...</row>` XML fragments.
75    pub(crate) temp_file: tempfile::NamedTempFile,
76    /// Number of bytes written to the temp file (used for diagnostics/testing).
77    #[allow(dead_code)]
78    pub(crate) data_len: u64,
79    /// Number of rows written to this streamed sheet.
80    pub(crate) row_count: u64,
81    /// Number of cell slots visited while writing this streamed sheet.
82    pub(crate) cell_count: u64,
83    /// Pre-built `<sheetViews>` XML fragment (if freeze panes are set).
84    pub(crate) sheet_views_xml: Option<String>,
85    /// Pre-built `<cols>` XML fragment (if column settings exist).
86    pub(crate) cols_xml: Option<String>,
87    /// Pre-built `<mergeCells>` XML fragment (if merge cells exist).
88    pub(crate) merge_cells_xml: Option<String>,
89}
90
91impl StreamedSheetData {
92    /// Create a deep copy of this streamed sheet data, duplicating the
93    /// temp file contents so the copy is fully independent.
94    pub(crate) fn try_clone(&self) -> Result<Self> {
95        let mut new_temp = tempfile::NamedTempFile::new()?;
96        let mut src = std::fs::File::open(self.temp_file.path())?;
97        std::io::copy(&mut src, new_temp.as_file_mut())?;
98        Ok(StreamedSheetData {
99            temp_file: new_temp,
100            data_len: self.data_len,
101            row_count: self.row_count,
102            cell_count: self.cell_count,
103            sheet_views_xml: self.sheet_views_xml.clone(),
104            cols_xml: self.cols_xml.clone(),
105            merge_cells_xml: self.merge_cells_xml.clone(),
106        })
107    }
108}
109
110#[derive(Debug, Clone, Copy, Default)]
111struct StreamFormulaUsage {
112    cells: u64,
113    input_bytes: u64,
114    output_bytes: u64,
115}
116
117/// A streaming worksheet writer that writes rows directly to a temp file.
118///
119/// Rows must be written in ascending order. Each row is serialized to XML
120/// and written to a temporary file immediately, keeping memory usage constant
121/// regardless of the number of rows.
122pub struct StreamWriter {
123    sheet_name: String,
124    writer: Option<BufWriter<tempfile::NamedTempFile>>,
125    bytes_written: u64,
126    row_count: u64,
127    cell_count: u64,
128    limits: StreamLimits,
129    formula_usage: StreamFormulaUsage,
130    last_row: u32,
131    started: bool,
132    finished: bool,
133    failed: bool,
134    config_count: u64,
135    config_bytes: u64,
136    write_failure_after_bytes: Option<u64>,
137    /// Reusable buffer holding one rendered row before it reaches the file.
138    row_buf: String,
139    col_widths: Vec<(u32, u32, f64)>,
140    col_options: Vec<(u32, StreamColOptions)>,
141    /// Canonical merge references with their normalized
142    /// (min_col, min_row, max_col, max_row) rectangles.
143    merge_cells: Vec<(String, (u32, u32, u32, u32))>,
144    /// Freeze pane: (x_split, y_split, top_left_cell).
145    freeze_pane: Option<(u32, u32, String)>,
146}
147
148// Compile-time guard: StreamWriter must stay Send without an unsafe impl.
149const _: () = {
150    fn assert_send<T: Send>() {}
151    let _ = assert_send::<StreamWriter>;
152};
153
154impl std::fmt::Debug for StreamWriter {
155    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
156        f.debug_struct("StreamWriter")
157            .field("sheet_name", &self.sheet_name)
158            .field("bytes_written", &self.bytes_written)
159            .field("last_row", &self.last_row)
160            .field("started", &self.started)
161            .field("finished", &self.finished)
162            .finish()
163    }
164}
165
166impl StreamWriter {
167    /// Create a new StreamWriter for the given sheet name.
168    pub fn new(sheet_name: &str) -> Self {
169        Self {
170            sheet_name: sheet_name.to_string(),
171            writer: None,
172            bytes_written: 0,
173            row_count: 0,
174            cell_count: 0,
175            limits: StreamLimits::default(),
176            formula_usage: StreamFormulaUsage::default(),
177            last_row: 0,
178            started: false,
179            finished: false,
180            failed: false,
181            config_count: 0,
182            config_bytes: 0,
183            write_failure_after_bytes: None,
184            row_buf: String::new(),
185            col_widths: Vec::new(),
186            col_options: Vec::new(),
187            merge_cells: Vec::new(),
188            freeze_pane: None,
189        }
190    }
191
192    /// Create a new StreamWriter and initialize its temporary file eagerly.
193    pub fn try_new(sheet_name: &str) -> Result<Self> {
194        let mut writer = Self::new(sheet_name);
195        writer.ensure_temp_file()?;
196        Ok(writer)
197    }
198
199    /// Create a StreamWriter with explicit finite operation limits.
200    pub fn new_with_limits(sheet_name: &str, limits: StreamLimits) -> Result<Self> {
201        let limits = limits.validate()?;
202        Ok(Self {
203            sheet_name: sheet_name.to_string(),
204            writer: None,
205            bytes_written: 0,
206            row_count: 0,
207            cell_count: 0,
208            limits,
209            formula_usage: StreamFormulaUsage::default(),
210            last_row: 0,
211            started: false,
212            finished: false,
213            failed: false,
214            config_count: 0,
215            config_bytes: 0,
216            write_failure_after_bytes: None,
217            row_buf: String::new(),
218            col_widths: Vec::new(),
219            col_options: Vec::new(),
220            merge_cells: Vec::new(),
221            freeze_pane: None,
222        })
223    }
224
225    /// Create a limited StreamWriter and initialize its temporary file eagerly.
226    pub fn try_new_with_limits(sheet_name: &str, limits: StreamLimits) -> Result<Self> {
227        let mut writer = Self::new_with_limits(sheet_name, limits)?;
228        writer.ensure_temp_file()?;
229        Ok(writer)
230    }
231
232    fn ensure_temp_file(&mut self) -> Result<&mut BufWriter<tempfile::NamedTempFile>> {
233        if self.writer.is_none() {
234            self.writer = Some(BufWriter::with_capacity(
235                TEMP_FILE_BUFFER_BYTES,
236                tempfile::NamedTempFile::new()?,
237            ));
238        }
239        self.writer
240            .as_mut()
241            .ok_or_else(|| Error::Internal("stream writer initialization failed".to_string()))
242    }
243
244    /// Get the sheet name.
245    pub fn sheet_name(&self) -> &str {
246        &self.sheet_name
247    }
248
249    /// Set column width for a single column (1-based).
250    /// Must be called before any write_row() calls.
251    pub fn set_col_width(&mut self, col: u32, width: f64) -> Result<()> {
252        self.set_col_width_range(col, col, width)
253    }
254
255    /// Set column width for a range (min_col..=max_col), both 1-based.
256    /// Must be called before any write_row() calls.
257    pub fn set_col_width_range(&mut self, min_col: u32, max_col: u32, width: f64) -> Result<()> {
258        if self.finished {
259            return Err(Error::StreamAlreadyFinished);
260        }
261        if self.started {
262            return Err(Error::StreamColumnsAfterRows);
263        }
264        if min_col == 0 || max_col == 0 || min_col > MAX_COLUMNS || max_col > MAX_COLUMNS {
265            return Err(Error::InvalidColumnNumber(if min_col == 0 {
266                min_col
267            } else {
268                max_col
269            }));
270        }
271        if let Some(existing) = self
272            .col_widths
273            .iter_mut()
274            .find(|(min, max, _)| *min == min_col && *max == max_col)
275        {
276            existing.2 = width;
277            return Ok(());
278        }
279        self.charge_config(1, std::mem::size_of::<(u32, u32, f64)>() as u64)?;
280        self.col_widths.push((min_col, max_col, width));
281        Ok(())
282    }
283
284    /// Set column style for a single column (1-based).
285    /// Must be called before any write_row() calls.
286    pub fn set_col_style(&mut self, col: u32, style_id: u32) -> Result<()> {
287        self.ensure_col_configurable(col)?;
288        self.get_or_create_col_options(col)?.style_id = Some(style_id);
289        Ok(())
290    }
291
292    /// Set column visibility for a single column (1-based).
293    /// Must be called before any write_row() calls.
294    pub fn set_col_visible(&mut self, col: u32, visible: bool) -> Result<()> {
295        self.ensure_col_configurable(col)?;
296        self.get_or_create_col_options(col)?.hidden = Some(!visible);
297        Ok(())
298    }
299
300    /// Set column outline level for a single column (1-based).
301    /// Must be called before any write_row() calls. Level must be 0-7.
302    pub fn set_col_outline_level(&mut self, col: u32, level: u8) -> Result<()> {
303        self.ensure_col_configurable(col)?;
304        if level > MAX_OUTLINE_LEVEL {
305            return Err(Error::OutlineLevelExceeded {
306                level,
307                max: MAX_OUTLINE_LEVEL,
308            });
309        }
310        self.get_or_create_col_options(col)?.outline_level = Some(level);
311        Ok(())
312    }
313
314    /// Set freeze panes for the streamed sheet.
315    /// Must be called before any write_row() calls.
316    /// `top_left_cell` is the cell below and to the right of the frozen area,
317    /// e.g., "A2" freezes row 1, "B1" freezes column A, "C3" freezes rows 1-2
318    /// and columns A-B.
319    pub fn set_freeze_panes(&mut self, top_left_cell: &str) -> Result<()> {
320        if self.finished {
321            return Err(Error::StreamAlreadyFinished);
322        }
323        if self.started {
324            return Err(Error::StreamColumnsAfterRows);
325        }
326        let (col, row) = cell_name_to_coordinates(top_left_cell)?;
327        if col == 1 && row == 1 {
328            return Err(Error::InvalidCellReference(
329                "freeze pane at A1 has no effect".to_string(),
330            ));
331        }
332        let additional_count = u64::from(self.freeze_pane.is_none());
333        let previous_bytes = self
334            .freeze_pane
335            .as_ref()
336            .map(|(_, _, value)| value.len() as u64)
337            .unwrap_or_default();
338        let next_bytes = top_left_cell.len() as u64;
339        self.replace_config(additional_count, previous_bytes, next_bytes)?;
340        self.freeze_pane = Some((col - 1, row - 1, top_left_cell.to_string()));
341        Ok(())
342    }
343
344    /// Write a row of values with row-level options.
345    pub fn write_row_with_options(
346        &mut self,
347        row: u32,
348        values: &[CellValue],
349        options: &StreamRowOptions,
350    ) -> Result<()> {
351        self.write_row_impl(row, values, None, Some(options))
352    }
353
354    /// Write a row of values. Rows must be written in ascending order.
355    /// Row numbers are 1-based.
356    pub fn write_row(&mut self, row: u32, values: &[CellValue]) -> Result<()> {
357        self.write_row_impl(row, values, None, None)
358    }
359
360    /// Write multiple rows of values starting at the given row number.
361    /// Each element in the slice becomes a row. Rows are numbered consecutively
362    /// from `start_row`. All rows must be in ascending order relative to any
363    /// previously written row.
364    pub fn write_rows(&mut self, start_row: u32, rows: &[Vec<CellValue>]) -> Result<()> {
365        for (i, values) in rows.iter().enumerate() {
366            let offset = u32::try_from(i).map_err(|_| Error::InvalidRowNumber(u32::MAX))?;
367            let row_num = start_row
368                .checked_add(offset)
369                .ok_or(Error::InvalidRowNumber(u32::MAX))?;
370            self.validate_row_structure(row_num, values, None)?;
371        }
372        let next_formula_usage =
373            self.preflight_formula_values(rows.iter().flat_map(|row| row.iter()))?;
374
375        let mut next_row_count = self.row_count;
376        let mut next_cell_count = self.cell_count;
377        let mut next_bytes = self.bytes_written;
378        for (i, values) in rows.iter().enumerate() {
379            let offset = u32::try_from(i).map_err(|_| Error::InvalidRowNumber(u32::MAX))?;
380            let row_num = start_row
381                .checked_add(offset)
382                .ok_or(Error::InvalidRowNumber(u32::MAX))?;
383            self.preflight_row(
384                row_num,
385                values,
386                None,
387                None,
388                &mut next_row_count,
389                &mut next_cell_count,
390                &mut next_bytes,
391            )?;
392        }
393        self.formula_usage = next_formula_usage;
394        let mut row_xml = self.take_row_buffer();
395        let mut result = Ok(());
396        for (i, values) in rows.iter().enumerate() {
397            let offset = u32::try_from(i).map_err(|_| Error::InvalidRowNumber(u32::MAX))?;
398            let row_num = start_row
399                .checked_add(offset)
400                .ok_or(Error::InvalidRowNumber(u32::MAX))?;
401            // Every row was admitted above, so rendering needs no limit here.
402            row_xml.clear();
403            render_row_xml(&mut row_xml, row_num, values, None, None, u64::MAX)?;
404            result = self.commit_row_xml(row_num, values.len(), &row_xml);
405            if result.is_err() {
406                break;
407            }
408        }
409        self.restore_row_buffer(row_xml);
410        result
411    }
412
413    /// Write a row with a specific style ID applied to all cells.
414    pub fn write_row_with_style(
415        &mut self,
416        row: u32,
417        values: &[CellValue],
418        style_id: u32,
419    ) -> Result<()> {
420        self.write_row_impl(row, values, Some(style_id), None)
421    }
422
423    /// Add a merge cell reference (e.g., "A1:B2").
424    ///
425    /// Must be called before finish(). The reference must be a valid range
426    /// in the form "A1:B2". It is stored in canonical form: absolute markers
427    /// are dropped, letters are uppercased, and inverted endpoints are
428    /// normalized to top-left:bottom-right. Re-adding an equivalent range is
429    /// a no-op; a range overlapping a different existing merge returns
430    /// [`Error::MergeCellOverlap`].
431    pub fn add_merge_cell(&mut self, reference: &str) -> Result<()> {
432        if self.finished {
433            return Err(Error::StreamAlreadyFinished);
434        }
435        let parts: Vec<&str> = reference.split(':').collect();
436        if parts.len() != 2 {
437            return Err(Error::InvalidMergeCellReference(reference.to_string()));
438        }
439        let (c1, r1) = cell_name_to_coordinates(parts[0])
440            .map_err(|_| Error::InvalidMergeCellReference(reference.to_string()))?;
441        let (c2, r2) = cell_name_to_coordinates(parts[1])
442            .map_err(|_| Error::InvalidMergeCellReference(reference.to_string()))?;
443        let range = (c1.min(c2), r1.min(r2), c1.max(c2), r1.max(r2));
444        let canonical = format!(
445            "{}:{}",
446            coordinates_to_cell_name(range.0, range.1)?,
447            coordinates_to_cell_name(range.2, range.3)?
448        );
449        for (existing, coords) in &self.merge_cells {
450            if *coords == range {
451                return Ok(());
452            }
453            if range.0 <= coords.2
454                && range.2 >= coords.0
455                && range.1 <= coords.3
456                && range.3 >= coords.1
457            {
458                return Err(Error::MergeCellOverlap {
459                    new: canonical,
460                    existing: existing.clone(),
461                });
462            }
463        }
464        self.charge_config(1, u64::try_from(canonical.len()).unwrap_or(u64::MAX))?;
465        self.merge_cells.push((canonical, range));
466        Ok(())
467    }
468
469    /// Consume the writer and return a [`StreamedSheetData`] containing the
470    /// temp file and pre-built XML fragments for the worksheet header/footer.
471    pub fn into_streamed_data(mut self) -> Result<(String, StreamedSheetData)> {
472        if self.finished {
473            return Err(Error::StreamAlreadyFinished);
474        }
475        if self.failed {
476            return Err(Error::Internal(
477                "stream writer is unusable after an output failure".to_string(),
478            ));
479        }
480        self.finished = true;
481
482        // Build XML fragments before consuming the writer.
483        let sheet_views_xml = self.build_sheet_views_xml();
484        let cols_xml = self.build_cols_xml();
485        let merge_cells_xml = self.build_merge_cells_xml();
486        let config_xml_bytes = sheet_views_xml
487            .as_ref()
488            .map(|value| value.len() as u64)
489            .unwrap_or_default()
490            .saturating_add(
491                cols_xml
492                    .as_ref()
493                    .map(|value| value.len() as u64)
494                    .unwrap_or_default(),
495            )
496            .saturating_add(
497                merge_cells_xml
498                    .as_ref()
499                    .map(|value| value.len() as u64)
500                    .unwrap_or_default(),
501            )
502            .saturating_add(512);
503        checked_stream_add(
504            self.bytes_written,
505            config_xml_bytes,
506            self.limits.output_bytes,
507            ResourceDimension::OutputBytes,
508        )?;
509        let bytes_written = self.bytes_written;
510        let sheet_name = self.sheet_name;
511
512        // Flush the writer and recover the temp file.
513        let mut writer = self
514            .writer
515            .map_or_else(|| tempfile::NamedTempFile::new().map(BufWriter::new), Ok)?;
516        writer.flush()?;
517        let temp_file = writer.into_inner().map_err(|e| Error::Io(e.into_error()))?;
518
519        let data = StreamedSheetData {
520            temp_file,
521            data_len: bytes_written,
522            row_count: self.row_count,
523            cell_count: self.cell_count,
524            sheet_views_xml,
525            cols_xml,
526            merge_cells_xml,
527        };
528        Ok((sheet_name, data))
529    }
530
531    /// Validate that column configuration is allowed (not finished, not started,
532    /// valid column number).
533    fn ensure_col_configurable(&self, col: u32) -> Result<()> {
534        if self.finished {
535            return Err(Error::StreamAlreadyFinished);
536        }
537        if self.started {
538            return Err(Error::StreamColumnsAfterRows);
539        }
540        if col == 0 || col > MAX_COLUMNS {
541            return Err(Error::InvalidColumnNumber(col));
542        }
543        Ok(())
544    }
545
546    /// Get or create a StreamColOptions entry for the given column.
547    fn get_or_create_col_options(&mut self, col: u32) -> Result<&mut StreamColOptions> {
548        if let Some(pos) = self.col_options.iter().position(|(c, _)| *c == col) {
549            Ok(&mut self.col_options[pos].1)
550        } else {
551            self.charge_config(
552                1,
553                u64::try_from(std::mem::size_of::<(u32, StreamColOptions)>()).unwrap_or(u64::MAX),
554            )?;
555            self.col_options.push((col, StreamColOptions::default()));
556            let last = self.col_options.len() - 1;
557            Ok(&mut self.col_options[last].1)
558        }
559    }
560
561    fn charge_config(&mut self, count: u64, bytes: u64) -> Result<()> {
562        let next_count = checked_stream_config_add(
563            self.config_count,
564            count,
565            self.limits.config_count,
566            ResourceDimension::CollectionCount,
567        )?;
568        let next_bytes = checked_stream_config_add(
569            self.config_bytes,
570            bytes,
571            self.limits.config_bytes,
572            ResourceDimension::RetainedBytes,
573        )?;
574        self.config_count = next_count;
575        self.config_bytes = next_bytes;
576        Ok(())
577    }
578
579    fn replace_config(
580        &mut self,
581        additional_count: u64,
582        previous_bytes: u64,
583        next_bytes: u64,
584    ) -> Result<()> {
585        let next_count = checked_stream_config_add(
586            self.config_count,
587            additional_count,
588            self.limits.config_count,
589            ResourceDimension::CollectionCount,
590        )?;
591        let retained = self
592            .config_bytes
593            .saturating_sub(previous_bytes)
594            .saturating_add(next_bytes);
595        if retained > self.limits.config_bytes {
596            return Err(resource_limit(
597                ResourceOperation::StreamWrite,
598                ResourceCategory::Streaming,
599                ResourceDimension::RetainedBytes,
600                self.limits.config_bytes,
601                retained,
602                ResourceStage::Validate,
603            ));
604        }
605        self.config_count = next_count;
606        self.config_bytes = retained;
607        Ok(())
608    }
609
610    /// Build the `<sheetViews>` XML fragment for freeze panes.
611    fn build_sheet_views_xml(&self) -> Option<String> {
612        let (x_split, y_split, top_left_cell) = self.freeze_pane.as_ref()?;
613        let active_pane = match (*x_split > 0, *y_split > 0) {
614            (true, true) => "bottomRight",
615            (true, false) => "topRight",
616            (false, true) => "bottomLeft",
617            (false, false) => unreachable!(),
618        };
619
620        let sheet_views = SheetViews {
621            sheet_views: vec![SheetView {
622                tab_selected: Some(true),
623                show_grid_lines: None,
624                show_formulas: None,
625                show_row_col_headers: None,
626                zoom_scale: None,
627                view: None,
628                top_left_cell: None,
629                workbook_view_id: 0,
630                pane: Some(Pane {
631                    x_split: if *x_split > 0 { Some(*x_split) } else { None },
632                    y_split: if *y_split > 0 { Some(*y_split) } else { None },
633                    top_left_cell: Some(top_left_cell.clone()),
634                    active_pane: Some(active_pane.to_string()),
635                    state: Some("frozen".to_string()),
636                }),
637                selection: vec![],
638            }],
639        };
640
641        quick_xml::se::to_string_with_root("sheetViews", &sheet_views).ok()
642    }
643
644    /// Build the `<cols>` XML fragment.
645    fn build_cols_xml(&self) -> Option<String> {
646        let has_widths = !self.col_widths.is_empty();
647        let has_options = !self.col_options.is_empty();
648        if !has_widths && !has_options {
649            return None;
650        }
651
652        let mut col_defs = Vec::new();
653        for &(min, max, width) in &self.col_widths {
654            col_defs.push(Col {
655                min,
656                max,
657                width: Some(width),
658                style: None,
659                hidden: None,
660                custom_width: Some(true),
661                outline_level: None,
662            });
663        }
664        for &(col_num, ref opts) in &self.col_options {
665            col_defs.push(Col {
666                min: col_num,
667                max: col_num,
668                width: opts.width,
669                style: opts.style_id,
670                hidden: opts.hidden,
671                custom_width: if opts.width.is_some() {
672                    Some(true)
673                } else {
674                    None
675                },
676                outline_level: opts.outline_level.filter(|&l| l > 0),
677            });
678        }
679
680        let cols = Cols { cols: col_defs };
681        quick_xml::se::to_string_with_root("cols", &cols).ok()
682    }
683
684    /// Build the `<mergeCells>` XML fragment.
685    fn build_merge_cells_xml(&self) -> Option<String> {
686        if self.merge_cells.is_empty() {
687            return None;
688        }
689
690        let mc = MergeCells {
691            count: Some(self.merge_cells.len() as u32),
692            merge_cells: self
693                .merge_cells
694                .iter()
695                .map(|(r, _)| MergeCell {
696                    reference: r.clone(),
697                })
698                .collect(),
699            cached_coords: Vec::new(),
700        };
701        quick_xml::se::to_string_with_root("mergeCells", &mc).ok()
702    }
703
704    /// Internal unified implementation for writing a row.
705    /// Renders the row XML once into a reusable buffer, admits it against
706    /// every stream limit, then writes it to the temp file.
707    fn write_row_impl(
708        &mut self,
709        row: u32,
710        values: &[CellValue],
711        cell_style_id: Option<u32>,
712        options: Option<&StreamRowOptions>,
713    ) -> Result<()> {
714        self.validate_row_structure(row, values, options)?;
715        let next_formula_usage = self.preflight_formula_values(values.iter())?;
716        validate_stream_values(values)?;
717
718        let mut row_xml = self.take_row_buffer();
719        let result = render_row_xml(
720            &mut row_xml,
721            row,
722            values,
723            cell_style_id,
724            options,
725            self.limits.row_xml_bytes,
726        )
727        .and_then(|row_xml_bytes| {
728            let mut next_row_count = self.row_count;
729            let mut next_cell_count = self.cell_count;
730            let mut next_bytes = self.bytes_written;
731            self.charge_row_totals(
732                values,
733                row_xml_bytes,
734                &mut next_row_count,
735                &mut next_cell_count,
736                &mut next_bytes,
737            )
738        })
739        .and_then(|()| {
740            self.formula_usage = next_formula_usage;
741            self.commit_row_xml(row, values.len(), &row_xml)
742        });
743        self.restore_row_buffer(row_xml);
744        result
745    }
746
747    fn take_row_buffer(&mut self) -> String {
748        let mut buffer = std::mem::take(&mut self.row_buf);
749        buffer.clear();
750        buffer
751    }
752
753    fn restore_row_buffer(&mut self, buffer: String) {
754        if buffer.capacity() <= RETAINED_ROW_BUFFER_BYTES {
755            self.row_buf = buffer;
756        }
757    }
758
759    fn preflight_formula_values<'a>(
760        &self,
761        values: impl IntoIterator<Item = &'a CellValue>,
762    ) -> Result<StreamFormulaUsage> {
763        let budget = crate::formula::FormulaBudget::secure_mutation();
764        let mut formula_cells = 0u64;
765        let mut formula_input_bytes = 0u64;
766        let mut formula_output_bytes = 0u64;
767        for value in values {
768            collect_formula_usage(
769                value,
770                &budget,
771                &mut formula_cells,
772                &mut formula_input_bytes,
773                &mut formula_output_bytes,
774            )?;
775        }
776        let next = StreamFormulaUsage {
777            cells: self.formula_usage.cells.saturating_add(formula_cells),
778            input_bytes: self
779                .formula_usage
780                .input_bytes
781                .saturating_add(formula_input_bytes),
782            output_bytes: self
783                .formula_usage
784                .output_bytes
785                .saturating_add(formula_output_bytes),
786        };
787        budget.charge_mutation_cells(next.cells)?;
788        budget.charge_mutation_input_total(next.input_bytes)?;
789        budget.charge_mutation_output(next.output_bytes)?;
790        Ok(next)
791    }
792
793    #[allow(clippy::too_many_arguments)]
794    fn preflight_row(
795        &self,
796        row: u32,
797        values: &[CellValue],
798        cell_style_id: Option<u32>,
799        options: Option<&StreamRowOptions>,
800        row_count: &mut u64,
801        cell_count: &mut u64,
802        output_bytes: &mut u64,
803    ) -> Result<()> {
804        self.validate_row_structure(row, values, options)?;
805        validate_stream_values(values)?;
806        let row_xml_bytes = measure_row_xml(
807            row,
808            values,
809            cell_style_id,
810            options,
811            self.limits.row_xml_bytes,
812        )?;
813        self.charge_row_totals(values, row_xml_bytes, row_count, cell_count, output_bytes)
814    }
815
816    /// Checks the cumulative row, cell, and byte limits for one admitted row.
817    fn charge_row_totals(
818        &self,
819        values: &[CellValue],
820        row_xml_bytes: u64,
821        row_count: &mut u64,
822        cell_count: &mut u64,
823        output_bytes: &mut u64,
824    ) -> Result<()> {
825        *row_count = checked_stream_add(
826            *row_count,
827            1,
828            self.limits.row_count,
829            ResourceDimension::RowCount,
830        )?;
831        *cell_count = checked_stream_add(
832            *cell_count,
833            u64::try_from(values.len()).unwrap_or(u64::MAX),
834            self.limits.cell_count,
835            ResourceDimension::CellCount,
836        )?;
837        *output_bytes = checked_stream_add(
838            *output_bytes,
839            row_xml_bytes,
840            self.limits.output_bytes,
841            ResourceDimension::OutputBytes,
842        )?;
843        Ok(())
844    }
845
846    fn validate_row_structure(
847        &self,
848        row: u32,
849        values: &[CellValue],
850        options: Option<&StreamRowOptions>,
851    ) -> Result<()> {
852        if self.finished {
853            return Err(Error::StreamAlreadyFinished);
854        }
855        if self.failed {
856            return Err(Error::Internal(
857                "stream writer is unusable after an output failure".to_string(),
858            ));
859        }
860
861        // Validate row number.
862        if row == 0 || row > MAX_ROWS {
863            return Err(Error::InvalidRowNumber(row));
864        }
865
866        // Enforce ascending row order.
867        if row <= self.last_row {
868            return Err(Error::StreamRowAlreadyWritten { row });
869        }
870
871        // Validate column count.
872        if values.len() > MAX_COLUMNS as usize {
873            return Err(Error::InvalidColumnNumber(values.len() as u32));
874        }
875
876        // Validate row options if provided.
877        if let Some(opts) = options {
878            if let Some(height) = opts.height {
879                if height > MAX_ROW_HEIGHT {
880                    return Err(Error::RowHeightExceeded {
881                        height,
882                        max: MAX_ROW_HEIGHT,
883                    });
884                }
885            }
886            if let Some(level) = opts.outline_level {
887                if level > MAX_OUTLINE_LEVEL {
888                    return Err(Error::OutlineLevelExceeded {
889                        level,
890                        max: MAX_OUTLINE_LEVEL,
891                    });
892                }
893            }
894        }
895
896        Ok(())
897    }
898
899    /// Writes one admitted row's XML to the temp file and records it.
900    fn commit_row_xml(&mut self, row: u32, cell_slots: usize, row_xml: &str) -> Result<()> {
901        let failure_after = self.write_failure_after_bytes;
902        let bytes = row_xml.as_bytes();
903        let writer = self.ensure_temp_file()?;
904        let written = match failure_after {
905            Some(failure_after)
906                if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > failure_after =>
907            {
908                let prefix = usize::try_from(failure_after)
909                    .unwrap_or(usize::MAX)
910                    .min(bytes.len());
911                if prefix > 0 {
912                    let _ = writer.write_all(&bytes[..prefix]);
913                }
914                Err(std::io::Error::other("injected stream output failure"))
915            }
916            _ => writer.write_all(bytes),
917        };
918        if let Err(error) = written {
919            self.failed = true;
920            return Err(Error::Io(error));
921        }
922        let row_bytes = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
923
924        self.row_count = self
925            .row_count
926            .checked_add(1)
927            .ok_or_else(|| Error::Internal("stream row count overflow".to_string()))?;
928        self.cell_count = self
929            .cell_count
930            .checked_add(u64::try_from(cell_slots).unwrap_or(u64::MAX))
931            .ok_or_else(|| Error::Internal("stream cell count overflow".to_string()))?;
932        self.bytes_written = self
933            .bytes_written
934            .checked_add(row_bytes)
935            .ok_or_else(|| Error::Internal("stream byte count overflow".to_string()))?;
936        self.started = true;
937        self.last_row = row;
938        Ok(())
939    }
940}
941
942/// Build the XML for the worksheet opening, including the XML declaration,
943/// worksheet namespace, sheetViews, cols, and the opening `<sheetData>` tag.
944pub(crate) fn build_worksheet_header(streamed: &StreamedSheetData) -> String {
945    let mut xml = String::with_capacity(512);
946    xml.push_str(r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>"#);
947    xml.push('\n');
948    xml.push_str(
949        r#"<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">"#,
950    );
951
952    if let Some(ref views) = streamed.sheet_views_xml {
953        xml.push_str(views);
954    }
955    if let Some(ref cols) = streamed.cols_xml {
956        xml.push_str(cols);
957    }
958
959    xml.push_str("<sheetData>");
960    xml
961}
962
963/// Build the XML for the worksheet closing: `</sheetData>`, mergeCells, and
964/// `</worksheet>`.
965pub(crate) fn build_worksheet_footer(streamed: &StreamedSheetData) -> String {
966    let mut xml = String::with_capacity(256);
967    xml.push_str("</sheetData>");
968
969    if let Some(ref mc) = streamed.merge_cells_xml {
970        xml.push_str(mc);
971    }
972
973    xml.push_str("</worksheet>");
974    xml
975}
976
977/// Write streamed sheet data to a ZIP writer. Composes the full worksheet
978/// XML by writing the header, streaming rows from the temp file, and
979/// appending the footer.
980pub(crate) fn write_streamed_sheet<W: std::io::Write + std::io::Seek>(
981    zip: &mut zip::ZipWriter<W>,
982    entry_name: &str,
983    streamed: &StreamedSheetData,
984    options: zip::write::SimpleFileOptions,
985    xml_limit: u64,
986) -> Result<()> {
987    let header = build_worksheet_header(streamed);
988    let footer = build_worksheet_footer(streamed);
989    let observed = u64::try_from(header.len())
990        .unwrap_or(u64::MAX)
991        .saturating_add(streamed.data_len)
992        .saturating_add(u64::try_from(footer.len()).unwrap_or(u64::MAX));
993    if observed > xml_limit {
994        return Err(resource_limit(
995            ResourceOperation::WorkbookSave,
996            ResourceCategory::Output,
997            ResourceDimension::XmlBytes,
998            xml_limit,
999            observed,
1000            ResourceStage::Serialize,
1001        ));
1002    }
1003    zip.start_file(entry_name, options)
1004        .map_err(|e| Error::Zip(e.to_string()))?;
1005
1006    // Write the header (XML declaration, <worksheet>, <sheetViews>, <cols>, <sheetData>).
1007    zip.write_all(header.as_bytes())?;
1008
1009    // Open the temp file by path for reading (starts at position 0).
1010    let file = std::fs::File::open(streamed.temp_file.path())?;
1011    let mut reader = std::io::BufReader::new(file);
1012    std::io::copy(&mut reader, zip)?;
1013
1014    // Write the footer (</sheetData>, <mergeCells>, </worksheet>).
1015    zip.write_all(footer.as_bytes())?;
1016
1017    Ok(())
1018}
1019
1020/// Destination for rendered row XML that enforces the row byte limit.
1021///
1022/// `push_str` charges its argument as one unit and `push_chars` charges each
1023/// character separately, so the size reported on rejection does not depend on
1024/// how plain text is grouped.
1025trait RowXmlSink {
1026    fn push_str(&mut self, value: &str);
1027    fn push_chars(&mut self, value: &str);
1028
1029    fn push(&mut self, value: char) {
1030        let mut encoded = [0u8; 4];
1031        self.push_str(value.encode_utf8(&mut encoded));
1032    }
1033}
1034
1035/// Running size of one row's XML measured against the row limit.
1036struct RowXmlCounter {
1037    written: u64,
1038    limit: u64,
1039    exceeded: bool,
1040}
1041
1042impl RowXmlCounter {
1043    fn new(limit: u64) -> Self {
1044        Self {
1045            written: 0,
1046            limit,
1047            exceeded: false,
1048        }
1049    }
1050
1051    /// Charges `amount` bytes as one unit and returns whether they fit.
1052    fn charge(&mut self, amount: usize) -> bool {
1053        if self.exceeded {
1054            return false;
1055        }
1056        let observed = self
1057            .written
1058            .saturating_add(u64::try_from(amount).unwrap_or(u64::MAX));
1059        self.written = observed;
1060        if observed > self.limit {
1061            self.exceeded = true;
1062            return false;
1063        }
1064        true
1065    }
1066
1067    /// Charges `value` one character at a time and returns whether it fits.
1068    fn charge_chars(&mut self, value: &str) -> bool {
1069        if self.exceeded {
1070            return false;
1071        }
1072        let remaining = self.limit.saturating_sub(self.written);
1073        let length = u64::try_from(value.len()).unwrap_or(u64::MAX);
1074        if length <= remaining {
1075            self.written = self.written.saturating_add(length);
1076            return true;
1077        }
1078        // Record the size at the first character that crosses the limit.
1079        let crossing = value
1080            .char_indices()
1081            .map(|(start, ch)| u64::try_from(start + ch.len_utf8()).unwrap_or(u64::MAX))
1082            .find(|end| *end > remaining)
1083            .unwrap_or(length);
1084        self.written = self.written.saturating_add(crossing);
1085        self.exceeded = true;
1086        false
1087    }
1088
1089    /// Returns the admitted row size, or the row XML limit error.
1090    fn finish(&self) -> Result<u64> {
1091        if self.exceeded {
1092            return Err(resource_limit(
1093                ResourceOperation::StreamWrite,
1094                ResourceCategory::Streaming,
1095                ResourceDimension::XmlBytes,
1096                self.limit,
1097                self.written,
1098                ResourceStage::Serialize,
1099            ));
1100        }
1101        Ok(self.written)
1102    }
1103}
1104
1105impl RowXmlSink for RowXmlCounter {
1106    fn push_str(&mut self, value: &str) {
1107        self.charge(value.len());
1108    }
1109
1110    fn push_chars(&mut self, value: &str) {
1111        self.charge_chars(value);
1112    }
1113}
1114
1115/// Row XML sink that keeps the admitted bytes in memory.
1116struct RowXmlBuffer<'a> {
1117    counter: RowXmlCounter,
1118    out: &'a mut String,
1119}
1120
1121impl RowXmlSink for RowXmlBuffer<'_> {
1122    fn push_str(&mut self, value: &str) {
1123        if self.counter.charge(value.len()) {
1124            self.out.push_str(value);
1125        }
1126    }
1127
1128    fn push_chars(&mut self, value: &str) {
1129        if self.counter.charge_chars(value) {
1130            self.out.push_str(value);
1131        }
1132    }
1133
1134    fn push(&mut self, value: char) {
1135        if self.counter.charge(value.len_utf8()) {
1136            self.out.push(value);
1137        }
1138    }
1139}
1140
1141fn measure_row_xml(
1142    row: u32,
1143    values: &[CellValue],
1144    cell_style_id: Option<u32>,
1145    options: Option<&StreamRowOptions>,
1146    limit: u64,
1147) -> Result<u64> {
1148    let mut counter = RowXmlCounter::new(limit);
1149    write_row_xml(&mut counter, row, values, cell_style_id, options);
1150    counter.finish()
1151}
1152
1153/// Render one row's XML into `out`, rejecting rows above `limit` bytes.
1154/// Returns the rendered size, which equals the bytes appended to `out`.
1155fn render_row_xml(
1156    out: &mut String,
1157    row: u32,
1158    values: &[CellValue],
1159    cell_style_id: Option<u32>,
1160    options: Option<&StreamRowOptions>,
1161    limit: u64,
1162) -> Result<u64> {
1163    let mut sink = RowXmlBuffer {
1164        counter: RowXmlCounter::new(limit),
1165        out,
1166    };
1167    write_row_xml(&mut sink, row, values, cell_style_id, options);
1168    sink.counter.finish()
1169}
1170
1171fn checked_stream_add(
1172    current: u64,
1173    additional: u64,
1174    limit: u64,
1175    dimension: ResourceDimension,
1176) -> Result<u64> {
1177    let observed = current.saturating_add(additional);
1178    if observed > limit {
1179        return Err(resource_limit(
1180            ResourceOperation::StreamWrite,
1181            ResourceCategory::Streaming,
1182            dimension,
1183            limit,
1184            observed,
1185            ResourceStage::Serialize,
1186        ));
1187    }
1188    Ok(observed)
1189}
1190
1191fn checked_stream_config_add(
1192    current: u64,
1193    additional: u64,
1194    limit: u64,
1195    dimension: ResourceDimension,
1196) -> Result<u64> {
1197    let observed = current.saturating_add(additional);
1198    if observed > limit {
1199        return Err(resource_limit(
1200            ResourceOperation::StreamWrite,
1201            ResourceCategory::Streaming,
1202            dimension,
1203            limit,
1204            observed,
1205            ResourceStage::Validate,
1206        ));
1207    }
1208    Ok(observed)
1209}
1210
1211fn collect_formula_usage(
1212    value: &CellValue,
1213    budget: &crate::formula::FormulaBudget,
1214    formula_cells: &mut u64,
1215    formula_input_bytes: &mut u64,
1216    formula_output_bytes: &mut u64,
1217) -> Result<()> {
1218    if let CellValue::Formula { expr, result } = value {
1219        let bytes = u64::try_from(expr.len()).unwrap_or(u64::MAX);
1220        budget.check_mutation_input(bytes)?;
1221        *formula_cells = formula_cells.saturating_add(1);
1222        *formula_input_bytes = formula_input_bytes.saturating_add(bytes);
1223        *formula_output_bytes = formula_output_bytes.saturating_add(bytes);
1224        if let Some(result) = result {
1225            *formula_output_bytes =
1226                formula_output_bytes.saturating_add(cached_formula_payload_bytes(result)?);
1227        }
1228    }
1229    Ok(())
1230}
1231
1232fn cached_formula_payload_bytes(value: &CellValue) -> Result<u64> {
1233    Ok(match value {
1234        CellValue::String(value) | CellValue::Error(value) => {
1235            u64::try_from(value.len()).unwrap_or(u64::MAX)
1236        }
1237        CellValue::RichString(_) | CellValue::Formula { .. } => {
1238            return Err(resource_limit(
1239                ResourceOperation::StreamWrite,
1240                ResourceCategory::Structure,
1241                ResourceDimension::CollectionCount,
1242                0,
1243                1,
1244                ResourceStage::Validate,
1245            ));
1246        }
1247        CellValue::Number(_) | CellValue::Date(_) => 32,
1248        CellValue::Bool(_) => 5,
1249        CellValue::Empty => 0,
1250    })
1251}
1252
1253/// Write an XML `<row>` element with inline strings to a pre-admitted sink.
1254fn write_row_xml<W: RowXmlSink>(
1255    xml: &mut W,
1256    row: u32,
1257    values: &[CellValue],
1258    cell_style_id: Option<u32>,
1259    options: Option<&StreamRowOptions>,
1260) {
1261    // Row number and style are formatted once per row; numbers and cell
1262    // references reuse one scratch buffer instead of allocating per cell.
1263    let row_text = row.to_string();
1264    let style_text = cell_style_id.map(|sid| sid.to_string());
1265    let mut scratch = String::new();
1266
1267    xml.push_str("<row r=\"");
1268    xml.push_str(&row_text);
1269    xml.push('"');
1270
1271    // Row-level attributes from options.
1272    if let Some(opts) = options {
1273        if let Some(sid) = opts.style_id {
1274            xml.push_str(" s=\"");
1275            xml.push_str(&sid.to_string());
1276            xml.push_str("\" customFormat=\"1\"");
1277        }
1278        if let Some(height) = opts.height {
1279            xml.push_str(" ht=\"");
1280            xml.push_str(&height.to_string());
1281            xml.push_str("\" customHeight=\"1\"");
1282        }
1283        if let Some(false) = opts.visible {
1284            xml.push_str(" hidden=\"1\"");
1285        }
1286        if let Some(level) = opts.outline_level {
1287            if level > 0 {
1288                xml.push_str(" outlineLevel=\"");
1289                xml.push_str(&level.to_string());
1290                xml.push('"');
1291            }
1292        }
1293    }
1294
1295    xml.push('>');
1296
1297    for (i, value) in values.iter().enumerate() {
1298        let col = (i as u32) + 1;
1299        if matches!(value, CellValue::Empty) {
1300            continue;
1301        }
1302
1303        scratch.clear();
1304        push_cell_name(&mut scratch, col, row, &row_text);
1305
1306        xml.push_str("<c r=\"");
1307        xml.push_str(&scratch);
1308        xml.push('"');
1309
1310        // Style attribute.
1311        if let Some(sid) = &style_text {
1312            xml.push_str(" s=\"");
1313            xml.push_str(sid);
1314            xml.push('"');
1315        }
1316
1317        match value {
1318            CellValue::String(s) => {
1319                xml.push_str(" t=\"inlineStr\"><is><t>");
1320                xml_escape_into(xml, s);
1321                xml.push_str("</t></is></c>");
1322            }
1323            CellValue::Number(n) => {
1324                xml.push_str("><v>");
1325                push_display(xml, &mut scratch, n);
1326                xml.push_str("</v></c>");
1327            }
1328            CellValue::Date(serial) => {
1329                xml.push_str(" t=\"d\"><v>");
1330                if let Some(datetime) = crate::cell::serial_to_datetime(*serial) {
1331                    xml.push_str(&datetime.format("%Y-%m-%dT%H:%M:%S").to_string());
1332                } else {
1333                    xml.push_str(&serial.to_string());
1334                }
1335                xml.push_str("</v></c>");
1336            }
1337            CellValue::Bool(b) => {
1338                xml.push_str(" t=\"b\"><v>");
1339                xml.push_str(if *b { "1" } else { "0" });
1340                xml.push_str("</v></c>");
1341            }
1342            CellValue::Formula { expr, result } => {
1343                // Set the cell type attribute based on the cached result type.
1344                // Without the correct t attribute, xml_cell_to_value cannot
1345                // decode the result on reopen.
1346                if let Some(res) = result {
1347                    match res.as_ref() {
1348                        CellValue::String(_) => xml.push_str(" t=\"str\""),
1349                        CellValue::Bool(_) => xml.push_str(" t=\"b\""),
1350                        CellValue::Error(_) => xml.push_str(" t=\"e\""),
1351                        CellValue::Date(_) => xml.push_str(" t=\"d\""),
1352                        _ => {} // Number: default (no t) is numeric
1353                    }
1354                }
1355                xml.push_str("><f>");
1356                xml_escape_into(xml, expr);
1357                xml.push_str("</f>");
1358                if let Some(res) = result {
1359                    match res.as_ref() {
1360                        CellValue::String(s) => {
1361                            xml.push_str("<v>");
1362                            xml_escape_into(xml, s);
1363                            xml.push_str("</v>");
1364                        }
1365                        CellValue::Number(n) => {
1366                            xml.push_str("<v>");
1367                            push_display(xml, &mut scratch, n);
1368                            xml.push_str("</v>");
1369                        }
1370                        CellValue::Bool(b) => {
1371                            xml.push_str("<v>");
1372                            xml.push_str(if *b { "1" } else { "0" });
1373                            xml.push_str("</v>");
1374                        }
1375                        CellValue::Date(d) => {
1376                            xml.push_str("<v>");
1377                            if let Some(datetime) = crate::cell::serial_to_datetime(*d) {
1378                                xml.push_str(&datetime.format("%Y-%m-%dT%H:%M:%S").to_string());
1379                            } else {
1380                                xml.push_str(&d.to_string());
1381                            }
1382                            xml.push_str("</v>");
1383                        }
1384                        CellValue::Error(e) => {
1385                            xml.push_str("<v>");
1386                            xml_escape_into(xml, e);
1387                            xml.push_str("</v>");
1388                        }
1389                        _ => {}
1390                    }
1391                }
1392                xml.push_str("</c>");
1393            }
1394            CellValue::Error(e) => {
1395                xml.push_str(" t=\"e\"><v>");
1396                xml_escape_into(xml, e);
1397                xml.push_str("</v></c>");
1398            }
1399            CellValue::RichString(runs) => {
1400                xml.push_str(" t=\"inlineStr\"><is><t>");
1401                for run in runs {
1402                    xml_escape_into(xml, &run.text);
1403                }
1404                xml.push_str("</t></is></c>");
1405            }
1406            CellValue::Empty => unreachable!(),
1407        }
1408    }
1409
1410    xml.push_str("</row>");
1411}
1412
1413/// Escape XML special characters into an existing string buffer, dropping
1414/// characters XML cannot represent. Unchanged text is pushed in runs.
1415fn xml_escape_into<W: RowXmlSink>(buf: &mut W, s: &str) {
1416    let mut run_start = 0;
1417    for (index, ch) in s.char_indices() {
1418        let replacement = match ch {
1419            '&' => "&amp;",
1420            '<' => "&lt;",
1421            '>' => "&gt;",
1422            '"' => "&quot;",
1423            '\'' => "&apos;",
1424            _ if !crate::utils::is_xml_char(ch) => "",
1425            _ => continue,
1426        };
1427        if run_start < index {
1428            buf.push_chars(&s[run_start..index]);
1429        }
1430        if !replacement.is_empty() {
1431            buf.push_str(replacement);
1432        }
1433        run_start = index + ch.len_utf8();
1434    }
1435    if run_start < s.len() {
1436        buf.push_chars(&s[run_start..]);
1437    }
1438}
1439
1440/// Append the A1 name of (`col`, `row`) to `out`, reusing the row's
1441/// formatted number. Matches `coordinates_to_cell_name`, including its
1442/// fallback text for coordinates outside the sheet.
1443fn push_cell_name(out: &mut String, col: u32, row: u32, row_text: &str) {
1444    if !(1..=MAX_COLUMNS).contains(&col) || !(1..=MAX_ROWS).contains(&row) {
1445        let _ = write!(out, "{col}:{row}");
1446        return;
1447    }
1448    // MAX_COLUMNS (XFD) needs at most three letters.
1449    let mut letters = [0u8; 3];
1450    let mut length = 0;
1451    let mut remaining = col;
1452    while remaining > 0 {
1453        remaining -= 1;
1454        letters[length] = b'A' + (remaining % 26) as u8;
1455        length += 1;
1456        remaining /= 26;
1457    }
1458    for &letter in letters[..length].iter().rev() {
1459        out.push(char::from(letter));
1460    }
1461    out.push_str(row_text);
1462}
1463
1464/// Push `value` formatted with `Display` as one token, using `scratch`.
1465fn push_display<W: RowXmlSink>(xml: &mut W, scratch: &mut String, value: impl std::fmt::Display) {
1466    scratch.clear();
1467    let _ = write!(scratch, "{value}");
1468    xml.push_str(scratch);
1469}
1470
1471fn validate_stream_values(values: &[CellValue]) -> Result<()> {
1472    for value in values {
1473        validate_stream_value(value)?;
1474    }
1475    Ok(())
1476}
1477
1478fn validate_stream_value(value: &CellValue) -> Result<()> {
1479    match value {
1480        CellValue::Number(n) | CellValue::Date(n) if !n.is_finite() => {
1481            Err(Error::StreamNonFiniteValue)
1482        }
1483        CellValue::Formula {
1484            result: Some(result),
1485            ..
1486        } => match result.as_ref() {
1487            CellValue::Formula { .. } => Err(resource_limit(
1488                ResourceOperation::StreamWrite,
1489                ResourceCategory::Structure,
1490                ResourceDimension::NestingDepth,
1491                1,
1492                2,
1493                ResourceStage::Validate,
1494            )),
1495            other => validate_stream_value(other),
1496        },
1497        _ => Ok(()),
1498    }
1499}
1500
1501#[cfg(test)]
1502mod tests {
1503    use super::*;
1504    use sheetkit_xml::worksheet::WorksheetXml;
1505    use std::io::{Read as _, Seek as _};
1506
1507    /// Helper to parse a streamed writer into a WorksheetXml for assertion.
1508    fn finish_and_parse(sw: StreamWriter) -> WorksheetXml {
1509        let (_, mut streamed) = sw.into_streamed_data().unwrap();
1510        let header = build_worksheet_header(&streamed);
1511        let footer = build_worksheet_footer(&streamed);
1512
1513        let file = streamed.temp_file.as_file_mut();
1514        file.seek(std::io::SeekFrom::Start(0)).unwrap();
1515        let mut row_data = String::new();
1516        file.read_to_string(&mut row_data).unwrap();
1517
1518        let full_xml = format!("{header}{row_data}{footer}");
1519        quick_xml::de::from_str(&full_xml).unwrap()
1520    }
1521
1522    /// Helper to get the raw XML from a stream writer.
1523    fn finish_and_get_xml(sw: StreamWriter) -> String {
1524        let (_, mut streamed) = sw.into_streamed_data().unwrap();
1525        let header = build_worksheet_header(&streamed);
1526        let footer = build_worksheet_footer(&streamed);
1527
1528        let file = streamed.temp_file.as_file_mut();
1529        file.seek(std::io::SeekFrom::Start(0)).unwrap();
1530        let mut row_data = String::new();
1531        file.read_to_string(&mut row_data).unwrap();
1532
1533        format!("{header}{row_data}{footer}")
1534    }
1535
1536    #[test]
1537    fn test_new_defers_temp_file_creation() {
1538        let sw = StreamWriter::new("Sheet1");
1539
1540        assert!(sw.writer.is_none());
1541    }
1542
1543    #[test]
1544    fn test_try_new_initializes_temp_file_fallibly() {
1545        let sw = StreamWriter::try_new("Sheet1").unwrap();
1546
1547        assert!(sw.writer.is_some());
1548    }
1549
1550    #[test]
1551    fn test_basic_write_and_finish() {
1552        let mut sw = StreamWriter::new("Sheet1");
1553        sw.write_row(1, &[CellValue::from("Name"), CellValue::from("Age")])
1554            .unwrap();
1555        sw.write_row(2, &[CellValue::from("Alice"), CellValue::from(30)])
1556            .unwrap();
1557        let xml = finish_and_get_xml(sw);
1558
1559        assert!(xml.contains("<?xml version=\"1.0\""));
1560        assert!(xml.contains("<worksheet"));
1561        assert!(xml.contains("<sheetData>"));
1562        assert!(xml.contains("</sheetData>"));
1563        assert!(xml.contains("</worksheet>"));
1564    }
1565
1566    #[test]
1567    fn test_parse_output_xml_back() {
1568        let mut sw = StreamWriter::new("TestSheet");
1569        sw.write_row(1, &[CellValue::from("Hello"), CellValue::from(42)])
1570            .unwrap();
1571        let ws = finish_and_parse(sw);
1572
1573        assert_eq!(ws.sheet_data.rows.len(), 1);
1574        assert_eq!(ws.sheet_data.rows[0].r, 1);
1575        assert_eq!(ws.sheet_data.rows[0].cells.len(), 2);
1576        // First cell is an inline string (t="inlineStr")
1577        assert_eq!(
1578            ws.sheet_data.rows[0].cells[0].t,
1579            sheetkit_xml::worksheet::CellTypeTag::InlineString
1580        );
1581        assert_eq!(ws.sheet_data.rows[0].cells[0].r, "A1");
1582        // Second cell is a number
1583        assert_eq!(
1584            ws.sheet_data.rows[0].cells[1].t,
1585            sheetkit_xml::worksheet::CellTypeTag::None
1586        );
1587        assert_eq!(ws.sheet_data.rows[0].cells[1].v, Some("42".to_string()));
1588        assert_eq!(ws.sheet_data.rows[0].cells[1].r, "B1");
1589    }
1590
1591    #[test]
1592    fn test_inline_strings_used() {
1593        let mut sw = StreamWriter::new("Sheet1");
1594        sw.write_row(1, &[CellValue::from("Hello"), CellValue::from("World")])
1595            .unwrap();
1596        let xml = finish_and_get_xml(sw);
1597
1598        // Should use inline strings, not shared string references
1599        assert!(xml.contains("t=\"inlineStr\""));
1600        assert!(xml.contains("<is><t>Hello</t></is>"));
1601        assert!(xml.contains("<is><t>World</t></is>"));
1602        // Should NOT contain shared string references
1603        assert!(!xml.contains("t=\"s\""));
1604    }
1605
1606    #[test]
1607    fn test_number_value() {
1608        let mut sw = StreamWriter::new("Sheet1");
1609        sw.write_row(1, &[CellValue::from(3.15)]).unwrap();
1610        let xml = finish_and_get_xml(sw);
1611
1612        assert!(xml.contains("<v>3.15</v>"));
1613    }
1614
1615    #[test]
1616    fn test_bool_values() {
1617        let mut sw = StreamWriter::new("Sheet1");
1618        sw.write_row(1, &[CellValue::from(true), CellValue::from(false)])
1619            .unwrap();
1620        let xml = finish_and_get_xml(sw);
1621
1622        assert!(xml.contains("<v>1</v>"));
1623        assert!(xml.contains("<v>0</v>"));
1624    }
1625
1626    #[test]
1627    fn test_formula_value() {
1628        let mut sw = StreamWriter::new("Sheet1");
1629        sw.write_row(
1630            1,
1631            &[CellValue::Formula {
1632                expr: "SUM(A2:A10)".to_string(),
1633                result: None,
1634            }],
1635        )
1636        .unwrap();
1637        let xml = finish_and_get_xml(sw);
1638
1639        assert!(xml.contains("SUM(A2:A10)"));
1640    }
1641
1642    #[test]
1643    fn test_error_value() {
1644        let mut sw = StreamWriter::new("Sheet1");
1645        sw.write_row(1, &[CellValue::Error("#DIV/0!".to_string())])
1646            .unwrap();
1647        let xml = finish_and_get_xml(sw);
1648
1649        assert!(xml.contains("#DIV/0!"));
1650    }
1651
1652    #[test]
1653    fn test_empty_values_are_skipped() {
1654        let mut sw = StreamWriter::new("Sheet1");
1655        sw.write_row(
1656            1,
1657            &[CellValue::from("A"), CellValue::Empty, CellValue::from("C")],
1658        )
1659        .unwrap();
1660        let ws = finish_and_parse(sw);
1661
1662        // 2 cells (Empty is skipped)
1663        assert_eq!(ws.sheet_data.rows[0].cells.len(), 2);
1664        assert_eq!(ws.sheet_data.rows[0].cells[0].r, "A1");
1665        assert_eq!(ws.sheet_data.rows[0].cells[1].r, "C1");
1666    }
1667
1668    #[test]
1669    fn test_write_row_with_style() {
1670        let mut sw = StreamWriter::new("Sheet1");
1671        sw.write_row_with_style(1, &[CellValue::from("Styled")], 5)
1672            .unwrap();
1673        let xml = finish_and_get_xml(sw);
1674
1675        assert!(xml.contains("s=\"5\""));
1676    }
1677
1678    #[test]
1679    fn test_set_col_width_before_rows() {
1680        let mut sw = StreamWriter::new("Sheet1");
1681        sw.set_col_width(1, 20.0).unwrap();
1682        sw.write_row(1, &[CellValue::from("data")]).unwrap();
1683        let ws = finish_and_parse(sw);
1684
1685        let cols = ws.cols.unwrap();
1686        assert_eq!(cols.cols.len(), 1);
1687        assert_eq!(cols.cols[0].min, 1);
1688        assert_eq!(cols.cols[0].max, 1);
1689        assert_eq!(cols.cols[0].width, Some(20.0));
1690        assert_eq!(cols.cols[0].custom_width, Some(true));
1691    }
1692
1693    #[test]
1694    fn test_set_col_width_range() {
1695        let mut sw = StreamWriter::new("Sheet1");
1696        sw.set_col_width_range(1, 3, 15.5).unwrap();
1697        let ws = finish_and_parse(sw);
1698
1699        let cols = ws.cols.unwrap();
1700        assert_eq!(cols.cols.len(), 1);
1701        assert_eq!(cols.cols[0].min, 1);
1702        assert_eq!(cols.cols[0].max, 3);
1703        assert_eq!(cols.cols[0].width, Some(15.5));
1704    }
1705
1706    #[test]
1707    fn test_col_width_in_output_xml() {
1708        let mut sw = StreamWriter::new("Sheet1");
1709        sw.set_col_width(2, 25.0).unwrap();
1710        sw.write_row(1, &[CellValue::from("data")]).unwrap();
1711        let xml = finish_and_get_xml(sw);
1712
1713        // Verify cols section appears before sheetData
1714        let cols_pos = xml.find("<cols>").unwrap();
1715        let sheet_data_pos = xml.find("<sheetData").unwrap();
1716        assert!(cols_pos < sheet_data_pos);
1717    }
1718
1719    #[test]
1720    fn test_col_width_after_rows_returns_error() {
1721        let mut sw = StreamWriter::new("Sheet1");
1722        sw.write_row(1, &[CellValue::from("data")]).unwrap();
1723        let result = sw.set_col_width(1, 20.0);
1724        assert!(result.is_err());
1725        assert!(matches!(result.unwrap_err(), Error::StreamColumnsAfterRows));
1726    }
1727
1728    #[test]
1729    fn test_rows_in_order_succeeds() {
1730        let mut sw = StreamWriter::new("Sheet1");
1731        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1732        sw.write_row(2, &[CellValue::from("b")]).unwrap();
1733        sw.write_row(3, &[CellValue::from("c")]).unwrap();
1734        let _data = sw.into_streamed_data().unwrap();
1735    }
1736
1737    #[test]
1738    fn test_rows_with_gaps_succeeds() {
1739        let mut sw = StreamWriter::new("Sheet1");
1740        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1741        sw.write_row(3, &[CellValue::from("b")]).unwrap();
1742        sw.write_row(5, &[CellValue::from("c")]).unwrap();
1743        let ws = finish_and_parse(sw);
1744
1745        assert_eq!(ws.sheet_data.rows.len(), 3);
1746        assert_eq!(ws.sheet_data.rows[0].r, 1);
1747        assert_eq!(ws.sheet_data.rows[1].r, 3);
1748        assert_eq!(ws.sheet_data.rows[2].r, 5);
1749    }
1750
1751    #[test]
1752    fn test_duplicate_row_number_fails() {
1753        let mut sw = StreamWriter::new("Sheet1");
1754        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1755        let result = sw.write_row(1, &[CellValue::from("b")]);
1756        assert!(result.is_err());
1757        assert!(matches!(
1758            result.unwrap_err(),
1759            Error::StreamRowAlreadyWritten { row: 1 }
1760        ));
1761    }
1762
1763    #[test]
1764    fn test_row_zero_fails() {
1765        let mut sw = StreamWriter::new("Sheet1");
1766        let result = sw.write_row(0, &[CellValue::from("a")]);
1767        assert!(result.is_err());
1768        assert!(matches!(result.unwrap_err(), Error::InvalidRowNumber(0)));
1769    }
1770
1771    #[test]
1772    fn test_row_out_of_order_fails() {
1773        let mut sw = StreamWriter::new("Sheet1");
1774        sw.write_row(5, &[CellValue::from("a")]).unwrap();
1775        let result = sw.write_row(3, &[CellValue::from("b")]);
1776        assert!(result.is_err());
1777        assert!(matches!(
1778            result.unwrap_err(),
1779            Error::StreamRowAlreadyWritten { row: 3 }
1780        ));
1781    }
1782
1783    #[test]
1784    fn test_merge_cells_in_output() {
1785        let mut sw = StreamWriter::new("Sheet1");
1786        sw.write_row(1, &[CellValue::from("Merged")]).unwrap();
1787        sw.add_merge_cell("A1:B1").unwrap();
1788        let ws = finish_and_parse(sw);
1789
1790        let mc = ws.merge_cells.unwrap();
1791        assert_eq!(mc.merge_cells.len(), 1);
1792        assert_eq!(mc.merge_cells[0].reference, "A1:B1");
1793    }
1794
1795    #[test]
1796    fn test_multiple_merge_cells() {
1797        let mut sw = StreamWriter::new("Sheet1");
1798        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1799        sw.add_merge_cell("A1:B1").unwrap();
1800        sw.add_merge_cell("C1:D1").unwrap();
1801        let ws = finish_and_parse(sw);
1802
1803        let mc = ws.merge_cells.unwrap();
1804        assert_eq!(mc.merge_cells.len(), 2);
1805        assert_eq!(mc.merge_cells[0].reference, "A1:B1");
1806        assert_eq!(mc.merge_cells[1].reference, "C1:D1");
1807    }
1808
1809    #[test]
1810    fn test_finish_twice_returns_error() {
1811        let mut sw = StreamWriter::new("Sheet1");
1812        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1813        // First consume
1814        sw.into_streamed_data().unwrap();
1815        // Cannot call again -- consumed by move.
1816    }
1817
1818    #[test]
1819    fn test_write_after_finish_returns_error() {
1820        // StreamWriter is consumed by into_streamed_data(), so this test
1821        // verifies that the finished flag works for the legacy path.
1822        let mut sw = StreamWriter::new("Sheet1");
1823        sw.write_row(1, &[CellValue::from("a")]).unwrap();
1824        sw.finished = true;
1825        let result = sw.write_row(2, &[CellValue::from("b")]);
1826        assert!(result.is_err());
1827        assert!(matches!(result.unwrap_err(), Error::StreamAlreadyFinished));
1828    }
1829
1830    #[test]
1831    fn test_finish_with_no_rows() {
1832        let sw = StreamWriter::new("Sheet1");
1833        let ws = finish_and_parse(sw);
1834
1835        // Should still produce valid XML
1836        assert!(ws.sheet_data.rows.is_empty());
1837    }
1838
1839    #[test]
1840    fn test_finish_with_cols_and_no_rows() {
1841        let mut sw = StreamWriter::new("Sheet1");
1842        sw.set_col_width(1, 20.0).unwrap();
1843        let ws = finish_and_parse(sw);
1844
1845        assert!(ws.cols.is_some());
1846        assert!(ws.sheet_data.rows.is_empty());
1847    }
1848
1849    #[test]
1850    fn test_add_merge_cell_invalid_reference() {
1851        let mut sw = StreamWriter::new("Sheet1");
1852        // Missing colon separator.
1853        let result = sw.add_merge_cell("A1B2");
1854        assert!(result.is_err());
1855        assert!(matches!(
1856            result.unwrap_err(),
1857            Error::InvalidMergeCellReference(_)
1858        ));
1859    }
1860
1861    #[test]
1862    fn test_add_merge_cell_invalid_cell_name() {
1863        let mut sw = StreamWriter::new("Sheet1");
1864        // Invalid cell name before colon.
1865        let result = sw.add_merge_cell("ZZZ:B2");
1866        assert!(result.is_err());
1867        assert!(matches!(
1868            result.unwrap_err(),
1869            Error::InvalidMergeCellReference(_)
1870        ));
1871    }
1872
1873    #[test]
1874    fn test_add_merge_cell_empty_reference() {
1875        let mut sw = StreamWriter::new("Sheet1");
1876        let result = sw.add_merge_cell("");
1877        assert!(result.is_err());
1878        assert!(matches!(
1879            result.unwrap_err(),
1880            Error::InvalidMergeCellReference(_)
1881        ));
1882    }
1883
1884    #[test]
1885    fn test_add_merge_cell_after_finish_fails() {
1886        let mut sw = StreamWriter::new("Sheet1");
1887        sw.finished = true;
1888        let result = sw.add_merge_cell("A1:B1");
1889        assert!(result.is_err());
1890        assert!(matches!(result.unwrap_err(), Error::StreamAlreadyFinished));
1891    }
1892
1893    #[test]
1894    fn add_merge_cell_canonicalizes_absolute_lowercase_and_inverted_ranges() {
1895        let mut sw = StreamWriter::new("Sheet1");
1896        sw.add_merge_cell("$a$1:b2").unwrap();
1897        sw.add_merge_cell("D4:C3").unwrap();
1898        let ws = finish_and_parse(sw);
1899        let refs: Vec<String> = ws
1900            .merge_cells
1901            .unwrap()
1902            .merge_cells
1903            .into_iter()
1904            .map(|m| m.reference)
1905            .collect();
1906        assert_eq!(refs, vec!["A1:B2".to_string(), "C3:D4".to_string()]);
1907    }
1908
1909    #[test]
1910    fn add_merge_cell_rejects_overlaps_and_dedupes_equivalent_ranges() {
1911        let mut sw = StreamWriter::new("Sheet1");
1912        sw.add_merge_cell("A1:B2").unwrap();
1913        // Equivalent spelling of an existing range is an idempotent no-op.
1914        sw.add_merge_cell("B2:A1").unwrap();
1915        assert_eq!(sw.config_count, 1);
1916        let err = sw.add_merge_cell("B2:C3").unwrap_err();
1917        match err {
1918            Error::MergeCellOverlap { new, existing } => {
1919                assert_eq!(new, "B2:C3");
1920                assert_eq!(existing, "A1:B2");
1921            }
1922            other => panic!("expected MergeCellOverlap, got {other:?}"),
1923        }
1924        assert_eq!(sw.config_count, 1);
1925        sw.add_merge_cell("C3:D4").unwrap();
1926        let ws = finish_and_parse(sw);
1927        assert_eq!(ws.merge_cells.unwrap().merge_cells.len(), 2);
1928    }
1929
1930    #[test]
1931    fn stream_writer_is_send() {
1932        fn assert_send<T: Send>() {}
1933        assert_send::<StreamWriter>();
1934    }
1935
1936    #[test]
1937    fn test_set_col_width_after_finish_fails() {
1938        let mut sw = StreamWriter::new("Sheet1");
1939        sw.finished = true;
1940        let result = sw.set_col_width(1, 10.0);
1941        assert!(result.is_err());
1942        assert!(matches!(result.unwrap_err(), Error::StreamAlreadyFinished));
1943    }
1944
1945    #[test]
1946    fn test_sheet_name_getter() {
1947        let sw = StreamWriter::new("MySheet");
1948        assert_eq!(sw.sheet_name(), "MySheet");
1949    }
1950
1951    #[test]
1952    fn test_all_value_types_in_single_row() {
1953        let mut sw = StreamWriter::new("Sheet1");
1954        sw.write_row(
1955            1,
1956            &[
1957                CellValue::from("text"),
1958                CellValue::from(42),
1959                CellValue::from(3.15),
1960                CellValue::from(true),
1961                CellValue::from(false),
1962                CellValue::Formula {
1963                    expr: "A1+B1".to_string(),
1964                    result: None,
1965                },
1966                CellValue::Error("#N/A".to_string()),
1967                CellValue::Empty,
1968            ],
1969        )
1970        .unwrap();
1971        let ws = finish_and_parse(sw);
1972
1973        // 7 cells (Empty is skipped)
1974        assert_eq!(ws.sheet_data.rows[0].cells.len(), 7);
1975    }
1976
1977    #[test]
1978    fn test_col_width_invalid_column_zero() {
1979        let mut sw = StreamWriter::new("Sheet1");
1980        let result = sw.set_col_width(0, 10.0);
1981        assert!(result.is_err());
1982        assert!(matches!(result.unwrap_err(), Error::InvalidColumnNumber(0)));
1983    }
1984
1985    #[test]
1986    fn test_write_row_with_options_height() {
1987        let mut sw = StreamWriter::new("Sheet1");
1988        let opts = StreamRowOptions {
1989            height: Some(30.0),
1990            ..Default::default()
1991        };
1992        sw.write_row_with_options(1, &[CellValue::from("tall row")], &opts)
1993            .unwrap();
1994        let ws = finish_and_parse(sw);
1995
1996        assert_eq!(ws.sheet_data.rows[0].ht, Some(30.0));
1997        assert_eq!(ws.sheet_data.rows[0].custom_height, Some(true));
1998    }
1999
2000    #[test]
2001    fn test_write_row_with_options_hidden() {
2002        let mut sw = StreamWriter::new("Sheet1");
2003        let opts = StreamRowOptions {
2004            visible: Some(false),
2005            ..Default::default()
2006        };
2007        sw.write_row_with_options(1, &[CellValue::from("hidden")], &opts)
2008            .unwrap();
2009        let ws = finish_and_parse(sw);
2010
2011        assert_eq!(ws.sheet_data.rows[0].hidden, Some(true));
2012    }
2013
2014    #[test]
2015    fn test_write_row_with_options_outline_level() {
2016        let mut sw = StreamWriter::new("Sheet1");
2017        let opts = StreamRowOptions {
2018            outline_level: Some(3),
2019            ..Default::default()
2020        };
2021        sw.write_row_with_options(1, &[CellValue::from("grouped")], &opts)
2022            .unwrap();
2023        let ws = finish_and_parse(sw);
2024
2025        assert_eq!(ws.sheet_data.rows[0].outline_level, Some(3));
2026    }
2027
2028    #[test]
2029    fn test_write_row_with_options_style() {
2030        let mut sw = StreamWriter::new("Sheet1");
2031        let opts = StreamRowOptions {
2032            style_id: Some(2),
2033            ..Default::default()
2034        };
2035        sw.write_row_with_options(1, &[CellValue::from("styled row")], &opts)
2036            .unwrap();
2037        let ws = finish_and_parse(sw);
2038
2039        assert_eq!(ws.sheet_data.rows[0].s, Some(2));
2040        assert_eq!(ws.sheet_data.rows[0].custom_format, Some(true));
2041    }
2042
2043    #[test]
2044    fn test_write_row_with_options_all() {
2045        let mut sw = StreamWriter::new("Sheet1");
2046        let opts = StreamRowOptions {
2047            height: Some(25.5),
2048            visible: Some(false),
2049            outline_level: Some(2),
2050            style_id: Some(7),
2051        };
2052        sw.write_row_with_options(1, &[CellValue::from("all options")], &opts)
2053            .unwrap();
2054        let ws = finish_and_parse(sw);
2055
2056        let row = &ws.sheet_data.rows[0];
2057        assert_eq!(row.ht, Some(25.5));
2058        assert_eq!(row.custom_height, Some(true));
2059        assert_eq!(row.hidden, Some(true));
2060        assert_eq!(row.outline_level, Some(2));
2061        assert_eq!(row.s, Some(7));
2062        assert_eq!(row.custom_format, Some(true));
2063    }
2064
2065    #[test]
2066    fn test_write_row_with_options_height_exceeded() {
2067        let mut sw = StreamWriter::new("Sheet1");
2068        let opts = StreamRowOptions {
2069            height: Some(500.0),
2070            ..Default::default()
2071        };
2072        let result = sw.write_row_with_options(1, &[CellValue::from("too tall")], &opts);
2073        assert!(result.is_err());
2074        assert!(matches!(
2075            result.unwrap_err(),
2076            Error::RowHeightExceeded { .. }
2077        ));
2078    }
2079
2080    #[test]
2081    fn test_write_row_with_options_outline_level_exceeded() {
2082        let mut sw = StreamWriter::new("Sheet1");
2083        let opts = StreamRowOptions {
2084            outline_level: Some(8),
2085            ..Default::default()
2086        };
2087        let result = sw.write_row_with_options(1, &[CellValue::from("bad level")], &opts);
2088        assert!(result.is_err());
2089    }
2090
2091    #[test]
2092    fn test_write_row_with_options_visible_true_no_hidden_attr() {
2093        let mut sw = StreamWriter::new("Sheet1");
2094        let opts = StreamRowOptions {
2095            visible: Some(true),
2096            ..Default::default()
2097        };
2098        sw.write_row_with_options(1, &[CellValue::from("visible")], &opts)
2099            .unwrap();
2100        let xml = finish_and_get_xml(sw);
2101
2102        // visible=true should NOT produce hidden attribute
2103        assert!(!xml.contains("hidden="));
2104    }
2105
2106    #[test]
2107    fn test_col_style() {
2108        let mut sw = StreamWriter::new("Sheet1");
2109        sw.set_col_style(1, 3).unwrap();
2110        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2111        let ws = finish_and_parse(sw);
2112
2113        let cols = ws.cols.unwrap();
2114        let styled_col = cols.cols.iter().find(|c| c.style.is_some()).unwrap();
2115        assert_eq!(styled_col.style, Some(3));
2116        assert_eq!(styled_col.min, 1);
2117        assert_eq!(styled_col.max, 1);
2118    }
2119
2120    #[test]
2121    fn test_col_visible() {
2122        let mut sw = StreamWriter::new("Sheet1");
2123        sw.set_col_visible(2, false).unwrap();
2124        sw.write_row(1, &[CellValue::from("a"), CellValue::from("b")])
2125            .unwrap();
2126        let ws = finish_and_parse(sw);
2127
2128        let cols = ws.cols.unwrap();
2129        let hidden_col = cols.cols.iter().find(|c| c.hidden == Some(true)).unwrap();
2130        assert_eq!(hidden_col.min, 2);
2131        assert_eq!(hidden_col.max, 2);
2132    }
2133
2134    #[test]
2135    fn test_col_outline_level() {
2136        let mut sw = StreamWriter::new("Sheet1");
2137        sw.set_col_outline_level(3, 2).unwrap();
2138        sw.write_row(1, &[CellValue::from("a")]).unwrap();
2139        let ws = finish_and_parse(sw);
2140
2141        let cols = ws.cols.unwrap();
2142        let outlined_col = cols
2143            .cols
2144            .iter()
2145            .find(|c| c.outline_level.is_some())
2146            .unwrap();
2147        assert_eq!(outlined_col.outline_level, Some(2));
2148        assert_eq!(outlined_col.min, 3);
2149        assert_eq!(outlined_col.max, 3);
2150    }
2151
2152    #[test]
2153    fn test_col_outline_level_exceeded() {
2154        let mut sw = StreamWriter::new("Sheet1");
2155        let result = sw.set_col_outline_level(1, 8);
2156        assert!(result.is_err());
2157    }
2158
2159    #[test]
2160    fn test_col_style_after_rows_error() {
2161        let mut sw = StreamWriter::new("Sheet1");
2162        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2163        let result = sw.set_col_style(1, 1);
2164        assert!(result.is_err());
2165        assert!(matches!(result.unwrap_err(), Error::StreamColumnsAfterRows));
2166    }
2167
2168    #[test]
2169    fn test_col_visible_after_rows_error() {
2170        let mut sw = StreamWriter::new("Sheet1");
2171        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2172        let result = sw.set_col_visible(1, false);
2173        assert!(result.is_err());
2174        assert!(matches!(result.unwrap_err(), Error::StreamColumnsAfterRows));
2175    }
2176
2177    #[test]
2178    fn test_col_outline_after_rows_error() {
2179        let mut sw = StreamWriter::new("Sheet1");
2180        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2181        let result = sw.set_col_outline_level(1, 1);
2182        assert!(result.is_err());
2183        assert!(matches!(result.unwrap_err(), Error::StreamColumnsAfterRows));
2184    }
2185
2186    #[test]
2187    fn test_freeze_panes_rows() {
2188        let mut sw = StreamWriter::new("Sheet1");
2189        sw.set_freeze_panes("A2").unwrap();
2190        sw.write_row(1, &[CellValue::from("header")]).unwrap();
2191        sw.write_row(2, &[CellValue::from("data")]).unwrap();
2192        let ws = finish_and_parse(sw);
2193
2194        let views = ws.sheet_views.unwrap();
2195        let pane = views.sheet_views[0].pane.as_ref().unwrap();
2196        assert_eq!(pane.y_split, Some(1));
2197        assert_eq!(pane.top_left_cell, Some("A2".to_string()));
2198        assert_eq!(pane.active_pane, Some("bottomLeft".to_string()));
2199        assert_eq!(pane.state, Some("frozen".to_string()));
2200        // xSplit should not appear when only rows are frozen
2201        assert_eq!(pane.x_split, None);
2202    }
2203
2204    #[test]
2205    fn test_freeze_panes_cols() {
2206        let mut sw = StreamWriter::new("Sheet1");
2207        sw.set_freeze_panes("B1").unwrap();
2208        sw.write_row(1, &[CellValue::from("a"), CellValue::from("b")])
2209            .unwrap();
2210        let ws = finish_and_parse(sw);
2211
2212        let views = ws.sheet_views.unwrap();
2213        let pane = views.sheet_views[0].pane.as_ref().unwrap();
2214        assert_eq!(pane.x_split, Some(1));
2215        assert_eq!(pane.top_left_cell, Some("B1".to_string()));
2216        assert_eq!(pane.active_pane, Some("topRight".to_string()));
2217        assert_eq!(pane.state, Some("frozen".to_string()));
2218        // ySplit should not appear when only cols are frozen
2219        assert_eq!(pane.y_split, None);
2220    }
2221
2222    #[test]
2223    fn test_freeze_panes_both() {
2224        let mut sw = StreamWriter::new("Sheet1");
2225        sw.set_freeze_panes("C3").unwrap();
2226        sw.write_row(1, &[CellValue::from("a")]).unwrap();
2227        let ws = finish_and_parse(sw);
2228
2229        let views = ws.sheet_views.unwrap();
2230        let pane = views.sheet_views[0].pane.as_ref().unwrap();
2231        assert_eq!(pane.x_split, Some(2));
2232        assert_eq!(pane.y_split, Some(2));
2233        assert_eq!(pane.top_left_cell, Some("C3".to_string()));
2234        assert_eq!(pane.active_pane, Some("bottomRight".to_string()));
2235        assert_eq!(pane.state, Some("frozen".to_string()));
2236    }
2237
2238    #[test]
2239    fn test_freeze_panes_after_rows_error() {
2240        let mut sw = StreamWriter::new("Sheet1");
2241        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2242        let result = sw.set_freeze_panes("A2");
2243        assert!(result.is_err());
2244        assert!(matches!(result.unwrap_err(), Error::StreamColumnsAfterRows));
2245    }
2246
2247    #[test]
2248    fn test_freeze_panes_a1_error() {
2249        let mut sw = StreamWriter::new("Sheet1");
2250        let result = sw.set_freeze_panes("A1");
2251        assert!(result.is_err());
2252        assert!(matches!(
2253            result.unwrap_err(),
2254            Error::InvalidCellReference(_)
2255        ));
2256    }
2257
2258    #[test]
2259    fn test_freeze_panes_invalid_cell_error() {
2260        let mut sw = StreamWriter::new("Sheet1");
2261        let result = sw.set_freeze_panes("ZZZZ1");
2262        assert!(result.is_err());
2263    }
2264
2265    #[test]
2266    fn test_freeze_panes_appears_before_cols() {
2267        let mut sw = StreamWriter::new("Sheet1");
2268        sw.set_freeze_panes("A2").unwrap();
2269        sw.set_col_width(1, 20.0).unwrap();
2270        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2271        let xml = finish_and_get_xml(sw);
2272
2273        let views_pos = xml.find("<sheetView").unwrap();
2274        let cols_pos = xml.find("<cols>").unwrap();
2275        let data_pos = xml.find("<sheetData").unwrap();
2276        assert!(views_pos < cols_pos);
2277        assert!(cols_pos < data_pos);
2278    }
2279
2280    #[test]
2281    fn test_freeze_panes_after_finish_error() {
2282        let mut sw = StreamWriter::new("Sheet1");
2283        sw.finished = true;
2284        let result = sw.set_freeze_panes("A2");
2285        assert!(result.is_err());
2286        assert!(matches!(result.unwrap_err(), Error::StreamAlreadyFinished));
2287    }
2288
2289    #[test]
2290    fn test_no_freeze_panes_no_sheet_views() {
2291        let mut sw = StreamWriter::new("Sheet1");
2292        sw.write_row(1, &[CellValue::from("data")]).unwrap();
2293        let xml = finish_and_get_xml(sw);
2294
2295        // When no freeze panes are set, sheetViews should not appear
2296        assert!(!xml.contains("<sheetView"));
2297    }
2298
2299    #[test]
2300    fn test_write_row_backward_compat() {
2301        // Ensure the original write_row still works exactly as before.
2302        let mut sw = StreamWriter::new("Sheet1");
2303        sw.write_row(1, &[CellValue::from("hello")]).unwrap();
2304        let ws = finish_and_parse(sw);
2305
2306        let row = &ws.sheet_data.rows[0];
2307        assert_eq!(row.r, 1);
2308        // Should not have any row-level attributes beyond r
2309        assert!(row.ht.is_none());
2310        assert!(row.hidden.is_none());
2311        assert!(row.outline_level.is_none());
2312        assert!(row.custom_format.is_none());
2313    }
2314
2315    #[test]
2316    fn test_col_options_combined_with_widths() {
2317        let mut sw = StreamWriter::new("Sheet1");
2318        sw.set_col_width(1, 20.0).unwrap();
2319        sw.set_col_style(2, 5).unwrap();
2320        sw.set_col_visible(3, false).unwrap();
2321        sw.write_row(
2322            1,
2323            &[
2324                CellValue::from("a"),
2325                CellValue::from("b"),
2326                CellValue::from("c"),
2327            ],
2328        )
2329        .unwrap();
2330        let ws = finish_and_parse(sw);
2331
2332        let cols = ws.cols.unwrap();
2333        assert_eq!(cols.cols.len(), 3);
2334    }
2335
2336    #[test]
2337    fn test_large_scale_10000_rows() {
2338        let mut sw = StreamWriter::new("BigSheet");
2339        for i in 1..=10_000u32 {
2340            sw.write_row(
2341                i,
2342                &[
2343                    CellValue::from(format!("Row {}", i)),
2344                    CellValue::from(i as i32),
2345                    CellValue::from(i as f64 * 1.5),
2346                ],
2347            )
2348            .unwrap();
2349        }
2350        let ws = finish_and_parse(sw);
2351
2352        assert_eq!(ws.sheet_data.rows.len(), 10_000);
2353        assert_eq!(ws.sheet_data.rows[0].r, 1);
2354        assert_eq!(ws.sheet_data.rows[9999].r, 10_000);
2355    }
2356
2357    #[test]
2358    fn test_xml_escape_in_formula() {
2359        let mut sw = StreamWriter::new("Sheet1");
2360        sw.write_row(
2361            1,
2362            &[CellValue::Formula {
2363                expr: "IF(A1>0,\"yes\",\"no\")".to_string(),
2364                result: None,
2365            }],
2366        )
2367        .unwrap();
2368        let xml = finish_and_get_xml(sw);
2369
2370        // The formula should be XML-escaped
2371        assert!(xml.contains("&gt;"));
2372    }
2373
2374    #[test]
2375    fn test_xml_escape_in_string() {
2376        let mut sw = StreamWriter::new("Sheet1");
2377        sw.write_row(1, &[CellValue::from("Tom & Jerry <friends>")])
2378            .unwrap();
2379        let xml = finish_and_get_xml(sw);
2380
2381        assert!(xml.contains("Tom &amp; Jerry &lt;friends&gt;"));
2382    }
2383
2384    #[test]
2385    fn test_into_streamed_data_returns_valid_data() {
2386        let mut sw = StreamWriter::new("Sheet1");
2387        sw.set_col_width(1, 20.0).unwrap();
2388        sw.write_row(1, &[CellValue::from("Hello"), CellValue::from(42)])
2389            .unwrap();
2390        sw.write_row(2, &[CellValue::from("World"), CellValue::from(99)])
2391            .unwrap();
2392        sw.add_merge_cell("A1:B1").unwrap();
2393
2394        let (name, streamed) = sw.into_streamed_data().unwrap();
2395        assert_eq!(name, "Sheet1");
2396        assert!(streamed.data_len > 0);
2397        assert!(streamed.cols_xml.is_some());
2398        assert!(streamed.merge_cells_xml.is_some());
2399    }
2400
2401    #[test]
2402    fn test_streamed_sheet_data_try_clone() {
2403        let mut sw = StreamWriter::new("Sheet1");
2404        sw.set_col_width(1, 20.0).unwrap();
2405        sw.set_freeze_panes("A2").unwrap();
2406        sw.write_row(1, &[CellValue::from("Hello")]).unwrap();
2407        sw.write_row(2, &[CellValue::from("World")]).unwrap();
2408        sw.add_merge_cell("A1:B1").unwrap();
2409
2410        let (_, original) = sw.into_streamed_data().unwrap();
2411        let cloned = original.try_clone().unwrap();
2412
2413        // Verify metadata is cloned.
2414        assert_eq!(cloned.data_len, original.data_len);
2415        assert_eq!(cloned.cols_xml, original.cols_xml);
2416        assert_eq!(cloned.sheet_views_xml, original.sheet_views_xml);
2417        assert_eq!(cloned.merge_cells_xml, original.merge_cells_xml);
2418
2419        // Verify temp file contents are identical but independent.
2420        assert_ne!(original.temp_file.path(), cloned.temp_file.path());
2421        let orig_bytes = std::fs::read(original.temp_file.path()).unwrap();
2422        let clone_bytes = std::fs::read(cloned.temp_file.path()).unwrap();
2423        assert_eq!(orig_bytes, clone_bytes);
2424        assert!(!orig_bytes.is_empty());
2425    }
2426
2427    #[test]
2428    fn test_date_value() {
2429        let mut sw = StreamWriter::new("Sheet1");
2430        // Excel serial number for 2024-01-15 = 45306
2431        sw.write_row(1, &[CellValue::Date(45306.0)]).unwrap();
2432        let xml = finish_and_get_xml(sw);
2433
2434        assert!(xml.contains("t=\"d\""));
2435        assert!(xml.contains("<v>2024-01-15T00:00:00</v>"));
2436    }
2437
2438    #[test]
2439    fn test_date_value_with_time() {
2440        let mut sw = StreamWriter::new("Sheet1");
2441        // Excel serial with fractional time (noon)
2442        sw.write_row(1, &[CellValue::Date(45306.5)]).unwrap();
2443        let xml = finish_and_get_xml(sw);
2444
2445        assert!(xml.contains("<v>2024-01-15T12:00:00</v>"));
2446    }
2447
2448    #[test]
2449    fn test_rich_string_to_inline_plain_text() {
2450        use crate::rich_text::RichTextRun;
2451        let mut sw = StreamWriter::new("Sheet1");
2452        sw.write_row(
2453            1,
2454            &[CellValue::RichString(vec![
2455                RichTextRun {
2456                    text: "Hello ".to_string(),
2457                    font: None,
2458                    size: None,
2459                    bold: true,
2460                    italic: false,
2461                    color: None,
2462                },
2463                RichTextRun {
2464                    text: "World".to_string(),
2465                    font: None,
2466                    size: None,
2467                    bold: false,
2468                    italic: true,
2469                    color: None,
2470                },
2471            ])],
2472        )
2473        .unwrap();
2474        let xml = finish_and_get_xml(sw);
2475
2476        // RichString is flattened to plain inline string
2477        assert!(xml.contains("t=\"inlineStr\""));
2478        assert!(xml.contains("<is><t>Hello World</t></is>"));
2479    }
2480
2481    #[test]
2482    fn test_rich_string_xml_escaping() {
2483        use crate::rich_text::RichTextRun;
2484        let mut sw = StreamWriter::new("Sheet1");
2485        sw.write_row(
2486            1,
2487            &[CellValue::RichString(vec![RichTextRun {
2488                text: "A & B <C>".to_string(),
2489                font: None,
2490                size: None,
2491                bold: false,
2492                italic: false,
2493                color: None,
2494            }])],
2495        )
2496        .unwrap();
2497        let xml = finish_and_get_xml(sw);
2498
2499        assert!(xml.contains("A &amp; B &lt;C&gt;"));
2500    }
2501
2502    #[test]
2503    fn test_formula_with_numeric_result() {
2504        let mut sw = StreamWriter::new("Sheet1");
2505        sw.write_row(
2506            1,
2507            &[CellValue::Formula {
2508                expr: "SUM(A2:A10)".to_string(),
2509                result: Some(Box::new(CellValue::Number(55.0))),
2510            }],
2511        )
2512        .unwrap();
2513        let xml = finish_and_get_xml(sw);
2514
2515        assert!(xml.contains("<f>SUM(A2:A10)</f>"));
2516        assert!(xml.contains("<v>55</v>"));
2517        // Numeric results should not have a t attribute (default is numeric)
2518        assert!(!xml.contains("t=\"str\""));
2519        assert!(!xml.contains("t=\"b\""));
2520        assert!(!xml.contains("t=\"e\""));
2521    }
2522
2523    #[test]
2524    fn test_formula_with_error_result() {
2525        let mut sw = StreamWriter::new("Sheet1");
2526        sw.write_row(
2527            1,
2528            &[CellValue::Formula {
2529                expr: "1/0".to_string(),
2530                result: Some(Box::new(CellValue::Error("#DIV/0!".to_string()))),
2531            }],
2532        )
2533        .unwrap();
2534        let xml = finish_and_get_xml(sw);
2535
2536        assert!(xml.contains("t=\"e\""));
2537        assert!(xml.contains("<f>1/0</f>"));
2538        assert!(xml.contains("<v>#DIV/0!</v>"));
2539    }
2540
2541    #[test]
2542    fn test_formula_with_string_result() {
2543        let mut sw = StreamWriter::new("Sheet1");
2544        sw.write_row(
2545            1,
2546            &[CellValue::Formula {
2547                expr: "IF(A1>0,\"yes\",\"no\")".to_string(),
2548                result: Some(Box::new(CellValue::String("yes".to_string()))),
2549            }],
2550        )
2551        .unwrap();
2552        let xml = finish_and_get_xml(sw);
2553
2554        assert!(xml.contains("t=\"str\""));
2555        assert!(xml.contains("<f>"));
2556        assert!(xml.contains("<v>yes</v>"));
2557    }
2558
2559    #[test]
2560    fn test_formula_with_bool_result() {
2561        let mut sw = StreamWriter::new("Sheet1");
2562        sw.write_row(
2563            1,
2564            &[CellValue::Formula {
2565                expr: "A1>0".to_string(),
2566                result: Some(Box::new(CellValue::Bool(true))),
2567            }],
2568        )
2569        .unwrap();
2570        let xml = finish_and_get_xml(sw);
2571
2572        assert!(xml.contains("t=\"b\""));
2573        assert!(xml.contains("<f>A1&gt;0</f>"));
2574        assert!(xml.contains("<v>1</v>"));
2575    }
2576
2577    #[test]
2578    fn test_formula_without_result() {
2579        let mut sw = StreamWriter::new("Sheet1");
2580        sw.write_row(
2581            1,
2582            &[CellValue::Formula {
2583                expr: "A1+B1".to_string(),
2584                result: None,
2585            }],
2586        )
2587        .unwrap();
2588        let xml = finish_and_get_xml(sw);
2589
2590        assert!(xml.contains("<f>A1+B1</f></c>"));
2591        // No <v> tag when result is None
2592        assert!(!xml.contains("<v>"));
2593    }
2594
2595    #[test]
2596    fn test_error_value_xml_escaping() {
2597        let mut sw = StreamWriter::new("Sheet1");
2598        sw.write_row(1, &[CellValue::Error("#VALUE!".to_string())])
2599            .unwrap();
2600        let xml = finish_and_get_xml(sw);
2601
2602        assert!(xml.contains("t=\"e\""));
2603        assert!(xml.contains("#VALUE!"));
2604    }
2605
2606    #[test]
2607    fn test_empty_row_produces_valid_xml() {
2608        let mut sw = StreamWriter::new("Sheet1");
2609        // Row with only empty values
2610        sw.write_row(1, &[CellValue::Empty, CellValue::Empty])
2611            .unwrap();
2612        let ws = finish_and_parse(sw);
2613
2614        assert_eq!(ws.sheet_data.rows.len(), 1);
2615        assert_eq!(ws.sheet_data.rows[0].r, 1);
2616        // All empties are skipped, row has no cells
2617        assert_eq!(ws.sheet_data.rows[0].cells.len(), 0);
2618    }
2619
2620    #[test]
2621    fn test_memory_efficiency() {
2622        // This test validates that large data doesn't accumulate in memory.
2623        // The StreamWriter writes to a temp file, so memory should remain
2624        // roughly constant regardless of row count.
2625        let mut sw = StreamWriter::new("Sheet1");
2626        for i in 1..=100_000u32 {
2627            sw.write_row(
2628                i,
2629                &[
2630                    CellValue::from(format!("Row number {}", i)),
2631                    CellValue::from(i as f64),
2632                ],
2633            )
2634            .unwrap();
2635        }
2636        // Verify substantial data was written to disk, not held in memory.
2637        assert!(sw.bytes_written > 1_000_000);
2638
2639        let (_, streamed) = sw.into_streamed_data().unwrap();
2640        assert!(streamed.data_len > 1_000_000);
2641    }
2642
2643    #[test]
2644    fn test_write_rows_basic() {
2645        let mut sw = StreamWriter::new("Sheet1");
2646        sw.write_rows(
2647            1,
2648            &[
2649                vec![CellValue::from("A"), CellValue::from(1)],
2650                vec![CellValue::from("B"), CellValue::from(2)],
2651                vec![CellValue::from("C"), CellValue::from(3)],
2652            ],
2653        )
2654        .unwrap();
2655        let ws = finish_and_parse(sw);
2656
2657        assert_eq!(ws.sheet_data.rows.len(), 3);
2658        assert_eq!(ws.sheet_data.rows[0].r, 1);
2659        assert_eq!(ws.sheet_data.rows[1].r, 2);
2660        assert_eq!(ws.sheet_data.rows[2].r, 3);
2661        assert_eq!(ws.sheet_data.rows[0].cells.len(), 2);
2662        assert_eq!(ws.sheet_data.rows[0].cells[0].r, "A1");
2663        assert_eq!(ws.sheet_data.rows[2].cells[0].r, "A3");
2664    }
2665
2666    #[test]
2667    fn test_write_rows_empty() {
2668        let mut sw = StreamWriter::new("Sheet1");
2669        sw.write_rows(1, &[]).unwrap();
2670        let ws = finish_and_parse(sw);
2671
2672        assert!(ws.sheet_data.rows.is_empty());
2673    }
2674
2675    #[test]
2676    fn test_write_rows_mixed_with_single() {
2677        let mut sw = StreamWriter::new("Sheet1");
2678        sw.write_row(1, &[CellValue::from("first")]).unwrap();
2679        sw.write_rows(
2680            2,
2681            &[
2682                vec![CellValue::from("second")],
2683                vec![CellValue::from("third")],
2684                vec![CellValue::from("fourth")],
2685            ],
2686        )
2687        .unwrap();
2688        let ws = finish_and_parse(sw);
2689
2690        assert_eq!(ws.sheet_data.rows.len(), 4);
2691        assert_eq!(ws.sheet_data.rows[0].r, 1);
2692        assert_eq!(ws.sheet_data.rows[1].r, 2);
2693        assert_eq!(ws.sheet_data.rows[2].r, 3);
2694        assert_eq!(ws.sheet_data.rows[3].r, 4);
2695    }
2696
2697    #[test]
2698    fn test_write_rows_overflow() {
2699        let mut sw = StreamWriter::new("Sheet1");
2700        sw.write_row(1, &[CellValue::from("ok")]).unwrap();
2701        let result = sw.write_rows(
2702            u32::MAX - 1,
2703            &[
2704                vec![CellValue::from("a")],
2705                vec![CellValue::from("b")],
2706                vec![CellValue::from("c")],
2707            ],
2708        );
2709        assert!(result.is_err());
2710    }
2711
2712    #[test]
2713    fn test_write_rows_backward_error() {
2714        let mut sw = StreamWriter::new("Sheet1");
2715        sw.write_row(5, &[CellValue::from("row5")]).unwrap();
2716        let result = sw.write_rows(3, &[vec![CellValue::from("a")], vec![CellValue::from("b")]]);
2717        assert!(result.is_err());
2718        assert!(matches!(
2719            result.unwrap_err(),
2720            Error::StreamRowAlreadyWritten { row: 3 }
2721        ));
2722    }
2723
2724    #[test]
2725    fn test_rejects_non_finite_values_without_advancing_stream_state() {
2726        let mut sw = StreamWriter::new("Sheet1");
2727        let error = sw.write_row(1, &[CellValue::Number(f64::NAN)]).unwrap_err();
2728        assert!(matches!(error, Error::StreamNonFiniteValue));
2729        assert_eq!(sw.last_row, 0);
2730        assert_eq!(sw.bytes_written, 0);
2731
2732        let error = sw
2733            .write_row(
2734                1,
2735                &[CellValue::Formula {
2736                    expr: "1/0".to_string(),
2737                    result: Some(Box::new(CellValue::Date(f64::INFINITY))),
2738                }],
2739            )
2740            .unwrap_err();
2741        assert!(matches!(error, Error::StreamNonFiniteValue));
2742        assert_eq!(sw.last_row, 0);
2743    }
2744
2745    #[test]
2746    fn test_sanitizes_illegal_xml_controls_and_preserves_whitespace() {
2747        let mut sw = StreamWriter::new("Sheet1");
2748        sw.write_row(
2749            1,
2750            &[
2751                CellValue::String("a\u{0001}b\t\n\rc".to_string()),
2752                CellValue::Formula {
2753                    expr: "A1&\"\u{0002}x\"".to_string(),
2754                    result: Some(Box::new(CellValue::String("r\u{0003}s".to_string()))),
2755                },
2756            ],
2757        )
2758        .unwrap();
2759        let xml = finish_and_get_xml(sw);
2760        assert!(!xml.contains('\u{0001}'));
2761        assert!(!xml.contains('\u{0002}'));
2762        assert!(!xml.contains('\u{0003}'));
2763        assert!(xml.contains("a b\t\n\rc") || xml.contains("ab\t\n\rc"));
2764        let parsed: WorksheetXml = quick_xml::de::from_str(&xml).unwrap();
2765        assert_eq!(parsed.sheet_data.rows.len(), 1);
2766    }
2767
2768    #[test]
2769    fn stream_limits_accept_exact_row_xml_and_reject_plus_one_without_output() {
2770        let value = CellValue::String("<&payload>".repeat(64));
2771        let mut probe = StreamWriter::new("Probe");
2772        probe.write_row(1, std::slice::from_ref(&value)).unwrap();
2773        let exact = probe.bytes_written;
2774
2775        let exact_limits = crate::save::StreamLimits {
2776            row_xml_bytes: exact,
2777            output_bytes: exact,
2778            ..crate::save::StreamLimits::default()
2779        };
2780        let mut accepted = StreamWriter::new_with_limits("Accepted", exact_limits).unwrap();
2781        accepted.write_row(1, std::slice::from_ref(&value)).unwrap();
2782        assert_eq!(accepted.bytes_written, exact);
2783
2784        let rejected_limits = crate::save::StreamLimits {
2785            row_xml_bytes: exact - 1,
2786            output_bytes: exact,
2787            ..crate::save::StreamLimits::default()
2788        };
2789        let mut rejected = StreamWriter::new_with_limits("Rejected", rejected_limits).unwrap();
2790        let error = rejected.write_row(1, &[value]).unwrap_err();
2791        let metadata = error.resource_metadata().unwrap();
2792        assert_eq!(
2793            metadata.operation(),
2794            crate::resource::ResourceOperation::StreamWrite
2795        );
2796        assert_eq!(
2797            metadata.dimension(),
2798            crate::resource::ResourceDimension::XmlBytes
2799        );
2800        assert_eq!(metadata.limit(), exact - 1);
2801        assert_eq!(metadata.observed(), exact);
2802        assert_eq!(rejected.bytes_written, 0);
2803        assert_eq!(rejected.last_row, 0);
2804        assert!(rejected.writer.is_none());
2805    }
2806
2807    #[test]
2808    fn stream_limits_reject_huge_string_formula_and_rich_text_before_output() {
2809        let limits = crate::save::StreamLimits {
2810            row_xml_bytes: 1024,
2811            output_bytes: 4096,
2812            ..crate::save::StreamLimits::default()
2813        };
2814        let cases = [
2815            CellValue::String("s".repeat(4096)),
2816            CellValue::Formula {
2817                expr: "A".repeat(4096),
2818                result: None,
2819            },
2820            CellValue::RichString(vec![crate::rich_text::RichTextRun {
2821                text: "r".repeat(4096),
2822                font: None,
2823                size: None,
2824                bold: false,
2825                italic: false,
2826                color: None,
2827            }]),
2828        ];
2829
2830        for value in cases {
2831            let mut writer = StreamWriter::new_with_limits("Rejected", limits).unwrap();
2832            assert!(matches!(
2833                writer.write_row(1, &[value]),
2834                Err(Error::ResourceLimitExceeded(_))
2835            ));
2836            assert_eq!(writer.bytes_written, 0);
2837            assert_eq!(writer.last_row, 0);
2838            assert!(writer.writer.is_none());
2839        }
2840    }
2841
2842    #[test]
2843    fn stream_batch_policy_failure_is_atomic_and_counts_rows_and_cells() {
2844        let mut probe = StreamWriter::new("Probe");
2845        probe
2846            .write_rows(
2847                1,
2848                &[
2849                    vec![CellValue::String("one".to_string())],
2850                    vec![CellValue::String("two".to_string())],
2851                ],
2852            )
2853            .unwrap();
2854        let exact_bytes = probe.bytes_written;
2855
2856        let limits = crate::save::StreamLimits {
2857            row_count: 2,
2858            cell_count: 2,
2859            output_bytes: exact_bytes,
2860            ..crate::save::StreamLimits::default()
2861        };
2862        let mut accepted = StreamWriter::new_with_limits("Accepted", limits).unwrap();
2863        accepted
2864            .write_rows(
2865                1,
2866                &[
2867                    vec![CellValue::String("one".to_string())],
2868                    vec![CellValue::String("two".to_string())],
2869                ],
2870            )
2871            .unwrap();
2872
2873        for exceeded in [
2874            crate::save::StreamLimits {
2875                row_count: 1,
2876                ..limits
2877            },
2878            crate::save::StreamLimits {
2879                cell_count: 1,
2880                ..limits
2881            },
2882            crate::save::StreamLimits {
2883                output_bytes: exact_bytes - 1,
2884                ..limits
2885            },
2886        ] {
2887            let mut rejected = StreamWriter::new_with_limits("Rejected", exceeded).unwrap();
2888            let error = rejected
2889                .write_rows(
2890                    1,
2891                    &[
2892                        vec![CellValue::String("one".to_string())],
2893                        vec![CellValue::String("two".to_string())],
2894                    ],
2895                )
2896                .unwrap_err();
2897            assert!(matches!(error, Error::ResourceLimitExceeded(_)));
2898            assert_eq!(rejected.bytes_written, 0);
2899            assert_eq!(rejected.last_row, 0);
2900            assert!(rejected.writer.is_none());
2901        }
2902    }
2903
2904    #[test]
2905    fn stream_formula_budget_enforces_per_formula_and_cumulative_input_before_output() {
2906        let mut oversized = StreamWriter::new("Oversized");
2907        let error = oversized
2908            .write_row(
2909                1,
2910                &[CellValue::Formula {
2911                    expr: "A".repeat(32_769),
2912                    result: None,
2913                }],
2914            )
2915            .unwrap_err();
2916        let metadata = error.resource_metadata().unwrap();
2917        assert_eq!(
2918            metadata.operation(),
2919            crate::resource::ResourceOperation::FormulaMutate
2920        );
2921        assert_eq!(
2922            metadata.dimension(),
2923            crate::resource::ResourceDimension::InputBytes
2924        );
2925        assert_eq!(oversized.bytes_written, 0);
2926        assert!(oversized.writer.is_none());
2927
2928        let formula = || CellValue::Formula {
2929            expr: "A".repeat(32_768),
2930            result: None,
2931        };
2932        let exact = (0..128).map(|_| formula()).collect::<Vec<_>>();
2933        let mut accepted = StreamWriter::new("Exact");
2934        accepted.write_row(1, &exact).unwrap();
2935
2936        let plus_one = (0..129).map(|_| formula()).collect::<Vec<_>>();
2937        let mut rejected = StreamWriter::new("PlusOne");
2938        let error = rejected.write_row(1, &plus_one).unwrap_err();
2939        let metadata = error.resource_metadata().unwrap();
2940        assert_eq!(
2941            metadata.dimension(),
2942            crate::resource::ResourceDimension::InputBytes
2943        );
2944        assert_eq!(metadata.limit(), 4 * 1024 * 1024);
2945        assert!(metadata.observed() > metadata.limit());
2946        assert_eq!(rejected.bytes_written, 0);
2947        assert!(rejected.writer.is_none());
2948    }
2949
2950    #[test]
2951    fn stream_policy_rejection_does_not_consume_formula_budget() {
2952        let limits = crate::save::StreamLimits {
2953            cell_count: 1,
2954            ..crate::save::StreamLimits::default()
2955        };
2956        let formula = || CellValue::Formula {
2957            expr: "A".repeat(32_768),
2958            result: None,
2959        };
2960        let rejected_values = (0..128).map(|_| formula()).collect::<Vec<_>>();
2961        let mut writer = StreamWriter::new_with_limits("Retry", limits).unwrap();
2962
2963        let error = writer.write_row(1, &rejected_values).unwrap_err();
2964        let metadata = error.resource_metadata().unwrap();
2965        assert_eq!(metadata.dimension(), ResourceDimension::CellCount);
2966        assert_eq!(writer.bytes_written, 0);
2967        assert_eq!(writer.last_row, 0);
2968        assert!(writer.writer.is_none());
2969
2970        writer
2971            .write_row(
2972                1,
2973                &[CellValue::Formula {
2974                    expr: "1".to_string(),
2975                    result: None,
2976                }],
2977            )
2978            .unwrap();
2979    }
2980
2981    #[test]
2982    fn stream_config_limits_are_atomic_and_deduplicate_updates() {
2983        let limits = crate::save::StreamLimits {
2984            config_count: 1,
2985            config_bytes: std::mem::size_of::<(u32, u32, f64)>() as u64,
2986            ..crate::save::StreamLimits::default()
2987        };
2988        let mut writer = StreamWriter::new_with_limits("Config", limits).unwrap();
2989        writer.set_col_width_range(1, 2, 10.0).unwrap();
2990        writer.set_col_width_range(1, 2, 20.0).unwrap();
2991        assert_eq!(writer.config_count, 1);
2992
2993        let error = writer.add_merge_cell("A1:B1").unwrap_err();
2994        let metadata = error.resource_metadata().unwrap();
2995        assert_eq!(metadata.dimension(), ResourceDimension::CollectionCount);
2996        assert_eq!(metadata.stage(), Some(ResourceStage::Validate));
2997        assert_eq!(writer.config_count, 1);
2998        assert_eq!(
2999            writer.config_bytes,
3000            std::mem::size_of::<(u32, u32, f64)>() as u64
3001        );
3002
3003        let mut retained = StreamWriter::new_with_limits(
3004            "Retained",
3005            crate::save::StreamLimits {
3006                config_bytes: 1,
3007                ..crate::save::StreamLimits::default()
3008            },
3009        )
3010        .unwrap();
3011        let error = retained.set_col_width(1, 10.0).unwrap_err();
3012        assert_eq!(
3013            error.resource_metadata().unwrap().dimension(),
3014            ResourceDimension::RetainedBytes
3015        );
3016        assert_eq!(retained.config_count, 0);
3017        assert_eq!(retained.config_bytes, 0);
3018        assert!(retained.col_widths.is_empty());
3019    }
3020
3021    #[test]
3022    fn stream_cached_formula_results_reject_nested_and_unserializable_values_without_recursion() {
3023        let mut nested = CellValue::String("cached".to_string());
3024        for _ in 0..20_000 {
3025            nested = CellValue::Formula {
3026                expr: "A1".to_string(),
3027                result: Some(Box::new(nested)),
3028            };
3029        }
3030        let values = vec![CellValue::Formula {
3031            expr: "A1".to_string(),
3032            result: Some(Box::new(nested)),
3033        }];
3034        let mut writer = StreamWriter::new("Nested");
3035        let error = writer.write_row(1, &values).unwrap_err();
3036        assert_eq!(
3037            error.resource_metadata().unwrap().category(),
3038            ResourceCategory::Structure
3039        );
3040        assert!(writer.writer.is_none());
3041        std::mem::forget(values);
3042
3043        let mut rich = StreamWriter::new("Rich");
3044        let error = rich
3045            .write_row(
3046                1,
3047                &[CellValue::Formula {
3048                    expr: "A1".to_string(),
3049                    result: Some(Box::new(CellValue::RichString(vec![]))),
3050                }],
3051            )
3052            .unwrap_err();
3053        assert_eq!(
3054            error.resource_metadata().unwrap().category(),
3055            ResourceCategory::Structure
3056        );
3057        assert!(rich.writer.is_none());
3058    }
3059
3060    #[test]
3061    fn partial_stream_output_failure_poison_prevents_retry_and_publication() {
3062        let mut writer = StreamWriter::new("Poisoned");
3063        writer.write_failure_after_bytes = Some(5);
3064        let error = writer
3065            .write_row(1, &[CellValue::String("payload".to_string())])
3066            .unwrap_err();
3067        assert!(matches!(error, Error::Io(_)));
3068        assert!(writer.failed);
3069        let path = writer
3070            .writer
3071            .as_ref()
3072            .unwrap()
3073            .get_ref()
3074            .path()
3075            .to_path_buf();
3076        assert!(path.exists());
3077        assert!(writer
3078            .write_row(1, &[CellValue::String("retry".to_string())])
3079            .is_err());
3080        assert!(writer.into_streamed_data().is_err());
3081        assert!(!path.exists());
3082    }
3083
3084    /// Charges every character of a run separately, as the escape loop did
3085    /// before plain text was pushed in runs.
3086    struct PerCharCounter(RowXmlCounter);
3087
3088    impl RowXmlSink for PerCharCounter {
3089        fn push_str(&mut self, value: &str) {
3090            self.0.charge(value.len());
3091        }
3092
3093        fn push_chars(&mut self, value: &str) {
3094            for ch in value.chars() {
3095                self.0.charge(ch.len_utf8());
3096            }
3097        }
3098    }
3099
3100    #[test]
3101    fn cell_names_match_coordinates_to_cell_name() {
3102        for row in [1, 9, 10, 1_048_576] {
3103            let row_text = row.to_string();
3104            for col in 1..=MAX_COLUMNS {
3105                let mut name = String::new();
3106                push_cell_name(&mut name, col, row, &row_text);
3107                assert_eq!(name, coordinates_to_cell_name(col, row).unwrap());
3108            }
3109        }
3110        let mut fallback = String::new();
3111        push_cell_name(&mut fallback, MAX_COLUMNS + 1, 1, "1");
3112        assert_eq!(fallback, format!("{}:1", MAX_COLUMNS + 1));
3113    }
3114
3115    #[test]
3116    fn rendered_row_limit_matches_per_character_accounting() {
3117        let values = vec![
3118            CellValue::String("ab\u{d55c}c&d\u{1}e\u{1f600}f<g".to_string()),
3119            CellValue::Number(12.5),
3120            CellValue::Formula {
3121                expr: "A1&\"\u{e9}\"".to_string(),
3122                result: Some(Box::new(CellValue::String("x\u{ae00}y".to_string()))),
3123            },
3124        ];
3125        let full = measure_row_xml(7, &values, Some(3), None, u64::MAX).unwrap();
3126        for limit in 1..=full + 2 {
3127            let mut reference = PerCharCounter(RowXmlCounter::new(limit));
3128            write_row_xml(&mut reference, 7, &values, Some(3), None);
3129            let expected = reference.0.finish();
3130
3131            let mut rendered = String::new();
3132            let actual = render_row_xml(&mut rendered, 7, &values, Some(3), None, limit);
3133            let measured = measure_row_xml(7, &values, Some(3), None, limit);
3134            for result in [&actual, &measured] {
3135                match (&expected, result) {
3136                    (Ok(e), Ok(a)) => assert_eq!(e, a),
3137                    (Err(e), Err(a)) => {
3138                        let (e, a) = (
3139                            e.resource_metadata().unwrap(),
3140                            a.resource_metadata().unwrap(),
3141                        );
3142                        assert_eq!(e.observed(), a.observed(), "limit {limit}");
3143                        assert_eq!(e.limit(), a.limit());
3144                    }
3145                    _ => panic!("limit {limit}: outcome differs"),
3146                }
3147            }
3148            if let Ok(size) = actual {
3149                assert_eq!(size, rendered.len() as u64);
3150            }
3151        }
3152    }
3153
3154    #[test]
3155    fn write_row_reuses_one_render_for_limit_and_output() {
3156        let values = vec![CellValue::String("a&b".to_string()), CellValue::Number(1.5)];
3157        let mut expected = String::new();
3158        let size = render_row_xml(&mut expected, 1, &values, None, None, u64::MAX).unwrap();
3159
3160        let limits = crate::save::StreamLimits {
3161            row_xml_bytes: size,
3162            ..crate::save::StreamLimits::default()
3163        };
3164        let mut exact = StreamWriter::new_with_limits("Exact", limits).unwrap();
3165        exact.write_row(1, &values).unwrap();
3166        assert_eq!(exact.bytes_written, size);
3167        let xml = finish_and_get_xml(exact);
3168        assert!(xml.contains(&expected));
3169
3170        let limits = crate::save::StreamLimits {
3171            row_xml_bytes: size - 1,
3172            ..crate::save::StreamLimits::default()
3173        };
3174        let mut rejected = StreamWriter::new_with_limits("Rejected", limits).unwrap();
3175        assert!(rejected.write_row(1, &values).is_err());
3176        assert_eq!(rejected.bytes_written, 0);
3177        assert!(rejected.writer.is_none());
3178    }
3179}