fast_xlsx 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e437e53063a29cc586d2d18200be43a28ec6a967907f053fb06b2c0494202cf9
-  data.tar.gz: 6c7fbc5799ef0526bcd9733114c50d7442d998769f7f8b00bbdc821c216a8ba1
+  metadata.gz: d4a6f42c2c4c1f1a9e4a5f59441d183e2257abbbbfd9593fa22d7be4a9cf7519
+  data.tar.gz: 1c89a99feafa34f127e14d49175503da754809ca2436197bbd1e4e59290a145d
 SHA512:
-  metadata.gz: 2ca68d242260d67c52265c2f373453d32da549842862fb4695f7c2f9d2267bf4bde9f1ebbafb200a44dc582a9c85e9a4082579169ccb7af03b349c74a991aeea
-  data.tar.gz: 28230cf03c0f109e690273b7906b57ab18cc5ecdceafb348155c7b6c1e8370c85aadc3889d22775d30abd08058f43ea81ff6aa8f8d207f58ed039e1f03ef3110
+  metadata.gz: 75823da46a7dcf4a0bc921211871fe591f9be3ccf788ce42456bd109f77778a9886dce51123b1d86e18255169770e3b28d9ebb5e03f4de497b170be6092bf150
+  data.tar.gz: 5f5439f853da37aa5730636dc20e6daf784b9b0374ad03aba78c10720e3976d080ec287938209ea62fb3e996931b904b0ecd05e59a83b5dda8468fde0424fb8b

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-30
+
+### Fixed
+
+- Values Excel cannot hold (a string over 32,767 characters, invalid UTF-8, a bad or over-long URL, more than 16,384 columns) raise before anything is written, instead of leaving the row half written.
+- `merge_range` with such a value no longer leaves the range merged; its value also takes its table column's format.
+- An unnamed worksheet takes the first free `SheetN` instead of a name that clashes with one given earlier (which failed only when saving).
+- Cell values and formats are copied out of Ruby objects when a row is converted, so Ruby code run while converting (a `to_s`) cannot change or free them before they are written.
+- Ruby code run while converting a value (a `to_s`, `jd`, ...) that touches the same workbook, or another thread writing to it, no longer deadlocks. A value that fails to convert leaves its row unwritten.
+- In `:constant` / `:low` mode, `merge_range` and `add_table` on rows already written to disk raise `FastXlsx::Error` instead of being dropped; cells beside a tall merge can still be written.
+- Table column formats apply to rows written after `add_table`.
+- Invalid worksheet names raise without leaving an extra sheet behind; names that differ only in case raise at `add_worksheet`, not at save.
+- Strings in other encodings (e.g. Windows-1252) are converted to UTF-8.
+- `data_validation` lists accept numbers and other values (listed by `to_s`).
+- Dates match Excel's 1900 date system (serials before 1900-03-01 were one too high); dates before 1900 raise `ArgumentError`.
+- `Workbook#save` accepts a `Pathname`.
+
+## [0.1.1] - 2026-09-30
+
+### Fixed
+
+- Precompiled (platform) gems failed to `require`: the extension was only looked up where a source install puts it, not in the per-Ruby-version directory that platform gems use. 0.1.0's platform gems cannot be loaded; upgrade to 0.1.1 (`bundle update fast_xlsx` if your lockfile has 0.1.0).
+
+### Changed
+
+- Releases now install and load the built platform gems on Linux, macOS and Windows with Ruby 3.3, 3.4 and 4.0 before publishing.
+
 ## [0.1.0] - 2026-09-30
 
 First release: a fast `.xlsx` writer built on rust_xlsxwriter. Early API; it may still change before 1.0.

data/README.md

@@ -276,6 +276,15 @@ cargo llvm-cov report --release                     # or --lcov / --html
 
 Rebuild in a clean shell afterwards (`rm -rf tmp && bundle exec rake compile`) so the everyday build is not instrumented.
 
