RubyGems - fast_xlsx - Versions diffs - 0.2.0 → 0.4.0 - Mend

fast_xlsx 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85532243a1cd812798374658f4b5673ea9cda88586e876b76281f99cbd8dd065
-  data.tar.gz: 67747bd17f6f4ecf7ed9041767498de5d0d3d416922250578bf5b87c0d41ad1c
+  metadata.gz: '045446748368a71ae4010c17da8b09d0a23ac2c3e9bdb0d63bf5ed54bf04221c'
+  data.tar.gz: 213cafbae07330020d41e179fc8473a92e5eab5da4cc595fb60e62f3764fa21e
 SHA512:
-  metadata.gz: 75d89ae4b66fce6129f09d8ba18d1766571fe740e3069eebc9be5334dbd254f5a75dbccf56c3d250a6a0deacfa109d86971b0974289d0822467b8971d6b3d40c
-  data.tar.gz: e9ff13d9d4014d5b2034ffdff56897d87ff00df6688145c6ae4bc637690323389ccd53c4c8e651e5da5177fb06ba2f141f96a3fe9dc60e0949ce69672984edb4
+  metadata.gz: dce10715e570fffa0c5ff69899065c07a3f34f6beb8a9597c095a39f271991d11f05239e62135d853063759a016518fca9f61113e0ae8991c97663a62b4066ff
+  data.tar.gz: d87800324af3edab7719ce665cb836d213456102833e04351cfdec508ef063e4c4b16aa80e298ab764262b6a4c6c97e8b2844b48b97639a3e005572369ecf2ce

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,27 @@
 ## [Unreleased]
+## [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
+- `to_xlsx` and `save` release Ruby's global lock while building and compressing the file, so other threads (e.g. in Puma or Sidekiq) keep running. An interrupt (Ctrl-C, `Timeout`, `Thread#raise`) takes effect once the save finishes.
+- Saving is 20-30% faster: files are compressed with zlib-rs instead of C zlib (which also drops the `libz-sys` dependency). Adding rows is about 15% faster from building with link-time optimisation.
+### Added
+- `write`, `write_comment`, `insert_image`, `insert_chart` and `freeze_panes` also take a cell reference such as `"B2"`. `write` is now native, which makes it about 15% faster.
+- `Worksheet#zoom`, `#tab_color`, `#hide_gridlines`, `#activate`, `#hide`, and `#page_setup` (orientation, paper size, fit to pages, rows/columns repeated on every page, print area, printed gridlines).
+### Fixed
+- A `merge_range` that overlaps an earlier merge raises before writing anything; before, it also blanked the earlier merge's value.
 ## [0.2.0] - 2026-10-01
 ### Added

data/Cargo.lock CHANGED Viewed

@@ -25,7 +25,7 @@ dependencies = [
  "quote",
  "regex",
  "rustc-hash",
- "shlex 1.3.0",
+ "shlex",
  "syn",
 ]
@@ -41,16 +41,6 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
-[[package]]
-name = "cc"
-version = "1.5.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
-dependencies = [
- "find-msvc-tools",
- "shlex 2.0.1",
-]
 [[package]]
 name = "cexpr"
 version = "0.6.0"
@@ -124,20 +114,12 @@ version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
-[[package]]
-name = "find-msvc-tools"
-version = "0.1.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484"
 [[package]]
 name = "flate2"
 version = "1.1.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"
 dependencies = [
- "crc32fast",
- "libz-sys",
  "zlib-rs",
 ]
@@ -205,17 +187,6 @@ dependencies = [
  "windows-link",
 ]
-[[package]]
-name = "libz-sys"
-version = "1.1.29"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85bc9657773828b90eeb625adff10eeac83cc21bbfd8e23a03eaa8a33c9e28d9"
-dependencies = [
- "cc",
- "pkg-config",
- "vcpkg",
-]
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -279,12 +250,6 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
-[[package]]
-name = "pkg-config"
-version = "0.3.34"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -415,12 +380,6 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
-[[package]]
-name = "shlex"
-version = "2.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 [[package]]
 name = "simd-adler32"
 version = "0.3.10"
@@ -463,12 +422,6 @@ version = "1.0.26"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"
-[[package]]
-name = "vcpkg"
-version = "0.2.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
 [[package]]
 name = "windows-link"
 version = "0.2.1"

data/Cargo.toml CHANGED Viewed

