Skip to main content

sheetkit_core/
merge.rs

1//! Merge cell operations.
2//!
3//! Provides functions for merging and unmerging ranges of cells in a worksheet.
4
5use crate::error::{Error, Result};
6use crate::utils::cell_ref::{cell_name_to_coordinates, coordinates_to_cell_name};
7use sheetkit_xml::worksheet::{MergeCell, MergeCells, WorksheetXml};
8
9/// Parse a range reference like "A1:C3" into ((col1, row1), (col2, row2)) coordinates,
10/// both 1-based. Ensures the returned rectangle is normalized so that
11/// (col1, row1) is the top-left and (col2, row2) is the bottom-right.
12fn parse_range(reference: &str) -> Result<(u32, u32, u32, u32)> {
13    let parts: Vec<&str> = reference.split(':').collect();
14    if parts.len() != 2 {
15        return Err(Error::InvalidCellReference(format!(
16            "expected range like 'A1:C3', got '{reference}'"
17        )));
18    }
19    let (c1, r1) = cell_name_to_coordinates(parts[0])?;
20    let (c2, r2) = cell_name_to_coordinates(parts[1])?;
21    let min_col = c1.min(c2);
22    let max_col = c1.max(c2);
23    let min_row = r1.min(r2);
24    let max_row = r1.max(r2);
25    Ok((min_col, min_row, max_col, max_row))
26}
27
28fn canonical_range_reference(range: (u32, u32, u32, u32)) -> Result<String> {
29    let (min_col, min_row, max_col, max_row) = range;
30    Ok(format!(
31        "{}:{}",
32        coordinates_to_cell_name(min_col, min_row)?,
33        coordinates_to_cell_name(max_col, max_row)?
34    ))
35}
36
37/// Check whether two rectangular ranges overlap.
38fn ranges_overlap(a: (u32, u32, u32, u32), b: (u32, u32, u32, u32)) -> bool {
39    let (a_min_col, a_min_row, a_max_col, a_max_row) = a;
40    let (b_min_col, b_min_row, b_max_col, b_max_row) = b;
41    a_min_col <= b_max_col
42        && a_max_col >= b_min_col
43        && a_min_row <= b_max_row
44        && a_max_row >= b_min_row
45}
46
47/// Populate the coordinate cache from the reference strings if it is stale.
48/// This handles worksheets deserialized from XML where the cache starts empty.
49fn ensure_cache(mc: &mut MergeCells) -> Result<()> {
50    if mc.cached_coords.len() == mc.merge_cells.len() {
51        return Ok(());
52    }
53    mc.cached_coords.clear();
54    mc.cached_coords.reserve(mc.merge_cells.len());
55    for entry in &mc.merge_cells {
56        mc.cached_coords.push(parse_range(&entry.reference)?);
57    }
58    Ok(())
59}
60
61/// Merge a range of cells on the given worksheet.
62///
63/// `top_left` and `bottom_right` are cell references like "A1" and "C3".
64/// Returns an error if the new range overlaps with any existing merge region.
65pub fn merge_cells(ws: &mut WorksheetXml, top_left: &str, bottom_right: &str) -> Result<()> {
66    let (tl_col, tl_row) = cell_name_to_coordinates(top_left)?;
67    let (br_col, br_row) = cell_name_to_coordinates(bottom_right)?;
68
69    let min_col = tl_col.min(br_col);
70    let max_col = tl_col.max(br_col);
71    let min_row = tl_row.min(br_row);
72    let max_row = tl_row.max(br_row);
73    let new_range = (min_col, min_row, max_col, max_row);
74
75    let reference = canonical_range_reference(new_range)?;
76
77    // Check for overlaps using cached coordinates (no string parsing per check).
78    if let Some(ref mut mc) = ws.merge_cells {
79        ensure_cache(mc)?;
80        for (i, coords) in mc.cached_coords.iter().enumerate() {
81            if ranges_overlap(new_range, *coords) {
82                return Err(Error::MergeCellOverlap {
83                    new: reference,
84                    existing: mc.merge_cells[i].reference.clone(),
85                });
86            }
87        }
88    }
89
90    // Add the merge cell entry and its cached coordinates.
91    let merge_cells = ws.merge_cells.get_or_insert_with(|| MergeCells {
92        count: None,
93        merge_cells: Vec::new(),
94        cached_coords: Vec::new(),
95    });
96    merge_cells.merge_cells.push(MergeCell { reference });
97    merge_cells.cached_coords.push(new_range);
98    merge_cells.count = Some(merge_cells.merge_cells.len() as u32);
99
100    Ok(())
101}
102
103/// Remove a specific merge cell range from the worksheet.
104///
105/// `reference` is the exact range string like "A1:C3" that was previously merged.
106/// Returns an error if the range is not found.
107pub fn unmerge_cell(ws: &mut WorksheetXml, reference: &str) -> Result<()> {
108    let mc = ws
109        .merge_cells
110        .as_mut()
111        .ok_or_else(|| Error::MergeCellNotFound(reference.to_string()))?;
112
113    ensure_cache(mc)?;
114    let requested_range = parse_range(reference)?;
115    let pos = mc
116        .cached_coords
117        .iter()
118        .position(|coords| *coords == requested_range);
119
120    match pos {
121        Some(idx) => {
122            mc.merge_cells.remove(idx);
123            if mc.cached_coords.len() > idx {
124                mc.cached_coords.remove(idx);
125            }
126        }
127        None => return Err(Error::MergeCellNotFound(reference.to_string())),
128    }
129
130    if mc.merge_cells.is_empty() {
131        ws.merge_cells = None;
132    } else {
133        mc.count = Some(mc.merge_cells.len() as u32);
134    }
135
136    Ok(())
137}
138
139/// Get all merge cell references in the worksheet.
140///
141/// Returns a list of range strings like `["A1:B2", "D1:F3"]`.
142pub fn get_merge_cells(ws: &WorksheetXml) -> Vec<String> {
143    ws.merge_cells
144        .as_ref()
145        .map(|mc| mc.merge_cells.iter().map(|m| m.reference.clone()).collect())
146        .unwrap_or_default()
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152
153    fn new_ws() -> WorksheetXml {
154        WorksheetXml::default()
155    }
156
157    #[test]
158    fn test_merge_cells_basic() {
159        let mut ws = new_ws();
160        merge_cells(&mut ws, "A1", "B2").unwrap();
161        let merged = get_merge_cells(&ws);
162        assert_eq!(merged, vec!["A1:B2"]);
163        assert_eq!(ws.merge_cells.as_ref().unwrap().count, Some(1));
164    }
165
166    #[test]
167    fn test_merge_cells_normalizes_reversed_and_lowercase_references() {
168        let mut ws = new_ws();
169        merge_cells(&mut ws, "c3", "a1").unwrap();
170        assert_eq!(get_merge_cells(&ws), vec!["A1:C3"]);
171
172        unmerge_cell(&mut ws, "c3:a1").unwrap();
173        assert!(get_merge_cells(&ws).is_empty());
174    }
175
176    #[test]
177    fn test_merge_cells_multiple() {
178        let mut ws = new_ws();
179        merge_cells(&mut ws, "A1", "B2").unwrap();
180        merge_cells(&mut ws, "D1", "F3").unwrap();
181        merge_cells(&mut ws, "A5", "C7").unwrap();
182        let merged = get_merge_cells(&ws);
183        assert_eq!(merged.len(), 3);
184        assert_eq!(merged[0], "A1:B2");
185        assert_eq!(merged[1], "D1:F3");
186        assert_eq!(merged[2], "A5:C7");
187        assert_eq!(ws.merge_cells.as_ref().unwrap().count, Some(3));
188    }
189
190    #[test]
191    fn test_merge_cells_overlap_detection() {
192        let mut ws = new_ws();
193        merge_cells(&mut ws, "A1", "C3").unwrap();
194
195        // Exact overlap.
196        let err = merge_cells(&mut ws, "A1", "C3").unwrap_err();
197        assert!(err.to_string().contains("overlaps"));
198
199        // Partial overlap -- B2:D4 overlaps with A1:C3.
200        let err = merge_cells(&mut ws, "B2", "D4").unwrap_err();
201        assert!(err.to_string().contains("overlaps"));
202
203        // Fully contained -- B2:B2 is inside A1:C3.
204        let err = merge_cells(&mut ws, "B2", "B2").unwrap_err();
205        assert!(err.to_string().contains("overlaps"));
206
207        // Non-overlapping should succeed.
208        merge_cells(&mut ws, "D1", "F3").unwrap();
209    }
210
211    #[test]
212    fn test_merge_cells_overlap_adjacent_no_overlap() {
213        let mut ws = new_ws();
214        merge_cells(&mut ws, "A1", "B2").unwrap();
215        // C1:D2 is adjacent but does not overlap with A1:B2.
216        merge_cells(&mut ws, "C1", "D2").unwrap();
217        // A3:B4 is below and does not overlap.
218        merge_cells(&mut ws, "A3", "B4").unwrap();
219        assert_eq!(get_merge_cells(&ws).len(), 3);
220    }
221
222    #[test]
223    fn test_unmerge_cell() {
224        let mut ws = new_ws();
225        merge_cells(&mut ws, "A1", "B2").unwrap();
226        merge_cells(&mut ws, "D1", "F3").unwrap();
227
228        unmerge_cell(&mut ws, "A1:B2").unwrap();
229        let merged = get_merge_cells(&ws);
230        assert_eq!(merged, vec!["D1:F3"]);
231        assert_eq!(ws.merge_cells.as_ref().unwrap().count, Some(1));
232    }
233
234    #[test]
235    fn test_unmerge_cell_last_removes_element() {
236        let mut ws = new_ws();
237        merge_cells(&mut ws, "A1", "B2").unwrap();
238        unmerge_cell(&mut ws, "A1:B2").unwrap();
239        assert!(ws.merge_cells.is_none());
240        assert!(get_merge_cells(&ws).is_empty());
241    }
242
243    #[test]
244    fn test_unmerge_cell_not_found() {
245        let mut ws = new_ws();
246        let err = unmerge_cell(&mut ws, "A1:B2").unwrap_err();
247        assert!(err.to_string().contains("not found"));
248
249        // Add one range, then try to unmerge a different range.
250        merge_cells(&mut ws, "A1", "B2").unwrap();
251        let err = unmerge_cell(&mut ws, "C1:D2").unwrap_err();
252        assert!(err.to_string().contains("not found"));
253    }
254
255    #[test]
256    fn test_get_merge_cells_empty() {
257        let ws = new_ws();
258        assert!(get_merge_cells(&ws).is_empty());
259    }
260
261    #[test]
262    fn test_merge_cells_invalid_reference() {
263        let mut ws = new_ws();
264        let err = merge_cells(&mut ws, "!!!", "B2").unwrap_err();
265        assert!(err.to_string().contains("invalid cell reference"));
266
267        let err = merge_cells(&mut ws, "A1", "ZZZ").unwrap_err();
268        assert!(matches!(err, Error::InvalidCellReference(_)));
269    }
270
271    #[test]
272    fn test_parse_range_valid() {
273        let (c1, r1, c2, r2) = parse_range("A1:C3").unwrap();
274        assert_eq!((c1, r1, c2, r2), (1, 1, 3, 3));
275    }
276
277    #[test]
278    fn test_parse_range_reversed() {
279        // Even if cells are given in reversed order, we normalize.
280        let (c1, r1, c2, r2) = parse_range("C3:A1").unwrap();
281        assert_eq!((c1, r1, c2, r2), (1, 1, 3, 3));
282    }
283
284    #[test]
285    fn test_parse_range_invalid() {
286        assert!(parse_range("A1").is_err());
287        assert!(parse_range("A1:B2:C3").is_err());
288        assert!(parse_range("").is_err());
289    }
290
291    #[test]
292    fn test_ranges_overlap_function() {
293        // Overlapping rectangles.
294        assert!(ranges_overlap((1, 1, 3, 3), (2, 2, 4, 4)));
295        // Identical.
296        assert!(ranges_overlap((1, 1, 3, 3), (1, 1, 3, 3)));
297        // Contained.
298        assert!(ranges_overlap((1, 1, 5, 5), (2, 2, 3, 3)));
299        // Adjacent horizontally -- no overlap.
300        assert!(!ranges_overlap((1, 1, 2, 2), (3, 1, 4, 2)));
301        // Adjacent vertically -- no overlap.
302        assert!(!ranges_overlap((1, 1, 2, 2), (1, 3, 2, 4)));
303        // Completely disjoint.
304        assert!(!ranges_overlap((1, 1, 2, 2), (5, 5, 6, 6)));
305    }
306
307    #[test]
308    fn test_merge_cache_stays_in_sync_after_add_and_remove() {
309        let mut ws = new_ws();
310        merge_cells(&mut ws, "A1", "B2").unwrap();
311        merge_cells(&mut ws, "D1", "F3").unwrap();
312        merge_cells(&mut ws, "A5", "C7").unwrap();
313
314        let mc = ws.merge_cells.as_ref().unwrap();
315        assert_eq!(mc.cached_coords.len(), 3);
316        assert_eq!(mc.cached_coords[0], (1, 1, 2, 2));
317        assert_eq!(mc.cached_coords[1], (4, 1, 6, 3));
318        assert_eq!(mc.cached_coords[2], (1, 5, 3, 7));
319
320        unmerge_cell(&mut ws, "D1:F3").unwrap();
321        let mc = ws.merge_cells.as_ref().unwrap();
322        assert_eq!(mc.cached_coords.len(), 2);
323        assert_eq!(mc.cached_coords[0], (1, 1, 2, 2));
324        assert_eq!(mc.cached_coords[1], (1, 5, 3, 7));
325    }
326
327    #[test]
328    fn test_merge_cache_lazy_init_from_deserialized_data() {
329        let mut ws = new_ws();
330        // Simulate a worksheet loaded from XML (cache is empty but merge_cells has entries).
331        ws.merge_cells = Some(MergeCells {
332            count: Some(2),
333            merge_cells: vec![
334                MergeCell {
335                    reference: "A1:B2".to_string(),
336                },
337                MergeCell {
338                    reference: "D5:F8".to_string(),
339                },
340            ],
341            cached_coords: Vec::new(),
342        });
343
344        // Adding a non-overlapping merge should succeed after lazy cache init.
345        merge_cells(&mut ws, "H1", "J3").unwrap();
346        let mc = ws.merge_cells.as_ref().unwrap();
347        assert_eq!(mc.merge_cells.len(), 3);
348        assert_eq!(mc.cached_coords.len(), 3);
349
350        // Adding an overlapping merge should still be detected.
351        let err = merge_cells(&mut ws, "A1", "A1").unwrap_err();
352        assert!(err.to_string().contains("overlaps"));
353    }
354
355    #[test]
356    fn test_merge_many_non_overlapping_regions() {
357        let mut ws = new_ws();
358        // Add 500 non-overlapping single-row merges across different rows.
359        for i in 0..500u32 {
360            let row = i + 1;
361            let top_left = format!("A{row}");
362            let bottom_right = format!("C{row}");
363            merge_cells(&mut ws, &top_left, &bottom_right).unwrap();
364        }
365        assert_eq!(get_merge_cells(&ws).len(), 500);
366        let mc = ws.merge_cells.as_ref().unwrap();
367        assert_eq!(mc.cached_coords.len(), 500);
368        assert_eq!(mc.count, Some(500));
369    }
370
371    #[test]
372    fn test_unmerge_then_add_reuses_cache_correctly() {
373        let mut ws = new_ws();
374        merge_cells(&mut ws, "A1", "B2").unwrap();
375        merge_cells(&mut ws, "D1", "E2").unwrap();
376        unmerge_cell(&mut ws, "A1:B2").unwrap();
377
378        // Now A1:B2 region is free -- adding it again should succeed.
379        merge_cells(&mut ws, "A1", "B2").unwrap();
380        assert_eq!(get_merge_cells(&ws).len(), 2);
381
382        // But D1:E2 overlap should still be caught.
383        let err = merge_cells(&mut ws, "D1", "D1").unwrap_err();
384        assert!(err.to_string().contains("overlaps"));
385    }
386
387    #[test]
388    fn test_equality_ignores_cache_state() {
389        let with_cache = MergeCells {
390            count: Some(1),
391            merge_cells: vec![MergeCell {
392                reference: "A1:B2".to_string(),
393            }],
394            cached_coords: vec![(1, 1, 2, 2)],
395        };
396        let without_cache = MergeCells {
397            count: Some(1),
398            merge_cells: vec![MergeCell {
399                reference: "A1:B2".to_string(),
400            }],
401            cached_coords: Vec::new(),
402        };
403        assert_eq!(with_cache, without_cache);
404    }
405
406    #[test]
407    fn test_cache_not_serialized() {
408        let mc = MergeCells {
409            count: Some(1),
410            merge_cells: vec![MergeCell {
411                reference: "A1:B2".to_string(),
412            }],
413            cached_coords: vec![(1, 1, 2, 2)],
414        };
415        let xml = quick_xml::se::to_string(&mc).unwrap();
416        assert!(!xml.contains("cached"));
417        assert!(xml.contains("A1:B2"));
418    }
419}