+Mutation tests ([cargo-mutants](https://mutants.rs)) change the Rust source one small edit at a time and check that a Ruby test fails for each change. `ext/fast_xlsx/tests/ruby_suite.rs` is what connects the two: it rebuilds the extension and runs the Ruby suite, so `cargo test` covers the Ruby tests too.
+
+```bash
+cargo install cargo-mutants
+cargo mutants --file ext/fast_xlsx/src/lib.rs --jobs 4   # ~7 minutes; results in mutants.out/
+```
+
+Mutants listed in `mutants.out/missed.txt` point at behaviour no test checks. The `Mutation tests` workflow runs this weekly and on demand.
+
 ### Releasing
 
 First generate the showcase workbook and open it in Excel to check every feature renders (the test suite only inspects the XML):

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.1.0)
+    fast_xlsx (0.1.2)
       rb_sys (~> 0.9.130)
 
 GEM
@@ -77,7 +77,7 @@ DEPENDENCIES
 CHECKSUMS
   caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
-  fast_xlsx (0.1.0)
+  fast_xlsx (0.1.2)
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
   ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564

data/ext/fast_xlsx/src/lib.rs

@@ -1,4 +1,4 @@
-use std::cell::Cell;
+use std::cell::{Cell, RefCell};
 use std::sync::{Arc, Mutex};
 
 use magnus::{
@@ -7,11 +7,11 @@ use magnus::{
     Value,
 };
 use rust_xlsxwriter::{
-    Color, ConditionalFormat2ColorScale, ConditionalFormat3ColorScale, ConditionalFormatCell,
-    ConditionalFormatCellRule, ConditionalFormatDataBar, ConditionalFormatFormula,
-    ConditionalFormatText, ConditionalFormatTextRule, ConditionalFormatValue, DataValidation,
-    DataValidationRule, FormatAlign, FormatBorder, FormatScript, FormatUnderline,
-    IntoDataValidationValue, IntoExcelData, XlsxError,
+    Color, ConditionalFormat, ConditionalFormat2ColorScale, ConditionalFormat3ColorScale,
+    ConditionalFormatCell, ConditionalFormatCellRule, ConditionalFormatDataBar,
+    ConditionalFormatFormula, ConditionalFormatText, ConditionalFormatTextRule,
+    ConditionalFormatValue, DataValidation, DataValidationRule, FormatAlign, FormatBorder,
+    FormatScript, FormatUnderline, IntoDataValidationValue, IntoExcelData, XlsxError,
 };
 
 use rust_xlsxwriter::{
@@ -49,9 +49,23 @@ struct Workbook {
 struct Worksheet {
     wb: Shared,
     index: usize,
+    // Where << / append write next.
     next_row: Cell<u32>,
+    // Highest row with cells written. In :constant / :low mode rows above it
+    // are on disk; rows a merge spans are held back, so merges don't count.
+    last_written_row: Cell<u32>,
     // constant_memory and low_memory worksheets write finished rows to disk.
     flushes_rows: bool,
+    // Formats of table columns, for cells written into a table's data rows
+    // after add_table (rust_xlsxwriter only formats cells that already exist).
+    // Owned copies, so they don't depend on the Ruby Format objects living on.
+    table_formats: RefCell<Vec<TableColumnFormat>>,
+}
+
+struct TableColumnFormat {
+    rows: std::ops::RangeInclusive<u32>,
+    col: u16,
+    format: Arc<rust_xlsxwriter::Format>,
 }
 
 impl Workbook {
@@ -65,6 +79,36 @@ impl Workbook {
 
     fn add_worksheet(&self, name: Option<String>) -> Result<Worksheet, Error> {
         let mut wb = self.inner.lock().unwrap();
+        // Excel sheet names are case-insensitive; rust_xlsxwriter only notices
+        // a clash when saving.
+        let taken: Vec<String> = wb
+            .worksheets()
+            .iter()
+            .map(|ws| ws.name().to_lowercase())
+            .collect();
+        let name = match name {
+            Some(name) => {
+                // Validate the name before adding: rust_xlsxwriter adds the
+                // sheet first, so a bad name would leave a "SheetN" behind.
+                rust_xlsxwriter::Worksheet::new()
+                    .set_name(&name)
+                    .map_err(xerr)?;
+                if taken.contains(&name.to_lowercase()) {
+                    let ruby = Ruby::get().unwrap();
+                    return Err(Error::new(
+                        ruby.get_inner(&ERROR),
+                        format!("a worksheet named {name:?} already exists (names ignore case)"),
+                    ));
+                }
+                name
+            }
+            // Like Excel, the first free "SheetN"; rust_xlsxwriter's default
+            // counts sheets, which can clash with a name given earlier.
+            None => (1..)
+                .map(|n| format!("Sheet{n}"))
+                .find(|n| !taken.contains(&n.to_lowercase()))
+                .unwrap(),
+        };
         let ws = if self.low_memory {
             wb.add_worksheet_with_low_memory()
         } else if self.constant_memory {
@@ -72,14 +116,14 @@ impl Workbook {
         } else {
             wb.add_worksheet()
         };
-        if let Some(name) = name {
-            ws.set_name(name).map_err(xerr)?;
-        }
+        ws.set_name(name).map_err(xerr)?;
         Ok(Worksheet {
             wb: self.inner.clone(),
             index: wb.worksheets().len() - 1,
             next_row: Cell::new(0),
+            last_written_row: Cell::new(0),
             flushes_rows: self.constant_memory || self.low_memory,
+            table_formats: RefCell::new(Vec::new()),
         })
     }
 
@@ -100,16 +144,17 @@ impl Workbook {
     fn set_properties(ruby: &Ruby, rb_self: &Self, fields: RHash) -> Result<(), Error> {
         let mut props = DocProperties::new();
         fields.foreach(|key: Symbol, value: String| {
+            let taken = std::mem::take(&mut props);
             props = match &*key.name()? {
-                "title" => props.clone().set_title(value),
-                "subject" => props.clone().set_subject(value),
-                "author" => props.clone().set_author(value),
-                "manager" => props.clone().set_manager(value),
-                "company" => props.clone().set_company(value),
-                "category" => props.clone().set_category(value),
-                "keywords" => props.clone().set_keywords(value),
-                "comments" => props.clone().set_comment(value),
-                "status" => props.clone().set_status(value),
+                "title" => taken.set_title(value),
+                "subject" => taken.set_subject(value),
+                "author" => taken.set_author(value),
+                "manager" => taken.set_manager(value),
+                "company" => taken.set_company(value),
+                "category" => taken.set_category(value),
+                "keywords" => taken.set_keywords(value),
+                "comments" => taken.set_comment(value),
+                "status" => taken.set_status(value),
                 other => {
                     return Err(Error::new(
                         ruby.exception_arg_error(),
@@ -124,19 +169,33 @@ impl Workbook {
     }
 }
 
-// Excel stores datetimes as days since 1900-01-01 in local time.
+// Excel serial date from days (and fraction) since 1899-12-30. Excel's 1900
+// date system counts a non-existent 1900-02-29 (serial 60), so real dates
+// before 1900-03-01 are one lower; it has no dates before 1900-01-01.
+fn excel_serial(days: f64) -> Result<f64, Error> {
+    if days < 2.0 {
+        let ruby = Ruby::get().unwrap();
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Excel cannot represent dates before 1900-01-01",
+        ));
+    }
+    Ok(if days < 61.0 { days - 1.0 } else { days })
+}
+
+// Time: seconds since 1970-01-01 (serial day 25569), in its own offset.
 fn excel_time(v: Value) -> Result<f64, Error> {
     let secs: f64 = v.funcall("to_f", ())?;
     let offset: i64 = v.funcall("utc_offset", ())?;
-    Ok((secs + offset as f64) / 86400.0 + 25569.0)
+    excel_serial((secs + offset as f64) / 86400.0 + 25569.0)
 }
 
 // Date / DateTime: Julian day and day fraction are both in the object's own
-// offset. JD 2415019 is Excel serial 0 (1899-12-30).
+// offset. JD 2415019 is 1899-12-30.
 fn excel_date(v: Value) -> Result<f64, Error> {
     let jd: i64 = v.funcall("jd", ())?;
     let fraction: f64 = f64::try_convert(v.funcall("day_fraction", ())?)?;
-    Ok((jd - 2_415_019) as f64 + fraction)
+    excel_serial((jd - 2_415_019) as f64 + fraction)
 }
 
 fn emit<T: IntoExcelData>(
@@ -144,85 +203,136 @@ fn emit<T: IntoExcelData>(
     row: u32,
     col: u16,
     data: T,
-    format: Option<&Format>,
+    format: Option<&rust_xlsxwriter::Format>,
 ) -> Result<(), Error> {
     match format {
-        Some(f) => ws.write_with_format(row, col, data, &f.0),
+        Some(f) => ws.write_with_format(row, col, data, f),
         None => ws.write(row, col, data),
     }
     .map(|_| ())
     .map_err(xerr)
 }
 
-// RichString#segments is [[text, Format or nil], ...]; nil means the default font.
-fn write_rich_string(
-    ws: &mut rust_xlsxwriter::Worksheet,
-    row: u32,
-    col: u16,
-    v: Value,
-    format: Option<&Format>,
-) -> Result<(), Error> {
-    let default = rust_xlsxwriter::Format::default();
-    let segments: RArray = v.funcall("segments", ())?;
-    let mut parts: Vec<(Option<&Format>, String)> = Vec::with_capacity(segments.len());
-    for segment in segments.into_iter() {
-        let (text, seg_format): (String, Value) = TryConvert::try_convert(segment)?;
-        parts.push((Option::<&Format>::try_convert(seg_format)?, text));
+// Excel's limit on the text in a cell.
+const MAX_CHARS: usize = 32_767;
+// Excel's column count.
+const MAX_COLS: usize = 16_384;
+
+// A cell value converted from Ruby. Converting may run Ruby code (to_s, jd,
+// url, ...), so it happens before the workbook lock is taken: Ruby code that
+// touches the same workbook, or another thread, would otherwise deadlock on it.
+// Writing a CellValue runs no Ruby code.
+// It holds Rust-owned copies, never Ruby objects: Ruby code run while the
+// rest of the row converts could change or drop them, and the GC does not
+// see references kept in a Rust Vec.
+enum CellValue {
+    Empty,
+    Text(String),
+    Number(f64),
+    Bool(bool),
+    Formula(String),
+    Url(String, Option<String>),
+    // RichString segments; None means the default font.
+    Rich(Vec<(Option<Arc<rust_xlsxwriter::Format>>, String)>),
+}
+
+impl CellValue {
+    fn from_ruby(ruby: &Ruby, v: Value) -> Result<Self, Error> {
+        let value = if v.is_nil() {
+            CellValue::Empty
+        } else if let Some(s) = RString::from_value(v) {
+            // Other encodings (e.g. Windows-1252 / Big5 from a legacy CSV) are
+            // converted; invalid bytes, or binary non-ASCII, raise.
+            CellValue::Text(s.to_string()?)
+        } else if v.is_kind_of(ruby.class_numeric()) {
+            CellValue::Number(f64::try_convert(v)?)
+        } else if v.is_kind_of(ruby.class_time()) {
+            CellValue::Number(excel_time(v)?)
+        } else if v.is_kind_of(ruby.class_true_class()) || v.is_kind_of(ruby.class_false_class()) {
+            CellValue::Bool(v.to_bool())
+        } else if v.is_kind_of(ruby.get_inner(&FORMULA)) {
+            CellValue::Formula(v.funcall("expression", ())?)
+        } else if v.is_kind_of(ruby.get_inner(&URL)) {
+            CellValue::Url(v.funcall("url", ())?, v.funcall("text", ())?)
+        } else if v.is_kind_of(ruby.get_inner(&RICH_STRING)) {
+            let segments: RArray = v.funcall("segments", ())?;
+            let mut parts = Vec::with_capacity(segments.len());
+            each_entry(segments, |_, segment| {
+                let (text, seg_format): (String, Value) = TryConvert::try_convert(segment)?;
+                let seg_format = Option::<&Format>::try_convert(seg_format)?;
+                parts.push((seg_format.map(|f| f.0.clone()), text));
+                Ok(())
+            })?;
+            CellValue::Rich(parts)
+        } else if v.respond_to("jd", false)? {
+            CellValue::Number(excel_date(v)?)
+        } else {
+            CellValue::Text(v.funcall("to_s", ())?)
+        };
+        value.check()?;
+        Ok(value)
     }
-    let rich: Vec<(&rust_xlsxwriter::Format, &str)> = parts
-        .iter()
-        .map(|(f, text)| (f.map_or(&default, |f| &f.0), text.as_str()))
-        .collect();
-    match format {
-        Some(f) => ws.write_rich_string_with_format(row, col, &rich, &f.0),
-        None => ws.write_rich_string(row, col, &rich),
+
+    // Rejects what the writer would, so a row or merge fails before anything
+    // is written. Numbers, booleans and formulas only fail on a bad row/column.
+    fn check(&self) -> Result<(), Error> {
+        thread_local! {
+            // Reused: every check writes to A1, replacing the one before.
+            static SCRATCH: RefCell<rust_xlsxwriter::Worksheet> =
+                RefCell::new(rust_xlsxwriter::Worksheet::new());
+        }
+        match self {
+            CellValue::Text(s) if s.chars().count() > MAX_CHARS => {
+                Err(xerr(XlsxError::MaxStringLengthExceeded))
+            }
+            // URLs and rich strings have more rules; let the writer apply them.
+            CellValue::Url(..) | CellValue::Rich(_) => {
+                SCRATCH.with_borrow_mut(|ws| self.write(ws, 0, 0, None))
+            }
+            _ => Ok(()),
+        }
     }
-    .map(|_| ())
-    .map_err(xerr)
-}
 
-fn put(
-    ruby: &Ruby,
-    ws: &mut rust_xlsxwriter::Worksheet,
-    row: u32,
-    col: u16,
-    v: Value,
-    format: Option<&Format>,
-) -> Result<(), Error> {
-    if v.is_nil() {
-        Ok(())
-    } else if let Some(s) = RString::from_value(v) {
-        // SAFETY: the borrowed str is copied by the writer before any Ruby code runs.
-        emit(ws, row, col, unsafe { s.as_str()? }, format)
-    } else if v.is_kind_of(ruby.class_numeric()) {
-        emit(ws, row, col, f64::try_convert(v)?, format)
-    } else if v.is_kind_of(ruby.class_time()) {
-        emit(ws, row, col, excel_time(v)?, format)
-    } else if v.is_kind_of(ruby.class_true_class()) || v.is_kind_of(ruby.class_false_class()) {
-        emit(ws, row, col, v.to_bool(), format)
-    } else if v.is_kind_of(ruby.get_inner(&FORMULA)) {
-        let expression: String = v.funcall("expression", ())?;
-        emit(
-            ws,
-            row,
-            col,
-            rust_xlsxwriter::Formula::new(expression),
-            format,
-        )
-    } else if v.is_kind_of(ruby.get_inner(&URL)) {
-        let url: String = v.funcall("url", ())?;
-        let mut link = rust_xlsxwriter::Url::new(url);
-        if let Some(text) = v.funcall::<_, _, Option<String>>("text", ())? {
-            link = link.set_text(text);
+    fn write(
+        &self,
+        ws: &mut rust_xlsxwriter::Worksheet,
+        row: u32,
+        col: u16,
+        format: Option<&rust_xlsxwriter::Format>,
+    ) -> Result<(), Error> {
+        match self {
+            CellValue::Empty => Ok(()),
+            CellValue::Text(s) => emit(ws, row, col, s.as_str(), format),
+            CellValue::Number(n) => emit(ws, row, col, *n, format),
+            CellValue::Bool(b) => emit(ws, row, col, *b, format),
+            CellValue::Formula(f) => emit(
+                ws,
+                row,
+                col,
+                rust_xlsxwriter::Formula::new(f.as_str()),
+                format,
+            ),
+            CellValue::Url(url, text) => {
+                let mut link = rust_xlsxwriter::Url::new(url.as_str());
+                if let Some(text) = text {
+                    link = link.set_text(text.as_str());
+                }
+                emit(ws, row, col, link, format)
+            }
+            CellValue::Rich(parts) => {
+                let default = rust_xlsxwriter::Format::default();
+                let rich: Vec<(&rust_xlsxwriter::Format, &str)> = parts
+                    .iter()
+                    .map(|(f, text)| (f.as_deref().unwrap_or(&default), text.as_str()))
+                    .collect();
+                match format {
+                    Some(f) => ws.write_rich_string_with_format(row, col, &rich, f),
+                    None => ws.write_rich_string(row, col, &rich),
+                }
+                .map(|_| ())
+                .map_err(xerr)
+            }
         }
-        emit(ws, row, col, link, format)
-    } else if v.is_kind_of(ruby.get_inner(&RICH_STRING)) {
-        write_rich_string(ws, row, col, v, format)
-    } else if v.respond_to("jd", false)? {
-        emit(ws, row, col, excel_date(v)?, format)
-    } else {
-        let s: String = v.funcall("to_s", ())?;
-        emit(ws, row, col, s, format)
     }
 }
 
@@ -391,6 +501,19 @@ fn check_header_footer(ruby: &Ruby, what: &str, text: &str) -> Result<(), Error>
     Ok(())
 }
 
+// Option `name` of a Ruby options Hash as given; nil when missing. For
+// choice(), which reports an invalid (or missing) value itself.
+fn raw_opt(ruby: &Ruby, options: RHash, name: &str) -> Value {
+    options
+        .get(ruby.to_symbol(name))
+        .unwrap_or_else(|| ruby.qnil().as_value())
+}
+
+// Option `name` of a Ruby options Hash, converted; missing or nil is None.
+fn opt<T: TryConvert>(ruby: &Ruby, options: RHash, name: &str) -> Result<Option<T>, Error> {
+    Option::<T>::try_convert(raw_opt(ruby, options, name))
+}
+
 // Rejects option keys outside `allowed`, so a typo raises instead of being ignored.
 fn check_keys(ruby: &Ruby, options: RHash, allowed: &[&str], what: &str) -> Result<(), Error> {
     options.foreach(|key: Symbol, _: Value| {
@@ -501,9 +624,13 @@ const TABLE_TOTALS: &[(&str, TableFunction)] = &[
 ];
 
 // A table column: a header String, or { header:, total:, total_label:, format: }.
-fn table_column(ruby: &Ruby, v: Value) -> Result<TableColumn, Error> {
+// Also returns a copy of the column's format, if any, for later writes.
+fn table_column(
+    ruby: &Ruby,
+    v: Value,
+) -> Result<(TableColumn, Option<Arc<rust_xlsxwriter::Format>>), Error> {
     let Some(spec) = RHash::from_value(v) else {
-        return Ok(TableColumn::new().set_header(String::try_convert(v)?));
+        return Ok((TableColumn::new().set_header(String::try_convert(v)?), None));
     };
     check_keys(
         ruby,
@@ -511,20 +638,19 @@ fn table_column(ruby: &Ruby, v: Value) -> Result<TableColumn, Error> {
         &["header", "total", "total_label", "format"],
         "table column",
     )?;
-    let nil = ruby.qnil().as_value();
-    let get = |name: &str| spec.get(ruby.to_symbol(name)).unwrap_or(nil);
-    let mut column = TableColumn::new().set_header(String::try_convert(get("header"))?);
-    if !get("total").is_nil() {
-        column =
-            column.set_total_function(choice(ruby, "table total", get("total"), TABLE_TOTALS)?);
+    let header = String::try_convert(raw_opt(ruby, spec, "header"))?;
+    let mut column = TableColumn::new().set_header(header);
+    if let Some(total) = opt::<Value>(ruby, spec, "total")? {
+        column = column.set_total_function(choice(ruby, "table total", total, TABLE_TOTALS)?);
     }
-    if !get("total_label").is_nil() {
-        column = column.set_total_label(String::try_convert(get("total_label"))?);
+    if let Some(label) = opt::<String>(ruby, spec, "total_label")? {
+        column = column.set_total_label(label);
     }
-    if let Some(format) = Option::<&Format>::try_convert(get("format"))? {
-        column = column.set_format(&format.0);
+    let format = opt::<&Format>(ruby, spec, "format")?.map(|f| f.0.clone());
+    if let Some(f) = &format {
+        column = column.set_format(&**f);
     }
-    Ok(column)
+    Ok((column, format))
 }
 
 const BORDERS: &[(&str, FormatBorder)] = &[
@@ -538,7 +664,7 @@ const BORDERS: &[(&str, FormatBorder)] = &[
 ];
 
 #[magnus::wrap(class = "FastXlsx::Format", free_immediately)]
-struct Format(rust_xlsxwriter::Format);
+struct Format(Arc<rust_xlsxwriter::Format>);
 
 impl Format {
     fn new(ruby: &Ruby, options: RHash) -> Result<Self, Error> {
@@ -626,7 +752,7 @@ impl Format {
             };
             Ok(ForEach::Continue)
         })?;
-        Ok(Format(f))
+        Ok(Format(Arc::new(f)))
     }
 }
 
@@ -649,7 +775,7 @@ fn each_entry(
 
 // A row's format: one Format (or nil) for every cell, or an Array with one per cell.
 enum RowFormat {
-    Same(Option<&'static Format>),
+    Same(Option<Arc<rust_xlsxwriter::Format>>),
     PerCell(RArray),
 }
 
@@ -657,16 +783,19 @@ impl RowFormat {
     fn from_value(v: Value) -> Result<Self, Error> {
         match RArray::from_value(v) {
             Some(formats) => Ok(RowFormat::PerCell(formats)),
-            None => Ok(RowFormat::Same(Option::<&Format>::try_convert(v)?)),
+            None => Ok(RowFormat::Same(
+                Option::<&Format>::try_convert(v)?.map(|f| f.0.clone()),
+            )),
         }
     }
 
-    fn at(&self, col: usize) -> Result<Option<&Format>, Error> {
+    fn at(&self, col: usize) -> Result<Option<Arc<rust_xlsxwriter::Format>>, Error> {
         match self {
-            RowFormat::Same(f) => Ok(*f),
-            RowFormat::PerCell(formats) => {
-                Option::<&Format>::try_convert(formats.entry::<Value>(col as isize)?)
-            }
+            RowFormat::Same(f) => Ok(f.clone()),
+            RowFormat::PerCell(formats) => Ok(Option::<&Format>::try_convert(
+                formats.entry::<Value>(col as isize)?,
+            )?
+            .map(|f| f.0.clone())),
         }
     }
 }
@@ -676,9 +805,14 @@ impl Worksheet {
         self.next_row.set(self.next_row.get().max(row + 1));
     }
 
+    fn note_written(&self, row: u32) {
+        self.last_written_row
+            .set(self.last_written_row.get().max(row));
+    }
+
     // rust_xlsxwriter silently drops writes to rows it has already flushed.
     fn check_not_flushed(&self, ruby: &Ruby, row: u32) -> Result<(), Error> {
-        if self.flushes_rows && row + 1 < self.next_row.get() {
+        if self.flushes_rows && row < self.last_written_row.get() {
             return Err(Error::new(
                 ruby.get_inner(&ERROR),
                 format!(
@@ -697,6 +831,22 @@ impl Worksheet {
         f(wb.worksheet_from_index(self.index).map_err(xerr)?)
     }
 
+    // The format to write a cell with: its own, else its table column's.
+    fn cell_format<'a>(
+        tables: &'a [TableColumnFormat],
+        row: u32,
+        col: u16,
+        own: Option<&'a rust_xlsxwriter::Format>,
+    ) -> Option<&'a rust_xlsxwriter::Format> {
+        own.or_else(|| {
+            tables
+                .iter()
+                .rev()
+                .find(|t| t.col == col && t.rows.contains(&row))
+                .map(|t| &*t.format)
+        })
+    }
+
     fn write_row(
         &self,
         ruby: &Ruby,
@@ -704,14 +854,32 @@ impl Worksheet {
         cells: RArray,
         format: &RowFormat,
     ) -> Result<(), Error> {
+        // Convert the whole row first: no lock is held while Ruby code runs,
+        // and a value that fails to convert leaves the row unwritten.
+        let mut values = Vec::with_capacity(cells.len());
+        each_entry(cells, |i, v| {
+            if i >= MAX_COLS {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!("too many columns: Excel allows {MAX_COLS}"),
+                ));
+            }
+            let col = i as u16;
+            values.push((col, CellValue::from_ruby(ruby, v)?, format.at(i)?));
+            Ok(())
+        })?;
+        let tables = self.table_formats.borrow();
         self.with_ws(|ws| {
-            each_entry(cells, |i, v| {
-                let col = u16::try_from(i)
-                    .map_err(|_| Error::new(ruby.exception_arg_error(), "too many columns"))?;
-                put(ruby, ws, row, col, v, format.at(i)?)
-            })
+            // Values were checked when converted, so only a bad row number
+            // fails here, and it fails on the first cell.
+            for (col, value, format) in &values {
+                let format = Self::cell_format(&tables, row, *col, format.as_deref());
+                value.write(ws, row, *col, format)?;
+            }
+            Ok(())
         })?;
         self.advance(row);
+        self.note_written(row);
         Ok(())
     }
 
@@ -724,8 +892,18 @@ impl Worksheet {
         format: Option<&Format>,
     ) -> Result<(), Error> {
         rb_self.check_not_flushed(ruby, row)?;
-        rb_self.with_ws(|ws| put(ruby, ws, row, col, v, format))?;
+        let value = CellValue::from_ruby(ruby, v)?;
+        let tables = rb_self.table_formats.borrow();
+        rb_self.with_ws(|ws| {
+            value.write(
+                ws,
+                row,
+                col,
+                Self::cell_format(&tables, row, col, format.map(|f| &*f.0)),
+            )
+        })?;
         rb_self.advance(row);
+        rb_self.note_written(row);
         Ok(())
     }
 
@@ -857,14 +1035,27 @@ impl Worksheet {
         v: Value,
         format: Option<&Format>,
     ) -> Result<Obj<Self>, Error> {
+        rb_self.check_not_flushed(ruby, first_row)?;
+        let value = CellValue::from_ruby(ruby, v)?;
+        let tables = rb_self.table_formats.borrow();
+        let format = Self::cell_format(&tables, first_row, first_col, format.map(|f| &*f.0));
         let default = rust_xlsxwriter::Format::new();
-        let merge_format = format.map_or(&default, |f| &f.0);
         rb_self.with_ws(|ws| {
-            ws.merge_range(first_row, first_col, last_row, last_col, "", merge_format)
-                .map_err(xerr)?;
-            put(ruby, ws, first_row, first_col, v, format)
+            // The value was checked when converted, so once the range is
+            // merged, writing it cannot fail.
+            ws.merge_range(
+                first_row,
+                first_col,
+                last_row,
+                last_col,
+                "",
+                format.unwrap_or(&default),
+            )
+            .map_err(xerr)?;
+            value.write(ws, first_row, first_col, format)
         })?;
         rb_self.advance(last_row);
+        rb_self.note_written(first_row);
         Ok(rb_self)
     }
 
@@ -878,20 +1069,19 @@ impl Worksheet {
         lc: u16,
         options: RHash,
     ) -> Result<Obj<Self>, Error> {
-        let nil = ruby.qnil().as_value();
-        let opt = |name: &str| options.get(ruby.to_symbol(name)).unwrap_or(nil);
         check_keys(
             ruby,
             options,
             &["type", "criteria", "value", "format", "colors"],
             "conditional_format",
         )?;
-        let format = Option::<&Format>::try_convert(opt("format"))?;
-        let value = opt("value");
+        let format = opt::<&Format>(ruby, options, "format")?;
+        let value = raw_opt(ruby, options, "value");
+        let criteria = raw_opt(ruby, options, "criteria");
         let kind = choice(
             ruby,
             "conditional format type",
-            opt("type"),
+            raw_opt(ruby, options, "type"),
             &[
                 ("cell", "cell"),
                 ("text", "text"),
@@ -900,86 +1090,69 @@ impl Worksheet {
                 ("color_scale", "color_scale"),
             ],
         )?;
-        rb_self.with_ws(|ws| {
-            let r = match kind {
-                "cell" => {
-                    let mut cf = ConditionalFormatCell::new().set_rule(cell_rule(
-                        ruby,
-                        opt("criteria"),
-                        value,
-                    )?);
-                    if let Some(f) = format {
-                        cf = cf.set_format(&f.0);
-                    }
-                    ws.add_conditional_format(fr, fc, lr, lc, &cf)
-                }
-                "text" => {
-                    let text = String::try_convert(value)?;
-                    let rule = match choice(
-                        ruby,
-                        "text criteria",
-                        opt("criteria"),
-                        &[
-                            ("contains", 0),
-                            ("not_contains", 1),
-                            ("begins_with", 2),
-                            ("ends_with", 3),
-                        ],
-                    )? {
-                        0 => ConditionalFormatTextRule::Contains(text),
-                        1 => ConditionalFormatTextRule::DoesNotContain(text),
-                        2 => ConditionalFormatTextRule::BeginsWith(text),
-                        _ => ConditionalFormatTextRule::EndsWith(text),
-                    };
-                    let mut cf = ConditionalFormatText::new().set_rule(rule);
-                    if let Some(f) = format {
-                        cf = cf.set_format(&f.0);
-                    }
-                    ws.add_conditional_format(fr, fc, lr, lc, &cf)
+        // Built before taking the lock: building converts Ruby values.
+        type AddRule = Box<dyn FnOnce(&mut rust_xlsxwriter::Worksheet) -> Result<(), XlsxError>>;
+        fn rule<T: ConditionalFormat + Send + Sync + 'static>(
+            (fr, fc, lr, lc): (u32, u16, u32, u16),
+            cf: T,
+        ) -> AddRule {
+            Box::new(move |ws| ws.add_conditional_format(fr, fc, lr, lc, &cf).map(|_| ()))
+        }
+        let range = (fr, fc, lr, lc);
+        let add_rule = match kind {
+            "cell" => {
+                let mut cf =
+                    ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?);
+                if let Some(f) = format {
+                    cf = cf.set_format(&*f.0);
                 }
-                "formula" => {
-                    let mut cf = ConditionalFormatFormula::new()
-                        .set_rule(String::try_convert(value)?.as_str());
-                    if let Some(f) = format {
-                        cf = cf.set_format(&f.0);
-                    }
-                    ws.add_conditional_format(fr, fc, lr, lc, &cf)
+                rule(range, cf)
+            }
+            "text" => {
+                let text = String::try_convert(value)?;
+                let text_rule = match choice(
+                    ruby,
+                    "text criteria",
+                    criteria,
+                    &[
+                        ("contains", 0),
+                        ("not_contains", 1),
+                        ("begins_with", 2),
+                        ("ends_with", 3),
+                    ],
+                )? {
+                    0 => ConditionalFormatTextRule::Contains(text),
+                    1 => ConditionalFormatTextRule::DoesNotContain(text),
+                    2 => ConditionalFormatTextRule::BeginsWith(text),
+                    _ => ConditionalFormatTextRule::EndsWith(text),
+                };
+                let mut cf = ConditionalFormatText::new().set_rule(text_rule);
+                if let Some(f) = format {
+                    cf = cf.set_format(&*f.0);
                 }
-                "data_bar" => {
-                    ws.add_conditional_format(fr, fc, lr, lc, &ConditionalFormatDataBar::new())
+                rule(range, cf)
+            }
+            "formula" => {
+                let mut cf =
+                    ConditionalFormatFormula::new().set_rule(String::try_convert(value)?.as_str());
+                if let Some(f) = format {
+                    cf = cf.set_format(&*f.0);
                 }
-                _ => {
-                    let colors = if opt("colors").is_nil() {
-                        3
-                    } else {
-                        u8::try_convert(opt("colors"))?
-                    };
-                    match colors {
-                        2 => ws.add_conditional_format(
-                            fr,
-                            fc,
-                            lr,
-                            lc,
-                            &ConditionalFormat2ColorScale::new(),
-                        ),
-                        3 => ws.add_conditional_format(
-                            fr,
-                            fc,
-                            lr,
-                            lc,
-                            &ConditionalFormat3ColorScale::new(),
-                        ),
-                        n => {
-                            return Err(Error::new(
-                                ruby.exception_arg_error(),
-                                format!("invalid colors {n}: use 2 or 3"),
-                            ))
-                        }
-                    }
+                rule(range, cf)
+            }
+            "data_bar" => rule(range, ConditionalFormatDataBar::new()),
+            _ => match opt::<u8>(ruby, options, "colors")?.unwrap_or(3) {
+                2 => rule(range, ConditionalFormat2ColorScale::new()),
+                3 => rule(range, ConditionalFormat3ColorScale::new()),
+                n => {
+                    return Err(Error::new(
+                        ruby.exception_arg_error(),
+                        format!("invalid colors {n}: use 2 or 3"),
+                    ))
                 }
-            };
-            r.map(|_| ()).map_err(xerr)
-        })?;
+            },
+        };
+        rb_self.with_ws(|ws| add_rule(ws).map_err(xerr))?;
         Ok(rb_self)
     }
 
@@ -993,8 +1166,6 @@ impl Worksheet {
         lc: u16,
         options: RHash,
     ) -> Result<Obj<Self>, Error> {
-        let nil = ruby.qnil().as_value();
-        let opt = |name: &str| options.get(ruby.to_symbol(name)).unwrap_or(nil);
         check_keys(
             ruby,
             options,
@@ -1009,12 +1180,13 @@ impl Worksheet {
             ],
             "data_validation",
         )?;
-        let (criteria, value) = (opt("criteria"), opt("value"));
+        let criteria = raw_opt(ruby, options, "criteria");
+        let value = raw_opt(ruby, options, "value");
         let dv = DataValidation::new();
         let mut dv = match choice(
             ruby,
             "data validation type",
-            opt("type"),
+            raw_opt(ruby, options, "type"),
             &[
                 ("list", "list"),
                 ("whole_number", "whole_number"),
@@ -1023,9 +1195,16 @@ impl Worksheet {
             ],
         )? {
             "list" => match RArray::from_value(value) {
-                Some(items) => dv
-                    .allow_list_strings(&items.to_vec::<String>()?)
-                    .map_err(xerr)?,
+                // Items are shown as text in the dropdown, so numbers and
+                // symbols are listed by their to_s.
+                Some(items) => {
+                    let mut labels = Vec::with_capacity(items.len());
+                    each_entry(items, |_, item| {
+                        labels.push(item.funcall::<_, _, String>("to_s", ())?);
+                        Ok(())
+                    })?;
+                    dv.allow_list_strings(&labels).map_err(xerr)?
+                }
                 None => dv
                     .allow_list_formula(rust_xlsxwriter::Formula::new(String::try_convert(value)?)),
             },
@@ -1042,9 +1221,8 @@ impl Worksheet {
             ("error_title", DataValidation::set_error_title),
             ("error_message", DataValidation::set_error_message),
         ] {
-            let text = opt(name);
-            if !text.is_nil() {
-                dv = set(dv, String::try_convert(text)?).map_err(xerr)?;
+            if let Some(text) = opt::<String>(ruby, options, name)? {
+                dv = set(dv, text).map_err(xerr)?;
             }
         }
         rb_self.with_ws(|ws| {
@@ -1079,8 +1257,6 @@ impl Worksheet {
         bytes: RString,
         options: RHash,
     ) -> Result<Obj<Self>, Error> {
-        let nil = ruby.qnil().as_value();
-        let opt = |name: &str| options.get(ruby.to_symbol(name)).unwrap_or(nil);
         check_keys(
             ruby,
             options,
@@ -1089,33 +1265,17 @@ impl Worksheet {
             ],
             "insert_image",
         )?;
-        let offset = |name: &str| -> Result<u32, Error> {
-            let v = opt(name);
-            if v.is_nil() {
-                Ok(0)
-            } else {
-                u32::try_convert(v)
-            }
-        };
         // SAFETY: the bytes are copied into the Image before any Ruby code runs.
         let mut image = Image::new_from_buffer(unsafe { bytes.as_slice() }).map_err(xerr)?;
-        let pixels = |name: &str| -> Result<Option<f64>, Error> {
-            let v = opt(name);
-            if v.is_nil() {
-                Ok(None)
-            } else {
-                f64::try_convert(v).map(Some)
-            }
-        };
-        let (width, height) = (pixels("width")?, pixels("height")?);
-        if !opt("scale").is_nil() {
+        let width = opt::<f64>(ruby, options, "width")?;
+        let height = opt::<f64>(ruby, options, "height")?;
+        if let Some(scale) = opt::<f64>(ruby, options, "scale")? {
             if width.is_some() || height.is_some() {
                 return Err(Error::new(
                     ruby.exception_arg_error(),
                     "pass either scale: or width:/height:, not both",
                 ));
             }
-            let scale = f64::try_convert(opt("scale"))?;
             image = image.set_scale_width(scale).set_scale_height(scale);
         } else if width.is_some() || height.is_some() {
             // Displayed size at scale 1, as rust_xlsxwriter computes it from the DPI.
@@ -1127,10 +1287,11 @@ impl Worksheet {
             let (sw, sh) = (scale_w.or(scale_h).unwrap(), scale_h.or(scale_w).unwrap());
             image = image.set_scale_width(sw).set_scale_height(sh);
         }
-        if !opt("alt_text").is_nil() {
-            image = image.set_alt_text(String::try_convert(opt("alt_text"))?);
+        if let Some(alt_text) = opt::<String>(ruby, options, "alt_text")? {
+            image = image.set_alt_text(alt_text);
         }
-        let (x, y) = (offset("x_offset")?, offset("y_offset")?);
+        let x = opt::<u32>(ruby, options, "x_offset")?.unwrap_or(0);
+        let y = opt::<u32>(ruby, options, "y_offset")?.unwrap_or(0);
         rb_self.with_ws(|ws| {
             ws.insert_image_with_offset(row, col, &image, x, y)
                 .map(|_| ())
@@ -1146,16 +1307,7 @@ impl Worksheet {
         col: u16,
         options: RHash,
     ) -> Result<Obj<Self>, Error> {
-        let nil = ruby.qnil().as_value();
         let arg_error = |msg: String| Error::new(ruby.exception_arg_error(), msg);
-        let text = |v: Value| -> Result<Option<String>, Error> {
-            if v.is_nil() {
-                Ok(None)
-            } else {
-                String::try_convert(v).map(Some)
-            }
-        };
-        let opt = |name: &str| options.get(ruby.to_symbol(name)).unwrap_or(nil);
         check_keys(
             ruby,
             options,
@@ -1165,41 +1317,47 @@ impl Worksheet {
             "insert_chart",
         )?;
 
-        let mut chart = Chart::new(choice(ruby, "chart type", opt("type"), CHART_TYPES)?);
-        let series = RArray::try_convert(opt("series"))?;
+        let chart_type = choice(
+            ruby,
+            "chart type",
+            raw_opt(ruby, options, "type"),
+            CHART_TYPES,
+        )?;
+        let mut chart = Chart::new(chart_type);
+        let series = RArray::try_convert(raw_opt(ruby, options, "series"))?;
         if series.is_empty() {
             return Err(arg_error(
                 "series: needs at least one { values:, categories:, name: } hash".into(),
             ));
         }
-        for s in series.into_iter() {
+        each_entry(series, |_, s| {
             let s = RHash::try_convert(s)?;
             check_keys(ruby, s, &["values", "categories", "name"], "chart series")?;
-            let get = |name: &str| s.get(ruby.to_symbol(name)).unwrap_or(nil);
-            let values = text(get("values"))?
+            let values = opt::<String>(ruby, s, "values")?
                 .ok_or_else(|| arg_error(format!("series {} needs values:", s.inspect())))?;
             let cs = chart.add_series().set_values(values.as_str());
-            if let Some(categories) = text(get("categories"))? {
+            if let Some(categories) = opt::<String>(ruby, s, "categories")? {
                 cs.set_categories(categories.as_str());
             }
-            if let Some(name) = text(get("name"))? {
+            if let Some(name) = opt::<String>(ruby, s, "name")? {
                 cs.set_name(name.as_str());
             }
-        }
-        if let Some(title) = text(opt("title"))? {
+            Ok(())
+        })?;
+        if let Some(title) = opt::<String>(ruby, options, "title")? {
             chart.title().set_name(title.as_str());
         }
-        if let Some(name) = text(opt("x_axis"))? {
+        if let Some(name) = opt::<String>(ruby, options, "x_axis")? {
             chart.x_axis().set_name(name.as_str());
         }
-        if let Some(name) = text(opt("y_axis"))? {
+        if let Some(name) = opt::<String>(ruby, options, "y_axis")? {
             chart.y_axis().set_name(name.as_str());
         }
-        if !opt("width").is_nil() {
-            chart.set_width(u32::try_convert(opt("width"))?);
+        if let Some(width) = opt::<u32>(ruby, options, "width")? {
+            chart.set_width(width);
         }
-        if !opt("height").is_nil() {
-            chart.set_height(u32::try_convert(opt("height"))?);
+        if let Some(height) = opt::<u32>(ruby, options, "height")? {
+            chart.set_height(height);
         }
         rb_self.with_ws(|ws| ws.insert_chart(row, col, &chart).map(|_| ()).map_err(xerr))?;
         Ok(rb_self)
@@ -1228,24 +1386,19 @@ impl Worksheet {
             ],
             "add_table",
         )?;
-        let nil = ruby.qnil().as_value();
-        let opt = |name: &str| options.get(ruby.to_symbol(name)).unwrap_or(nil);
-        let flag = |name: &str, default: bool| {
-            let v = opt(name);
-            if v.is_nil() {
-                default
-            } else {
-                v.to_bool()
-            }
+        // Ruby truthiness, as before: any non-nil, non-false value enables.
+        let flag = |name: &str, default: bool| -> Result<bool, Error> {
+            Ok(opt::<Value>(ruby, options, name)?.map_or(default, |v| v.to_bool()))
         };
         // The table writes its header row, which must not be flushed yet.
         rb_self.check_not_flushed(ruby, fr)?;
+        let total_row = flag("total_row", false)?;
         let mut table = Table::new()
-            .set_total_row(flag("total_row", false))
-            .set_banded_rows(flag("banded_rows", true))
-            .set_autofilter(flag("autofilter", true));
-        if !opt("columns").is_nil() {
-            let specs = RArray::try_convert(opt("columns"))?;
+            .set_total_row(total_row)
+            .set_banded_rows(flag("banded_rows", true)?)
+            .set_autofilter(flag("autofilter", true)?);
+        let mut column_formats = Vec::new();
+        if let Some(specs) = opt::<RArray>(ruby, options, "columns")? {
             let width = usize::from(lc.saturating_sub(fc)) + 1;
             if specs.len() != width {
                 return Err(Error::new(
@@ -1256,25 +1409,45 @@ impl Worksheet {
                     ),
                 ));
             }
-            let columns = specs
-                .into_iter()
-                .map(|v| table_column(ruby, v))
-                .collect::<Result<Vec<_>, _>>()?;
+            let mut columns = Vec::with_capacity(specs.len());
+            each_entry(specs, |i, v| {
+                let (column, format) = table_column(ruby, v)?;
+                columns.push(column);
+                if let Some(format) = format {
+                    column_formats.push((fc + i as u16, format));
+                }
+                Ok(())
+            })?;
             table = table.set_columns(&columns);
         }
-        if !opt("style").is_nil() {
-            table = table.set_style(choice(ruby, "table style", opt("style"), TABLE_STYLES)?);
+        if let Some(style) = opt::<Value>(ruby, options, "style")? {
+            table = table.set_style(choice(ruby, "table style", style, TABLE_STYLES)?);
         }
-        if !opt("name").is_nil() {
-            table = table.set_name(String::try_convert(opt("name"))?);
+        if let Some(name) = opt::<String>(ruby, options, "name")? {
+            table = table.set_name(name);
         }
         rb_self.with_ws(|ws| {
             ws.add_table(fr, fc, lr, lc, &table)
                 .map(|_| ())
                 .map_err(xerr)
         })?;
+        // Data rows: under the header, above the total row.
+        let data_rows = (fr + 1)..=lr.saturating_sub(u32::from(total_row));
+        rb_self
+            .table_formats
+            .borrow_mut()
+            .extend(
+                column_formats
+                    .into_iter()
+                    .map(|(col, format)| TableColumnFormat {
+                        rows: data_rows.clone(),
+                        col,
+                        format,
+                    }),
+            );
         // Continue appending under the header, so `<<` fills the table.
         rb_self.advance(fr);
+        rb_self.note_written(fr);
         Ok(rb_self)
     }
 
@@ -1295,17 +1468,14 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     wb.define_singleton_method("_new", function!(Workbook::new, 2))?;
     wb.define_method("_add_worksheet", method!(Workbook::add_worksheet, 1))?;
     wb.define_method("to_xlsx", method!(Workbook::to_xlsx, 0))?;
-    wb.define_method("save", method!(Workbook::save, 1))?;
+    wb.define_method("_save", method!(Workbook::save, 1))?;
     wb.define_method("_properties", method!(Workbook::set_properties, 1))?;
 
     let ws = module.define_class("Worksheet", ruby.class_object())?;
     ws.define_method("_write", method!(Worksheet::write, 4))?;
     ws.define_method("_append", method!(Worksheet::append, 2))?;
     ws.define_method("_column_width", method!(Worksheet::set_column_width, 3))?;
-    ws.define_method(
-        "_column_format",
-        method!(Worksheet::set_column_format, 3),
-    )?;
+    ws.define_method("_column_format", method!(Worksheet::set_column_format, 3))?;
     ws.define_method("_autofit", method!(Worksheet::autofit, 0))?;
     ws.define_method("autofilter", method!(Worksheet::autofilter, 4))?;
     ws.define_method("name", method!(Worksheet::name, 0))?;

data/ext/fast_xlsx/tests/ruby_suite.rs

@@ -0,0 +1,20 @@
+// Runs the Ruby test suite against this crate's current source.
+//
+// The extension's behaviour is tested from Ruby (test/), but cargo-mutants only
+// runs `cargo test`. This test rebuilds the extension from the (possibly
+// mutated) source and runs the Ruby suite, so a mutant counts as caught when a
+// Ruby test fails. The dev profile shares build artifacts with `cargo test`.
+use std::path::Path;
+use std::process::Command;
+
+#[test]
+fn ruby_test_suite_passes() {
+    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");
+    let status = Command::new("bundle")
+        .args(["exec", "rake", "compile", "test"])
+        .current_dir(&root)
+        .env("RB_SYS_CARGO_PROFILE", "dev")
+        .status()
+        .expect("could not run `bundle exec rake compile test`");
+    assert!(status.success(), "the Ruby test suite failed");
+}

data/lib/fast_xlsx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastXlsx
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/fast_xlsx.rb

@@ -45,7 +45,13 @@ module FastXlsx
   end
 
   # The native extension looks up FastXlsx::Error, so load it after Error is defined.
-  require "fast_xlsx/fast_xlsx"
+  # Precompiled gems ship one binary per Ruby version (fast_xlsx/3.4/fast_xlsx);
+  # a gem compiled on install has a single fast_xlsx/fast_xlsx.
+  begin
+    require "fast_xlsx/#{RUBY_VERSION[/\d+\.\d+/]}/fast_xlsx"
+  rescue LoadError
+    require "fast_xlsx/fast_xlsx"
+  end
 
   # Owns the worksheets; serialize with #to_xlsx or #save.
   class Workbook
@@ -78,6 +84,11 @@ module FastXlsx
       worksheets.find { |ws| ws.name == name }
     end
 
+    # path: a String, Pathname or anything responding to #to_path.
+    def save(path)
+      _save(File.path(path))
+    end
+
     # Document properties shown in Excel's File > Info: title:, subject:,
     # author:, manager:, company:, category:, keywords:, comments:, status:.
     # Later calls add to earlier ones.

data/sig/fast_xlsx.rbs

@@ -36,7 +36,7 @@ module FastXlsx
                      ?company: String, ?category: String, ?keywords: String,
                      ?comments: String, ?status: String) -> self
     def to_xlsx: () -> String
-    def save: (String path) -> void
+    def save: (String | _ToPath path) -> void
   end
 
   class Format

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Zac
@@ -48,6 +48,7 @@ files:
 - ext/fast_xlsx/build.rs
 - ext/fast_xlsx/extconf.rb
 - ext/fast_xlsx/src/lib.rs
+- ext/fast_xlsx/tests/ruby_suite.rs
 - lib/fast_xlsx.rb
 - lib/fast_xlsx/version.rb
 - sig/fast_xlsx.rbs