@@ -11,3 +11,7 @@ resolver = "2"
 # harder to debug if something goes wrong. It's recommended to keep debug
 # symbols in the release build so that you can debug the final binary if needed.
 debug = true
+# One codegen unit and link-time optimisation across crates: adding rows is
+# about 15% faster, at the cost of a slower gem build.
+lto = "fat"
+codegen-units = 1

data/README.md CHANGED Viewed

@@ -18,6 +18,7 @@ ws = wb.add_worksheet("Report")                  # later: wb.worksheet("Report")
 ws << ["id", "name", "created_at"]                # append a row
 ws.concat(records.map { |r| [r.id, r.name, r.created_at] })  # append many rows in one call
 ws.write(0, 5, 42)                                # write a single cell (row, col, value)
+ws.write("F1", 42)                                # or by its Excel reference
 wb.properties(title: "Q3 report", author: "Zac", keywords: "Confidential") # File > Info in Excel
 wb.save("report.xlsx")                            # or wb.to_xlsx => binary String
@@ -81,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 written without a format get `yyyy-mm-dd` or `yyyy-mm-dd hh:mm:ss`; a table column's format or `column_format` wins over that. A format you pass replaces it, so give date cells one with a `num_format` (e.g. `Format.new(bold: true, num_format: "yyyy-mm-dd")`), or Excel shows the serial number.
 ### Columns and filters
 ```ruby
@@ -91,6 +94,22 @@ ws.autofit                        # size other columns to the data written so fa
 ws.autofilter("A1:D101")          # filter buttons on A1:D101
 ```
+### Sheet view and printing
+```ruby
+ws.zoom(150)                # 10..400 percent
+ws.tab_color("#C00000")
+ws.hide_gridlines
+ws.activate                 # Excel opens on this sheet (un-hides it if hidden)
+other.hide                  # the sheet Excel opens on can't be hidden: activate another one first
+ws.page_setup(landscape: true, paper: :a4,  # or :letter, :legal, :tabloid, :a3, :a5, Excel's paper number, 0 = printer default
+              fit_width: 1,                 # 1 page wide, as many pages tall as needed
+              repeat_rows: 0,               # print the header row on every page (an index or a Range)
+              print_area: "A1:D100",        # any cell range style
+              gridlines: true)              # print the gridlines
+```
 ### Cell ranges
 `autofilter`, `merge_range`, `conditional_format`, `data_validation` and `add_table` take a range in any of these styles:
