fast_xlsx 0.1.0

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