fast_xlsx 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eddcb1a0c063b94222c0a83e15b7a855a83b26674390ee87f59f1938d7007c9f
-  data.tar.gz: 5aa9b9a7b6dbfb70bb53364b16fa31bb2c745534aefc9f0631367ed6cf658043
+  metadata.gz: f530f027eb2e902f4bed36fdfd75af2851ff93a9762915a56f9de3e966eab593
+  data.tar.gz: 794ddb87412acfa82840681a9caf32f85eb0d5b47fc0921c7091f3bbde020677
 SHA512:
-  metadata.gz: d854850a2dd9d9b82d8bbbe4568f41336b3e4a89b977ddfcffb8e08a083305222111dded66d33e8f999dfbfae4d1da319e16f40835e83962bb7ac6081686b333
-  data.tar.gz: 973794fd6d14e139f8173e0726f0938f61022f5b503d5b761b4abaf089b9e0dd3debec9083248859f9380a64fd6ead89ec2efc8af64296338960b6caed1269df
+  metadata.gz: 915d233e6c422187d23853c1c521bdefbf3336d85af03574882dc14a8055b1f692e3044588281c33c94e451be5123f516c4b07e2596111782c2b2a1f68fa261a
+  data.tar.gz: 98aa0c5de0d29816828a8fe6215c5132b7bd88297ed13bf6db9df9ddd6f0221e27f7a804a082e4430daffbb235193f1c85ffb898f41f6fee94940625d0caabb2

data/.cargo/mutants.toml

