fast_xlsx 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14314a7af34dfb1bfd00bac2f8fde41c4fa03447020dfef48571055bdac3151d
-  data.tar.gz: 915ca1cd79de28ca34023af4d884eb9c6728bd86abd29aa19bd62ca08e3914fe
+  metadata.gz: 8326db5fb0c181c2c47af1f6b0d5799aa0bb69ff2d3b63d5286dbd1cd32fa2b8
+  data.tar.gz: 560335ade1b435b9084cb3d48e4e4b20d906140c4d2a6e243751d93d1eb01964
 SHA512:
-  metadata.gz: 346ed04a149c9f6201fdb84af8b5b1a5a1008a17ac1df8faaa26af8d500dc2e13ecd8eb55705638a99a27501d7ca757f08a50825c7faac4a4a2593fb556a94e5
-  data.tar.gz: 712d24c13ab60499f91795cdbdd4d3c251e41c6b30b60dc8c9e3d25aaa671da98710d128dd673c859ad2ec336c817d69da6a46ea5e9f7a8015025444db59bcef
+  metadata.gz: 360e7a3686eb4705527139fc7c50834046aa4d45d7e3e79e6f913475cb039de2e64119600a8c9a0e1147136be98a6776f8bbe8db267b67533e99c390fdaced4e
+  data.tar.gz: c23307efb6c2c0ceb1faef4336be02512f98cda7bff60b01324e614d82374247187ee1225a04c04a1cf9208d8b4abce3852a943f166f57f53801c743c4df1af3

data/.yardopts

@@ -0,0 +1,7 @@
+--markup markdown
+--no-private
+--hide-api private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-01
+
+### Added
+
+- API documentation: every public method has YARD docs (shown on rubydoc.info).
+
+### Changed
+
+- Errors follow one rule (see the README): a row or column outside the sheet raises `RangeError` (row 1,048,576, column 16,384 or a row of more than 16,384 cells raised `FastXlsx::Error` or `ArgumentError`); a reversed range or single-cell merge raises `ArgumentError` (was `FastXlsx::Error`); a header or footer over 255 characters raises `FastXlsx::Error` like other text over Excel's limits (was `ArgumentError`); a negative or NaN image size, font size or margin raises `ArgumentError` (was written into the file or ignored); `zoom` converts numbers with `to_int` like other arguments (`zoom(150.9)` raised `TypeError`); `column_width` outside 0..255 and `row_height` outside 0..409 raise `ArgumentError` (a negative one hid the column or row).
+- Date and time cells written with a format that has no `num_format` (e.g. `append(row, format: bold)`) get the default date format added, instead of showing as serial numbers. This applies to a cell's own format, a table column's and `column_format`'s; a format with a `num_format` is used as is.
+
+## [0.4.0] - 2026-10-01
+
+### Changed
+
+- Dates and times written without a format now get `yyyy-mm-dd` (`Date`) or `yyyy-mm-dd hh:mm:ss` (`Time`, `DateTime`) instead of showing as serial numbers. A cell's own format, its table column's and `column_format` still win. Applying the format makes writing date-heavy data about 15% slower, the same as passing a date format yourself.
+
 ## [0.3.0] - 2026-10-01
 
 ### Changed

data/README.md

@@ -82,6 +82,8 @@ ws.write(1, 2, Date.today, date)                         # format one cell
 
 Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
 
+Dates and times are shown as `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`. A format without a `num_format` (yours, a table column's or `column_format`'s) keeps its look and gets that date format added, so `append(row, format: bold)` gives bold dates; a format with a `num_format` is used as is.
+
 ### Columns and filters
 
 ```ruby
@@ -250,8 +252,8 @@ Values are mapped by type:
 |---|---|
 | `Integer`, `Float`, any `Numeric` | number |
 | `String` | string |
-| `Time` | number (Excel serial date, local time) |
-| `Date`, `DateTime` | number (Excel serial date, own offset) |
+| `Time`, `DateTime` | date and time (`yyyy-mm-dd hh:mm:ss` unless formatted), in its own offset |
+| `Date` | date (`yyyy-mm-dd` unless formatted) |
 | `FastXlsx::Formula.new("SUM(A1:A9)")` | formula |
 | `FastXlsx::URL.new("https://…")`, `URL.new(url, text: "Title")` | hyperlink (optionally showing other text) |
 | `FastXlsx::RichString.new(["Total: ", bold], "1,234")` | text with a format per segment |
@@ -261,7 +263,16 @@ Values are mapped by type:
 
 `<<` and `concat` append after the last row written to that worksheet. In `:constant` / `:low` memory mode rows are written to disk as you go, so fill each worksheet top to bottom.
 
-Errors from the writer (invalid sheet names, writes to rows already on disk, …) raise `FastXlsx::Error`.
+### Errors
+
+| Error | Raised for |
+|---|---|
+| `TypeError` | an argument of the wrong type, e.g. a String where a row number goes |
+| `RangeError` | a row or column outside the sheet (1,048,576 × 16,384), or a negative count (an infinite Float raises `FloatDomainError`, a `RangeError`) |
+| `ArgumentError` | the right type but a value that isn't allowed: an unknown option or symbol, an invalid color or cell reference, a reversed range or single-cell merge, a size or margin that is negative, NaN or beyond Excel's limits |
+| `FastXlsx::Error` | what the workbook can't do: duplicate or invalid names, writing to rows already on disk, overlapping merges, hiding the sheet Excel opens on, text over Excel's limits (cells, URLs, headers and footers), unsupported images |
+
+Numbers are converted like Ruby's own methods do (`to_int`), so `1.9` as a row is row `1`.
 
 ## Performance
 
@@ -273,17 +284,17 @@ Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; x
 
 | Library | Time | vs fastest | Ruby objects allocated |
 |---|---:|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **69 ms** | 1.0x | 7 |
-| **fast_xlsx** (`memory: :low`) | **78 ms** | 1.1x | 7 |
-| **fast_xlsx** | **80 ms** | 1.2x | 10 |
-| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 171 ms | 2.5x | 561,728 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 194 ms | 2.8x | 20,079 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 228 ms | 3.3x | 320,076 |
-| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 583 ms | 8.4x | 1,483,899 |
-| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 691 ms | 10.0x | 745,122 |
-| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2650 ms | 38.3x | 8,700,448 |
-
-All outputs are 681–750 KB.
+| **fast_xlsx** (`memory: :constant`) | **77 ms** | 1.0x | 7 |
+| **fast_xlsx** (`memory: :low`) | **86 ms** | 1.1x | 7 |
+| **fast_xlsx** | **89 ms** | 1.1x | 10 |
+| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 183 ms | 2.4x | 561,728 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 200 ms | 2.6x | 20,079 |
+| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 238 ms | 3.1x | 320,076 |
+| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 608 ms | 7.8x | 1,483,899 |
+| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 689 ms | 8.9x | 745,122 |
+| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2755 ms | 35.6x | 8,700,448 |
+
+All outputs are 689–750 KB.
 
 ### Memory
 
@@ -321,7 +332,12 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb f
 bundle add fast_xlsx
 ```
 
