imprimatur 0.1.0

data/ext/imprimatur_native/core/src/xlsx/range.rs

@@ -0,0 +1,124 @@
+//! A1-style references and rectangular ranges, the way data validations and
+//! comments address cells.
+
+#[cfg(test)]
+mod tests;
+
+use std::fmt;
+use std::str::FromStr;
+
+use super::cell::push_cell_reference;
+use super::worksheet::{MAX_COLUMNS, MAX_ROWS, check_column, check_row};
+use crate::{Error, Result};
+
+/// A rectangle of cells, zero-based and inclusive: `B2:D9` is rows 1 to 8 of
+/// columns 1 to 3. Parsed from and displayed as A1 text.
+///
+/// ```
+/// use imprimatur::xlsx::CellRange;
+///
+/// let range: CellRange = "D9:b2".parse()?;
+/// assert_eq!(range.to_string(), "B2:D9");
+/// assert_eq!(range.top_left(), (1, 1));
+/// # Ok::<(), imprimatur::Error>(())
+/// ```
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct CellRange {
+    top: u32,
+    left: u16,
+    bottom: u32,
+    right: u16,
+}
+
+impl CellRange {
+    /// The range between two `(row, column)` corners, in either order.
+    ///
+    /// # Errors
+    /// [`Error::RowOutOfRange`] or [`Error::ColumnOutOfRange`].
+    pub fn new(first: (u32, u16), last: (u32, u16)) -> Result<Self> {
+        for (row, column) in [first, last] {
+            check_row(row)?;
+            check_column(column)?;
+        }
+        Ok(Self {
+            top: first.0.min(last.0),
+            left: first.1.min(last.1),
+            bottom: first.0.max(last.0),
+            right: first.1.max(last.1),
+        })
+    }
+
+    /// A single cell.
+    ///
+    /// # Errors
+    /// As [`new`](Self::new).
+    pub fn cell(row: u32, column: u16) -> Result<Self> {
+        Self::new((row, column), (row, column))
+    }
+
+    #[must_use]
+    pub const fn top_left(&self) -> (u32, u16) {
+        (self.top, self.left)
+    }
+
+    #[must_use]
+    pub const fn bottom_right(&self) -> (u32, u16) {
+        (self.bottom, self.right)
+    }
+
+    pub(crate) const fn overlaps(&self, other: &Self) -> bool {
+        self.top <= other.bottom
+            && other.top <= self.bottom
+            && self.left <= other.right
+            && other.left <= self.right
+    }
+}
+
+impl FromStr for CellRange {
+    type Err = Error;
+
+    /// `B2`, or `B2:D9` with the corners in either order. No `$` markers,
+    /// sheet names or whole-column ranges.
+    fn from_str(text: &str) -> Result<Self> {
+        let invalid = |_| Error::InvalidRange(text.to_owned());
+        let (first, last) = text.split_once(':').unwrap_or((text, text));
+        let first = parse_cell_reference(first).map_err(invalid)?;
+        let last = parse_cell_reference(last).map_err(invalid)?;
+        Self::new(first, last)
+    }
+}
+
+impl fmt::Display for CellRange {
+    fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let mut text = String::with_capacity(21);
+        push_cell_reference(&mut text, self.top, self.left);
+        if (self.top, self.left) != (self.bottom, self.right) {
+            text.push(':');
+            push_cell_reference(&mut text, self.bottom, self.right);
+        }
+        out.write_str(&text)
+    }
+}
+
+/// An A1 reference such as `B2`, its letters in either case, as a zero-based
+/// `(row, column)`.
+///
+/// # Errors
+/// [`Error::InvalidRange`] for anything else, or a cell beyond `XFD1048576`.
+pub fn parse_cell_reference(reference: &str) -> Result<(u32, u16)> {
+    let invalid = || Error::InvalidRange(reference.to_owned());
+    let split = reference.find(|ch: char| !ch.is_ascii_alphabetic()).ok_or_else(invalid)?;
+    let (letters, digits) = reference.split_at(split);
+    let digits_valid = digits.bytes().all(|byte| byte.is_ascii_digit()) && !digits.starts_with('0');
+    ((1..=3).contains(&letters.len()) && digits_valid).ok_or_else(invalid)?;
+    // Bijective base 26: A is 1, Z 26, AA 27. Three letters stay under 2**15.
+    let column = letters
+        .bytes()
+        .fold(0_u32, |sum, letter| sum * 26 + u32::from(letter.to_ascii_uppercase() - b'A') + 1);
+    let column = u16::try_from(column - 1).ok().filter(|&column| column < MAX_COLUMNS);
+    let row = digits.parse::<u32>().ok().filter(|&row| row <= MAX_ROWS);
+    match (row, column) {
+        (Some(row), Some(column)) => Ok((row - 1, column)),
+        _ => Err(invalid()),
+    }
+}