@@ -102,6 +121,8 @@ ws.autofilter(0..100, 0..3)   # rows and columns, each an Integer or a Range
 ws.merge_range(0, 0..3, "Q3 report", title) # row 1, columns A–D
 ```
+Methods that take one cell (`write`, `write_comment`, `insert_image`, `insert_chart`, `freeze_panes`) take `(row, col)` or a reference like `"B2"`.
 `autofit` only sees rows still in memory, so in `:constant` / `:low` memory mode it ignores rows already written to disk; set widths with `column_width` instead.
 ### Layout
@@ -231,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 |
@@ -254,17 +275,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`) | **92 ms** | 1.0x | 7 |
-| **fast_xlsx** (`memory: :low`) | **101 ms** | 1.1x | 7 |
-| **fast_xlsx** | **102 ms** | 1.1x | 10 |
-| [xlsxtream](https://github.com/felixbuenemann/xlsxtream) 3.1 | 181 ms | 2.0x | 561,728 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 (constant_memory) | 202 ms | 2.2x | 20,079 |
-| [fast_excel](https://github.com/Paxa/fast_excel) 0.5 | 240 ms | 2.6x | 320,076 |
-| [write_xlsx](https://github.com/cxn03651/write_xlsx) 1.15 | 610 ms | 6.7x | 1,483,899 |
-| [caxlsx](https://github.com/caxlsx/caxlsx) 4.5 | 678 ms | 7.4x | 745,122 |
-| [rubyXL](https://github.com/weshatheleopard/rubyXL) 3.4 | 2624 ms | 28.6x | 8,700,448 |
-All outputs are 702–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
@@ -272,14 +293,18 @@ All outputs are 702–750 KB.
 | Library | Unique strings | Repeated strings |
 |---|---:|---:|
-| **fast_xlsx** (`memory: :constant`) | **+2 MB** | **+2 MB** |
-| **fast_xlsx** (`memory: :low`) | +62 MB | **+2 MB** |
-| **fast_xlsx** | +270 MB | +217 MB |
-| fast_excel 0.5 (constant_memory) | +10 MB | +10 MB |
-| fast_excel 0.5 | +183 MB | +151 MB |
+| **fast_xlsx** (`memory: :constant`) | **+1 MB** | **+1 MB** |
+| **fast_xlsx** (`memory: :low`) | +61 MB | **+1 MB** |
+| **fast_xlsx** | +271 MB | +217 MB |
+| fast_excel 0.5 (constant_memory) | +10 MB | +9 MB |
+| fast_excel 0.5 | +182 MB | +151 MB |
 The `:standard` mode uses more memory than fast_excel's: when saving, rust_xlsxwriter assembles each worksheet's XML in memory (so several worksheets can be built in parallel) instead of streaming it from a temp file. Use `memory: :constant` or `memory: :low` for large exports.
+### Threads
+Most of the time goes into saving (building the XML and compressing it). `to_xlsx` and `save` do that without holding Ruby's global lock, so in a threaded server (Puma, Sidekiq) other threads keep running while a large export is saved. An interrupt (Ctrl-C, `Timeout`, `Thread#raise`) takes effect once the save finishes.
 ### Reproduce
 ```bash

data/bench/Gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.2.0)
+    fast_xlsx (0.4.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.2.0)
+  fast_xlsx (0.4.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/Cargo.toml CHANGED Viewed

@@ -12,7 +12,9 @@ crate-type = ["cdylib"]
 [dependencies]
 magnus = "0.9"
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
-rust_xlsxwriter = { version = "0.99.1", features = ["constant_memory", "zlib"] }
+# No "zlib" feature: without it zip compresses with zlib-rs, which saves
+# 20-30% faster than the system zlib (and needs no C library).
+rust_xlsxwriter = { version = "0.99.1", features = ["constant_memory"] }
 [build-dependencies]
 rb-sys-env = "0.2.2"

data/ext/fast_xlsx/src/lib.rs CHANGED Viewed

@@ -1,4 +1,6 @@
 use std::cell::{Cell, RefCell};
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::LazyLock;
 use std::sync::{Arc, Mutex};
 use magnus::{
@@ -39,9 +41,56 @@ fn xerr(e: XlsxError) -> Error {
 type Shared = Arc<Mutex<rust_xlsxwriter::Workbook>>;
+// Runs `f` without Ruby's global lock, so other Ruby threads run meanwhile.
+// `f` must not touch any Ruby object, and must release the workbook mutex
+// before returning: a Ruby thread waiting on that mutex holds the lock this
+// thread then needs back.
+//
+// Uses the "2" variant: rb_thread_call_without_gvl raises pending interrupts
+// (Thread#raise, Timeout, Ctrl-C) by longjmp-ing over these Rust frames,
+// which skips their destructors. This one never raises; if an interrupt is
+// already pending it returns without calling `f`, which then runs with the
+// lock held. Either way Ruby raises the interrupt after the method returns.
+// Without an unblocking function, an interrupt waits for `f` to finish.
+fn without_gvl<R>(f: impl FnOnce() -> R) -> R {
+    unsafe extern "C" fn call<F: FnOnce() -> R, R>(
+        data: *mut std::ffi::c_void,
+    ) -> *mut std::ffi::c_void {
+        let (f, result) = &mut *(data as *mut (Option<F>, Option<std::thread::Result<R>>));
+        // A panic must not unwind into Ruby's C code; it is resumed below.
+        *result = Some(std::panic::catch_unwind(std::panic::AssertUnwindSafe(
+            f.take().unwrap(),
+        )));
+        std::ptr::null_mut()
+    }
+    fn run<F: FnOnce() -> R, R>(f: F) -> R {
+        let mut data: (Option<F>, Option<std::thread::Result<R>>) = (Some(f), None);
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl2(
+                Some(call::<F, R>),
+                &mut data as *mut _ as *mut std::ffi::c_void,
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        let Some(result) = data.1 else {
+            // An interrupt was pending, so `call` never ran.
+            return (data.0.take().unwrap())();
+        };
+        match result {
+            Ok(result) => result,
+            Err(panic) => std::panic::resume_unwind(panic),
+        }
+    }
+    run(f)
+}
 #[magnus::wrap(class = "FastXlsx::Workbook", free_immediately)]
 struct Workbook {
     inner: Shared,
+    // Index of the sheet Excel opens on (0 unless one is activated), shared
+    // with the worksheets: it can't be hidden.
+    active: Arc<AtomicUsize>,
     constant_memory: bool,
     low_memory: bool,
 }
@@ -50,6 +99,7 @@ struct Workbook {
 struct Worksheet {
     wb: Shared,
     index: usize,
+    active: Arc<AtomicUsize>,
     // Where << / append write next.
     next_row: Cell<u32>,
     // Highest row with cells written. In :constant / :low mode rows above it
@@ -61,6 +111,10 @@ struct Worksheet {
     // 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>>,
+    // Merged ranges as (first_row, first_col, last_row, last_col).
+    merges: RefCell<Vec<(u32, u16, u32, u16)>>,
+    // Column ranges given a format with column_format.
+    formatted_columns: RefCell<Vec<(u16, u16)>>,
 }
 struct TableColumnFormat {
@@ -73,6 +127,7 @@ impl Workbook {
     fn new(constant_memory: bool, low_memory: bool) -> Self {
         Workbook {
             inner: Arc::new(Mutex::new(rust_xlsxwriter::Workbook::new())),
+            active: Arc::new(AtomicUsize::new(0)),
             constant_memory,
             low_memory,
         }
@@ -121,25 +176,27 @@ impl Workbook {
         Ok(Worksheet {
             wb: self.inner.clone(),
             index: wb.worksheets().len() - 1,
+            active: self.active.clone(),
             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()),
+            merges: RefCell::new(Vec::new()),
+            formatted_columns: RefCell::new(Vec::new()),
         })
     }
+    // Saving (XML and compression) can take a while, so it runs without
+    // Ruby's global lock. The mutex guard is dropped inside the closure.
     fn to_xlsx(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
-        let buf = rb_self
-            .inner
-            .lock()
-            .unwrap()
-            .save_to_buffer()
-            .map_err(xerr)?;
+        let inner = &rb_self.inner;
+        let buf = without_gvl(|| inner.lock().unwrap().save_to_buffer()).map_err(xerr)?;
         Ok(ruby.str_from_slice(&buf))
     }
     fn save(&self, path: String) -> Result<(), Error> {
-        self.inner.lock().unwrap().save(path).map_err(xerr)
+        let inner = &self.inner;
+        without_gvl(|| inner.lock().unwrap().save(path).map(|_| ())).map_err(xerr)
     }
     // "Name" for the whole workbook, "Sheet1!Name" for one sheet. Duplicate
@@ -229,8 +286,9 @@ fn emit<T: IntoExcelData>(
 // Excel's limit on the text in a cell.
 const MAX_CHARS: usize = 32_767;
-// Excel's column count.
+// Excel's column and row counts.
 const MAX_COLS: usize = 16_384;
+const MAX_ROWS: u32 = 1_048_576;
 // 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
@@ -243,6 +301,8 @@ 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>),
@@ -261,7 +321,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)) {
@@ -279,7 +339,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", ())?)
         };
@@ -287,6 +348,20 @@ impl CellValue {
         Ok(value)
     }
+    // The format for a value written without one: without a number format
+    // Excel shows a date as its serial number.
+    fn default_format(&self) -> Option<&'static rust_xlsxwriter::Format> {
+        static DATE: LazyLock<rust_xlsxwriter::Format> =
+            LazyLock::new(|| rust_xlsxwriter::Format::new().set_num_format("yyyy-mm-dd"));
+        static DATE_TIME: LazyLock<rust_xlsxwriter::Format> =
+            LazyLock::new(|| rust_xlsxwriter::Format::new().set_num_format("yyyy-mm-dd hh:mm:ss"));
+        match self {
+            CellValue::Date(_, false) => Some(&DATE),
+            CellValue::Date(_, true) => Some(&DATE_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> {
@@ -317,7 +392,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,
@@ -686,6 +761,16 @@ const PROTECTION_ALLOW: &[(&str, ProtectionFlag)] = &[
     ("edit_objects", |o| &mut o.edit_objects),
 ];
+// Excel's paper size codes; page_setup also takes the number itself.
+const PAPER_SIZES: &[(&str, u8)] = &[
+    ("letter", 1),
+    ("tabloid", 3),
+    ("legal", 5),
+    ("a3", 8),
+    ("a4", 9),
+    ("a5", 11),
+];
 const BORDERS: &[(&str, FormatBorder)] = &[
     ("thin", FormatBorder::Thin),
     ("medium", FormatBorder::Medium),
@@ -886,6 +971,28 @@ impl Worksheet {
         })
     }
+    // The format a value is written with: its own, else its table column's,
+    // else its type's default (dates) unless column_format covers the column,
+    // whose format rust_xlsxwriter applies to cells written without one.
+    fn format_for<'a>(
+        &self,
+        tables: &'a [TableColumnFormat],
+        row: u32,
+        col: u16,
+        own: Option<&'a rust_xlsxwriter::Format>,
+        value: &CellValue,
+    ) -> Option<&'a rust_xlsxwriter::Format> {
+        Self::cell_format(tables, row, col, own).or_else(|| {
+            value.default_format().filter(|_| {
+                !self
+                    .formatted_columns
+                    .borrow()
+                    .iter()
+                    .any(|&(first, last)| (first..=last).contains(&col))
+            })
+        })
+    }
     fn write_row(
         &self,
         ruby: &Ruby,
@@ -912,7 +1019,7 @@ impl Worksheet {
             // 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, row, *col, format.as_deref(), value);
                 value.write(ws, row, *col, format)?;
             }
             Ok(())
@@ -922,6 +1029,29 @@ impl Worksheet {
         Ok(())
     }
+    // Worksheet#write. The (row, col, value, format = nil) form is handled
+    // here rather than in a Ruby wrapper, since it runs once per cell; the
+    // rest ("B2", or a wrong argument count) goes to Ruby's _write_ref.
+    fn write_any(ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Obj<Self>, Error> {
+        let index = |i: usize| args.get(i).and_then(|v| Integer::from_value(*v));
+        if let (3 | 4, Some(row), Some(col)) = (args.len(), index(0), index(1)) {
+            let format = match args.get(3) {
+                Some(f) => Option::<&Format>::try_convert(*f)?,
+                None => None,
+            };
+            Self::write(
+                ruby,
+                &rb_self,
+                row.to_u32()?,
+                col.to_u16()?,
+                args[2],
+                format,
+            )?;
+            return Ok(rb_self);
+        }
+        rb_self.funcall("_write_ref", args)
+    }
     fn write(
         ruby: &Ruby,
         rb_self: &Self,
@@ -938,7 +1068,7 @@ impl Worksheet {
                 ws,
                 row,
                 col,
-                Self::cell_format(&tables, row, col, format.map(|f| &*f.0)),
+                rb_self.format_for(&tables, row, col, format.map(|f| &*f.0), &value),
             )
         })?;
         rb_self.advance(row);
@@ -983,7 +1113,9 @@ impl Worksheet {
             ws.set_column_range_format(first, last, &format.0)
                 .map(|_| ())
                 .map_err(xerr)
-        })
+        })?;
+        self.formatted_columns.borrow_mut().push((first, last));
+        Ok(())
     }
     fn autofilter(
@@ -1075,9 +1207,39 @@ impl Worksheet {
         format: Option<&Format>,
     ) -> Result<Obj<Self>, Error> {
         rb_self.check_not_flushed(ruby, first_row)?;
+        // rust_xlsxwriter blanks the range before it notices an overlap, which
+        // wipes the earlier merge's value, so check first.
+        // A range rust_xlsxwriter rejects anyway (reversed, too big) is left
+        // to it, so its error names the real problem.
+        // ponytail: linear scan; sheets have few merges.
+        let range = (first_row, first_col, last_row, last_col);
+        let valid = first_row <= last_row
+            && first_col <= last_col
+            && last_row < MAX_ROWS
+            && usize::from(last_col) < MAX_COLS;
+        let overlap = rb_self
+            .merges
+            .borrow()
+            .iter()
+            .copied()
+            .find(|&(fr, fc, lr, lc)| {
+                first_row <= lr && fr <= last_row && first_col <= lc && fc <= last_col
+            })
+            .filter(|_| valid);
+        if let Some((fr, fc, lr, lc)) = overlap {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                format!(
+                    "merge range {} overlaps the earlier merge {}",
+                    rust_xlsxwriter::utility::cell_range(first_row, first_col, last_row, last_col),
+                    rust_xlsxwriter::utility::cell_range(fr, fc, lr, lc),
+                ),
+            ));
+        }
         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 format =
+            rb_self.format_for(&tables, 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
@@ -1093,6 +1255,7 @@ impl Worksheet {
             .map_err(xerr)?;
             value.write(ws, first_row, first_col, format)
         })?;
+        rb_self.merges.borrow_mut().push(range);
         rb_self.advance(last_row);
         rb_self.note_written(first_row);
         Ok(rb_self)
@@ -1490,6 +1653,142 @@ impl Worksheet {
         Ok(rb_self)
     }
+    fn activate(rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        let mut wb = rb_self.wb.lock().unwrap();
+        // rust_xlsxwriter leaves sheets activated earlier selected, which
+        // groups them in Excel (edits then go to all of them).
+        for (i, ws) in wb.worksheets_mut().iter_mut().enumerate() {
+            ws.set_active(i == rb_self.index);
+            ws.set_selected(i == rb_self.index);
+        }
+        rb_self.active.store(rb_self.index, Ordering::Relaxed);
+        Ok(rb_self)
+    }
+    fn hide(ruby: &Ruby, rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        // rust_xlsxwriter would quietly unhide it when saving.
+        if rb_self.active.load(Ordering::Relaxed) == rb_self.index {
+            return Err(Error::new(
+                ruby.get_inner(&ERROR),
+                "can't hide the sheet Excel opens on (the first one unless another is activated): activate another sheet first",
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            ws.set_hidden(true);
+            Ok(())
+        })?;
+        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()?;
+        // rust_xlsxwriter only prints a warning for these.
+        if !(10..=400).contains(&percent) {
+            return Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("invalid zoom {percent}: use 10..400"),
+            ));
+        }
+        rb_self.with_ws(|ws| {
+            ws.set_zoom(percent as u16);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+    fn tab_color(ruby: &Ruby, rb_self: Obj<Self>, value: Value) -> Result<Obj<Self>, Error> {
+        let rgb = color(ruby, value)?;
+        rb_self.with_ws(|ws| {
+            ws.set_tab_color(rgb);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+    fn hide_gridlines(rb_self: Obj<Self>) -> Result<Obj<Self>, Error> {
+        rb_self.with_ws(|ws| {
+            ws.set_screen_gridlines(false);
+            Ok(())
+        })?;
+        Ok(rb_self)
+    }
+    // Ranges arrive as [first, last] / [first_row, first_col, last_row,
+    // last_col], already parsed by lib/fast_xlsx.rb.
+    fn page_setup(ruby: &Ruby, rb_self: &Self, options: RHash) -> Result<(), Error> {
+        check_keys(
+            ruby,
+            options,
+            &[
+                "landscape",
+                "paper",
+                "fit_width",
+                "fit_height",
+                "repeat_rows",
+                "repeat_columns",
+                "print_area",
+                "gridlines",
+            ],
+            "page_setup",
+        )?;
+        let landscape = opt::<Value>(ruby, options, "landscape")?.map(|v| v.to_bool());
+        let paper = match opt::<Value>(ruby, options, "paper")? {
+            None => None,
+            Some(v) if Integer::from_value(v).is_some() => Some(
+                Integer::from_value(v)
+                    .and_then(|n| n.to_u8().ok())
+                    .ok_or_else(|| {
+                        Error::new(
+                            ruby.exception_arg_error(),
+                            format!("invalid paper {}: use a symbol or Excel's paper number (0 for the printer's default)", v.inspect()),
+                        )
+                    })?,
+            ),
+            Some(v) => Some(choice(ruby, "paper", v, PAPER_SIZES)?),
+        };
+        let fit_width = opt::<u16>(ruby, options, "fit_width")?;
+        let fit_height = opt::<u16>(ruby, options, "fit_height")?;
+        let repeat_rows = opt::<(u32, u32)>(ruby, options, "repeat_rows")?;
+        let repeat_columns = opt::<(u16, u16)>(ruby, options, "repeat_columns")?;
+        let print_area = opt::<(u32, u16, u32, u16)>(ruby, options, "print_area")?;
+        let gridlines = opt::<Value>(ruby, options, "gridlines")?.map(|v| v.to_bool());
+        rb_self.with_ws(|ws| {
+            match landscape {
+                Some(true) => ws.set_landscape(),
+                Some(false) => ws.set_portrait(),
+                None => ws,
+            };
+            if let Some(paper) = paper {
+                ws.set_paper_size(paper);
+            }
+            // 0 means as many pages as the content needs.
+            if fit_width.unwrap_or(0) > 0 || fit_height.unwrap_or(0) > 0 {
+                ws.set_print_fit_to_pages(fit_width.unwrap_or(0), fit_height.unwrap_or(0));
+            }
+            if let Some((first, last)) = repeat_rows {
+                ws.set_repeat_rows(first, last).map_err(xerr)?;
+            }
+            if let Some((first, last)) = repeat_columns {
+                ws.set_repeat_columns(first, last).map_err(xerr)?;
+            }
+            if let Some((fr, fc, lr, lc)) = print_area {
+                ws.set_print_area(fr, fc, lr, lc).map_err(xerr)?;
+            }
+            if let Some(gridlines) = gridlines {
+                ws.set_print_gridlines(gridlines);
+            }
+            Ok(())
+        })
+    }
     fn group_rows(
         ruby: &Ruby,
         rb_self: Obj<Self>,
@@ -1578,6 +1877,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let ws = module.define_class("Worksheet", ruby.class_object())?;
     ws.define_method("_write", method!(Worksheet::write, 4))?;
+    ws.define_method("write", method!(Worksheet::write_any, -1))?;
     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))?;
@@ -1593,7 +1893,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         method!(Worksheet::conditional_format, 5),
     )?;
     ws.define_method("_data_validation", method!(Worksheet::data_validation, 5))?;
-    ws.define_method("freeze_panes", method!(Worksheet::freeze_panes, 2))?;
+    ws.define_method("_freeze_panes", method!(Worksheet::freeze_panes, 2))?;
     ws.define_method("row_height", method!(Worksheet::set_row_height, 2))?;
     ws.define_method("page_breaks", method!(Worksheet::set_page_breaks, 1))?;
     ws.define_method("_page_header", method!(Worksheet::set_header, 1))?;
@@ -1603,6 +1903,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "vertical_page_breaks",
         method!(Worksheet::set_vertical_page_breaks, 1),
     )?;
+    ws.define_method("activate", method!(Worksheet::activate, 0))?;
+    ws.define_method("hide", method!(Worksheet::hide, 0))?;
+    ws.define_method("zoom", method!(Worksheet::zoom, 1))?;
+    ws.define_method("tab_color", method!(Worksheet::tab_color, 1))?;
+    ws.define_method("hide_gridlines", method!(Worksheet::hide_gridlines, 0))?;
+    ws.define_method("_page_setup", method!(Worksheet::page_setup, 1))?;
     ws.define_method("_group_rows", method!(Worksheet::group_rows, 3))?;
     ws.define_method("_group_columns", method!(Worksheet::group_columns, 3))?;
     ws.define_method("_protect", method!(Worksheet::protect, 2))?;

data/lib/fast_xlsx/version.rb CHANGED Viewed

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

data/lib/fast_xlsx.rb CHANGED Viewed

@@ -102,10 +102,15 @@ module FastXlsx
   # Cell writer for one sheet; create with Workbook#add_worksheet.
   class Worksheet
-    def write(row, col, value, format = nil)
+    # 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
+    # wrapper. Other forms come here.
+    def _write_ref(*args)
+      row, col, (value, format) = CellRange.cell(args, 1..2)
       _write(row, col, value, format)
       self
     end
+    private :_write_ref
     def append(values, format: nil)
       _append(values, format)
@@ -158,14 +163,16 @@ module FastXlsx
     end
     # Adds a comment (Excel "note") to a cell.
-    def write_comment(row, col, text, author: nil)
+    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:.
-    def insert_image(row, col, source, **)
+    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
@@ -173,7 +180,8 @@ module FastXlsx
     # 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:.
-    def insert_chart(row, col, type:, series:, **)
+    def insert_chart(*cell, type:, series:, **)
+      row, col, = CellRange.cell(cell)
       _insert_chart(row, col, { type: type, series: series, ** })
     end
@@ -197,6 +205,18 @@ module FastXlsx
       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:.
+    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
+      options[:print_area] = CellRange.split(print_area.is_a?(Array) ? print_area : [print_area]).first if print_area
+      _page_setup(options)
+      self
+    end
     # Print margins in inches; margins not given keep their current value.
     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 })
@@ -214,6 +234,13 @@ module FastXlsx
       _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.
+    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,
@@ -236,6 +263,7 @@ module FastXlsx
   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)'
+    CELL_FORMS = 'a cell is (row, col) or "B2"'
     module_function
@@ -243,12 +271,7 @@ module FastXlsx
     # Returns [[first_row, first_col, last_row, last_col], the args after it].
     def split(args, following = 0..0)
       range, rest = parse(args)
-      unless following.cover?(rest.size)
-        expected = following.minmax.uniq.join("..")
-        raise ArgumentError, "wrong number of arguments after the cell range (given #{rest.size}, " \
-                             "expected #{expected}); #{FORMS}"
-      end
+      check_following(rest, following, "cell range", FORMS)
       [range, rest]
     end
@@ -263,6 +286,30 @@ module FastXlsx
       end
     end
+    # (row, col) or a single-cell reference ("B2") off the front of args, as
+    # [row, col, the args after it].
+    def cell(args, following = 0..0)
+      row, col, *rest = args.first.is_a?(String) ? [*single_cell(args.first), *args.drop(1)] : args
+      raise ArgumentError, "expected a cell, got #{args.inspect}; #{CELL_FORMS}" if col.nil?
+      check_following(rest, following, "cell", CELL_FORMS)
+      [row, col, rest]
+    end
+    def single_cell(ref)
+      first_row, first_col, last_row, last_col = excel(ref)
+      return [first_row, first_col] if first_row == last_row && first_col == last_col
+      raise ArgumentError, "expected a single cell like \"B2\", got #{ref.inspect}"
+    end
+    def check_following(rest, following, what, forms)
+      return if following.cover?(rest.size)
+      raise ArgumentError, "wrong number of arguments after the #{what} " \
+                           "(given #{rest.size}, expected #{following.minmax.uniq.join("..")}); #{forms}"
+    end
     def rows_and_cols(rows, cols)
       first_row, last_row = bounds(rows)
       first_col, last_col = bounds(cols)

data/sig/fast_xlsx.rbs CHANGED Viewed

@@ -57,6 +57,7 @@ module FastXlsx
   class Worksheet
     def write: (Integer row, Integer col, cell value, ?Format? format) -> self
+             | (String cell, cell value, ?Format? format) -> self
     def append: (Array[cell] values, ?format: Format? | Array[Format?]) -> self
     def <<: (Array[cell] row) -> self
     def concat: (Array[Array[cell]] rows) -> self
@@ -72,11 +73,20 @@ module FastXlsx
                   | (String range) -> self
                   | (indexes rows, indexes cols) -> self
     def freeze_panes: (Integer row, Integer col) -> self
+                    | (String cell) -> self
     def row_height: (Integer row, Numeric height) -> self
     def page_breaks: (Array[Integer] rows) -> self
     def vertical_page_breaks: (Array[Integer] cols) -> self
     def page_header: (String text, ?margin: Numeric?) -> self
     def page_footer: (String text, ?margin: Numeric?) -> self
+    def activate: () -> self
+    def hide: () -> self
+    def zoom: (Integer 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,
+                     ?fit_width: Integer, ?fit_height: Integer, ?repeat_rows: indexes, ?repeat_columns: indexes,
+                     ?print_area: String | Array[cell_range], ?gridlines: bool) -> self
     def margins: (?left: Numeric?, ?right: Numeric?, ?top: Numeric?, ?bottom: Numeric?,
                   ?header: Numeric?, ?footer: Numeric?) -> self
     type protect_action = :format_cells | :format_columns | :format_rows | :insert_columns | :insert_rows
@@ -98,13 +108,19 @@ module FastXlsx
                           ?input_title: String, ?input_message: String,
                           ?error_title: String, ?error_message: String) -> self
     def write_comment: (Integer row, Integer col, String text, ?author: String?) -> self
+                     | (String cell, String text, ?author: String?) -> self
     def insert_image: (Integer row, Integer col, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
                        ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
+                    | (String cell, String | _Reader source, ?scale: Numeric, ?width: Numeric, ?height: Numeric,
+                       ?x_offset: Integer, ?y_offset: Integer, ?alt_text: String) -> self
     type chart_series = { values: String, ?categories: String, ?name: String }
     def insert_chart: (Integer row, Integer col, type: Symbol, series: Array[chart_series],
                        ?title: String, ?x_axis: String, ?y_axis: String,
                        ?width: Integer, ?height: Integer) -> self
+                    | (String cell, type: Symbol, series: Array[chart_series],
+                       ?title: String, ?x_axis: String, ?y_axis: String,
+                       ?width: Integer, ?height: Integer) -> self
     type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: Format }
     def add_table: (*cell_range range,

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Zac