-Precompiled gems are built for common platforms; other platforms need a Rust toolchain to install. Requires CRuby 3.3+; JRuby and TruffleRuby are not supported because this is a native extension.
+### Support and versioning
+
+- **Ruby:** CRuby 3.3 and later. A Ruby version is dropped only after it reaches its end of life, and only in a minor release. JRuby and TruffleRuby are not supported (this is a native extension).
+- **Precompiled gems:** Linux (x86_64 and aarch64, glibc and musl; ARM musl), macOS (arm64 and x86_64) and Windows (x64). Before each release the Linux x86_64, macOS arm64 and Windows gems are installed and loaded on Ruby 3.3, 3.4 and 4.0. Other platforms build from source and need a Rust toolchain.
+- **Versions:** from 1.0, [Semantic Versioning](https://semver.org): no breaking API change before 2.0. Until then a minor release (0.x.0) can change behaviour; the [changelog](CHANGELOG.md) lists every change under "Changed".
+- **Output:** `.xlsx` files that open in Excel 2007 and later, LibreOffice and Google Sheets. Updating rust_xlsxwriter can change the bytes of the file but not what it contains.
 
 ## Development
 

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.3.0)
+    fast_xlsx (0.5.0)
       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.3.0)
+  fast_xlsx (0.5.0)
   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,5 +1,6 @@
 use std::cell::{Cell, RefCell};
 use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::LazyLock;
 use std::sync::{Arc, Mutex};
 
 use magnus::{
@@ -33,9 +34,43 @@ static FORMULA: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "Formula")
 static URL: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "URL"));
 static RICH_STRING: Lazy<RClass> = Lazy::new(|ruby| fast_xlsx_const(ruby, "RichString"));
 
+// A row or column outside the sheet is a RangeError, like a negative one
+// (which fails converting to an unsigned number before reaching the writer).
 fn xerr(e: XlsxError) -> Error {
     let ruby = Ruby::get().unwrap();
-    Error::new(ruby.get_inner(&ERROR), e.to_string())
+    let class = match e {
+        XlsxError::RowColumnLimitError => ruby.exception_range_error(),
+        // Values that aren't allowed, like a reversed range.
+        XlsxError::RowColumnOrderError | XlsxError::MergeRangeSingleCell => {
+            ruby.exception_arg_error()
+        }
+        _ => ruby.get_inner(&ERROR),
+    };
+    Error::new(class, e.to_string())
+}
+
+// Excel's limits that rust_xlsxwriter doesn't check: a negative width or
+// height hides the column or row, a larger one is capped or invalid.
+// A size that must be a finite number above 0 (NaN or a negative one would
+// be written into the file as is).
+fn check_positive(ruby: &Ruby, what: &str, size: f64) -> Result<f64, Error> {
+    if size.is_finite() && size > 0.0 {
+        return Ok(size);
+    }
+    Err(Error::new(
+        ruby.exception_arg_error(),
+        format!("invalid {what} {size}: use a number above 0"),
+    ))
+}
+
+fn check_size(ruby: &Ruby, what: &str, size: f64, max: f64) -> Result<(), Error> {
+    if (0.0..=max).contains(&size) {
+        return Ok(());
+    }
+    Err(Error::new(
+        ruby.exception_arg_error(),
+        format!("invalid {what} {size}: use 0..{max}"),
+    ))
 }
 
 type Shared = Arc<Mutex<rust_xlsxwriter::Workbook>>;
@@ -112,12 +147,14 @@ struct Worksheet {
     table_formats: RefCell<Vec<TableColumnFormat>>,
     // Merged ranges as (first_row, first_col, last_row, last_col).
     merges: RefCell<Vec<(u32, u16, u32, u16)>>,
+    // Formats given with column_format: (first, last, style).
+    formatted_columns: RefCell<Vec<(u16, u16, Arc<Style>)>>,
 }
 
 struct TableColumnFormat {
     rows: std::ops::RangeInclusive<u32>,
     col: u16,
-    format: Arc<rust_xlsxwriter::Format>,
+    format: Arc<Style>,
 }
 
 impl Workbook {
@@ -179,6 +216,7 @@ impl Workbook {
             flushes_rows: self.constant_memory || self.low_memory,
             table_formats: RefCell::new(Vec::new()),
             merges: RefCell::new(Vec::new()),
+            formatted_columns: RefCell::new(Vec::new()),
         })
     }
 
@@ -297,11 +335,13 @@ enum CellValue {
     Empty,
     Text(String),
     Number(f64),
+    // An Excel serial date; true when it has a time of day (Time, DateTime).
+    Date(f64, bool),
     Bool(bool),
     Formula(String),
     Url(String, Option<String>),
     // RichString segments; None means the default font.
-    Rich(Vec<(Option<Arc<rust_xlsxwriter::Format>>, String)>),
+    Rich(Vec<(Option<Arc<Style>>, String)>),
 }
 
 impl CellValue {
@@ -315,7 +355,7 @@ impl CellValue {
         } 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)?)
+            CellValue::Date(excel_time(v)?, true)
         } 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)) {
@@ -333,7 +373,8 @@ impl CellValue {
             })?;
             CellValue::Rich(parts)
         } else if v.respond_to("jd", false)? {
-            CellValue::Number(excel_date(v)?)
+            // Date has no #hour; DateTime does.
+            CellValue::Date(excel_date(v)?, v.respond_to("hour", false)?)
         } else {
             CellValue::Text(v.funcall("to_s", ())?)
         };
@@ -341,6 +382,14 @@ impl CellValue {
         Ok(value)
     }
 
+    // Some(has a time of day) for date cells.
+    fn date_kind(&self) -> Option<bool> {
+        match self {
+            CellValue::Date(_, time) => Some(*time),
+            _ => None,
+        }
+    }
+
     // 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> {
