fast_xlsx 0.1.0-arm-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db5d2a9a270df5498d3e79f69a4a41eea77018f814374552e926929ce7f094fc
+  data.tar.gz: ef4b4fa4695c280c15836067e4150aed908950c035eb6c3a74cc45c754d26133
+SHA512:
+  metadata.gz: 302ca0e6c60e9d5d676bbaff8d4d96d95e9099ed76e881dcae5987fbb1a26d1dd17da5994186dc2077c0177602b02dbb80fbe3ca89ce704d862e063a49f41c89
+  data.tar.gz: e94fd22371e384bf400d1e07c0cfc392a9beb2e7382ecf4ab661e483caf14e882f743385fb1fc84eb47776d9374841c767aede9369841a0197cfc9e8b23d5c56

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+First release: a fast `.xlsx` writer built on rust_xlsxwriter. Early API; it may still change before 1.0.
+
+### Workbooks and worksheets
+
+- `FastXlsx::Workbook.new(memory: :standard | :constant | :low)`: keep every cell in memory, or write finished rows to disk with strings inline (`:constant`) or in the shared string table (`:low`)
+- `Workbook#add_worksheet`, `#worksheet(name)`, `#worksheets`, `#properties` (document properties), `#to_xlsx`, `#save`
+- `Worksheet#<<`, `#append`, `#concat`, `#write` (all return the worksheet); writes to rows already on disk raise `FastXlsx::Error`
+- Rows and columns are 0-based
+
+### Cell values
+
+- Numeric, String, Time, Date/DateTime, boolean and nil
+- `FastXlsx::Formula`, `FastXlsx::URL` (optionally showing other text), `FastXlsx::RichString` (a format per text segment)
+
+### Formatting
+
+- `FastXlsx::Format`: fonts, colors, number formats, alignment, wrapping, rotation, indent, borders and underline styles; unknown options and invalid values raise `ArgumentError`
+- One format per row or per cell in `append`; `Worksheet#column_format` for column defaults
+
+### Layout and features
+
+- `column_width`, `autofit` (keeps widths set explicitly), `row_height`, `freeze_panes`, `merge_range`, `autofilter`
+- `conditional_format` (cell, text, formula, data bar, color scale), `data_validation` (lists, numbers, text length, messages)
+- `add_table` (styles, total row, column totals), `insert_chart`, `insert_image` (path or IO, scale or pixel size), `write_comment`
+- Printing: `page_header`, `page_footer`, `margins`, `page_breaks`, `vertical_page_breaks`
+- Unknown options to the option-hash methods raise `ArgumentError`
+
+### Packaging
+
+- Precompiled gems for Linux (glibc and musl, x86_64 and aarch64, arm), macOS (arm64 and x86_64) and Windows (x64); requires CRuby 3.3+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Zac
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,298 @@
+# FastXlsx
+
+[![codecov](https://codecov.io/gh/7a6163/fast_xlsx/graph/badge.svg)](https://codecov.io/gh/7a6163/fast_xlsx)
+
+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.
+
+## Usage
+
+```ruby
+require "fast_xlsx"
+
+wb = FastXlsx::Workbook.new                       # or memory: :constant / :low, see below
+ws = wb.add_worksheet("Report")                  # later: wb.worksheet("Report"), wb.worksheets
+
+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)
+
+wb.properties(title: "Q3 report", author: "Zac", keywords: "Confidential") # File > Info in Excel
+wb.save("report.xlsx")                            # or wb.to_xlsx => binary String
+```
+
+### Memory modes
+
+By default every cell stays in memory until the file is saved. For large exports, two modes write each finished row to a temp file instead:
+
+```ruby
+FastXlsx::Workbook.new                          # memory: :standard (default): everything in memory, any write order
+FastXlsx::Workbook.new(memory: :constant)       # rows on disk, strings stored inline in each cell
+FastXlsx::Workbook.new(memory: :low)            # rows on disk, strings in Excel's shared string table
+```
+
+| | `:standard` (default) | `:constant` | `:low` |
+|---|---|---|---|
+| Finished rows | kept in memory | written to disk | written to disk |
+| Memory grows with | all cells | nothing (flat) | the number of unique strings |
+| Write order | any | top to bottom only | top to bottom only |
+| `autofit` | full | only sees rows still in memory | only sees rows still in memory |
+| Strings | shared string table | inline in each cell | shared string table |
+| Output | standard | some readers (e.g. xsv) don't support inline strings | standard |
+
+Which one:
+
+- **`:standard`** for normal reports, when you need to go back and change earlier rows, or rely on `autofit`.
+- **`:constant`** for large exports written row by row: memory stays flat whatever the data, and it is the fastest mode.
+- **`:low`** for large exports that other programs will read: memory stays low when strings repeat (regions, statuses, …) and the file uses the standard shared string table. With many unique strings it keeps those strings in memory until `save`.
+
+In both disk-backed modes, writing to a row that was already written to disk raises `FastXlsx::Error`, and tables must be added before their data (see [Tables](#tables)). An unknown mode raises `ArgumentError`.
+
+### Formats
+
+```ruby
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin, align: :center)
+date   = FastXlsx::Format.new(num_format: "yyyy-mm-dd")
+
+ws.append(["id", "name", "created_at"], format: header)  # format every cell in the row
+ws.append([1, "a", Time.now], format: [nil, nil, date]) # or one format (or nil) per cell
+ws.write(1, 2, Date.today, date)                         # format one cell
+```
+
+| Option | Values |
+|---|---|
+| `bold`, `italic`, `strikeout`, `text_wrap`, `shrink` | `true` / `false` |
+| `underline` | `true` (single), `:single`, `:double`, `:single_accounting`, `:double_accounting` |
+| `font_script` | `:superscript`, `:subscript` |
+| `rotation` | degrees, `-90..90`, or `270` for stacked text |
+| `indent` | indent level, e.g. `2` |
+| `font_size` | number, e.g. `14` |
+| `font_name` | e.g. `"Arial"` |
+| `font_color`, `bg_color` | `"#RRGGBB"` or `0xRRGGBB` |
+| `num_format` | Excel number format, e.g. `"#,##0.00"`, `"yyyy-mm-dd"` |
+| `align` | `:left`, `:center`, `:right` |
+| `valign` | `:top`, `:center`, `:bottom` |
+| `border`, `border_left`, `border_right`, `border_top`, `border_bottom` | `:thin`, `:medium`, `:thick`, `:dashed`, `:dotted`, `:double`, `:hair` |
+| `border_color` | `"#RRGGBB"` or `0xRRGGBB` |
+
+Per-side borders override `border`. Unknown options and invalid values raise `ArgumentError`.
+
+### Columns and filters
+
+```ruby
+ws.column_width(0, 20)        # column A, width in characters
+ws.column_width(1..3, 12)     # columns B–D
+ws.column_format(4, FastXlsx::Format.new(num_format: "#,##0.00")) # default for cells in E written without a format
+ws.autofit                        # size other columns to the data written so far; set widths are kept
+ws.autofilter(0, 0, 100, 3)       # filter buttons on A1:D101 (first_row, first_col, last_row, last_col)
+```
+
+`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
+
+```ruby
+ws.freeze_panes(1, 0)                          # keep the first row visible while scrolling
+ws.row_height(0, 30)                       # row 1, height in points
+ws.merge_range(0, 0, 0, 3, "Q3 report", title) # merge A1:D1; the value can be any cell type
+ws.page_breaks([50, 100])                  # print a new page before rows 51 and 101
+ws.vertical_page_breaks([8])               # and before column I
+ws.page_header("&CPage &P of &N")               # printed header, Excel header/footer codes
+ws.page_footer("&L&A", margin: 0.2)             # sheet name on the left; margin in inches
+ws.margins(left: 0.5, top: 1)              # other margins keep Excel's defaults
+```
+
+### Conditional formats
+
+```ruby
+red = FastXlsx::Format.new(font_color: "#9C0006", bg_color: "#FFC7CE")
+
+# rows 1–100 of column B (first_row, first_col, last_row, last_col)
+ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :<, value: 0, format: red)
+ws.conditional_format(0, 1, 99, 1, type: :cell, criteria: :between, value: [1, 10], format: red)
+ws.conditional_format(0, 0, 99, 0, type: :text, criteria: :contains, value: "error", format: red)
+ws.conditional_format(0, 0, 99, 3, type: :formula, value: "=$D1>100", format: red)
+ws.conditional_format(0, 2, 99, 2, type: :data_bar)
+ws.conditional_format(0, 2, 99, 2, type: :color_scale)            # 3-color; colors: 2 for 2-color
+```
+
+| `type` | `criteria` | `value` |
+|---|---|---|
+| `:cell` | `:==`, `:!=`, `:>`, `:>=`, `:<`, `:<=`, `:between`, `:not_between` | number or string; `[min, max]` for the range criteria |
+| `:text` | `:contains`, `:not_contains`, `:begins_with`, `:ends_with` | string |
+| `:formula` | — | formula string, relative to the top-left cell |
+| `:data_bar`, `:color_scale` | — | — |
+
+### Data validation
+
+```ruby
+ws.data_validation(1, 2, 100, 2, type: :list, value: %w[Open Closed])     # dropdown in C2:C101
+ws.data_validation(1, 2, 100, 2, type: :list, value: "=$Z$1:$Z$10")       # dropdown from a range
+ws.data_validation(1, 3, 100, 3, type: :whole_number, criteria: :between, value: [1, 10],
+                   input_title: "Quantity", input_message: "1 to 10",
+                   error_title: "Invalid", error_message: "Enter a whole number from 1 to 10")
+```
+
+`type` is `:list`, `:whole_number`, `:decimal` or `:text_length`; the number types take the same `criteria` as `:cell` conditional formats.
+
+### Comments
+
+```ruby
+ws.write_comment(0, 0, "Checked by finance", author: "Zac")   # Excel shows it as a note on A1
+```
+
+### Images
+
+```ruby
+ws.insert_image(0, 0, "logo.png")                                  # top-left corner in A1
+ws.insert_image(0, 5, StringIO.new(blob.download), scale: 0.5, x_offset: 10, y_offset: 4, alt_text: "Logo")
+ws.insert_image(10, 0, "chart.png", width: 320, height: 180)       # pixel size; one of them keeps the aspect ratio
+```
+
+A String is always treated as a path, so wrap raw bytes (such as Active Storage's `blob.download`) in a `StringIO`.
+
+The source is a file path or any IO responding to `#read` (PNG, JPEG, GIF or BMP). Offsets are in pixels. Data that is not a supported image raises `FastXlsx::Error`.
+
+### Tables
+
+```ruby
+ws.concat([%w[Region Rep Sales], *sales])            # header row, then the data
+ws.add_table(0, 0, sales.size + 1, 2, total_row: true, style: :medium2, # +1 row for the totals
+             columns: [{ header: "Region", total_label: "Total" }, "Rep", { header: "Sales", total: :sum }])
+```
+
+The range includes the header row and, with `total_row: true`, the total row; the table writes the headers. `columns` must match the range width. Options: `style` (`:light1`–`:light21`, `:medium1`–`:medium28`, `:dark1`–`:dark11`, `:none`), `name`, `total_row`, `banded_rows`, `autofilter`. Column totals: `:sum`, `:average`, `:count`, `:count_numbers`, `:max`, `:min`, `:std_dev`, `:var`.
+
+You can also add the table first and then append the data: after `add_table`, `<<` / `append` / `concat` continue right under the header row. In `:constant` / `:low` memory mode this is the only order that works; adding a table whose header row was already written to disk raises `FastXlsx::Error`.
+
+### Charts
+
+```ruby
+ws.concat([%w[Month Sales Costs], ["Jan", 10, 7], ["Feb", 25, 12], ["Mar", 18, 11]])
+
+ws.insert_chart(1, 4, type: :column,
+                series: [
+                  { name: "Sales", categories: "Sheet1!$A$2:$A$4", values: "Sheet1!$B$2:$B$4" },
+                  { name: "Costs", categories: "Sheet1!$A$2:$A$4", values: "Sheet1!$C$2:$C$4" }
+                ],
+                title: "Q1", x_axis: "Month", y_axis: "Amount", width: 600, height: 360)
+```
+
+`type`: `:column`, `:column_stacked`, `:bar`, `:bar_stacked`, `:line`, `:line_stacked`, `:area`, `:area_stacked`, `:pie`, `:doughnut`, `:radar`, `:scatter`. Ranges use Excel syntax, so a chart can plot data from another worksheet. Sizes are in pixels (default 480 × 288).
+
+Values are mapped by type:
+
+| Ruby | Excel |
+|---|---|
+| `Integer`, `Float`, any `Numeric` | number |
+| `String` | string |
+| `Time` | number (Excel serial date, local time) |
+| `Date`, `DateTime` | number (Excel serial date, own offset) |
+| `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 |
+| `true` / `false` | boolean |
+| `nil` | empty cell |
+| anything else | `to_s` as string |
+
+`<<` 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`.
+
+## Performance
+
+Apple Silicon, Ruby 4.0.5. Each library uses its own idiomatic row-append API; xlsxtream is a streaming writer with fewer features.
+
+### Speed
+
+20,000 rows × 5 columns (integer, string, integer, `Time`, float), build + serialize to a String, median of 7 runs (3 for rubyXL):
+
+| 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.
+
+### Memory
+
+200,000 rows × 5 columns saved to a file; extra peak RSS over a process that only builds the data, median of 3 runs. "Unique" gives every row a different 100-character string; "repeated" uses a handful of values (regions, statuses), as most reports do:
+
+| 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 |
+
+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.
+
+### Reproduce
+
+```bash
+bundle exec rake compile
+BUNDLE_GEMFILE=bench/Gemfile bundle install
+BUNDLE_GEMFILE=bench/Gemfile bundle exec ruby bench/compare.rb   # speed; optional row count argument
+
+# memory: peak RSS of one run (use /usr/bin/time -v on Linux); subtract the baseline
+BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb baseline unique
+BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb fast_xlsx:low unique
+```
+
+## Installation
+
+```bash
+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.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake compile   # build the Rust extension into lib/fast_xlsx/
+bundle exec rake test
+bundle exec rake           # compile + test + rubocop
+```
+
+Coverage of the Rust extension while the Ruby tests run (needs [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov) and `rustup component add llvm-tools-preview`):
+
+```bash
+rm -rf tmp lib/fast_xlsx/fast_xlsx.bundle           # force an instrumented rebuild
+eval "$(cargo llvm-cov show-env --export-prefix)"
+bundle exec rake compile test
+cargo llvm-cov report --release                     # or --lcov / --html
+```
+
+Rebuild in a clean shell afterwards (`rm -rf tmp && bundle exec rake compile`) so the everyday build is not instrumented.
+
+### Releasing
+
+First generate the showcase workbook and open it in Excel to check every feature renders (the test suite only inspects the XML):
+
+```bash
+bundle exec rake compile
+ruby -Ilib examples/showcase.rb showcase.xlsx
+```
+
+Then bump `FastXlsx::VERSION`, update `CHANGELOG.md`, commit, and push a matching tag:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The `Build gems` workflow builds the source gem plus precompiled gems for each platform and pushes them to RubyGems (trusted publishing) and GitHub Packages. It refuses to publish if the tag and `VERSION` differ.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rb_sys/extensiontask"
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load("fast_xlsx.gemspec")
+
+RbSys::ExtensionTask.new("fast_xlsx", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/fast_xlsx"
+end
+
+task default: %i[compile test rubocop]

data/bench/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Libraries compared in bench/compare.rb. Kept out of the main Gemfile so CI
+# does not install them. Usage: BUNDLE_GEMFILE=bench/Gemfile bundle exec ruby bench/compare.rb
+
+source "https://rubygems.org"
+
+gem "fast_xlsx", path: ".."
+
+gem "caxlsx"
+gem "fast_excel"
+gem "rubyXL"
+gem "write_xlsx"
+gem "xlsxtream"

data/bench/Gemfile.lock

@@ -0,0 +1,110 @@
+PATH
+  remote: ..
+  specs:
+    fast_xlsx (0.1.0)
+      rb_sys (~> 0.9.130)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    caxlsx (4.5.0)
+      htmlentities (~> 4.3, >= 4.3.4)
+      marcel (~> 1.0)
+      nokogiri (~> 1.10, >= 1.10.4)
+      rubyzip (>= 2.4, < 4)
+    fast_excel (0.5.0)
+      ffi (> 1.9, < 2)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
+    htmlentities (4.4.2)
+    marcel (1.2.1)
+    nkf (0.3.0)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-musl)
+      racc (~> 1.4)
+    racc (1.8.1)
+    rake-compiler-dock (1.12.0)
+    rb_sys (0.9.130)
+      rake-compiler-dock (= 1.12.0)
+    rubyXL (3.4.38)
+      nokogiri (>= 1.10.8)
+      rubyzip (>= 3.2.2)
+    rubyzip (3.7.0)
+    write_xlsx (1.15.1)
+      nkf
+      rubyzip (>= 2.4.0, < 4.0)
+    xlsxtream (3.1.0)
+      zip_kit (>= 6.2, < 7)
+    zip_kit (6.3.4)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  caxlsx
+  fast_excel
+  fast_xlsx!
+  rubyXL
+  write_xlsx
+  xlsxtream
+
+CHECKSUMS
+  caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
+  fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
+  fast_xlsx (0.1.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
+  ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
+  htmlentities (4.4.2) sha256=bbafbdf69f2eca9262be4efef7e43e6a1de54c95eb600f26984f71d2fe96c5c3
+  marcel (1.2.1) sha256=1678e9360e32f9eafa917c80029e2f6d10b2715c66a4b87b6d0da9b9cd1f859f
+  nkf (0.3.0) sha256=357a8dbeba38b727b75930f665146546076a394a1c243faf634ff176e3588895
+  nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f
+  nokogiri (1.19.4-aarch64-linux-musl) sha256=35c65b9ce72b3bb03207bdbe7067915019dc18c1b9b59139684bd6690fdd01af
+  nokogiri (1.19.4-arm-linux-gnu) sha256=a301313e38bb065d68239e79734bcd6f56fb6efaacebde29e9abf2a4735340ca
+  nokogiri (1.19.4-arm-linux-musl) sha256=588923c101bcfa78869734d247d25b598674323e7f22474fc468f6e5647311eb
+  nokogiri (1.19.4-arm64-darwin) sha256=a46db9853286e6597b36ebc6953817d15acf3a299583eb3f89fdc6f91dd63527
+  nokogiri (1.19.4-x86_64-darwin) sha256=7fd17057d3e1f00e9954a74b3cd76595d3d4a5ef233b7ed9599047c204f70551
+  nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
+  nokogiri (1.19.4-x86_64-linux-musl) sha256=17dfb7c1fa194ae02fbf7c51a7afc8d278045ab3fdacfd86f91d02d7b274470b
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rake-compiler-dock (1.12.0) sha256=f13205c2738f3d2053afcd03491a9e4541b22a59a0bfc53fc8bc883bd8188023
+  rb_sys (0.9.130) sha256=7d486d99c1da02635515deaf9860fc5aea90bb4ab2589b2deec7fdc7d3548615
+  rubyXL (3.4.38) sha256=6b3f46a5ff8ec9903a562604a379a6b79b67cdec73515162b1785bd6092e6ce6
+  rubyzip (3.7.0) sha256=65c19294da75297a939006f3516deacc33185fbd721ff1954f7a231db6d3e121
+  write_xlsx (1.15.1) sha256=6a97a5ea9af2fd2f248af4aa61cdced0933b6887c96826b6a04f8384a656d3a2
+  xlsxtream (3.1.0) sha256=68ce0cac504d86beb9bc626defd5977146c68e5ca2a4ab76c5c61c48e0a66fcd
+  zip_kit (6.3.4) sha256=407c6d39feef818678fae2d129077bd2f920c9806072af3482e671eeae3c48ea
+
+BUNDLED WITH
+  4.0.10

data/bench/compare.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Compares fast_xlsx with other Ruby xlsx writers on the same data.
+#
+#   BUNDLE_GEMFILE=bench/Gemfile bundle install
+#   bundle exec rake compile
+#   BUNDLE_GEMFILE=bench/Gemfile bundle exec ruby bench/compare.rb [rows]
+require "stringio"
+
+require "fast_xlsx"
+require "fast_excel"
+require "caxlsx"
+require "write_xlsx"
+require "xlsxtream"
+require "rubyXL"
+require "rubyXL/convenience_methods"
+
+def elapsed
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+  Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+end
+
+ROWS = Integer(ARGV[0] || 20_000)
+DATA = Array.new(ROWS) do |n|
+  [n, "String string #{n}" * 5, n * 7 % 1000, Time.at((n * 1000) + 1_492_922_688), n * 100.5]
+end
+
+# Each writer builds one worksheet from DATA and returns the .xlsx bytes.
+WRITERS = {
+  "fast_xlsx" => lambda {
+    wb = FastXlsx::Workbook.new
+    wb.add_worksheet.concat(DATA)
+    wb.to_xlsx
+  },
+  "fast_xlsx (memory: :constant)" => lambda {
+    wb = FastXlsx::Workbook.new(memory: :constant)
+    wb.add_worksheet.concat(DATA)
+    wb.to_xlsx
+  },
+  "fast_xlsx (memory: :low)" => lambda {
+    wb = FastXlsx::Workbook.new(memory: :low)
+    wb.add_worksheet.concat(DATA)
+    wb.to_xlsx
+  },
+  "fast_excel" => lambda {
+    wb = FastExcel.open
+    ws = wb.add_worksheet
+    DATA.each { |r| ws << r }
+    wb.read_string
+  },
+  "fast_excel (constant_memory)" => lambda {
+    wb = FastExcel.open(constant_memory: true)
+    ws = wb.add_worksheet
+    DATA.each { |r| ws << r }
+    wb.read_string
+  },
+  "write_xlsx" => lambda {
+    io = StringIO.new
+    wb = WriteXLSX.new(io)
+    ws = wb.add_worksheet
+    DATA.each_with_index { |r, i| ws.write_row(i, 0, r) }
+    wb.close
+    io.string
+  },
+  "xlsxtream" => lambda {
+    io = StringIO.new
+    Xlsxtream::Workbook.open(io) do |xlsx|
+      xlsx.write_worksheet("Sheet1") { |ws| DATA.each { |r| ws << r } }
+    end
+    io.string
+  },
+  "caxlsx" => lambda {
+    package = Axlsx::Package.new
+    package.workbook.add_worksheet { |ws| DATA.each { |r| ws.add_row(r) } }
+    package.to_stream.read
+  },
+  "rubyXL" => lambda {
+    wb = RubyXL::Workbook.new
+    ws = wb[0]
+    DATA.each_with_index { |r, i| r.each_with_index { |v, j| ws.add_cell(i, j, v) } }
+    wb.stream.read
+  }
+}.freeze
+
+def measure(writer, runs)
+  bytes = writer.call # warm up
+  times = Array.new(runs) do
+    GC.start
+    elapsed { writer.call }
+  end
+  GC.start
+  before = GC.stat(:total_allocated_objects)
+  writer.call
+  { ms: times.sort[runs / 2] * 1000, allocs: GC.stat(:total_allocated_objects) - before, kb: bytes.bytesize / 1024 }
+end
+
+puts "#{ROWS} rows x 5 columns (integer, string, integer, Time, float), Ruby #{RUBY_VERSION}, #{RUBY_PLATFORM}"
+puts
+
+results = WRITERS.to_h do |name, writer|
+  runs = name == "rubyXL" ? 3 : 7
+  [name, measure(writer, runs)]
+end
+
+fastest = results.values.map { |r| r[:ms] }.min
+puts "| Library | Time (median) | vs fastest | Ruby objects allocated | Output |"
+puts "|---|---:|---:|---:|---:|"
+results.sort_by { |_, r| r[:ms] }.each do |name, r|
+  puts format("| %<name>s | %<ms>.0f ms | %<x>.1fx | %<allocs>s | %<kb>d KB |",
+              name: name, ms: r[:ms], x: r[:ms] / fastest,
+              allocs: r[:allocs].to_s.reverse.scan(/\d{1,3}/).join(",").reverse, kb: r[:kb])
+end

data/bench/memory.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Writes one workbook in this process so its peak memory can be read by the OS:
+#
+#   BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -l bundle exec ruby bench/memory.rb fast_xlsx:low unique  # macOS
+#   BUNDLE_GEMFILE=bench/Gemfile /usr/bin/time -v bundle exec ruby bench/memory.rb fast_xlsx:low unique  # Linux
+#
+# writer: baseline (build the data only), fast_xlsx[:constant|:low], fast_excel[:constant]
+# data:   unique (every string differs) or repeated (a few distinct strings)
+# Subtract the baseline's peak to get what writing the file adds.
+require "fast_xlsx"
+require "fileutils"
+require "tmpdir"
+
+writer = ARGV[0]
+kind = ARGV[1] || "unique"
+rows = Integer(ARGV[2] || 200_000)
+regions = %w[North South East West Central]
+statuses = %w[Open Closed Pending Cancelled]
+data = Array.new(rows) do |n|
+  label = kind == "unique" ? "String string #{n}" * 5 : regions[n % 5]
+  [n, label, statuses[n % 4], Time.at((n * 1000) + 1_492_922_688), n * 100.5]
+end
+out = File.join(Dir.tmpdir, "fast_xlsx_memory_#{Process.pid}.xlsx")
+
+case writer
+when "baseline"
+  nil
+when /\Afast_xlsx/
+  mode = writer.split(":")[1]
+  wb = FastXlsx::Workbook.new(memory: (mode || "standard").to_sym)
+  wb.add_worksheet.concat(data)
+  wb.save(out)
+when /\Afast_excel/
+  require "fast_excel"
+  wb = FastExcel.open(out, constant_memory: writer.end_with?(":constant"))
+  ws = wb.add_worksheet
+  data.each { |r| ws << r }
+  wb.close
+else
+  abort "unknown writer #{writer}"
+end
+FileUtils.rm_f(out)

data/bench/write.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Usage: bundle exec rake compile && ruby -Ilib bench/write.rb
+# Compares against fast_excel when it can be loaded (FAST_EXCEL=/path/to/fast_excel/lib/fast_excel).
+require "fast_xlsx"
+
+def elapsed
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+  Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+end
+
+ROWS = 20_000
+DATA = Array.new(ROWS) do |n|
+  [n, "String string #{n}" * 5, n * 7 % 1000, Time.at((n * 1000) + 1_492_922_688), n * 100.5]
+end
+
+def report(label, runs = 7, &block)
+  times = Array.new(runs) do
+    GC.start
+    elapsed(&block)
+  end
+  puts "  #{label.ljust(26)} #{(times.sort[runs / 2] * 1000).round(1)} ms"
+end
+
+begin
+  require ENV.fetch("FAST_EXCEL", "fast_excel")
+rescue LoadError
+  nil
+end
+
+[false, true].each do |cm|
+  puts "memory=#{cm ? "constant" : "standard"}, #{ROWS}x5 cells, median of 7"
+  report("fast_xlsx <<") do
+    wb = FastXlsx::Workbook.new(memory: cm ? :constant : :standard)
+    ws = wb.add_worksheet
+    DATA.each { |r| ws << r }
+    wb.to_xlsx
+  end
+  report("fast_xlsx concat") do
+    wb = FastXlsx::Workbook.new(memory: cm ? :constant : :standard)
+    wb.add_worksheet.concat(DATA)
+    wb.to_xlsx
+  end
+  next unless defined?(FastExcel)
+
+  report("fast_excel <<") do
+    wb = FastExcel.open(constant_memory: cm)
+    ws = wb.add_worksheet
+    DATA.each { |r| ws << r }
+    wb.read_string
+  end
+end

data/examples/showcase.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# Builds one workbook with a worksheet per feature, to check the output in
+# Excel (or LibreOffice / Numbers) before a release.
+#
+#   bundle exec rake compile
+#   ruby -Ilib examples/showcase.rb [showcase.xlsx]
+require "date"
+require "stringio"
+require "zlib"
+require "fast_xlsx"
+
+path = ARGV[0] || "showcase.xlsx"
+
+# A small gradient PNG, generated so the example needs no image file.
+def gradient_png(width, height)
+  rows = (0...height).map do |y|
+    "\0".b + (0...width).map { |x| [x * 255 / width, y * 255 / height, 200].pack("C3") }.join
+  end
+  chunk = ->(type, data) { [data.bytesize].pack("N") + type + data + [Zlib.crc32(type + data)].pack("N") }
+  "\x89PNG\r\n\x1A\n".b +
+    chunk.call("IHDR", [width, height, 8, 2, 0, 0, 0].pack("NNC5")) +
+    chunk.call("IDAT", Zlib::Deflate.deflate(rows.join)) +
+    chunk.call("IEND", "".b)
+end
+
+wb = FastXlsx::Workbook.new
+wb.properties(title: "fast_xlsx showcase", author: "fast_xlsx", keywords: "example")
+
+bold = FastXlsx::Format.new(bold: true)
+header = FastXlsx::Format.new(bold: true, bg_color: "#DDEBF7", border_bottom: :thin, align: :center)
+money = FastXlsx::Format.new(num_format: "#,##0.00")
+date = FastXlsx::Format.new(num_format: "yyyy-mm-dd")
+datetime = FastXlsx::Format.new(num_format: "yyyy-mm-dd hh:mm")
+
+# Values: every cell type.
+ws = wb.add_worksheet("Values")
+ws.column_width(0, 22).column_width(1, 40)
+ws.append(%w[Type Value], format: header)
+ws << ["Integer", 42]
+ws << ["Float", 3.14159]
+ws.append(["Money format", 1_234_567.891], format: [nil, money])
+ws.append(["Date", Date.new(2024, 2, 29)], format: [nil, date])
+ws.append(["Time", Time.new(2024, 2, 29, 13, 45)], format: [nil, datetime])
+ws << ["Boolean", true]
+ws << ["nil (empty cell)", nil]
+ws << ["Formula =SUM(B2:B3)", FastXlsx::Formula.new("SUM(B2:B3)")]
+ws << ["URL", FastXlsx::URL.new("https://github.com/7a6163/fast_xlsx")]
+ws << ["URL with text", FastXlsx::URL.new("https://github.com/7a6163/fast_xlsx", text: "fast_xlsx on GitHub")]
+ws << ["Rich string",
+       FastXlsx::RichString.new(["Bold ", bold], "plain ", ["italic", FastXlsx::Format.new(italic: true)])]
+ws << ["Symbol (to_s)", :symbol]
+
+# Formats: one option per row.
+ws = wb.add_worksheet("Formats")
+ws.column_width(0, 24).column_width(1, 30)
+ws.append(%w[Option Sample], format: header)
+{
+  "bold" => { bold: true }, "italic" => { italic: true }, "strikeout" => { strikeout: true },
+  "underline :double" => { underline: :double }, "font_script :superscript" => { font_script: :superscript },
+  "font_size 16" => { font_size: 16 }, "font_name Courier New" => { font_name: "Courier New" },
+  "font_color #C00000" => { font_color: "#C00000" }, "bg_color #FFF2CC" => { bg_color: "#FFF2CC" },
+  "align :right" => { align: :right }, "valign :top" => { valign: :top }, "indent 2" => { indent: 2 },
+  "rotation 45" => { rotation: 45 }, "text_wrap" => { text_wrap: true }, "shrink" => { shrink: true },
+  "border :medium + color" => { border: :medium, border_color: "#2F5597" },
+  "border_bottom :double" => { border_bottom: :double }
+}.each do |label, options|
+  text = label == "text_wrap" ? "long text that wraps inside the cell width" : "Sample text"
+  ws.append([label, text], format: [nil, FastXlsx::Format.new(**options)])
+end
+ws.row_height(14, 40)
+
+# Layout: widths, autofit, merged title, frozen header, filter.
+ws = wb.add_worksheet("Layout")
+ws.merge_range(0, 0, 0, 3, "Merged title across A1:D1", FastXlsx::Format.new(bold: true, font_size: 14, align: :center))
+ws.append(%w[Region Rep Amount Note], format: header)
+20.times { |i| ws << [%w[North South East West][i % 4], "Rep #{i + 1}", (i + 1) * 125.5, "row #{i + 1}"] }
+ws.column_format(2, money)
+ws.column_width(3, 30) # kept by autofit
+ws.autofit
+ws.freeze_panes(2, 0)
+ws.autofilter(1, 0, 21, 3)
+
+# Conditional formats.
+ws = wb.add_worksheet("Conditional")
+red = FastXlsx::Format.new(font_color: "#9C0006", bg_color: "#FFC7CE")
+green = FastXlsx::Format.new(font_color: "#006100", bg_color: "#C6EFCE")
+ws.append(["Cell < 0", "Text contains 'error'", "Data bar", "Color scale", "Formula (A > 50)"], format: header)
+values = [-30, 80, 15, -5, 60, 95, 40, -10, 70, 25]
+values.each_with_index { |v, i| ws << [v, i.even? ? "ok" : "error #{i}", v.abs, v, v] }
+ws.conditional_format(1, 0, 10, 0, type: :cell, criteria: :<, value: 0, format: red)
+ws.conditional_format(1, 1, 10, 1, type: :text, criteria: :contains, value: "error", format: red)
+ws.conditional_format(1, 2, 10, 2, type: :data_bar)
+ws.conditional_format(1, 3, 10, 3, type: :color_scale)
+ws.conditional_format(1, 4, 10, 4, type: :formula, value: "=$A2>50", format: green)
+ws.column_width(0..4, 22)
+
+# Data validation.
+ws = wb.add_worksheet("Validation")
+ws.append(["Status (dropdown)", "Quantity 1-10", "Price >= 0", "Code <= 5 chars"], format: header)
+ws.data_validation(1, 0, 20, 0, type: :list, value: %w[Open Pending Closed],
+                                input_title: "Status", input_message: "Pick a status")
+ws.data_validation(1, 1, 20, 1, type: :whole_number, criteria: :between, value: [1, 10],
+                                error_title: "Invalid quantity", error_message: "Enter a whole number from 1 to 10")
+ws.data_validation(1, 2, 20, 2, type: :decimal, criteria: :>=, value: 0)
+ws.data_validation(1, 3, 20, 3, type: :text_length, criteria: :<=, value: 5)
+ws.column_width(0..3, 20)
+
+# Table with a total row.
+ws = wb.add_worksheet("Table")
+sales = [%w[North Ann 1200], %w[South Bob 950], %w[East Cai 1430], %w[West Dee 780]].map { |r, n, a| [r, n, a.to_i] }
+ws.add_table(0, 0, sales.size + 1, 2, total_row: true, style: :medium2,
+                                      columns: [{ header: "Region", total_label: "Total" }, "Rep",
+                                                { header: "Sales", total: :sum, format: money }])
+ws.concat(sales)
+ws.column_width(0..2, 14)
+
+# Charts.
+ws = wb.add_worksheet("Chart")
+ws.append(%w[Month Sales Costs], format: header)
+ws.concat([["Jan", 10, 7], ["Feb", 25, 12], ["Mar", 18, 11], ["Apr", 30, 16], ["May", 27, 14]])
+series = [{ name: "Sales", categories: "Chart!$A$2:$A$6", values: "Chart!$B$2:$B$6" },
+          { name: "Costs", categories: "Chart!$A$2:$A$6", values: "Chart!$C$2:$C$6" }]
+ws.insert_chart(0, 4, type: :column, series: series, title: "Column", x_axis: "Month", y_axis: "Amount")
+ws.insert_chart(16, 4, type: :line, series: series, title: "Line", width: 600, height: 300)
+ws.insert_chart(16, 0, type: :pie, series: [series.first], title: "Pie", width: 300, height: 300)
+
+# Image and comment.
+ws = wb.add_worksheet("Media")
+ws << ["Generated PNG at scale 1, pixel size 240x60, and with an offset. B1 has a comment."]
+ws.write_comment(0, 1, "This is a note (comment).", author: "fast_xlsx")
+png = gradient_png(120, 40)
+ws.insert_image(2, 0, StringIO.new(png), alt_text: "Gradient")
+ws.insert_image(2, 3, StringIO.new(png), width: 240, height: 60)
+ws.insert_image(8, 0, StringIO.new(png), x_offset: 20, y_offset: 10, scale: 1.5)
+
+# Printing: check File > Print preview.
+ws = wb.add_worksheet("Printing")
+ws.page_header("&CPage &P of &N").page_footer("&L&A&R&D", margin: 0.2).margins(left: 0.5, right: 0.5)
+ws.page_breaks([30])
+ws.vertical_page_breaks([4])
+ws.append(%w[Row A B C D E F], format: header)
+60.times { |i| ws << [i + 1, *Array.new(6) { |c| (i + 1) * (c + 1) }] }
+
+wb.save(path)
+puts "wrote #{path}"

data/lib/fast_xlsx/3.3/fast_xlsx.so

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: data/lib/fast_xlsx/3.3/fast_xlsx.so
+size: 33943032 bytes
+sha256: 261882173f94edd46d754f7eac0b7938388c6f670b16f1ffdbc7977305e688ee

data/lib/fast_xlsx/3.4/fast_xlsx.so

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: data/lib/fast_xlsx/3.4/fast_xlsx.so
+size: 33915280 bytes
+sha256: 76348560391dcfd884ff751b6af72ba2717822fbe21c27e59aba5a2775cf9ec3

data/lib/fast_xlsx/4.0/fast_xlsx.so

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: data/lib/fast_xlsx/4.0/fast_xlsx.so
+size: 33890116 bytes
+sha256: c9241b2aee4fc4bdbccf8ae2ea3d559df08de4c56620e80cf8798b5e56ef860c

data/lib/fast_xlsx/version.rb

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

data/lib/fast_xlsx.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "fast_xlsx/version"
+
+# Fast .xlsx writer backed by rust_xlsxwriter.
+module FastXlsx
+  class Error < StandardError; end
+
+  # Cell value written as an Excel formula, e.g. Formula.new("SUM(A1:A9)").
+  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.
+  # 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
+    def self.new(*args, **kwargs)
+      raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..2)" if args.size > 2
+
+      kwargs[:url] = args[0] unless args.empty?
+      kwargs[:text] = args[1] if args.size > 1
+      super(**kwargs)
+    end
+
+    # Also reached by URL[...] and #with, so values are normalized here.
+    def initialize(url:, text: nil)
+      super(url: url.to_s, text: text&.to_s)
+    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].
+  class RichString
+    attr_reader :segments
+
+    def initialize(*parts)
+      raise ArgumentError, "RichString needs at least one segment" if parts.empty?
+
+      @segments = parts.map { |part| part.is_a?(Array) ? [part[0].to_s, part[1]] : [part.to_s, nil] }.freeze
+    end
+  end
+
+  # The native extension looks up FastXlsx::Error, so load it after Error is defined.
+  require "fast_xlsx/fast_xlsx"
+
+  # Owns the worksheets; serialize with #to_xlsx or #save.
+  class Workbook
+    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).
+    def self.new(memory: :standard)
+      unless MEMORY_MODES.include?(memory)
+        raise ArgumentError, "unknown memory mode #{memory.inspect} (expected one of #{MEMORY_MODES.join(", ")})"
+      end
+
+      _new(memory == :constant, memory == :low)
+    end
+
+    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.
+    def worksheets
+      @worksheets ||= []
+    end
+
+    def worksheet(name)
+      worksheets.find { |ws| ws.name == name }
+    end
+
+    # Document properties shown in Excel's File > Info: title:, subject:,
+    # author:, manager:, company:, category:, keywords:, comments:, status:.
+    # Later calls add to earlier ones.
+    def properties(**fields)
+      merged = (@properties || {}).merge(fields)
+      _properties(merged) # validates before anything is remembered
+      @properties = merged
+      self
+    end
+  end
+
+  # Cell writer for one sheet; create with Workbook#add_worksheet.
+  class Worksheet
+    def write(row, col, value, format = nil)
+      _write(row, col, value, format)
+      self
+    end
+
+    def append(values, format: nil)
+      _append(values, format)
+    end
+
+    # columns: a 0-based column index or a Range of them. width is in characters.
+    def column_width(columns, width)
+      bounds = column_bounds(columns)
+      _column_width(*bounds, width)
+      @fixed_widths ||= {}
+      @fixed_widths.delete(bounds) # re-insert so autofit replays calls in order
+      @fixed_widths[bounds] = width
+      self
+    end
+
+    # Sizes columns to the data written so far. Widths set with
+    # column_width are kept.
+    def autofit
+      _autofit
+      @fixed_widths&.each { |bounds, width| _column_width(*bounds, width) }
+      self
+    end
+
+    # Merges the range and writes value (any cell type) into its first cell.
+    def merge_range(first_row, first_col, last_row, last_col, value, format = nil)
+      _merge_range(first_row, first_col, last_row, last_col, 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.
+    def conditional_format(first_row, first_col, last_row, last_col, type:, **)
+      _conditional_format(first_row, first_col, last_row, last_col, { 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.
+    def data_validation(first_row, first_col, last_row, last_col, type:, **)
+      _data_validation(first_row, first_col, last_row, last_col, { type: type, ** })
+    end
+
+    # Adds a comment (Excel "note") to a cell.
+    def write_comment(row, col, text, author: nil)
+      _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, **)
+      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:.
+    def insert_chart(row, col, type:, series:, **)
+      _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:.
+    def add_table(first_row, first_col, last_row, last_col, **)
+      _add_table(first_row, first_col, last_row, last_col, { ** })
+    end
+
+    # Printed page header/footer using Excel codes such as "&CPage &P of &N".
+    # margin: is in inches.
+    def page_header(text, margin: nil)
+      _page_header(text)
+      margin ? margins(header: margin) : self
+    end
+
+    def page_footer(text, margin: nil)
+      _page_footer(text)
+      margin ? margins(footer: margin) : 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 })
+      self
+    end
+
+    # Default format for cells in these columns that are written without one.
+    def column_format(columns, format)
+      _column_format(*column_bounds(columns), format)
+      self
+    end
+
+    private
+
+    def column_bounds(columns)
+      columns.is_a?(Integer) ? [columns, columns] : columns.minmax
+    end
+  end
+
+  # Cell style, e.g. Format.new(bold: true). Pass to Worksheet#write.
+  class Format
+    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)
+      _new(options)
+    end
+  end
+end

