fast_xlsx 0.2.0-x86_64-linux → 0.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 385d5c9b69ab08b516cfa1f99e4075b691b9a264924c32498303f4d577abfeaa
-  data.tar.gz: 3c28e89e17339b7f2077d0be122eddf858789be99acd9d18a404c044e309ee44
+  metadata.gz: aa33588d163149bd2ff649232a7f10246b81dee9f777f55c38afa7d735d90917
+  data.tar.gz: '08f220f1a035657a1ab915c9b73ab67ed316cb15c7cbd532df922e2e9cdc339d'
 SHA512:
-  metadata.gz: 02670f7b5ebf4a2cf27955651de5a9a7409202700871cdd493f73788de50c7a0e8cb37d0732f8e5ad99ab13fd9017b4f452fac96c5cb6c361e203e4793c35dc0
-  data.tar.gz: 3744269cbb53e37c8519a5df27a196d0fbab8672f8ca985a24c74c06486f326707cd1c2f5303ef7498f994ce7f695ff905745f5c31e38db9eb08dd4c9937d308
+  metadata.gz: 1a9a6c93be3e311157652e72f8ce0ac34f9f7059ea1c871e746c66e0d5c4503e45e3031f55245bd76dc8e598460831828b2fba51078f2613e9b4a412823f5969
+  data.tar.gz: 53f6f6d9e41ff5e1aac020b2139aaf06ae6395cd48bf3ddd6095e451680856208ad292e97f7dbc334f3d615cd282ac6132104dbd691b26d93a8d3eece85efd8a

data/CHANGELOG.md

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

data/README.md

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

data/bench/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    fast_xlsx (0.2.0)
+    fast_xlsx (0.3.0)
       rb_sys (~> 0.9.130)
 
 GEM
@@ -77,7 +77,7 @@ DEPENDENCIES
 CHECKSUMS
   caxlsx (4.5.0) sha256=e3d98d859f148df05d5462086b5079b523f29c1766b569535f1d68629ce743ff
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
-  fast_xlsx (0.2.0)
+  fast_xlsx (0.3.0)
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
   ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564

data/lib/fast_xlsx/version.rb

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

data/lib/fast_xlsx.rb

@@ -102,10 +102,15 @@ module FastXlsx
 
   # Cell writer for one sheet; create with Workbook#add_worksheet.
   class Worksheet
-    def write(row, col, value, format = nil)
+    # write(row, col, value, format = nil) or write("B2", value, format = nil)
+    # is native: the (row, col) form runs once per cell, so it skips a Ruby
+    # wrapper. Other forms come here.
+    def _write_ref(*args)
+      row, col, (value, format) = CellRange.cell(args, 1..2)
       _write(row, col, value, format)
       self
     end
+    private :_write_ref
 
     def append(values, format: nil)
       _append(values, format)
@@ -158,14 +163,16 @@ module FastXlsx
     end
 
     # Adds a comment (Excel "note") to a cell.
-    def write_comment(row, col, text, author: nil)
+    def write_comment(*args, author: nil)
+      row, col, (text, *) = CellRange.cell(args, 1..1)
       _write_comment(row, col, text, author)
     end
 
     # Inserts a PNG, JPEG, GIF or BMP image with its top-left corner in the
     # cell. source is a file path or an IO (anything responding to #read).
     # Options: scale: or width:/height: (pixels), x_offset:, y_offset: (pixels), alt_text:.
-    def insert_image(row, col, source, **)
+    def insert_image(*args, **)
+      row, col, (source, *) = CellRange.cell(args, 1..1)
       bytes = source.respond_to?(:read) ? source.read : File.binread(source)
       _insert_image(row, col, bytes, { ** })
     end
@@ -173,7 +180,8 @@ module FastXlsx
     # Inserts a chart with its top-left corner in the cell. series is an Array
     # of { values:, categories:, name: } with Excel ranges such as
     # "Sheet1!$B$2:$B$13". Options: title:, x_axis:, y_axis:, width:, height:.
-    def insert_chart(row, col, type:, series:, **)
+    def insert_chart(*cell, type:, series:, **)
+      row, col, = CellRange.cell(cell)
       _insert_chart(row, col, { type: type, series: series, ** })
     end
 