@@ -0,0 +1,7 @@
+# cargo-mutants settings (see .github/workflows/mutants.yml).
+exclude_re = [
+  # Equivalent mutant: sending every format through FastXlsx::Format._coerce,
+  # not just Hashes, changes nothing but speed (_coerce returns a Format or
+  # nil as it is), so no test can catch it.
+  'replace match guard RHash::from_value\(\*?f\)\.is_some\(\) with true in Worksheet::write_any',
+]

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-03
+
+### Fixed
+
+- Rails' `ActiveSupport::TimeWithZone` (e.g. `created_at`) and other objects that act like a `Time` without being one were written as text; they are dates now.
+
+### Changed
+
+- Writing `Time` values is about 25% faster (read through Ruby's C API instead of method calls), and `Date` values a little faster.
+
+## [0.8.0] - 2026-10-02
+
+### Changed
+
+- The API is frozen for 1.0: 0.8.x releases only fix bugs. The README states the deprecation policy.
+
+### Added
+
+- `write` and `merge_range` also take the format as `format:`, like `append` (positional still works).
+
 ## [0.7.0] - 2026-10-02
 
 ### Added

data/README.md

@@ -5,9 +5,85 @@
 
 Fast `.xlsx` writer for Ruby, built on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter) via [magnus](https://github.com/matsadler/magnus).
 
-> **Status: early.** The API may still change before 1.0.
+> **Status: release candidate.** The API is frozen as of 0.8: 0.8.x releases only fix bugs, and 1.0 follows once it has been in real use without needing changes.
 
-## Usage
+**Roadmap:** [1.0.0](https://github.com/7a6163/fast_xlsx/milestone/1) (release plan) · [1.x](https://github.com/7a6163/fast_xlsx/milestone/2) (planned features)
+
+**Contents:** [Installation](#installation) · [Getting started](#getting-started) · [Guide](#guide) · [Performance](#performance) · [Support and versioning](#support-and-versioning) · [Development](#development)
+
+## Installation
+
+```bash
+bundle add fast_xlsx
+```
+
+Requires CRuby 3.3 or later. Precompiled gems cover Linux, macOS and Windows; see [Support and versioning](#support-and-versioning).
+
+Coming from fast_excel? See [Migrating from fast_excel](docs/MIGRATING_FROM_FAST_EXCEL.md).
+
+## Getting started
+
+A sales report, step by step: a header, one row per sale, a totals row, then sized columns, a frozen header and filter buttons.
+
+```ruby
+require "date"
+require "fast_xlsx"
+
+# Sample data; in an app it comes from your database.
+Sale = Struct.new(:region, :product, :units, :price, :sold_on)
+sales = [
+  Sale.new("North", "Widget", 120, 9.5, Date.new(2026, 7, 3)),
+  Sale.new("North", "Gadget", 45, 24.0, Date.new(2026, 7, 9)),
+  Sale.new("South", "Widget", 80, 9.5, Date.new(2026, 7, 14)),
+  Sale.new("South", "Gizmo", 12, 120.0, Date.new(2026, 7, 21))
+]
+
+# 1. A workbook with one worksheet.
+wb = FastXlsx::Workbook.new
+ws = wb.add_worksheet("Sales")
+
+# 2. A header row, bold on a light blue fill.
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+ws.append(["Region", "Product", "Units", "Price", "Sold on", "Revenue"], format: header)
+
+# 3. One row per sale. Dates show as yyyy-mm-dd on their own; a formula is a
+#    FastXlsx::Formula. In formulas rows count from 1, so the first sale is row 2.
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+sales.each.with_index(2) do |sale, row|
+  ws.append([sale.region, sale.product, sale.units, sale.price, sale.sold_on,
+             FastXlsx::Formula.new("C#{row}*D#{row}")],
+            format: [nil, nil, nil, money, nil, money])
+end
+
+# 4. A totals row: the header's look, with the money format added.
+last = sales.size + 1
+ws.append(["Total", nil, FastXlsx::Formula.new("SUM(C2:C#{last})"), nil, nil,
+           FastXlsx::Formula.new("SUM(F2:F#{last})")],
+          format: [header, header, header, header, header, header.merge(num_format: "#,##0.00")])
+
+# 5. Easier to read: columns sized to fit (set by hand where autofit can't tell), the header kept in view while
+#    scrolling, and filter buttons on the header (rows and columns count from 0).
+ws.autofit
+ws.column_width(3..5, 12) # money, dates, formulas: autofit measures raw values
+ws.freeze_panes("A2")
+ws.autofilter("A1:F#{last}")
+
+# 6. Save it. (In Rails: send_data wb.to_xlsx, filename: "sales.xlsx", ...)
+wb.save("sales.xlsx")
+```
+
+- **Rows and columns count from 0** in method calls (`write(0, 0, ...)` is A1); Excel references like `"A2"` and formulas count from 1 as in Excel.
+- **Formulas** are calculated by Excel when it opens the file.
+- **Large exports** (tens of thousands of rows and up): use `FastXlsx::Workbook.new(memory: :constant)`. Rows go to disk as they are added, so memory stays flat; fill each worksheet from top to bottom. See [Memory modes](#memory-modes).
+- **Rails**: build the workbook in the controller and `send_data wb.to_xlsx`; see [Rails](#rails).
+
+The [Guide](#guide) below covers every feature; the [API docs](https://www.rubydoc.info/gems/fast_xlsx) list every method.
+
+## Guide
+
+[Writing cells](#writing-cells) · [Rails](#rails) · [Memory modes](#memory-modes) · [Formats](#formats) · [Columns and filters](#columns-and-filters) · [Sheet view and printing](#sheet-view-and-printing) · [Cell ranges](#cell-ranges) · [Layout](#layout) · [Outline groups](#outline-groups) · [Defined names](#defined-names) · [Protection](#protection) · [Conditional formats](#conditional-formats) · [Data validation](#data-validation) · [Comments](#comments) · [Images](#images) · [Tables](#tables) · [Charts](#charts) · [Errors](#errors)
+
+### Writing cells
 
 ```ruby
 require "fast_xlsx"
@@ -19,6 +95,7 @@ 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
+ws.write("F1", 42, { bold: true })                # a format positionally, or as format: like append
 ws["F1"] = 42                                     # the same (ws[0, 5] = 42 too)
 
 wb.properties(title: "Q3 report", author: "Zac", keywords: "Confidential") # File > Info in Excel
@@ -293,7 +370,7 @@ Values are mapped by type:
 |---|---|
 | `Integer`, `Float`, any `Numeric` | number |
 | `String` | string |
-| `Time`, `DateTime` | date and time (`yyyy-mm-dd hh:mm:ss` unless formatted), in its own offset |
+| `Time`, `DateTime`, time-like objects such as Rails' `ActiveSupport::TimeWithZone` | 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) |
@@ -367,17 +444,12 @@ BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb b
 BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb fast_xlsx:low unique
 ```
 
-## Installation
-
-```bash
-bundle add fast_xlsx
-```
-
-### Support and versioning
+## 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".
+- **Deprecations:** from 1.0, a method or option to be removed first prints a warning (with `warn`, so on by default) for at least one minor release, with the CHANGELOG naming its replacement; it goes only in the next major version.
 - **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.7.0)
+    fast_xlsx (0.8.1)
       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.7.0)
+  fast_xlsx (0.8.1)
   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/docs/MIGRATING_FROM_FAST_EXCEL.md

@@ -0,0 +1,123 @@
+# Migrating from fast_excel
+
+fast_xlsx started as a rewrite of [fast_excel](https://github.com/Paxa/fast_excel) on [rust_xlsxwriter](https://github.com/jmcnamara/rust_xlsxwriter), and keeps its spirit: append rows fast, with little memory. Most code moves over with a few renames. This guide lists them, then the differences in behaviour to check.
+
+**Why switch**
+
+- 2.8–3.3× faster on the [README benchmark](../README.md#speed), and `memory: :constant` adds about 1 MB however large the file.
+- Precompiled gems for Linux, macOS and Windows: no C compiler or FFI at install.
+- Dates show as dates without a format, every option is checked (a typo raises instead of being ignored), and saving doesn't block other threads.
+- Conditional formats, data validation, tables, charts, images, comments, protection and printing options as Ruby methods.
+
+**Before you start**
+
+- fast_xlsx needs CRuby 3.3 or later (fast_excel supports 2.7+).
+- Rows and columns are 0-based in both, and `<<` appends in both.
+
+## A report, before and after
+
+```ruby
+# fast_excel
+workbook = FastExcel.open(constant_memory: true)
+worksheet = workbook.add_worksheet("Orders")
+bold = workbook.bold_format
+worksheet.append_row(["Order", "Total", "Placed at"], bold)
+money = workbook.number_format("#,##0.00")
+orders.each { |o| worksheet.append_row([o.number, o.total, o.created_at], [nil, money, nil]) }
+worksheet.set_column_width(0, 20)
+send_data workbook.read_string, filename: "orders.xlsx"
+```
+
+```ruby
+# fast_xlsx
+workbook = FastXlsx::Workbook.new(memory: :constant)
+worksheet = workbook.add_worksheet("Orders")
+worksheet.append(["Order", "Total", "Placed at"], format: { bold: true })
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+orders.each { |o| worksheet.append([o.number, o.total, o.created_at], format: [nil, money, nil]) }
+worksheet.column_width(0, 20)
+send_data workbook.to_xlsx, filename: "orders.xlsx"
+```
+
+`created_at` now shows as `yyyy-mm-dd hh:mm:ss` without a format; with fast_excel it was a number unless you passed a date format.
+
+## Method by method
+
+### Workbook
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `FastExcel.open` | `FastXlsx::Workbook.new` |
+| `FastExcel.open(constant_memory: true)` | `FastXlsx::Workbook.new(memory: :constant)` (or `:low`, which keeps Excel's shared strings) |
+| `FastExcel.open("report.xlsx")` … `workbook.close` | `FastXlsx::Workbook.new` … `workbook.save("report.xlsx")` |
+| `workbook.read_string` | `workbook.to_xlsx` |
+| `workbook.remove_tmp_folder` | not needed: no temp file is created |
+| `workbook.add_worksheet(name)` | `workbook.add_worksheet(name)` |
+| `workbook.get_worksheet_by_name(name)` | `workbook.worksheet(name)` |
+| `workbook.add_format(bold: true)` | `FastXlsx::Format.new(bold: true)`, or pass `{ bold: true }` where a format goes |
+| `workbook.bold_format` | `FastXlsx::Format.new(bold: true)` |
+| `workbook.number_format("0.00")` | `FastXlsx::Format.new(num_format: "0.00")` |
+
+### Writing
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `worksheet << values` / `append_row(values, format)` | `worksheet << values` / `append(values, format: format)` |
+| `write_value(row, col, value, format)` | `write(row, col, value, format)`, or `write("B2", value, format)`, or `worksheet["B2"] = value` |
+| `write_number`, `write_string`, `write_datetime`, `write_formula`, `write_url`, `write_boolean` | `write`: the type comes from the value |
+| `write_row(row, values, formats)` | `values.each_with_index { \|v, col\| worksheet.write(row, col, v, format) }`, or `append` when it is the next row |
+| `FastExcel::Formula.new("SUM(A1:A9)")` | `FastXlsx::Formula.new("SUM(A1:A9)")` |
+| `FastExcel::URL.new(url)` | `FastXlsx::URL.new(url)`, and `URL.new(url, text: "shown")` |
+| `FastExcel.date_num(time, offset)` with a date format | `time` as it is: dates are converted and formatted for you |
+| `worksheet.last_row_number` | `worksheet.next_row - 1` |
+
+### Columns, rows and filters
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `set_column_width(col, width)` | `column_width(col, width)` |
+| `set_columns_width(first, last, width)` | `column_width(first..last, width)` |
+| `set_column(first, last, width, format)` | `column_width(first..last, width)` and `column_format(first..last, format)` |
+| `set_row(row, height, format)` | `row_height(row, height)` and `row_format(row, format)` |
+| `worksheet.auto_width = true` (before writing) | `worksheet.autofit` (after writing; see below) |
+| `enable_filters!(end_col: 3)` | `autofilter(0, 0, worksheet.next_row - 1, 3)`, or `autofilter("A1:D100")` |
+| `freeze_panes`, `merge_range` and other libxlsxwriter functions | Ruby methods with the same idea: `freeze_panes("A2")`, `merge_range("A1:D1", "Title")`; see the [Guide](../README.md#guide) |
+
+### Format options
+
+| fast_excel | fast_xlsx |
+|---|---|
+| `bold:`, `italic:`, `text_wrap:`, `shrink:`, `font_size:`, `font_name:`, `num_format:`, `rotation:`, `indent:`, `bg_color:` | the same |
+| `font_family:` | `font_name:` |
+| `font_strikeout: true` | `strikeout: true` |
+| `underline: :underline_single` (`_double`, `_single_accounting`, `_double_accounting`) | `underline: true` or `:single` (`:double`, `:single_accounting`, `:double_accounting`) |
+| `font_script: :font_subscript` / `:font_superscript` | `font_script: :subscript` / `:superscript` |
+| `font_color: :orange`, `"#FF0000"`, `0xFF0000` | `"#FF0000"` or `0xFF0000`: color names aren't supported, use their hex value |
+| `border: :border_thin` | `border: :thin` (also `:medium`, `:thick`, `:dashed`, `:dotted`, `:double`, `:hair`) |
+| `left: :medium`, `top:`, `right:`, `bottom:` | `border_left: :medium`, `border_top:`, `border_right:`, `border_bottom:` |
+| `left_color:`, `top_color:` … per side | `border_color:`, one color for every side |
+| `align: { h: :align_center, v: :align_vertical_center }` | `align: :center, valign: :center` |
+
+## Differences in behaviour
+
+- **Dates have a format.** fast_excel wrote `Time` and `Date` as plain numbers unless you passed a date format. fast_xlsx shows them as `yyyy-mm-dd` (`Date`) or `yyyy-mm-dd hh:mm:ss` (`Time`, `DateTime`), and adds that to a format without a `num_format` (a bold row stays bold). Pass your own `num_format` to keep a different one. Both use the value's own UTC offset, so times don't shift. Dates before 1900-03-01 now show correctly; fast_excel's showed one day late, because Excel counts a 1900-02-29 that never existed.
+- **Errors raise.** Unknown or misspelled options, invalid colors and values Excel can't hold (a string over 32,767 characters, a row past 1,048,576) raise `ArgumentError`, `RangeError` or `FastXlsx::Error`; see [Errors](../README.md#errors). In `:constant` mode, writing to a row already on disk raises `FastXlsx::Error` (fast_excel raised `ArgumentError`).
+- **Autofit runs after writing.** fast_excel measured text as you wrote it (strings only). `autofit` measures what is in memory when you call it, so in `:constant` / `:low` mode it only sees the last rows: set widths with `column_width` there. It measures raw values, so give formatted numbers, dates and formulas a width by hand.
+- **No temp files.** fast_excel always wrote to a file, a temporary one without a filename. fast_xlsx builds the workbook in memory (`:standard`) or in its own temp files (`:constant` / `:low`) and gives you the result with `to_xlsx` or `save`.
+- **Formats are values.** A `FastXlsx::Format` is frozen and created on its own, not from a workbook, so one format can serve several workbooks. Use `format.merge(italic: true)` for a variant.
+
+## Not available
+
+- **The libxlsxwriter functions under `Libxlsxwriter.*`.** fast_xlsx has no raw binding; the [Guide](../README.md#guide) and the [API docs](https://www.rubydoc.info/gems/fast_xlsx) cover what is exposed, and the [roadmap](https://github.com/7a6163/fast_xlsx/milestone/2) what is planned.
+- **`FastExcel.open(default_format: ...)`.** Use `column_format` / `row_format`, or pass the format when writing.
+- **Some format options:** color names, per-side border colors, `font_outline`, `font_shadow`, `text_justlast`, and alignments other than left, center and right (horizontal) or top, center and bottom (vertical).
+- **Reading or editing existing files**: neither library does this.
+
+## Checklist
+
+1. Replace `gem "fast_excel"` with `gem "fast_xlsx"`, and check you are on Ruby 3.3+.
+2. Swap `FastExcel.open` / `read_string` / `close` for `FastXlsx::Workbook.new` / `to_xlsx` / `save`.
+3. Rename the methods and format options from the tables above; run your code: a missed rename raises `NoMethodError` or `ArgumentError` rather than being ignored.
+4. Drop `FastExcel.date_num` and date formats you only added to make dates readable.
+5. Replace `auto_width = true` with `autofit` after writing (or `column_width` in `:constant` mode).
+6. Open one generated file in Excel and compare.

data/examples/getting_started.rb

@@ -0,0 +1,44 @@
+require "date"
+require "fast_xlsx"
+
+# Sample data; in an app it comes from your database.
+Sale = Struct.new(:region, :product, :units, :price, :sold_on)
+sales = [
+  Sale.new("North", "Widget", 120, 9.5, Date.new(2026, 7, 3)),
+  Sale.new("North", "Gadget", 45, 24.0, Date.new(2026, 7, 9)),
+  Sale.new("South", "Widget", 80, 9.5, Date.new(2026, 7, 14)),
+  Sale.new("South", "Gizmo", 12, 120.0, Date.new(2026, 7, 21))
+]
+
+# 1. A workbook with one worksheet.
+wb = FastXlsx::Workbook.new
+ws = wb.add_worksheet("Sales")
+
+# 2. A header row, bold on a light blue fill.
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin)
+ws.append(["Region", "Product", "Units", "Price", "Sold on", "Revenue"], format: header)
+
+# 3. One row per sale. Dates show as yyyy-mm-dd on their own; a formula is a
+#    FastXlsx::Formula. In formulas rows count from 1, so the first sale is row 2.
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+sales.each.with_index(2) do |sale, row|
+  ws.append([sale.region, sale.product, sale.units, sale.price, sale.sold_on,
+             FastXlsx::Formula.new("C#{row}*D#{row}")],
+            format: [nil, nil, nil, money, nil, money])
+end
+
+# 4. A totals row: the header's look, with the money format added.
+last = sales.size + 1
+ws.append(["Total", nil, FastXlsx::Formula.new("SUM(C2:C#{last})"), nil, nil,
+           FastXlsx::Formula.new("SUM(F2:F#{last})")],
+          format: [header, header, header, header, header, header.merge(num_format: "#,##0.00")])
+
+# 5. Easier to read: columns sized to fit (set by hand where autofit can't tell), the header kept in view while
+#    scrolling, and filter buttons on the header (rows and columns count from 0).
+ws.autofit
+ws.column_width(3..5, 12) # money, dates, formulas: autofit measures raw values
+ws.freeze_panes("A2")
+ws.autofilter("A1:F#{last}")
+
+# 6. Save it. (In Rails: send_data wb.to_xlsx, filename: "sales.xlsx", ...)
+wb.save("sales.xlsx")

data/ext/fast_xlsx/Cargo.toml

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

data/ext/fast_xlsx/src/lib.rs

@@ -52,6 +52,27 @@ fn xerr(e: XlsxError) -> Error {
 
 // 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.
+const BOTH_FORMATS: &str = "pass the format either positionally or as format:, not both";
+
+// The format from write's keywords ({ format: f }); others are rejected.
+fn format_keyword(ruby: &Ruby, keywords: Value) -> Result<Value, Error> {
+    let keywords = RHash::try_convert(keywords)?;
+    let format = ruby.to_symbol("format");
+    keywords.foreach(|key: Value, _: Value| {
+        if key.eql(format)? {
+            Ok(ForEach::Continue)
+        } else {
+            Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("unknown keyword: {}", key.inspect()),
+            ))
+        }
+    })?;
+    Ok(keywords
+        .get(format)
+        .unwrap_or_else(|| ruby.qnil().as_value()))
+}
+
 // 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> {
@@ -307,7 +328,29 @@ fn excel_serial(days: f64) -> Result<f64, Error> {
 }
 
 // Time: seconds since 1970-01-01 (serial day 25569), in its own offset.
+// For a Time (checked by the caller): Ruby's C functions, with no method calls,
+// since this runs once per cell.
 fn excel_time(v: Value) -> Result<f64, Error> {
+    use magnus::rb_sys::{protect, AsRawValue, FromRawValue};
+    // Both can raise (a Time out of range or uninitialized, or a zone object
+    // whose Ruby code fails), so they run under protect: a raise becomes an
+    // Err instead of a longjmp over these Rust frames.
+    let mut spec = None;
+    protect(|| {
+        // SAFETY: protect catches anything this raises.
+        spec = Some(unsafe { rb_sys::rb_time_timespec(v.as_raw()) });
+        rb_sys::Qnil as rb_sys::VALUE
+    })?;
+    // SAFETY: as above.
+    let offset = protect(|| unsafe { rb_sys::rb_time_utc_offset(v.as_raw()) })?;
+    let (spec, offset) = (spec.unwrap(), unsafe { Value::from_raw(offset) });
+    let secs = spec.tv_sec as f64 + spec.tv_nsec as f64 / 1e9;
+    excel_serial((secs + i64::try_convert(offset)? as f64) / 86400.0 + 25569.0)
+}
+
+// Something that acts like a Time without being one at the C level, such as
+// Rails' ActiveSupport::TimeWithZone (it delegates to a Time).
+fn excel_time_like(v: Value) -> Result<f64, Error> {
     let secs: f64 = v.funcall("to_f", ())?;
     let offset: i64 = v.funcall("utc_offset", ())?;
     excel_serial((secs + offset as f64) / 86400.0 + 25569.0)
@@ -315,9 +358,14 @@ fn excel_time(v: Value) -> Result<f64, Error> {
 
 // Date / DateTime: Julian day and day fraction are both in the object's own
 // offset. JD 2415019 is 1899-12-30.
-fn excel_date(v: Value) -> Result<f64, Error> {
+// `time`: a DateTime, with a time of day; a Date's day fraction is always 0.
+fn excel_date(v: Value, time: bool) -> Result<f64, Error> {
     let jd: i64 = v.funcall("jd", ())?;
-    let fraction: f64 = f64::try_convert(v.funcall("day_fraction", ())?)?;
+    let fraction = if time {
+        f64::try_convert(v.funcall("day_fraction", ())?)?
+    } else {
+        0.0
+    };
     excel_serial((jd - 2_415_019) as f64 + fraction)
 }
 
@@ -392,7 +440,10 @@ impl CellValue {
             CellValue::Rich(parts)
         } else if v.respond_to("jd", false)? {
             // Date has no #hour; DateTime does.
-            CellValue::Date(excel_date(v)?, v.respond_to("hour", false)?)
+            let time = v.respond_to("hour", false)?;
+            CellValue::Date(excel_date(v, time)?, time)
+        } else if v.respond_to("utc_offset", false)? && v.respond_to("to_f", false)? {
+            CellValue::Date(excel_time_like(v)?, true)
         } else {
             CellValue::Text(v.funcall("to_s", ())?)
         };
@@ -1171,15 +1222,25 @@ impl Worksheet {
     // 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> {
+        // A real format: keyword arrives as a trailing Hash; Ruby says whether
+        // it was one, so a Hash written as the value isn't mistaken for it.
+        let keyword_given = unsafe { rb_sys::rb_keyword_given_p() } != 0;
+        let (args, keyword) = match (keyword_given, args.split_last()) {
+            (true, Some((last, rest))) => (rest, Some(format_keyword(ruby, *last)?)),
+            _ => (args, None),
+        };
         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)) {
+            if keyword.is_some() && args.len() == 4 {
+                return Err(Error::new(ruby.exception_arg_error(), BOTH_FORMATS));
+            }
             // A Hash of options becomes a (cached) Format, as in Ruby.
-            let format_arg = match args.get(3) {
-                Some(f) if RHash::from_value(*f).is_some() => Some(
+            let format_arg = match keyword.or_else(|| args.get(3).copied()) {
+                Some(f) if RHash::from_value(f).is_some() => Some(
                     ruby.get_inner(&FORMAT)
-                        .funcall::<_, _, Value>("_coerce", (*f,))?,
+                        .funcall::<_, _, Value>("_coerce", (f,))?,
                 ),
-                f => f.copied(),
+                f => f,
             };
             let format = match format_arg {
                 Some(f) => Option::<&Format>::try_convert(f)?,
@@ -1195,7 +1256,14 @@ impl Worksheet {
             )?;
             return Ok(rb_self);
         }
-        rb_self.funcall("_write_ref", args)
+        rb_self.funcall(
+            "_write_ref",
+            (
+                ruby.ary_from_iter(args.iter().copied()),
+                keyword.is_some(),
+                keyword,
+            ),
+        )
     }
 
     fn write(

data/lib/fast_xlsx/version.rb

@@ -2,5 +2,5 @@
 
 module FastXlsx
   # The gem version.
-  VERSION = "0.7.0"
+  VERSION = "0.8.1"
 end

data/lib/fast_xlsx.rb

@@ -186,10 +186,13 @@ module FastXlsx
   #   Writes one cell.
   #   @overload write(row, col, value, format = nil)
   #   @overload write(ref, value, format = nil)
+  #   @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, Hash, nil] a Hash of options works too
+  #   @param format [Format, Hash, nil] positional or format: (a little slower:
+  #     Ruby builds a Hash for the keyword); a Hash of options works too
   #   @return [self]
   #
   # @!method <<(values)
@@ -252,11 +255,15 @@ module FastXlsx
   #   Hides the gridlines on screen (see {#page_setup} for printing).
   #   @return [self]
   class Worksheet
+    NO_FORMAT = Object.new.freeze # format: not given
+    private_constant :NO_FORMAT
+
     # 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)
+    def _write_ref(args, keyword_given, keyword_format)
       row, col, (value, format) = CellRange.cell(args, 1..2)
+      format = Format.check_both(args.size > (args.first.is_a?(String) ? 2 : 3), keyword_given, format, keyword_format)
       _write(row, col, value, Format._coerce(format))
       self
     end
@@ -311,10 +318,12 @@ module FastXlsx
 
     # Merges the range and writes value (any cell type) into its first cell.
     # @overload merge_range(*range, value, format = nil)
+    # @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)
+    def merge_range(*args, format: NO_FORMAT)
+      range, (value, positional) = CellRange.split(args, 1..2)
+      format = Format.check_both(!positional.nil?, !NO_FORMAT.equal?(format), positional, format)
       _merge_range(*range, value, Format._coerce(format))
     end
 
@@ -726,6 +735,15 @@ module FastXlsx
       Format.new(**to_h, **other.to_h, **)
     end
 
+    # The format given positionally or as format:, raising if both were.
+    # @api private
+    def self.check_both(positional_given, keyword_given, positional, keyword)
+      return positional unless keyword_given
+      raise ArgumentError, "pass the format either positionally or as format:, not both" if positional_given
+
+      keyword
+    end
+
     # Distinct Hashes kept by {._coerce}; past this, the oldest is dropped.
     CACHE_SIZE = 1_024
 

data/sig/fast_xlsx.rbs

@@ -67,7 +67,9 @@ module FastXlsx
     def []=: (String cell, cell value) -> cell
            | (Integer row, Integer col, cell value) -> cell
     def write: (Integer row, Integer col, cell value, ?format? format) -> self
+             | (Integer row, Integer col, cell value, format: format?) -> self
              | (String cell, 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
@@ -120,6 +122,7 @@ module FastXlsx
     def merge_range: (Integer first_row, Integer first_col, Integer last_row, Integer last_col, cell value, ?format? format) -> self
                    | (String range, cell value, ?format? format) -> self
                    | (indexes rows, indexes cols, cell value, ?format? format) -> self
+                   | (*cell_range | cell args, format: format?) -> self
     def conditional_format: (*cell_range range,
                              type: :cell | :text | :formula | :data_bar | :color_scale,
                              ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Zac
@@ -32,6 +32,7 @@ extensions:
 - ext/fast_xlsx/extconf.rb
 extra_rdoc_files: []
 files:
+- ".cargo/mutants.toml"
 - ".yardopts"
 - CHANGELOG.md
 - Cargo.lock
@@ -44,6 +45,8 @@ files:
 - bench/compare.rb
 - bench/memory.rb
 - bench/write.rb
+- docs/MIGRATING_FROM_FAST_EXCEL.md
+- examples/getting_started.rb
 - examples/showcase.rb
 - ext/fast_xlsx/Cargo.toml
 - ext/fast_xlsx/build.rs