data/ext/imprimatur_native/core/src/xlsx/styles.rs

@@ -0,0 +1,240 @@
+//! `xl/styles.xml`: every distinct format in the workbook, split into the
+//! number formats, fonts, fills and borders it refers to.
+
+#[cfg(test)]
+mod tests;
+
+use std::collections::HashMap;
+use std::hash::Hash;
+use std::sync::Arc;
+
+use super::format::{Border, DEFAULT_FONT, Font, Format};
+use super::package::MAIN_NS;
+use super::worksheet::{MAX_FORMATS, Worksheet};
+use crate::style::{Align, Color};
+use crate::xml::XmlWriter;
+use crate::{Error, Result};
+
+/// The first id Excel leaves free for custom number formats.
+const FIRST_CUSTOM_NUMBER_FORMAT: u32 = 164;
+
+/// Distinct values in order of first use, numbered from a starting id.
+/// There are at most [`MAX_FORMATS`] of them, so ids stay small.
+struct Table<T> {
+    ids: HashMap<T, u32>,
+    order: Vec<T>,
+    next: u32,
+}
+
+impl<T: Copy + Eq + Hash> Table<T> {
+    fn new(first: u32) -> Self {
+        Self { ids: HashMap::new(), order: Vec::new(), next: first }
+    }
+
+    fn id(&mut self, value: &T) -> u32 {
+        if let Some(&id) = self.ids.get(value) {
+            return id;
+        }
+        let id = self.next;
+        self.next += 1;
+        self.order.push(*value);
+        self.ids.insert(*value, id);
+        id
+    }
+}
+
+/// The workbook's cell formats; cell style `n` is `formats[n - 1]`, 0 the default.
+#[derive(Default)]
+pub struct Stylesheet {
+    /// Shared with the sheets that use them: merging copies no format.
+    ids: HashMap<Arc<Format>, u32>,
+    formats: Vec<Arc<Format>>,
+}
+
+impl Stylesheet {
+    /// Merges a sheet's formats in; returns the workbook style for each of
+    /// the sheet's own style ids (index 0, the default, stays 0).
+    pub fn add_sheet(&mut self, sheet: &Worksheet) -> Result<Vec<u32>> {
+        let mut remap = vec![0];
+        for format in sheet.formats() {
+            if let Some(&id) = self.ids.get(format) {
+                remap.push(id);
+                continue;
+            }
+            (self.formats.len() < MAX_FORMATS).ok_or(Error::TooManyFormats)?;
+            self.formats.push(Arc::clone(format));
+            let id = u32::try_from(self.formats.len()).map_err(|_| Error::TooManyFormats)?;
+            self.ids.insert(Arc::clone(format), id);
+            remap.push(id);
+        }
+        Ok(remap)
+    }
+
+    pub fn to_xml(&self) -> String {
+        let mut number_formats = Table::<&str>::new(FIRST_CUSTOM_NUMBER_FORMAT);
+        let mut fonts = Table::<&Font>::new(1);
+        let mut fills = Table::<Color>::new(2);
+        let mut borders = Table::<Border>::new(1);
+        let xfs: Vec<[u32; 4]> = self
+            .formats
+            .iter()
+            .map(|format| {
+                let number = match format.number_code.as_deref() {
+                    None | Some("General") => 0,
+                    Some(code) => number_formats.id(&code),
+                };
+                let font = if format.font == Font::default() { 0 } else { fonts.id(&&format.font) };
+                let fill = format.fill.map_or(0, |color| fills.id(&color));
+                let border = format.border.map_or(0, |border| borders.id(&border));
+                [number, font, fill, border]
+            })
+            .collect();
+
+        let mut xml = XmlWriter::new();
+        xml.open("styleSheet", &[("xmlns", MAIN_NS)]);
+        if !number_formats.order.is_empty() {
+            let count = number_formats.order.len().to_string();
+            xml.open("numFmts", &[("count", &count)]);
+            for (offset, code) in (0..).zip(&number_formats.order) {
+                let id = (FIRST_CUSTOM_NUMBER_FORMAT + offset).to_string();
+                xml.empty("numFmt", &[("numFmtId", &id), ("formatCode", code)]);
+            }
+            xml.close("numFmts");
+        }
+        write_fonts(&mut xml, &fonts.order);
+        write_fills(&mut xml, &fills.order);
+        write_borders(&mut xml, &borders.order);
+        xml.open("cellStyleXfs", &[("count", "1")]);
+        xml.empty("xf", &[("numFmtId", "0"), ("fontId", "0"), ("fillId", "0"), ("borderId", "0")]);
+        xml.close("cellStyleXfs");
+        let count = (xfs.len() + 1).to_string();
+        xml.open("cellXfs", &[("count", &count)]);
+        xml.empty(
+            "xf",
+            &[
+                ("numFmtId", "0"),
+                ("fontId", "0"),
+                ("fillId", "0"),
+                ("borderId", "0"),
+                ("xfId", "0"),
+            ],
+        );
+        for (format, ids) in self.formats.iter().zip(&xfs) {
+            write_xf(&mut xml, format, *ids);
+        }
+        xml.close("cellXfs");
+        xml.open("cellStyles", &[("count", "1")]);
+        xml.empty("cellStyle", &[("name", "Normal"), ("xfId", "0"), ("builtinId", "0")]);
+        xml.close("cellStyles");
+        xml.close("styleSheet");
+        xml.finish()
+    }
+}
+
+fn write_fonts(xml: &mut XmlWriter, fonts: &[&Font]) {
+    let count = (fonts.len() + 1).to_string();
+    xml.open("fonts", &[("count", &count)]);
+    let default = Font::default();
+    for font in std::iter::once(&default).chain(fonts.iter().copied()) {
+        xml.open("font", &[]);
+        for (on, tag) in [(font.bold, "b"), (font.italic, "i"), (font.underline, "u")] {
+            if on {
+                xml.empty(tag, &[]);
+            }
+        }
+        xml.empty("sz", &[("val", &font.size())]);
+        if let Some(color) = font.color {
+            xml.empty("color", &[("rgb", &color.argb())]);
+        }
+        xml.empty("name", &[("val", font.name())]);
+        // The family is a fallback hint; only Calibri's is known (2, swiss).
+        if font.name() == DEFAULT_FONT {
+            xml.empty("family", &[("val", "2")]);
+        }
+        xml.close("font");
+    }
+    xml.close("fonts");
+}
+
+/// Excel reserves the first two fills: none and gray125.
+fn write_fills(xml: &mut XmlWriter, fills: &[Color]) {
+    let count = (fills.len() + 2).to_string();
+    xml.open("fills", &[("count", &count)]);
+    for pattern in ["none", "gray125"] {
+        xml.open("fill", &[]);
+        xml.empty("patternFill", &[("patternType", pattern)]);
+        xml.close("fill");
+    }
+    for color in fills {
+        xml.open("fill", &[]);
+        xml.open("patternFill", &[("patternType", "solid")]);
+        xml.empty("fgColor", &[("rgb", &color.argb())]);
+        xml.empty("bgColor", &[("indexed", "64")]);
+        xml.close("patternFill");
+        xml.close("fill");
+    }
+    xml.close("fills");
+}
+
+fn write_borders(xml: &mut XmlWriter, borders: &[Border]) {
+    let count = (borders.len() + 1).to_string();
+    xml.open("borders", &[("count", &count)]);
+    xml.open("border", &[]);
+    for side in ["left", "right", "top", "bottom", "diagonal"] {
+        xml.empty(side, &[]);
+    }
+    xml.close("border");
+    for border in borders {
+        xml.open("border", &[]);
+        for side in ["left", "right", "top", "bottom"] {
+            xml.open(side, &[("style", border.as_str())]);
+            xml.empty("color", &[("auto", "1")]);
+            xml.close(side);
+        }
+        xml.empty("diagonal", &[]);
+        xml.close("border");
+    }
+    xml.close("borders");
+}
+
+fn write_xf(xml: &mut XmlWriter, format: &Format, [number, font, fill, border]: [u32; 4]) {
+    let ids = [number, font, fill, border].map(|id| id.to_string());
+    let mut attrs = vec![
+        ("numFmtId", ids[0].as_str()),
+        ("fontId", ids[1].as_str()),
+        ("fillId", ids[2].as_str()),
+        ("borderId", ids[3].as_str()),
+        ("xfId", "0"),
+    ];
+    for (applies, name) in [
+        (number != 0, "applyNumberFormat"),
+        (font != 0, "applyFont"),
+        (fill != 0, "applyFill"),
+        (border != 0, "applyBorder"),
+        (format.has_alignment(), "applyAlignment"),
+    ] {
+        if applies {
+            attrs.push((name, "1"));
+        }
+    }
+    if !format.has_alignment() {
+        xml.empty("xf", &attrs);
+        return;
+    }
+    xml.open("xf", &attrs);
+    let mut alignment = Vec::new();
+    if let Some(align) = format.align {
+        alignment.push(("horizontal", Align::as_str(align)));
+    }
+    if let Some(valign) = format.valign {
+        alignment.push(("vertical", valign.as_str()));
+    }
+    if let Some(direction) = format.direction {
+        alignment.push(("readingOrder", direction.reading_order()));
+    }
+    if format.wrap {
+        alignment.push(("wrapText", "1"));
+    }
+    xml.empty("alignment", &alignment);
+    xml.close("xf");
+}