@@ -197,6 +205,18 @@ module FastXlsx
       margin ? margins(footer: margin) : self
     end
 
+    # Printing: landscape:, paper: (:letter, :legal, :tabloid, :a3, :a4, :a5 or
+    # Excel's paper number), fit_width:/fit_height: (pages; 0 or left out =
+    # as many as needed), repeat_rows:/repeat_columns: (an index or Range,
+    # printed on every page), print_area: (any cell range), gridlines:.
+    def page_setup(repeat_rows: nil, repeat_columns: nil, print_area: nil, **options)
+      options[:repeat_rows] = CellRange.bounds(repeat_rows) if repeat_rows
+      options[:repeat_columns] = CellRange.bounds(repeat_columns) if repeat_columns
+      options[:print_area] = CellRange.split(print_area.is_a?(Array) ? print_area : [print_area]).first if print_area
+      _page_setup(options)
+      self
+    end
+
     # Print margins in inches; margins not given keep their current value.
     def margins(left: nil, right: nil, top: nil, bottom: nil, header: nil, footer: nil)
       _margins(*[left, right, top, bottom, header, footer].map { |m| m || -1.0 })
@@ -214,6 +234,13 @@ module FastXlsx
       _group_columns(*CellRange.bounds(columns), collapsed)
     end
 
+    # Keeps the rows above and the columns left of the cell visible while
+    # scrolling: (1, 0) or "A2" freezes the first row.
+    def freeze_panes(*cell)
+      _freeze_panes(*CellRange.cell(cell).first(2))
+      self
+    end
+
     # Locks the sheet against editing. Cells whose format has locked: false
     # stay editable. allow: actions users may still take, any of :format_cells,
     # :format_columns, :format_rows, :insert_columns, :insert_rows,
@@ -236,6 +263,7 @@ module FastXlsx
   module CellRange
     REF = /\A\$?([A-Za-z]{1,3})\$?([1-9]\d*)\z/ # ASCII only: /i also matches the Kelvin sign
     FORMS = 'a range is (first_row, first_col, last_row, last_col), "A1:D10" or (rows, cols)'
+    CELL_FORMS = 'a cell is (row, col) or "B2"'
 
     module_function
 
@@ -243,12 +271,7 @@ module FastXlsx
     # Returns [[first_row, first_col, last_row, last_col], the args after it].
     def split(args, following = 0..0)
       range, rest = parse(args)
-      unless following.cover?(rest.size)
-        expected = following.minmax.uniq.join("..")
-        raise ArgumentError, "wrong number of arguments after the cell range (given #{rest.size}, " \
-                             "expected #{expected}); #{FORMS}"
-      end
-
+      check_following(rest, following, "cell range", FORMS)
       [range, rest]
     end
 
@@ -263,6 +286,30 @@ module FastXlsx
       end
     end
 
+    # (row, col) or a single-cell reference ("B2") off the front of args, as
+    # [row, col, the args after it].
+    def cell(args, following = 0..0)
+      row, col, *rest = args.first.is_a?(String) ? [*single_cell(args.first), *args.drop(1)] : args
+      raise ArgumentError, "expected a cell, got #{args.inspect}; #{CELL_FORMS}" if col.nil?
+
+      check_following(rest, following, "cell", CELL_FORMS)
+      [row, col, rest]
+    end
+
+    def single_cell(ref)
+      first_row, first_col, last_row, last_col = excel(ref)
+      return [first_row, first_col] if first_row == last_row && first_col == last_col
+
+      raise ArgumentError, "expected a single cell like \"B2\", got #{ref.inspect}"
+    end
+
+    def check_following(rest, following, what, forms)
+      return if following.cover?(rest.size)
+
+      raise ArgumentError, "wrong number of arguments after the #{what} " \
+                           "(given #{rest.size}, expected #{following.minmax.uniq.join("..")}); #{forms}"
+    end
+
     def rows_and_cols(rows, cols)
       first_row, last_row = bounds(rows)
       first_col, last_col = bounds(cols)

data/sig/fast_xlsx.rbs

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

metadata

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