Skip to main content

sheetkit_xml/
shared_strings.rs

1//! Shared Strings XML schema structures.
2//!
3//! Represents `xl/sharedStrings.xml` in the OOXML package.
4
5use serde::{Deserialize, Serialize};
6
7use crate::namespaces;
8
9/// Shared String Table root element (`xl/sharedStrings.xml`).
10#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
11#[serde(rename = "sst")]
12pub struct Sst {
13    #[serde(rename = "@xmlns", default = "crate::default_spreadsheet_ml_ns")]
14    pub xmlns: String,
15
16    /// Total reference count of shared strings in the workbook.
17    #[serde(rename = "@count", skip_serializing_if = "Option::is_none")]
18    pub count: Option<u32>,
19
20    /// Number of unique string entries.
21    #[serde(rename = "@uniqueCount", skip_serializing_if = "Option::is_none")]
22    pub unique_count: Option<u32>,
23
24    /// Shared string items.
25    #[serde(rename = "si", default)]
26    pub items: Vec<Si>,
27}
28
29/// Shared String Item.
30#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
31pub struct Si {
32    /// Plain text content.
33    #[serde(rename = "t", skip_serializing_if = "Option::is_none")]
34    pub t: Option<T>,
35
36    /// Rich text runs (formatted text).
37    #[serde(rename = "r", default)]
38    pub r: Vec<R>,
39}
40
41/// Text element with optional space preservation.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43pub struct T {
44    #[serde(
45        rename = "@xml:space",
46        alias = "@space",
47        skip_serializing_if = "Option::is_none"
48    )]
49    pub xml_space: Option<String>,
50
51    #[serde(rename = "$value", default)]
52    pub value: String,
53}
54
55/// Rich text run.
56#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
57pub struct R {
58    /// Run properties (formatting).
59    #[serde(rename = "rPr", skip_serializing_if = "Option::is_none")]
60    pub r_pr: Option<RPr>,
61
62    /// Text content.
63    #[serde(rename = "t")]
64    pub t: T,
65}
66
67/// Run properties (text formatting within a rich text run).
68#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
69pub struct RPr {
70    #[serde(rename = "rFont", skip_serializing_if = "Option::is_none")]
71    pub r_font: Option<FontName>,
72
73    #[serde(rename = "family", skip_serializing_if = "Option::is_none")]
74    pub family: Option<FontFamily>,
75
76    #[serde(rename = "b", skip_serializing_if = "Option::is_none")]
77    pub b: Option<BoolVal>,
78
79    #[serde(rename = "i", skip_serializing_if = "Option::is_none")]
80    pub i: Option<BoolVal>,
81
82    #[serde(rename = "strike", skip_serializing_if = "Option::is_none")]
83    pub strike: Option<BoolVal>,
84
85    #[serde(rename = "color", skip_serializing_if = "Option::is_none")]
86    pub color: Option<Color>,
87
88    #[serde(rename = "sz", skip_serializing_if = "Option::is_none")]
89    pub sz: Option<FontSize>,
90
91    #[serde(rename = "u", skip_serializing_if = "Option::is_none")]
92    pub u: Option<Underline>,
93
94    #[serde(rename = "vertAlign", skip_serializing_if = "Option::is_none")]
95    pub vert_align: Option<VertAlign>,
96
97    #[serde(rename = "scheme", skip_serializing_if = "Option::is_none")]
98    pub scheme: Option<FontScheme>,
99}
100
101/// Boolean value wrapper.
102#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
103pub struct BoolVal {
104    #[serde(rename = "@val", skip_serializing_if = "Option::is_none")]
105    pub val: Option<bool>,
106}
107
108/// Underline style.
109#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
110pub struct Underline {
111    #[serde(rename = "@val", skip_serializing_if = "Option::is_none")]
112    pub val: Option<String>,
113}
114
115/// Vertical text alignment.
116#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
117pub struct VertAlign {
118    #[serde(rename = "@val")]
119    pub val: String,
120}
121
122/// Font size.
123#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
124pub struct FontSize {
125    #[serde(rename = "@val")]
126    pub val: f64,
127}
128
129/// Color.
130#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
131pub struct Color {
132    #[serde(rename = "@rgb", skip_serializing_if = "Option::is_none")]
133    pub rgb: Option<String>,
134
135    #[serde(rename = "@theme", skip_serializing_if = "Option::is_none")]
136    pub theme: Option<u32>,
137
138    #[serde(rename = "@tint", skip_serializing_if = "Option::is_none")]
139    pub tint: Option<f64>,
140}
141
142/// Font name.
143#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
144pub struct FontName {
145    #[serde(rename = "@val")]
146    pub val: String,
147}
148
149/// Font family.
150#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
151pub struct FontFamily {
152    #[serde(rename = "@val")]
153    pub val: u32,
154}
155
156/// Font scheme.
157#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
158pub struct FontScheme {
159    #[serde(rename = "@val")]
160    pub val: String,
161}
162
163impl Default for Sst {
164    fn default() -> Self {
165        Self {
166            xmlns: namespaces::SPREADSHEET_ML.to_string(),
167            count: Some(0),
168            unique_count: Some(0),
169            items: vec![],
170        }
171    }
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177
178    #[test]
179    fn test_rich_text_properties_preserve_values_and_schema_order() {
180        let xml = r#"<rPr><rFont val="Calibri"/><family val="2"/><b val="true"/><i val="false"/><strike val="true"/><color rgb="FF112233"/><sz val="11"/><u val="singleAccounting"/><vertAlign val="superscript"/><scheme val="minor"/></rPr>"#;
181
182        let properties: RPr = quick_xml::de::from_str(xml).unwrap();
183        assert_eq!(properties.strike.as_ref().unwrap().val, Some(true));
184        assert_eq!(
185            properties.u.as_ref().unwrap().val,
186            Some("singleAccounting".to_string())
187        );
188        assert_eq!(properties.vert_align.as_ref().unwrap().val, "superscript");
189
190        let serialized = quick_xml::se::to_string(&properties).unwrap();
191        assert!(serialized.find("<rFont").unwrap() < serialized.find("<family").unwrap());
192        assert!(serialized.find("<strike").unwrap() < serialized.find("<color").unwrap());
193        assert!(serialized.find("<sz").unwrap() < serialized.find("<u ").unwrap());
194        assert!(serialized.find("<u ").unwrap() < serialized.find("<vertAlign").unwrap());
195        let reparsed: RPr = quick_xml::de::from_str(&serialized).unwrap();
196        assert_eq!(properties, reparsed);
197    }
198
199    // NOTE: quick-xml's serde Deserializer trims leading whitespace from text
200    // events by default (via internal StartTrimmer). This means text like " text"
201    // becomes "text" after deserialization. For production use, the higher-level
202    // reader should handle whitespace preservation using the raw Reader API.
203    // Tests here verify the serde round-trip behavior as-is.
204
205    #[test]
206    fn test_sst_default() {
207        let sst = Sst::default();
208        assert_eq!(sst.xmlns, namespaces::SPREADSHEET_ML);
209        assert_eq!(sst.count, Some(0));
210        assert_eq!(sst.unique_count, Some(0));
211        assert!(sst.items.is_empty());
212    }
213
214    #[test]
215    fn test_sst_roundtrip() {
216        let sst = Sst {
217            xmlns: namespaces::SPREADSHEET_ML.to_string(),
218            count: Some(3),
219            unique_count: Some(2),
220            items: vec![
221                Si {
222                    t: Some(T {
223                        xml_space: None,
224                        value: "Hello".to_string(),
225                    }),
226                    r: vec![],
227                },
228                Si {
229                    t: Some(T {
230                        xml_space: None,
231                        value: "World".to_string(),
232                    }),
233                    r: vec![],
234                },
235            ],
236        };
237        let xml = quick_xml::se::to_string(&sst).unwrap();
238        let parsed: Sst = quick_xml::de::from_str(&xml).unwrap();
239        assert_eq!(sst.count, parsed.count);
240        assert_eq!(sst.unique_count, parsed.unique_count);
241        assert_eq!(sst.items.len(), parsed.items.len());
242        assert_eq!(
243            sst.items[0].t.as_ref().unwrap().value,
244            parsed.items[0].t.as_ref().unwrap().value
245        );
246    }
247
248    #[test]
249    fn test_sst_with_plain_strings() {
250        let sst = Sst {
251            xmlns: namespaces::SPREADSHEET_ML.to_string(),
252            count: Some(2),
253            unique_count: Some(2),
254            items: vec![
255                Si {
256                    t: Some(T {
257                        xml_space: None,
258                        value: "Name".to_string(),
259                    }),
260                    r: vec![],
261                },
262                Si {
263                    t: Some(T {
264                        xml_space: None,
265                        value: "Age".to_string(),
266                    }),
267                    r: vec![],
268                },
269            ],
270        };
271        let xml = quick_xml::se::to_string(&sst).unwrap();
272        assert!(xml.contains("Name"));
273        assert!(xml.contains("Age"));
274    }
275
276    #[test]
277    fn test_sst_with_rich_text() {
278        let sst = Sst {
279            xmlns: namespaces::SPREADSHEET_ML.to_string(),
280            count: Some(1),
281            unique_count: Some(1),
282            items: vec![Si {
283                t: None,
284                r: vec![
285                    R {
286                        r_pr: Some(RPr {
287                            r_font: Some(FontName {
288                                val: "Calibri".to_string(),
289                            }),
290                            family: None,
291                            b: Some(BoolVal { val: None }),
292                            i: None,
293                            strike: None,
294                            color: None,
295                            sz: Some(FontSize { val: 11.0 }),
296                            u: None,
297                            vert_align: None,
298                            scheme: None,
299                        }),
300                        t: T {
301                            xml_space: None,
302                            value: "Bold".to_string(),
303                        },
304                    },
305                    R {
306                        r_pr: None,
307                        t: T {
308                            xml_space: None,
309                            value: " Normal".to_string(),
310                        },
311                    },
312                ],
313            }],
314        };
315
316        let xml = quick_xml::se::to_string(&sst).unwrap();
317        let parsed: Sst = quick_xml::de::from_str(&xml).unwrap();
318        assert_eq!(parsed.items.len(), 1);
319        assert!(parsed.items[0].t.is_none());
320        assert_eq!(parsed.items[0].r.len(), 2);
321        assert!(parsed.items[0].r[0].r_pr.is_some());
322        assert!(parsed.items[0].r[0].r_pr.as_ref().unwrap().b.is_some());
323        assert_eq!(parsed.items[0].r[0].t.value, "Bold");
324        // Note: quick-xml's StartTrimmer trims leading whitespace from text
325        // after a start tag. " Normal" becomes "Normal" during deserialization.
326        // The higher-level reader must handle whitespace preservation.
327        assert_eq!(parsed.items[0].r[1].t.value, "Normal");
328    }
329
330    #[test]
331    fn test_parse_real_excel_shared_strings() {
332        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
333<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="4" uniqueCount="3">
334  <si><t>Name</t></si>
335  <si><t>Value</t></si>
336  <si><t>Description</t></si>
337</sst>"#;
338
339        let parsed: Sst = quick_xml::de::from_str(xml).unwrap();
340        assert_eq!(parsed.count, Some(4));
341        assert_eq!(parsed.unique_count, Some(3));
342        assert_eq!(parsed.items.len(), 3);
343        assert_eq!(parsed.items[0].t.as_ref().unwrap().value, "Name");
344        assert_eq!(parsed.items[1].t.as_ref().unwrap().value, "Value");
345        assert_eq!(parsed.items[2].t.as_ref().unwrap().value, "Description");
346    }
347
348    #[test]
349    fn test_parse_real_excel_rich_text_shared_strings() {
350        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
351<sst xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" count="1" uniqueCount="1">
352  <si>
353    <r>
354      <rPr><b/><sz val="11"/><rFont val="Calibri"/></rPr>
355      <t>Bold</t>
356    </r>
357    <r>
358      <t> text</t>
359    </r>
360  </si>
361</sst>"#;
362
363        let parsed: Sst = quick_xml::de::from_str(xml).unwrap();
364        assert_eq!(parsed.items.len(), 1);
365        let item = &parsed.items[0];
366        assert!(item.t.is_none());
367        assert_eq!(item.r.len(), 2);
368        assert!(item.r[0].r_pr.is_some());
369        assert!(item.r[0].r_pr.as_ref().unwrap().b.is_some());
370        assert_eq!(item.r[0].t.value, "Bold");
371        // Leading whitespace trimmed by quick-xml's StartTrimmer
372        assert_eq!(item.r[1].t.value, "text");
373    }
374
375    #[test]
376    fn test_text_with_space_preservation() {
377        let t = T {
378            xml_space: Some("preserve".to_string()),
379            value: "  leading spaces  ".to_string(),
380        };
381        let xml = quick_xml::se::to_string(&t).unwrap();
382        assert!(xml.contains("xml:space=\"preserve\""));
383        let parsed: T = quick_xml::de::from_str(&xml).unwrap();
384        assert_eq!(parsed.xml_space, Some("preserve".to_string()));
385        // Note: quick-xml's StartTrimmer trims leading whitespace.
386        // The xml:space="preserve" attribute is preserved in the struct
387        // for correct re-serialization; actual whitespace preservation
388        // requires the higher-level reader to use raw Reader API.
389        assert_eq!(parsed.value, "leading spaces");
390    }
391
392    #[test]
393    fn test_empty_sst_roundtrip() {
394        let sst = Sst::default();
395        let xml = quick_xml::se::to_string(&sst).unwrap();
396        let parsed: Sst = quick_xml::de::from_str(&xml).unwrap();
397        assert!(parsed.items.is_empty());
398        assert_eq!(parsed.count, Some(0));
399        assert_eq!(parsed.unique_count, Some(0));
400    }
401
402    #[test]
403    fn test_sst_serialize_structure() {
404        let sst = Sst {
405            xmlns: namespaces::SPREADSHEET_ML.to_string(),
406            count: Some(1),
407            unique_count: Some(1),
408            items: vec![Si {
409                t: Some(T {
410                    xml_space: None,
411                    value: "test".to_string(),
412                }),
413                r: vec![],
414            }],
415        };
416        let xml = quick_xml::se::to_string(&sst).unwrap();
417        assert!(xml.contains("<sst"));
418        assert!(xml.contains("<si>"));
419        assert!(xml.contains("<t>"));
420        assert!(xml.contains("test"));
421    }
422}