data/sig/fast_xlsx.rbs

@@ -0,0 +1,100 @@
+module FastXlsx
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  interface _Reader
+    def read: () -> String
+  end
+
+  type cell = Numeric | String | Time | Date | Formula | URL | RichString | bool | nil | _ToS
+
+  class RichString
+    attr_reader segments: Array[[String, Format?]]
+    def initialize: (*(_ToS | [_ToS, Format?]) parts) -> void
+  end
+
+  class Formula
+    attr_reader expression: String
+    def self.new: (_ToS expression) -> Formula
+  end
+
+  class URL
+    attr_reader url: String
+    attr_reader text: String?
+    def self.new: (_ToS url, ?text: _ToS?) -> URL
+  end
+
+  class Workbook
+    MEMORY_MODES: Array[Symbol]
+    def self.new: (?memory: :standard | :constant | :low) -> Workbook
+    def add_worksheet: (?String? name) -> Worksheet
+    def worksheets: () -> Array[Worksheet]
+    def worksheet: (String name) -> Worksheet?
+    def properties: (?title: String, ?subject: String, ?author: String, ?manager: String,
+                     ?company: String, ?category: String, ?keywords: String,
+                     ?comments: String, ?status: String) -> self
+    def to_xlsx: () -> String
+    def save: (String path) -> void
+  end
+
+  class Format
+    type color = String | Integer
+    type border = :thin | :medium | :thick | :dashed | :dotted | :double | :hair
+
+    type underline = bool | :single | :double | :single_accounting | :double_accounting
+
+    def self.new: (?bold: bool, ?italic: bool, ?underline: underline, ?strikeout: bool, ?text_wrap: bool,
+                   ?shrink: bool, ?num_format: String, ?font_size: Numeric, ?font_name: String,
+                   ?font_color: color, ?bg_color: color, ?font_script: :superscript | :subscript,
+                   ?align: :left | :center | :right, ?valign: :top | :center | :bottom,
+                   ?rotation: Integer, ?indent: Integer,
+                   ?border: border, ?border_left: border, ?border_right: border,
+                   ?border_top: border, ?border_bottom: border, ?border_color: color) -> Format
+  end
+
+  class Worksheet
+    def write: (Integer row, Integer col, 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
+    def column_width: (Integer | Range[Integer] columns, Numeric width) -> self
+    def column_format: (Integer | Range[Integer] columns, Format format) -> self
+    def autofit: () -> self
+    def autofilter: (Integer first_row, Integer first_col, Integer last_row, Integer last_col) -> self
+    def freeze_panes: (Integer row, Integer col) -> 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 margins: (?left: Numeric?, ?right: Numeric?, ?top: Numeric?, ?bottom: Numeric?,
+                  ?header: Numeric?, ?footer: Numeric?) -> self
+    def merge_range: (Integer first_row, Integer first_col, Integer last_row, Integer last_col, cell value, ?Format? format) -> self
+    def conditional_format: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                             type: :cell | :text | :formula | :data_bar | :color_scale,
+                             ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
+                             ?format: Format, ?colors: 2 | 3) -> self
+    def data_validation: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                          type: :list | :whole_number | :decimal | :text_length,
+                          ?criteria: Symbol, ?value: Numeric | String | Array[Numeric | String],
+                          ?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
+    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
+    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
+    type table_column = String | { header: String, ?total: Symbol, ?total_label: String, ?format: Format }
+
+    def add_table: (Integer first_row, Integer first_col, Integer last_row, Integer last_col,
+                    ?columns: Array[table_column], ?style: Symbol, ?name: String,
+                    ?total_row: bool, ?banded_rows: bool, ?autofilter: bool) -> self
+    def name: () -> String
+    def next_row: () -> Integer
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: fast_xlsx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: arm-linux-musl
+authors:
+- Zac
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-09-30 00:00:00.000000000 Z
+dependencies: []
+description: Writes Excel .xlsx files from Ruby through a native Rust extension (rust_xlsxwriter
+  + magnus).
+email:
+- 579103+7a6163@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- bench/Gemfile
+- bench/Gemfile.lock
+- bench/compare.rb
+- bench/memory.rb
+- bench/write.rb
+- examples/showcase.rb
+- lib/fast_xlsx.rb
+- lib/fast_xlsx/3.3/fast_xlsx.so
+- lib/fast_xlsx/3.4/fast_xlsx.so
+- lib/fast_xlsx/4.0/fast_xlsx.so
+- lib/fast_xlsx/version.rb
+- sig/fast_xlsx.rbs
+homepage: https://github.com/7a6163/fast_xlsx
+licenses:
+- MIT
+metadata:
+  github_repo: ssh://github.com/7a6163/fast_xlsx
+  homepage_uri: https://github.com/7a6163/fast_xlsx
+  source_code_uri: https://github.com/7a6163/fast_xlsx
+  changelog_uri: https://github.com/7a6163/fast_xlsx/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Fast xlsx writer for Ruby, powered by rust_xlsxwriter
+test_files: []