@@ -371,7 +420,7 @@ impl CellValue {
         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::Number(n) | CellValue::Date(n, _) => emit(ws, row, col, *n, format),
             CellValue::Bool(b) => emit(ws, row, col, *b, format),
             CellValue::Formula(f) => emit(
                 ws,
@@ -391,7 +440,7 @@ impl CellValue {
                 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()))
+                    .map(|(f, text)| (f.as_deref().map_or(&default, |s| &s.format), text.as_str()))
                     .collect();
                 match format {
                     Some(f) => ws.write_rich_string_with_format(row, col, &rich, f),
@@ -562,7 +611,7 @@ fn check_header_footer(ruby: &Ruby, what: &str, text: &str) -> Result<(), Error>
     let len = expanded.chars().count();
     if len > 255 {
         return Err(Error::new(
-            ruby.exception_arg_error(),
+            ruby.get_inner(&ERROR),
             format!("{what} is {len} characters; Excel allows 255"),
         ));
     }
@@ -693,10 +742,7 @@ const TABLE_TOTALS: &[(&str, TableFunction)] = &[
 
 // A table column: a header String, or { header:, total:, total_label:, format: }.
 // 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> {
+fn table_column(ruby: &Ruby, v: Value) -> Result<(TableColumn, Option<Arc<Style>>), Error> {
     let Some(spec) = RHash::from_value(v) else {
         return Ok((TableColumn::new().set_header(String::try_convert(v)?), None));
     };
@@ -716,7 +762,7 @@ fn table_column(
     }
     let format = opt::<&Format>(ruby, spec, "format")?.map(|f| f.0.clone());
     if let Some(f) = &format {
-        column = column.set_format(&**f);
+        column = column.set_format(&f.format);
     }
     Ok((column, format))
 }
@@ -761,11 +807,52 @@ const BORDERS: &[(&str, FormatBorder)] = &[
 ];
 
 #[magnus::wrap(class = "FastXlsx::Format", free_immediately)]
-struct Format(Arc<rust_xlsxwriter::Format>);
+struct Format(Arc<Style>);
+
+// A Format as written: the format itself, and for one without a num_format,
+// copies with the default date formats added, used for date cells (Excel
+// shows a date with no number format as its serial number).
+struct Style {
+    format: rust_xlsxwriter::Format,
+    date: Option<rust_xlsxwriter::Format>,
+    date_time: Option<rust_xlsxwriter::Format>,
+}
+
+const DATE_FORMAT: &str = "yyyy-mm-dd";
+const DATE_TIME_FORMAT: &str = "yyyy-mm-dd hh:mm:ss";
+
+impl Style {
+    fn new(format: rust_xlsxwriter::Format, has_num_format: bool) -> Self {
+        let with =
+            |num_format: &str| (!has_num_format).then(|| format.clone().set_num_format(num_format));
+        Style {
+            date: with(DATE_FORMAT),
+            date_time: with(DATE_TIME_FORMAT),
+            format,
+        }
+    }
+
+    // The date variant for a date cell (`time`: it has a time of day), if
+    // this format has no num_format of its own.
+    fn for_date(&self, time: bool) -> Option<&rust_xlsxwriter::Format> {
+        if time {
+            self.date_time.as_ref()
+        } else {
+            self.date.as_ref()
+        }
+    }
+
+    // What a value is written with: `date` is Some(has time) for date cells.
+    fn pick(&self, date: Option<bool>) -> &rust_xlsxwriter::Format {
+        date.and_then(|time| self.for_date(time))
+            .unwrap_or(&self.format)
+    }
+}
 
 impl Format {
     fn new(ruby: &Ruby, options: RHash) -> Result<Self, Error> {
         let mut f = rust_xlsxwriter::Format::new();
+        let mut has_num_format = false;
         options.foreach(|key: Symbol, value: Value| {
             let taken = std::mem::take(&mut f);
             f = match &*key.name()? {
@@ -813,8 +900,15 @@ impl Format {
                 "locked" => taken.set_unlocked(),
                 "hidden" if value.to_bool() => taken.set_hidden(),
                 "border_color" => taken.set_border_color(color(ruby, value)?),
-                "num_format" => taken.set_num_format(String::try_convert(value)?),
-                "font_size" => taken.set_font_size(f64::try_convert(value)?),
+                "num_format" => {
+                    has_num_format = true;
+                    taken.set_num_format(String::try_convert(value)?)
+                }
+                "font_size" => taken.set_font_size(check_positive(
+                    ruby,
+                    "font_size",
+                    f64::try_convert(value)?,
+                )?),
                 "font_name" => taken.set_font_name(String::try_convert(value)?),
                 "font_color" => taken.set_font_color(color(ruby, value)?),
                 "bg_color" => taken.set_background_color(color(ruby, value)?),
@@ -855,7 +949,7 @@ impl Format {
             };
             Ok(ForEach::Continue)
         })?;
-        Ok(Format(Arc::new(f)))
+        Ok(Format(Arc::new(Style::new(f, has_num_format))))
     }
 }
 
@@ -878,7 +972,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<Arc<rust_xlsxwriter::Format>>),
+    Same(Option<Arc<Style>>),
     PerCell(RArray),
 }
 
@@ -892,7 +986,7 @@ impl RowFormat {
         }
     }
 
-    fn at(&self, col: usize) -> Result<Option<Arc<rust_xlsxwriter::Format>>, Error> {
+    fn at(&self, col: usize) -> Result<Option<Arc<Style>>, Error> {
         match self {
             RowFormat::Same(f) => Ok(f.clone()),
             RowFormat::PerCell(formats) => Ok(Option::<&Format>::try_convert(
@@ -934,20 +1028,42 @@ 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>(
+    // The format a value is written with: its own, else its table column's.
+    // A date cell takes that format's date variant (when it has no
+    // num_format); with neither, its column_format's date variant, or the
+    // default date format when the column has no format. Other cells without
+    // one get None, so rust_xlsxwriter applies any column format itself.
+    fn format_for<'a>(
         tables: &'a [TableColumnFormat],
+        columns: &'a [(u16, u16, Arc<Style>)],
         row: u32,
         col: u16,
-        own: Option<&'a rust_xlsxwriter::Format>,
+        own: Option<&'a Style>,
+        value: &CellValue,
     ) -> Option<&'a rust_xlsxwriter::Format> {
-        own.or_else(|| {
+        static DEFAULTS: LazyLock<Style> =
+            LazyLock::new(|| Style::new(rust_xlsxwriter::Format::new(), false));
+        let date = value.date_kind();
+        let style = own.or_else(|| {
             tables
                 .iter()
                 .rev()
                 .find(|t| t.col == col && t.rows.contains(&row))
                 .map(|t| &*t.format)
-        })
+        });
+        if let Some(style) = style {
+            return Some(style.pick(date));
+        }
+        let time = date?;
+        match columns
+            .iter()
+            .rev()
+            .find(|(first, last, _)| (*first..=*last).contains(&col))
+        {
+            // None when it has a num_format: rust_xlsxwriter applies it.
+            Some((_, _, style)) => style.for_date(time),
+            None => DEFAULTS.for_date(time),
+        }
     }
 
     fn write_row(
@@ -963,7 +1079,7 @@ impl Worksheet {
         each_entry(cells, |i, v| {
             if i >= MAX_COLS {
                 return Err(Error::new(
-                    ruby.exception_arg_error(),
+                    ruby.exception_range_error(),
                     format!("too many columns: Excel allows {MAX_COLS}"),
                 ));
             }
@@ -972,11 +1088,13 @@ impl Worksheet {
             Ok(())
         })?;
         let tables = self.table_formats.borrow();
+        let columns = self.formatted_columns.borrow();
         self.with_ws(|ws| {
             // 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());
+                let format =
+                    Self::format_for(&tables, &columns, row, *col, format.as_deref(), value);
                 value.write(ws, row, *col, format)?;
             }
             Ok(())
@@ -1020,12 +1138,13 @@ impl Worksheet {
         rb_self.check_not_flushed(ruby, row)?;
         let value = CellValue::from_ruby(ruby, v)?;
         let tables = rb_self.table_formats.borrow();
+        let columns = rb_self.formatted_columns.borrow();
         rb_self.with_ws(|ws| {
             value.write(
                 ws,
                 row,
                 col,
-                Self::cell_format(&tables, row, col, format.map(|f| &*f.0)),
+                Self::format_for(&tables, &columns, row, col, format.map(|f| &*f.0), &value),
             )
         })?;
         rb_self.advance(row);
@@ -1057,8 +1176,15 @@ impl Worksheet {
         Ok(rb_self)
     }
 
-    fn set_column_width(&self, first: u16, last: u16, width: f64) -> Result<(), Error> {
-        self.with_ws(|ws| {
+    fn set_column_width(
+        ruby: &Ruby,
+        rb_self: &Self,
+        first: u16,
+        last: u16,
+        width: f64,
+    ) -> Result<(), Error> {
+        check_size(ruby, "column width", width, 255.0)?;
+        rb_self.with_ws(|ws| {
             ws.set_column_range_width(first, last, width)
                 .map(|_| ())
                 .map_err(xerr)
@@ -1067,10 +1193,14 @@ impl Worksheet {
 
     fn set_column_format(&self, first: u16, last: u16, format: &Format) -> Result<(), Error> {
         self.with_ws(|ws| {
-            ws.set_column_range_format(first, last, &format.0)
+            ws.set_column_range_format(first, last, &format.0.format)
                 .map(|_| ())
                 .map_err(xerr)
-        })
+        })?;
+        self.formatted_columns
+            .borrow_mut()
+            .push((first, last, format.0.clone()));
+        Ok(())
     }
 
     fn autofilter(
@@ -1101,7 +1231,13 @@ impl Worksheet {
         Ok(rb_self)
     }
 
-    fn set_row_height(rb_self: Obj<Self>, row: u32, height: f64) -> Result<Obj<Self>, Error> {
+    fn set_row_height(
+        ruby: &Ruby,
+        rb_self: Obj<Self>,
+        row: u32,
+        height: f64,
+    ) -> Result<Obj<Self>, Error> {
+        check_size(ruby, "row height", height, 409.0)?;
         rb_self.with_ws(|ws| ws.set_row_height(row, height).map(|_| ()).map_err(xerr))?;
         Ok(rb_self)
     }
@@ -1122,17 +1258,32 @@ impl Worksheet {
         })
     }
 
-    // Inches; a negative value keeps the current margin.
+    // Inches; None keeps the current margin.
+    #[allow(clippy::too_many_arguments)]
     fn set_margins(
-        &self,
-        left: f64,
-        right: f64,
-        top: f64,
-        bottom: f64,
-        header: f64,
-        footer: f64,
+        ruby: &Ruby,
+        rb_self: &Self,
+        left: Option<f64>,
+        right: Option<f64>,
+        top: Option<f64>,
+        bottom: Option<f64>,
+        header: Option<f64>,
+        footer: Option<f64>,
     ) -> Result<(), Error> {
-        self.with_ws(|ws| {
+        // rust_xlsxwriter keeps a margin given as a negative number.
+        let inches = |margin: Option<f64>| -> Result<f64, Error> {
+            match margin {
+                None => Ok(-1.0),
+                Some(m) if m.is_finite() && m >= 0.0 => Ok(m),
+                Some(m) => Err(Error::new(
+                    ruby.exception_arg_error(),
+                    format!("invalid margin {m}: use 0 or more inches"),
+                )),
+            }
+        };
+        let (left, right, top) = (inches(left)?, inches(right)?, inches(top)?);
+        let (bottom, header, footer) = (inches(bottom)?, inches(header)?, inches(footer)?);
+        rb_self.with_ws(|ws| {
             ws.set_margins(left, right, top, bottom, header, footer);
             Ok(())
         })
@@ -1193,7 +1344,15 @@ impl Worksheet {
         }
         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 columns = rb_self.formatted_columns.borrow();
+        let format = Self::format_for(
+            &tables,
+            &columns,
+            first_row,
+            first_col,
+            format.map(|f| &*f.0),
+            &value,
+        );
         let default = rust_xlsxwriter::Format::new();
         rb_self.with_ws(|ws| {
             // The value was checked when converted, so once the range is
@@ -1260,7 +1419,7 @@ impl Worksheet {
                 let mut cf =
                     ConditionalFormatCell::new().set_rule(cell_rule(ruby, criteria, value)?);
                 if let Some(f) = format {
-                    cf = cf.set_format(&*f.0);
+                    cf = cf.set_format(&f.0.format);
                 }
                 rule(range, cf)
             }
@@ -1284,7 +1443,7 @@ impl Worksheet {
                 };
                 let mut cf = ConditionalFormatText::new().set_rule(text_rule);
                 if let Some(f) = format {
-                    cf = cf.set_format(&*f.0);
+                    cf = cf.set_format(&f.0.format);
                 }
                 rule(range, cf)
             }
@@ -1292,7 +1451,7 @@ impl Worksheet {
                 let mut cf =
                     ConditionalFormatFormula::new().set_rule(String::try_convert(value)?.as_str());
                 if let Some(f) = format {
-                    cf = cf.set_format(&*f.0);
+                    cf = cf.set_format(&f.0.format);
                 }
                 rule(range, cf)
             }
@@ -1423,9 +1582,14 @@ impl Worksheet {
         )?;
         // 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 width = opt::<f64>(ruby, options, "width")?;
-        let height = opt::<f64>(ruby, options, "height")?;
-        if let Some(scale) = opt::<f64>(ruby, options, "scale")? {
+        let positive = |name: &str| -> Result<Option<f64>, Error> {
+            opt::<f64>(ruby, options, name)?
+                .map(|v| check_positive(ruby, name, v))
+                .transpose()
+        };
+        let width = positive("width")?;
+        let height = positive("height")?;
+        if let Some(scale) = positive("scale")? {
             if width.is_some() || height.is_some() {
                 return Err(Error::new(
                     ruby.exception_arg_error(),
@@ -1634,16 +1798,7 @@ impl Worksheet {
         Ok(rb_self)
     }
 
-    fn zoom(ruby: &Ruby, rb_self: Obj<Self>, percent: Value) -> Result<Obj<Self>, Error> {
-        // Integers only: converting would quietly truncate 150.9.
-        let percent = Integer::from_value(percent)
-            .ok_or_else(|| {
-                Error::new(
-                    ruby.exception_type_error(),
-                    format!("zoom must be an Integer, got {}", percent.inspect()),
-                )
-            })?
-            .to_i64()?;
+    fn zoom(ruby: &Ruby, rb_self: Obj<Self>, percent: i64) -> Result<Obj<Self>, Error> {
         // rust_xlsxwriter only prints a warning for these.
         if !(10..=400).contains(&percent) {
             return Err(Error::new(

data/ext/fast_xlsx/tests/ruby_suite.rs

@@ -14,9 +14,9 @@ fn ruby_test_suite_passes() {
         .args(["exec", "rake", "compile", "test"])
         .current_dir(&root)
         .env("RB_SYS_CARGO_PROFILE", "dev")
-        // The suite needs a few CPU seconds; a mutant that loops forever is
-        // stopped instead of running on after cargo-mutants gives up on it.
-        .env("FAST_XLSX_TEST_CPU_SECONDS", "120")
+        // The suite takes seconds; a mutant that hangs (a loop or a deadlock)
+        // is killed instead of running on after cargo-mutants gives up on it.
+        .env("FAST_XLSX_TEST_TIMEOUT_SECONDS", "120")
         .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,6 @@
 # frozen_string_literal: true
 
 module FastXlsx
-  VERSION = "0.3.0"
+  # The gem version.
+  VERSION = "0.5.0"
 end

data/lib/fast_xlsx.rb

@@ -3,21 +3,48 @@
 require_relative "fast_xlsx/version"
 
 # Fast .xlsx writer backed by rust_xlsxwriter.
+#
+# @example
+#   wb = FastXlsx::Workbook.new
+#   ws = wb.add_worksheet("Report")
+#   ws << ["id", "name", "created_at"]
+#   ws.concat(records.map { |r| [r.id, r.name, r.created_at] })
+#   wb.save("report.xlsx")
+#
+# Rows and columns are 0-based. Errors: TypeError for an argument of the wrong
+# type, RangeError for a row or column outside the sheet, ArgumentError for a
+# value that isn't allowed, {FastXlsx::Error} for what the workbook can't do.
 module FastXlsx
+  # Raised for what the workbook can't do: duplicate or invalid names, writing
+  # to rows already on disk, overlapping merges, text over Excel's limits, ...
   class Error < StandardError; end
 
-  # Cell value written as an Excel formula, e.g. Formula.new("SUM(A1:A9)").
+  # A cell value written as an Excel formula.
+  #
+  # @!attribute [r] expression
+  #   @return [String] the formula, without the leading "="
+  # @example
+  #   ws << [1, 2, FastXlsx::Formula.new("SUM(A1:B1)")]
   Formula = Data.define(:expression) do
     def initialize(expression:)
       super(expression: expression.to_s)
     end
   end
 
-  # Cell value written as a hyperlink, e.g. URL.new("https://example.com").
-  # text: shown in the cell instead of the URL itself.
+  # A cell value written as a hyperlink.
+  #
+  # @!attribute [r] url
+  #   @return [String] http(s)://, mailto:, file:// or internal:Sheet2!A1
+  # @!attribute [r] text
+  #   @return [String, nil] shown in the cell instead of the URL
+  # @example
+  #   FastXlsx::URL.new("https://example.com")
+  #   FastXlsx::URL.new("https://example.com/report/42", text: "Q3 report")
   # Subclassed (not a Data.define block) so .new can call super, which lets it
   # accept URL.new(url, text: ...) as well as the usual Data forms.
   class URL < Data.define(:url, :text) # rubocop:disable Style/DataInheritance
+    # @overload new(url, text = nil)
+    # @overload new(url:, text: nil)
     def self.new(*args, **kwargs)
       raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..2)" if args.size > 2
 
@@ -32,11 +59,18 @@ module FastXlsx
     end
   end
 
-  # Text with a format per segment, e.g. RichString.new(["Total: ", bold], "1,234").
-  # Each segment is a String (default font) or [String, Format].
+  # Text with a format per segment.
+  #
+  # @example
+  #   bold = FastXlsx::Format.new(bold: true)
+  #   ws << [FastXlsx::RichString.new(["Total: ", bold], "1,234")]
   class RichString
+    # @return [Array<Array(String, Format)>] [text, format or nil] per segment
     attr_reader :segments
 
+    # @param parts [Array<String, Array(String, Format)>] each a String (default
+    #   font) or [String, Format]
+    # @raise [ArgumentError] when no segment is given
     def initialize(*parts)
       raise ArgumentError, "RichString needs at least one segment" if parts.empty?
 
@@ -53,15 +87,31 @@ module FastXlsx
     require "fast_xlsx/fast_xlsx"
   end
 
-  # Owns the worksheets; serialize with #to_xlsx or #save.
+  # Owns the worksheets; serialize with {#to_xlsx} or {#save}.
+  #
+  # @!method to_xlsx
+  #   The workbook as an .xlsx file. Runs without Ruby's global lock, so
+  #   other threads keep running meanwhile.
+  #   @return [String] binary
+  #   @raise [FastXlsx::Error] e.g. duplicate defined names
+  #
+  # @!method define_name(name, formula)
+  #   A defined name: "Rate" for the whole workbook, "Sheet1!Sales" for one
+  #   sheet. Duplicates and unknown sheets are reported when saving.
+  #   @param name [String]
+  #   @param formula [String] e.g. "=0.96" or "=Sheet1!$A$1:$A$9"
+  #   @return [self]
+  #   @raise [FastXlsx::Error] for a name Excel doesn't allow
   class Workbook
+    # Accepted memory: modes.
     MEMORY_MODES = %i[standard constant low].freeze
 
-    # memory: :standard keeps every cell in memory until saving. :constant and
-    # :low write each finished row to disk, so each worksheet must be filled
-    # top to bottom. :constant stores strings inline (memory stays flat); :low
-    # keeps Excel's shared string table (memory grows with the number of
-    # unique strings, output is standard).
+    # @param memory [Symbol] :standard keeps every cell in memory until saving.
+    #   :constant and :low write each finished row to disk, so each worksheet
+    #   must be filled top to bottom: :constant stores strings inline (memory
+    #   stays flat), :low keeps Excel's shared string table (memory grows with
+    #   the number of unique strings).
+    # @raise [ArgumentError] for an unknown mode
     def self.new(memory: :standard)
       unless MEMORY_MODES.include?(memory)
         raise ArgumentError, "unknown memory mode #{memory.inspect} (expected one of #{MEMORY_MODES.join(", ")})"
@@ -70,28 +120,40 @@ module FastXlsx
       _new(memory == :constant, memory == :low)
     end
 
+    # @param name [String, nil] nil takes the first free "SheetN"
+    # @return [Worksheet]
+    # @raise [FastXlsx::Error] for an invalid name or one already used
+    #   (names ignore case)
     def add_worksheet(name = nil)
       _add_worksheet(name).tap { |ws| worksheets << ws }
     end
 
     # The same Worksheet objects add_worksheet returned, so their append
     # position is shared.
+    # @return [Array<Worksheet>]
     def worksheets
       @worksheets ||= []
     end
 
+    # @param name [String]
+    # @return [Worksheet, nil]
     def worksheet(name)
       worksheets.find { |ws| ws.name == name }
     end
 
-    # path: a String, Pathname or anything responding to #to_path.
+    # Writes the .xlsx file. Runs without Ruby's global lock, like {#to_xlsx}.
+    # @param path [String, Pathname, #to_path]
+    # @return [nil]
     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.
+    # Document properties shown in Excel's File > Info. Later calls add to
+    # earlier ones.
+    # @param fields [Hash{Symbol => String}] title:, subject:, author:,
+    #   manager:, company:, category:, keywords:, comments:, status:
+    # @return [self]
+    # @raise [ArgumentError] for an unknown field
     def properties(**fields)
       merged = (@properties || {}).merge(fields)
       _properties(merged) # validates before anything is remembered
@@ -100,7 +162,73 @@ module FastXlsx
     end
   end
 
-  # Cell writer for one sheet; create with Workbook#add_worksheet.
+  # Cell writer for one sheet; create with {Workbook#add_worksheet}.
+  #
+  # A cell is (row, col) or a reference like "B2". A range is four 0-based
+  # numbers (first_row, first_col, last_row, last_col), a reference like
+  # "A1:D10", or rows and columns as Integers or Ranges, e.g. (0..9, 0..3).
+  #
+  # @!method write(*cell, value, format = nil)
+  #   Writes one cell.
+  #   @overload write(row, col, value, format = nil)
+  #   @overload write(ref, value, format = nil)
+  #   @param value [Numeric, String, Time, Date, DateTime, true, false, nil,
+  #     Formula, URL, RichString, #to_s] dates get yyyy-mm-dd (hh:mm:ss) unless
+  #     the format has a num_format
+  #   @param format [Format, nil]
+  #   @return [self]
+  #
+  # @!method <<(values)
+  #   Appends a row after the last row written.
+  #   @param values [Array] cell values, as for {#write}
+  #   @return [self]
+  #
+  # @!method concat(rows)
+  #   Appends several rows.
+  #   @param rows [Array<Array>]
+  #   @return [self]
+  #
+  # @!method next_row
+  #   @return [Integer] the row {#<<} writes next
+  #
+  # @!method name
+  #   @return [String]
+  #
+  # @!method row_height(row, height)
+  #   @param height [Numeric] points, 0..409
+  #   @return [self]
+  #   @raise [ArgumentError] for a height outside 0..409
+  #
+  # @!method page_breaks(rows)
+  #   Starts a printed page before each of these rows.
+  #   @param rows [Array<Integer>]
+  #   @return [self]
+  #
+  # @!method vertical_page_breaks(cols)
+  #   Starts a printed page before each of these columns.
+  #   @param cols [Array<Integer>]
+  #   @return [self]
+  #
+  # @!method activate
+  #   Makes Excel open on this sheet (un-hiding it if hidden).
+  #   @return [self]
+  #
+  # @!method hide
+  #   @return [self]
+  #   @raise [FastXlsx::Error] for the sheet Excel opens on (the first one
+  #     unless another is activated)
+  #
+  # @!method zoom(percent)
+  #   @param percent [Integer, #to_int] 10..400
+  #   @return [self]
+  #
+  # @!method tab_color(color)
+  #   @param color [String, Integer] "#RRGGBB" or 0xRRGGBB
+  #   @return [self]
+  #
+  # @!method hide_gridlines
+  #   Hides the gridlines on screen (see {#page_setup} for printing).
+  #   @return [self]
   class Worksheet
     # write(row, col, value, format = nil) or write("B2", value, format = nil)
     # is native: the (row, col) form runs once per cell, so it skips a Ruby
@@ -112,11 +240,18 @@ module FastXlsx
     end
     private :_write_ref
 
+    # Appends a row after the last row written.
+    # @param values [Array] cell values, as for {#write}
+    # @param format [Format, Array<Format, nil>, nil] one for every cell, or
+    #   one per cell
+    # @return [self]
     def append(values, format: nil)
       _append(values, format)
     end
 
-    # columns: a 0-based column index or a Range of them. width is in characters.
+    # @param columns [Integer, Range<Integer>]
+    # @param width [Numeric] characters, 0..255
+    # @return [self]
     def column_width(columns, width)
       range = CellRange.bounds(columns)
       _column_width(*range, width)
@@ -126,89 +261,131 @@ module FastXlsx
       self
     end
 
-    # Sizes columns to the data written so far. Widths set with
-    # column_width are kept.
+    # Sizes columns to the data written so far (in :constant / :low mode, the
+    # rows still in memory). Widths set with {#column_width} are kept.
+    # @return [self]
     def autofit
       _autofit
       @fixed_widths&.each { |bounds, width| _column_width(*bounds, width) }
       self
     end
 
-    # The methods below take a cell range in any of these styles:
-    #   (first_row, first_col, last_row, last_col)  four 0-based numbers
-    #   ("A1:D10") or ("B2")                        an Excel reference
-    #   (rows, cols)                                Integers or Ranges, e.g. (0..9, 0..3)
-
     # Filter buttons on the range's first row.
+    # @param range a cell range (see {Worksheet})
+    # @return [self]
     def autofilter(*range)
       _autofilter(*CellRange.split(range).first)
     end
 
     # Merges the range and writes value (any cell type) into its first cell.
+    # @overload merge_range(*range, value, format = nil)
+    # @return [self]
+    # @raise [FastXlsx::Error] when it overlaps an earlier merge
     def merge_range(*args)
       range, (value, format) = CellRange.split(args, 1..2)
       _merge_range(*range, value, format)
     end
 
-    # Highlights cells in the range by rule. type: :cell, :text, :formula,
-    # :data_bar or :color_scale; see the README for each type's options.
+    # Highlights cells in the range by rule; see the README for each type's
+    # options.
+    # @param range a cell range (see {Worksheet})
+    # @param type [Symbol] :cell, :text, :formula, :data_bar or :color_scale
+    # @option options [Symbol] :criteria e.g. :>, :between, :contains
+    # @option options [Numeric, String, Array] :value
+    # @option options [Format] :format
+    # @option options [Integer] :colors 2 or 3 (:color_scale)
+    # @return [self]
     def conditional_format(*range, type:, **)
       _conditional_format(*CellRange.split(range).first, { type: type, ** })
     end
 
-    # Restricts what can be entered in the range. type: :list, :whole_number,
-    # :decimal or :text_length; see the README for the options.
+    # Restricts what can be entered in the range; see the README.
+    # @param range a cell range (see {Worksheet})
+    # @param type [Symbol] :list, :whole_number, :decimal or :text_length
+    # @option options [Symbol] :criteria e.g. :>, :between
+    # @option options [Numeric, String, Array] :value
+    # @option options [String] :input_title, :input_message, :error_title, :error_message
+    # @return [self]
     def data_validation(*range, type:, **)
       _data_validation(*CellRange.split(range).first, { type: type, ** })
     end
 
-    # Adds a comment (Excel "note") to a cell.
+    # Adds a comment (an Excel "note") to a cell.
+    # @overload write_comment(*cell, text, author: nil)
+    # @return [self]
     def write_comment(*args, author: nil)
       row, col, (text, *) = CellRange.cell(args, 1..1)
       _write_comment(row, col, text, author)
     end
 
-    # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the
-    # cell. source is a file path or an IO (anything responding to #read).
-    # Options: scale: or width:/height: (pixels), x_offset:, y_offset: (pixels), alt_text:.
+    # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the cell.
+    # @overload insert_image(*cell, source, **options)
+    #   @param source [String, #read] a file path or an IO
+    #   @option options [Numeric] :scale
+    #   @option options [Numeric] :width, :height pixels (the other keeps the ratio)
+    #   @option options [Integer] :x_offset, :y_offset pixels
+    #   @option options [String] :alt_text
+    # @return [self]
+    # @raise [FastXlsx::Error] for data that isn't a supported image
     def insert_image(*args, **)
       row, col, (source, *) = CellRange.cell(args, 1..1)
       bytes = source.respond_to?(:read) ? source.read : File.binread(source)
       _insert_image(row, col, bytes, { ** })
     end
 
-    # Inserts a chart with its top-left corner in the cell. series is an Array
-    # of { values:, categories:, name: } with Excel ranges such as
-    # "Sheet1!$B$2:$B$13". Options: title:, x_axis:, y_axis:, width:, height:.
+    # Inserts a chart with its top-left corner in the cell.
+    # @param cell (row, col) or "B2"
+    # @param type [Symbol] :area, :bar, :column, :line, :pie, :doughnut,
+    #   :radar, :scatter, and the stacked variants
+    # @param series [Array<Hash>] { values:, categories:, name: } with ranges
+    #   such as "Sheet1!$B$2:$B$13"
+    # @option options [String] :title, :x_axis, :y_axis
+    # @option options [Integer] :width, :height pixels
+    # @return [self]
     def insert_chart(*cell, type:, series:, **)
       row, col, = CellRange.cell(cell)
       _insert_chart(row, col, { type: type, series: series, ** })
     end
 
     # Turns the range (header row included, total row too when total_row: true)
-    # into an Excel table. columns: header Strings or { header:, total:,
-    # total_label:, format: }; other options: style:, name:, total_row:,
-    # banded_rows:, autofilter:.
+    # into an Excel table. Rows appended later under the header fill it.
+    # @param range a cell range (see {Worksheet})
+    # @option options [Array<String, Hash>] :columns header Strings or
+    #   { header:, total:, total_label:, format: }
+    # @option options [Symbol] :style e.g. :medium2
+    # @option options [String] :name
+    # @option options [Boolean] :total_row, :banded_rows, :autofilter
+    # @return [self]
     def add_table(*range, **)
       _add_table(*CellRange.split(range).first, { ** })
     end
 
-    # Printed page header/footer using Excel codes such as "&CPage &P of &N".
-    # margin: is in inches.
+    # Printed page header, using Excel codes such as "&CPage &P of &N".
+    # @param margin [Numeric, nil] inches
+    # @return [self]
     def page_header(text, margin: nil)
       _page_header(text)
       margin ? margins(header: margin) : self
     end
 
+    # Printed page footer; see {#page_header}.
+    # @return [self]
     def page_footer(text, margin: nil)
       _page_footer(text)
       margin ? margins(footer: margin) : self
     end
 
-    # Printing: landscape:, paper: (:letter, :legal, :tabloid, :a3, :a4, :a5 or
-    # Excel's paper number), fit_width:/fit_height: (pages; 0 or left out =
-    # as many as needed), repeat_rows:/repeat_columns: (an index or Range,
-    # printed on every page), print_area: (any cell range), gridlines:.
+    # Printing options.
+    # @option options [Boolean] :landscape
+    # @option options [Symbol, Integer] :paper :letter, :legal, :tabloid, :a3,
+    #   :a4, :a5 or Excel's paper number (0: the printer's default)
+    # @option options [Integer] :fit_width, :fit_height pages (0 or left out:
+    #   as many as needed)
+    # @param repeat_rows [Integer, Range, nil] printed on every page
+    # @param repeat_columns [Integer, Range, nil] printed on every page
+    # @param print_area a cell range: "A1:D100" or [first_row, first_col, last_row, last_col]
+    # @option options [Boolean] :gridlines print the gridlines
+    # @return [self]
     def page_setup(repeat_rows: nil, repeat_columns: nil, print_area: nil, **options)
       options[:repeat_rows] = CellRange.bounds(repeat_rows) if repeat_rows
       options[:repeat_columns] = CellRange.bounds(repeat_columns) if repeat_columns
@@ -218,39 +395,56 @@ module FastXlsx
     end
 
     # Print margins in inches; margins not given keep their current value.
+    # @return [self]
+    # @raise [ArgumentError] for a negative or NaN margin
     def margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
-      _margins(*[left, right, top, bottom, header, footer].map { |m| m || -1.0 })
+      _margins(left, right, top, bottom, header, footer)
       self
     end
 
-    # Outline group with an expand/collapse button. rows: a 0-based row index
-    # or a Range; grouping rows already grouped nests them (up to 7 levels).
-    # collapsed: true hides them until expanded.
+    # Outline group with an expand/collapse button. Grouping rows already
+    # grouped nests them (up to 7 levels).
+    # @param rows [Integer, Range<Integer>]
+    # @param collapsed [Boolean] hidden until expanded
+    # @return [self]
+    # @raise [FastXlsx::Error] in :constant / :low memory mode, which can't
+    #   write outline levels for rows
     def group_rows(rows, collapsed: false)
       _group_rows(*CellRange.bounds(rows), collapsed)
     end
 
+    # Outline group of columns; see {#group_rows}. Works in every memory mode.
+    # @param columns [Integer, Range<Integer>]
+    # @return [self]
     def group_columns(columns, collapsed: false)
       _group_columns(*CellRange.bounds(columns), collapsed)
     end
 
     # Keeps the rows above and the columns left of the cell visible while
     # scrolling: (1, 0) or "A2" freezes the first row.
+    # @return [self]
     def freeze_panes(*cell)
       _freeze_panes(*CellRange.cell(cell).first(2))
       self
     end
 
     # Locks the sheet against editing. Cells whose format has locked: false
-    # stay editable. allow: actions users may still take, any of :format_cells,
-    # :format_columns, :format_rows, :insert_columns, :insert_rows,
-    # :insert_links, :delete_columns, :delete_rows, :sort, :use_autofilter,
-    # :use_pivot_tables, :edit_scenarios, :edit_objects.
+    # stay editable. Calling it again replaces the password and actions.
+    # @param password [String, nil] stops editing in Excel; it doesn't
+    #   encrypt the file
+    # @param allow [Symbol, Array<Symbol>] actions users may still take:
+    #   :format_cells, :format_columns, :format_rows, :insert_columns,
+    #   :insert_rows, :insert_links, :delete_columns, :delete_rows, :sort,
+    #   :use_autofilter, :use_pivot_tables, :edit_scenarios, :edit_objects
+    # @return [self]
     def protect(password: nil, allow: [])
       _protect(password, Array(allow))
     end
 
     # Default format for cells in these columns that are written without one.
+    # @param columns [Integer, Range<Integer>]
+    # @param format [Format]
+    # @return [self]
     def column_format(columns, format)
       _column_format(*CellRange.bounds(columns), format)
       self
@@ -260,6 +454,7 @@ module FastXlsx
   # Cell ranges in the styles Worksheet methods accept: four 0-based numbers,
   # an Excel reference ("A1:D10", "B2"), or rows and columns as Integers or
   # Ranges.
+  # @api private
   module CellRange
     REF = /\A\$?([A-Za-z]{1,3})\$?([1-9]\d*)\z/ # ASCII only: /i also matches the Kelvin sign
     FORMS = 'a range is (first_row, first_col, last_row, last_col), "A1:D10" or (rows, cols)'
@@ -279,8 +474,8 @@ module FastXlsx
       case args
       in [Numeric, Numeric, Numeric, Numeric, *rest] then [args.first(4), rest]
       in [String => ref, *rest] then [excel(ref), rest]
-      in [Integer | Range => rows, Integer | Range => cols, *rest]
-        [rows_and_cols(rows, cols), rest]
+      in [Integer | Range, Integer | Range, *rest] # (no "=> name" here: YARD can't parse it)
+        [rows_and_cols(args[0], args[1]), rest]
       else
         raise ArgumentError, "expected a cell range, got #{args.inspect}; #{FORMS}"
       end
@@ -351,8 +546,19 @@ module FastXlsx
   end
   private_constant :CellRange
 
-  # Cell style, e.g. Format.new(bold: true). Pass to Worksheet#write.
+  # A cell style; pass it to {Worksheet#write}, {Worksheet#append} and the
+  # other methods that take a format. See the README for every option.
+  #
+  # @example
+  #   header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+  #   money  = FastXlsx::Format.new(num_format: "#,##0.00")
   class Format
+    # @param options [Hash] bold:, italic:, underline:, strikeout:,
+    #   font_script:, font_size:, font_name:, font_color:, bg_color:,
+    #   num_format:, align:, valign:, text_wrap:, rotation:, indent:, shrink:,
+    #   border:, border_left:, border_right:, border_top:, border_bottom:,
+    #   border_color:, locked:, hidden:
+    # @raise [ArgumentError] for an unknown option or an invalid value
     def self.new(**options)
       # Apply border: first so border_left: etc. override it whatever the order.
       options = { border: options[:border], **options.except(:border) } if options.key?(:border)

data/sig/fast_xlsx.rbs

@@ -81,7 +81,7 @@ module FastXlsx
     def page_footer: (String text, ?margin: Numeric?) -> self
     def activate: () -> self
     def hide: () -> self
-    def zoom: (Integer percent) -> self
+    def zoom: (int percent) -> self
     def tab_color: (String | Integer color) -> self
     def hide_gridlines: () -> self
     def page_setup: (?landscape: bool, ?paper: :letter | :legal | :tabloid | :a3 | :a4 | :a5 | Integer,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Zac
@@ -32,6 +32,7 @@ extensions:
 - ext/fast_xlsx/extconf.rb
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - Cargo.lock
 - Cargo.toml