data/ext/imprimatur_native/core/src/xlsx/text.rs

@@ -0,0 +1,122 @@
+//! Cell text: the OOXML escaping for characters XML cannot carry, and the
+//! shared string table.
+
+#[cfg(test)]
+mod tests;
+
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fmt::Write as _;
+
+use super::package::MAIN_NS;
+use crate::xml::{XmlWriter, is_forbidden};
+use crate::{Error, Result};
+
+/// Characters a cell or a comment holds at most.
+const MAX_TEXT: usize = 32_767;
+
+/// Refuses text longer than a cell or a comment holds.
+pub fn check_length(text: &str) -> Result<()> {
+    let length = text.chars().count();
+    (length <= MAX_TEXT).ok_or(Error::TextTooLong(length))
+}
+
+/// Escapes text as an `ST_Xstring` (ECMA-376 Part 1, 22.9.2.19): characters
+/// XML cannot carry become `_xHHHH_`, and an underscore that would read as the
+/// start of such an escape becomes `_x005F_`.
+pub fn escape(text: &str) -> Cow<'_, str> {
+    let needs = |(at, ch): (usize, char)| is_forbidden(ch) || looks_escaped(text, at);
+    if !text.char_indices().any(needs) {
+        return Cow::Borrowed(text);
+    }
+    let mut escaped = String::with_capacity(text.len() + 7);
+    for (at, ch) in text.char_indices() {
+        if needs((at, ch)) {
+            // Writing to a String cannot fail.
+            let _ = write!(escaped, "_x{:04X}_", u32::from(ch));
+        } else {
+            escaped.push(ch);
+        }
+    }
+    Cow::Owned(escaped)
+}
+
+/// The inverse of [`escape`]: each `_xHHHH_` back to its character. An
+/// escape of a surrogate, which no `char` holds, stays as written.
+pub fn unescape(text: &str) -> Cow<'_, str> {
+    if !text.contains("_x") {
+        return Cow::Borrowed(text);
+    }
+    let mut out = String::with_capacity(text.len());
+    let mut rest = text;
+    while let Some(at) = rest.find("_x") {
+        out.push_str(&rest[..at]);
+        let candidate = &rest[at..];
+        let decoded = looks_escaped(candidate, 0)
+            .then(|| u32::from_str_radix(&candidate[2..6], 16).ok().and_then(char::from_u32))
+            .flatten();
+        if let Some(ch) = decoded {
+            out.push(ch);
+            rest = &candidate[7..];
+        } else {
+            out.push_str("_x");
+            rest = &candidate[2..];
+        }
+    }
+    out.push_str(rest);
+    Cow::Owned(out)
+}
+
+/// True when byte `at` starts `_xHHHH_`. The pattern is ASCII, so checking
+/// bytes from `at` is exact and keeps escaping linear.
+fn looks_escaped(text: &str, at: usize) -> bool {
+    let Some([b'_', b'x', digits @ .., b'_']) = text.as_bytes().get(at..at + 7) else {
+        return false;
+    };
+    digits.iter().all(u8::is_ascii_hexdigit)
+}
+
+/// Whether `<t>` needs `xml:space="preserve"` to keep its edge whitespace.
+pub fn needs_preserve(text: &str) -> bool {
+    text.starts_with(char::is_whitespace) || text.ends_with(char::is_whitespace)
+}
+
+/// Every distinct text in the workbook, numbered in order of first use.
+#[derive(Default)]
+pub struct SharedStrings<'a> {
+    index: HashMap<&'a str, usize>,
+    order: Vec<&'a str>,
+    references: usize,
+}
+
+impl<'a> SharedStrings<'a> {
+    /// The text's index in the table, adding it on first use.
+    pub fn intern(&mut self, text: &'a str) -> usize {
+        self.references += 1;
+        *self.index.entry(text).or_insert_with(|| {
+            self.order.push(text);
+            self.order.len() - 1
+        })
+    }
+
+    pub const fn is_empty(&self) -> bool {
+        self.order.is_empty()
+    }
+
+    /// `xl/sharedStrings.xml`.
+    pub fn to_xml(&self) -> String {
+        let mut xml = XmlWriter::new();
+        let count = self.references.to_string();
+        let unique = self.order.len().to_string();
+        xml.open("sst", &[("xmlns", MAIN_NS), ("count", &count), ("uniqueCount", &unique)]);
+        for text in &self.order {
+            xml.open("si", &[]);
+            let attrs: &[(&str, &str)] =
+                if needs_preserve(text) { &[("xml:space", "preserve")] } else { &[] };
+            xml.element("t", attrs, &escape(text));
+            xml.close("si");
+        }
+        xml.close("sst");
+        xml.finish()
+    }
+}