### Install Xlsxtream Gem

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Instructions for adding the Xlsxtream gem to your Ruby project's Gemfile and installing it via Bundler, or installing it directly using the gem command.

```ruby
gem 'xlsxtream'
```

```bash
$ bundle
$ gem install xlsxtream
```

--------------------------------

### Stream XLSX Output with Rails (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Provides an example of integrating Xlsxtream with a Rails controller using `ZipKit::RailsStreaming` to stream XLSX reports directly to the client without buffering the entire file in memory.

```ruby
# Output from Rails (will stream without buffering)
class ReportsController < ApplicationController
  include ZipKit::RailsStreaming
  EXCEL_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

  def download
    zip_kit_stream(filename: "report.xlsx", type: EXCEL_CONTENT_TYPE) do |zip_kit_streamer|
      Xlsxtream::Workbook.open(zip_kit_streamer) do |xlsx|
        xlsx.write_worksheet 'Sheet1' do |sheet|
          # Boolean, Date, Time, DateTime and Numeric are properly mapped
          sheet << [true, Date.today, 'hello', 'world', 42, 3.14159265359, 42**13]
        end
      end
    end
  end
end
```

--------------------------------

### Create and Write XLSX Files with Workbook.open

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Demonstrates how to initialize a new workbook and write data to it using the Workbook.open method. It covers writing to file paths, IO objects, and applying basic font or header styling.

```ruby
require 'xlsxtream'
require 'stringio'

Xlsxtream::Workbook.open('report.xlsx') do |xlsx|
  xlsx.write_worksheet 'Sales Data' do |sheet|
    sheet << ['Product', 'Quantity', 'Price', 'Date']
    sheet << ['Widget A', 100, 29.99, Date.today]
    sheet << ['Widget B', 250, 19.99, Date.today - 7]
  end
end

io = StringIO.new
Xlsxtream::Workbook.open(io) do |xlsx|
  xlsx.write_worksheet 'Sheet1' do |sheet|
    sheet << ['Data', 'Row', 1]
  end
end
io.rewind

Xlsxtream::Workbook.open('styled.xlsx', font: { name: 'Times New Roman', size: 10, family: 'Roman' }) do |xlsx|
  xlsx.write_worksheet 'Report' do |sheet|
    sheet << ['Custom font styling applied']
  end
end

Xlsxtream::Workbook.open('with_header.xlsx', has_header_row: true) do |xlsx|
  xlsx.write_worksheet 'Data' do |sheet|
    sheet << ['Column A', 'Column B', 'Column C']
    sheet << ['value1', 'value2', 'value3']
  end
end
```

--------------------------------

### Create XLSX Workbook and Write Data (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Demonstrates how to create a new XLSX workbook, write data to a worksheet, and close the file. It shows basic data types like booleans, dates, times, and numerics being automatically mapped.

```ruby
# Creates a new workbook file, write and close it at the end of the block
Xlsxtream::Workbook.open('my_data.xlsx') do |xlsx|
  xlsx.write_worksheet 'Sheet1' do |sheet|
    # Boolean, Date, Time, DateTime and Numeric are properly mapped
    sheet << [true, Date.today, 'hello', 'world', 42, 3.14159265359, 42**13]
  end
end
```

--------------------------------

### Configure Workbook Font and Header Row (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Demonstrates how to set a custom default font for the workbook and how to designate the first row as a header row with bold and centered text.

```ruby
# Changing the default font from Calibri, 12pt, Swiss
Xlsxtream::Workbook.new(io, font: {
  name: 'Times New Roman',
  size: 10, # size in pt
  family: 'Roman' # Swiss, Modern, Script, Decorative
})

# Treat the first output row as a header, using bold and centred text
Xlsxtream::Workbook.new(io, has_header_row: true)
```

--------------------------------

### Write to IO Object and Multiple Worksheets (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Shows how to write XLSX data to an IO-like object (e.g., StringIO) and how to create multiple worksheets with custom names, including adding rows using `add_row`.

```ruby
io = StringIO.new
xlsx = Xlsxtream::Workbook.new(io)

# Number of columns doesn't have to match
xlsx.write_worksheet 'Sheet1' do |sheet|
  sheet << ['first', 'row']
  sheet << ['second', 'row', 'with', 'more colums']
end

# Write multiple worksheets with custom names
xlsx.write_worksheet 'AppendixSheet' do |sheet|
  sheet.add_row ['Timestamp', 'Comment']
  sheet.add_row [Time.now, 'Good times']
  sheet.add_row [Time.now, 'Time-machine']
end

# Writes metadata and ZIP archive central directory
xlsx.close
# Close IO object
io.close
```

--------------------------------

### Create Worksheets with Block Syntax using write_worksheet

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Explains how to add worksheets to a workbook using the block-based write_worksheet method. This approach automatically handles worksheet closure and supports features like shared strings and auto-formatting.

```ruby
require 'xlsxtream'

Xlsxtream::Workbook.open('multi_sheet.xlsx') do |xlsx|
  xlsx.write_worksheet 'Users' do |sheet|
    sheet << ['ID', 'Name', 'Email', 'Active']
    sheet << [1, 'Alice', 'alice@example.com', true]
    sheet << [2, 'Bob', 'bob@example.com', false]
  end

  xlsx.write_worksheet(name: 'Products') do |sheet|
    sheet << ['SKU', 'Description', 'Price']
    sheet << ['ABC-123', 'Premium Widget', 99.99]
  end

  xlsx.write_worksheet(name: 'Inventory', use_shared_strings: true) do |sheet|
    1000.times do |i|
      sheet << ['Active', 'Category A', "Item #{i}"]
    end
  end

  xlsx.write_worksheet(name: 'AutoFormatted', auto_format: true) do |sheet|
    sheet << ['true', '42', '3.14', '2024-01-15', '2024-01-15T10:30:00Z']
  end
end
```

--------------------------------

### Create Worksheets Manually with add_worksheet

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Shows how to manage worksheet lifecycles manually using add_worksheet, which is useful for iterative or conditional writing scenarios. Note that worksheets must be explicitly closed before opening new ones.

```ruby
require 'xlsxtream'

Xlsxtream::Workbook.open('manual_control.xlsx') do |xlsx|
  worksheet = xlsx.add_worksheet(name: 'Streaming Data')
  worksheet << ['Header 1', 'Header 2', 'Header 3']

  100.times do |i|
    worksheet << ["Row #{i}", i * 10, Time.now]
  end

  worksheet.close

  ws2 = xlsx.add_worksheet(name: 'Summary')
  ws2 << ['Total Rows', 100]
  ws2.close
end
```

--------------------------------

### Enable Shared String Tables (SST) for Deduplication (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Illustrates how to enable the Shared String Table (SST) for a worksheet to deduplicate repetitive string data, optimizing file size. Note that SSTs are kept in memory and should be used judiciously.

```ruby
# If you have highly repetitive data, you can enable Shared String Tables (SST)
# for the workbook or a single worksheet. The SST has to be kept in memory,
# so do not use it if you have a huge amount of rows or a little duplication
# of content across cells. A single SST is used for the whole workbook.
xlsx.write_worksheet(name: 'SheetWithSST', use_shared_strings: true) do |sheet|
  sheet << ['the', 'same', 'old', 'story']
  sheet << ['the', 'old', 'same', 'story']
  sheet << ['old', 'the', 'same', 'story']
end
```

--------------------------------

### Column Width Configuration

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Explains how to configure column widths for worksheets, either globally at the workbook level or specifically per worksheet, using character counts or pixel dimensions.

```APIDOC
## Column Width Configuration

Column widths can be specified at the workbook level (applies to all worksheets) or per-worksheet. Widths are set using `width_chars` (approximate character width) or `width_pixels` (exact pixel width, relative to 11pt Calibri font).

### Request Example (Workbook Level)
```ruby
require 'xlsxtream'

# Column widths at workbook level (applied to all worksheets)
Xlsxtream::Workbook.open('fixed_widths.xlsx', columns: [
  { width_chars: 10 },    # Column A: ~10 characters wide
  { width_chars: 30 },    # Column B: ~30 characters wide
  { width_pixels: 100 },  # Column C: exactly 100 pixels wide
  {}                      # Column D: default width
]) do |xlsx|
  xlsx.write_worksheet 'Data' do |sheet|
    sheet << ['Short', 'This column has more space', 'Fixed', 'Auto']
    sheet << ['ID', 'Description text that may be longer', 'Value', 'Notes']
  end
end
```

### Request Example (Per-Worksheet)
```ruby
# Per-worksheet column widths override workbook defaults
Xlsxtream::Workbook.open('mixed_widths.xlsx') do |xlsx|
  xlsx.write_worksheet(name: 'Wide Columns', columns: [
    { width_pixels: 200 },
    { width_pixels: 300 }
  ]) do |sheet|
    sheet << ['Wide Column A', 'Even Wider Column B']
  end

  xlsx.write_worksheet(name: 'Narrow Columns', columns: [
    { width_chars: 5 },
    { width_chars: 8 }
  ]) do |sheet|
    sheet << ['Small', 'Medium']
  end
end
```
```

--------------------------------

### Create Worksheet Sequentially Without Block (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Explains how to create a worksheet without using a block, using `add_worksheet`. This method requires manual closing of the worksheet before opening a new one.

```ruby
# You can also create worksheet without a block, using the `add_worksheet` method.
# It can be only used sequentially, so remember to manually close the worksheet
# when you are done (before opening a new one).
worksheet = xls.add_worksheet(name: 'SheetWithoutBlock')
worksheet << ['some', 'data']
worksheet.close
```

--------------------------------

### Configure Column Widths in XlsxStream

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Sets column widths at the workbook level (applying to all worksheets) or per-worksheet using 'width_chars' for approximate character width or 'width_pixels' for exact pixel width. Per-worksheet settings override workbook defaults.

```ruby
require 'xlsxtream'

# Column widths at workbook level (applied to all worksheets)
Xlsxtream::Workbook.open('fixed_widths.xlsx', columns: [
  { width_chars: 10 },    # Column A: ~10 characters wide
  { width_chars: 30 },    # Column B: ~30 characters wide
  { width_pixels: 100 },  # Column C: exactly 100 pixels wide
  {}                      # Column D: default width
]) do |xlsx|
  xlsx.write_worksheet 'Data' do |sheet|
    sheet << ['Short', 'This column has more space', 'Fixed', 'Auto']
    sheet << ['ID', 'Description text that may be longer', 'Value', 'Notes']
  end
end

# Per-worksheet column widths override workbook defaults
Xlsxtream::Workbook.open('mixed_widths.xlsx') do |xlsx|
  xlsx.write_worksheet(name: 'Wide Columns', columns: [
    { width_pixels: 200 },
    { width_pixels: 300 }
  ]) do |sheet|
    sheet << ['Wide Column A', 'Even Wider Column B']
  end

  xlsx.write_worksheet(name: 'Narrow Columns', columns: [
    { width_chars: 5 },
    { width_chars: 8 }
  ]) do |sheet|
    sheet << ['Small', 'Medium']
  end
end
```

--------------------------------

### Specify Column Widths for Worksheets (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Shows how to define column widths in pixels or characters for a worksheet. It also notes that pixel widths are relative to a default font and size.

```ruby
# Specifying column widths in pixels or characters; 3 column example;
# "pixel" widths appear to be *relative* to an assumed 11pt Calibri
# font, so if selecting a different font or size (see above), do not
# adjust widths to match. Calculate pixel widths for 11pt Calibri.
Xlsxtream::Workbook.new(io, columns: [
  { width_pixels: 33 },
  { width_chars: 7 },
  { width_chars: 24 }
])
# The :columns option can also be given to write_worksheet, so it's
# possible to have multiple worksheets with different column widths.
```

--------------------------------

### Add Data Rows with << and add_row

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Demonstrates how to append rows of data to an Excel worksheet using the `<<` operator and its alias `add_row`. It covers automatic type conversion for various Ruby data types and handling of nil/empty values.

```APIDOC
## Worksheet#<< and add_row - Add Data Rows

The `<<` operator (aliased as `add_row`) appends a row of data to the worksheet. It automatically handles type conversion for Ruby native types: Numeric values, Booleans, Date, Time, DateTime, and strings. Empty strings and nil values result in empty cells.

### Request Example
```ruby
require 'xlsxtream'
require 'date'

Xlsxtream::Workbook.open('data_types.xlsx') do |xlsx|
  xlsx.write_worksheet 'All Types' do |sheet|
    # String values
    sheet << ['Hello', 'World', :symbol_converted_to_string]

    # Numeric values (Integer and Float)
    sheet << [42, 3.14159265359, -100, 1e6, 42**13]

    # Boolean values
    sheet << [true, false]

    # Date and Time types (properly formatted in Excel)
    sheet << [Date.today, Time.now, DateTime.now]

    # Mixed types in one row
    sheet << ['Product A', 25, 19.99, true, Date.new(2024, 1, 1)]

    # Nil and empty strings create empty cells
    sheet << ['Before', nil, '', 'After']

    # Using add_row alias
    sheet.add_row ['Using', 'add_row', 'method']

    # Variable column counts are allowed
    sheet << ['Short row']
    sheet << ['This', 'row', 'has', 'more', 'columns', 'than', 'others']
  end
end
```
```

--------------------------------

### Xlsxtream::Workbook Operations

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Methods for initializing a workbook, adding worksheets, and writing data rows.

```APIDOC
## POST /Xlsxtream::Workbook

### Description
Initializes a new XLSX workbook and manages the lifecycle of worksheets and data streaming.

### Method
POST

### Parameters
#### Request Body
- **io** (Object) - Required - An IO-like object or file path to write the XLSX data.
- **font** (Hash) - Optional - Configuration for default font (name, size, family).
- **has_header_row** (Boolean) - Optional - If true, treats the first row as a header.
- **columns** (Array) - Optional - Configuration for column widths (width_pixels or width_chars).

### Request Example
```ruby
Xlsxtream::Workbook.open('data.xlsx') do |xlsx|
  xlsx.write_worksheet 'Sheet1' do |sheet|
    sheet << ['Column1', 'Column2']
  end
end
```

### Response
#### Success Response (200)
- **status** (String) - Returns success upon closing the workbook and flushing the ZIP stream.
```

--------------------------------

### Enable Auto-Formatting for Data Types (Ruby)

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Demonstrates the `auto_format` option, which allows Xlsxtream to automatically detect and format strings that represent booleans, numbers, dates, and times, preventing Excel warnings about numbers stored as text.

```ruby
# Strings in numeric or date/time format can be auto-detected and formatted
# appropriately. This is a convenient way to avoid an Excel-warning about
# "Number stored as text". Dates and times must be in the ISO-8601 format and
# numeric values must contain only numbers and an optional decimal separator.
# The strings true and false are detected as boolean values.
xlsx.write_worksheet(name: 'SheetWithAutoFormat', auto_format: true) do |sheet|
  # these two rows will be identical in the xlsx-output
  sheet << [true, 11.85, DateTime.parse('2050-01-01T12:00'), Date.parse('1984-01-01')]
  sheet << ['true', '11.85', '2050-01-01T12:00', '1984-01-01']
end
```

--------------------------------

### Shared String Table (SST) for String Deduplication

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Details on enabling and using the Shared String Table (SST) to reduce Excel file size by storing duplicate strings only once.

```APIDOC
## Shared String Table (SST) for String Deduplication

Enable shared string tables to deduplicate repetitive string values, reducing file size when the same strings appear multiple times. SST keeps strings in memory, so avoid using it with huge unique string counts.

### Request Example (Workbook Level SST)
```ruby
require 'xlsxtream'

# Enable SST at workbook level (all worksheets share one table)
Xlsxtream::Workbook.open('with_sst.xlsx', use_shared_strings: true) do |xlsx|
  xlsx.write_worksheet 'Repetitive Data' do |sheet|
    # These repeated strings are stored once in the SST
    1000.times do |i|
      sheet << ['Active', 'Category A', 'Region West', i]
    end
    # Without SST: 'Active' stored 1000 times
    # With SST: 'Active' stored once, referenced 1000 times
  end
end
```

### Request Example (Selective SST per Worksheet)
```ruby
require 'xlsxtream'

# Enable SST per-worksheet for selective optimization
Xlsxtream::Workbook.open('selective_sst.xlsx') do |xlsx|
  # Worksheet with repetitive data - enable SST
  xlsx.write_worksheet(name: 'Orders', use_shared_strings: true) do |sheet|
    sheet << ['Status', 'Type', 'Amount']
    10000.times do |i|
      status = i.even? ? 'Completed' : 'Pending'
      type = ['Standard', 'Express', 'Overnight'][i % 3]
      sheet << [status, type, i * 10]
    end
  end

  # Worksheet with unique data - skip SST to save memory
  xlsx.write_worksheet(name: 'Unique IDs') do |sheet|
    sheet << ['UUID']
    1000.times { sheet << [SecureRandom.uuid] }
  end
end
```
```

--------------------------------

### Use Shared String Table (SST) with XlsxStream

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Enables shared string tables to deduplicate repetitive string values, reducing Excel file size. SST stores unique strings once and references them multiple times. It can be enabled at the workbook level for all worksheets or selectively per-worksheet. Avoid using SST with a very large number of unique strings to conserve memory.

```ruby
require 'xlsxtream'

# Enable SST at workbook level (all worksheets share one table)
Xlsxtream::Workbook.open('with_sst.xlsx', use_shared_strings: true) do |xlsx|
  xlsx.write_worksheet 'Repetitive Data' do |sheet|
    # These repeated strings are stored once in the SST
    1000.times do |i|
      sheet << ['Active', 'Category A', 'Region West', i]
    end
    # Without SST: 'Active' stored 1000 times
    # With SST: 'Active' stored once, referenced 1000 times
  end
end

# Enable SST per-worksheet for selective optimization
Xlsxtream::Workbook.open('selective_sst.xlsx') do |xlsx|
  # Worksheet with repetitive data - enable SST
  xlsx.write_worksheet(name: 'Orders', use_shared_strings: true) do |sheet|
    sheet << ['Status', 'Type', 'Amount']
    10000.times do |i|
      status = i.even? ? 'Completed' : 'Pending'
      type = ['Standard', 'Express', 'Overnight'][i % 3]
      sheet << [status, type, i * 10]
    end
  end

  # Worksheet with unique data - skip SST to save memory
  xlsx.write_worksheet(name: 'Unique IDs') do |sheet|
    sheet << ['UUID']
    1000.times { sheet << [SecureRandom.uuid] }
  end
end
```

--------------------------------

### Xlsxtream::Worksheet Operations

Source: https://github.com/felixbuenemann/xlsxtream/blob/master/README.md

Methods for creating and populating individual worksheets within a workbook.

```APIDOC
## POST /Xlsxtream::Workbook/write_worksheet

### Description
Creates a new worksheet within the workbook and allows adding rows of data. Supports optional shared string tables and auto-formatting.

### Method
POST

### Parameters
#### Request Body
- **name** (String) - Required - The name of the worksheet.
- **use_shared_strings** (Boolean) - Optional - Enable SST for repetitive data.
- **auto_format** (Boolean) - Optional - Enable auto-detection of types for strings.

### Request Example
```ruby
xlsx.write_worksheet(name: 'Data', use_shared_strings: true) do |sheet|
  sheet << [1, 'data', true]
end
```

### Response
#### Success Response (200)
- **worksheet** (Object) - The active worksheet instance.
```

--------------------------------

### Auto-Format String Values in Ruby with Xlsxtream

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Demonstrates how Xlsxtream automatically detects and converts string values to appropriate Excel types like booleans, integers, floats, dates, and datetimes when auto-format is enabled. This prevents common Excel warnings. It also shows per-worksheet auto-format configuration.

```Ruby
require 'xlsxtream'

Xlsxtream::Workbook.open('auto_format.xlsx', auto_format: true) do |xlsx|
  xlsx.write_worksheet 'Converted Types' do |sheet|
    sheet << ['Type', 'String Input', 'Auto-Formatted Result']

    # Boolean detection
    sheet << ['Boolean', 'true', true]    # 'true' -> Boolean TRUE
    sheet << ['Boolean', 'false', false]  # 'false' -> Boolean FALSE

    # Integer detection
    sheet << ['Integer', '42', 42]
    sheet << ['Integer', '-100', -100]

    # Float detection
    sheet << ['Float', '3.14', 3.14]
    sheet << ['Float', '-0.5', -0.5]

    # ISO 8601 Date detection (yyyy-mm-dd)
    sheet << ['Date', '2024-01-15', Date.parse('2024-01-15')]

    # ISO 8601 DateTime detection
    sheet << ['DateTime', '2024-01-15T10:30:00', DateTime.parse('2024-01-15T10:30:00')]
    sheet << ['DateTime', '2024-01-15T10:30:00Z', DateTime.parse('2024-01-15T10:30:00Z')]
    sheet << ['DateTime', '2024-01-15T10:30:00+05:00', DateTime.parse('2024-01-15T10:30:00+05:00')]
  end
end

# Per-worksheet auto-format
Xlsxtream::Workbook.open('mixed_format.xlsx') do |xlsx|
  xlsx.write_worksheet(name: 'Auto', auto_format: true) do |sheet|
    sheet << ['42', '3.14', '2024-01-01']  # Converted to number, float, date
  end

  xlsx.write_worksheet(name: 'Raw') do |sheet|
    sheet << ['42', '3.14', '2024-01-01']  # Kept as strings
  end
end
```

--------------------------------

### Add Data Rows to Worksheet with XlsxStream

Source: https://context7.com/felixbuenemann/xlsxtream/llms.txt

Appends rows of data to an Excel worksheet using the '<<' operator or 'add_row' alias. It automatically converts native Ruby types (Numeric, Boolean, Date, Time, DateTime, String) and handles nil/empty strings as empty cells. Variable column counts per row are supported.

```ruby
require 'xlsxtream'
require 'date'

Xlsxtream::Workbook.open('data_types.xlsx') do |xlsx|
  xlsx.write_worksheet 'All Types' do |sheet|
    # String values
    sheet << ['Hello', 'World', :symbol_converted_to_string]

    # Numeric values (Integer and Float)
    sheet << [42, 3.14159265359, -100, 1e6, 42**13]

    # Boolean values
    sheet << [true, false]

    # Date and Time types (properly formatted in Excel)
    sheet << [Date.today, Time.now, DateTime.now]

    # Mixed types in one row
    sheet << ['Product A', 25, 19.99, true, Date.new(2024, 1, 1)]

    # Nil and empty strings create empty cells
    sheet << ['Before', nil, '', 'After']

    # Using add_row alias
    sheet.add_row ['Using', 'add_row', 'method']

    # Variable column counts are allowed
    sheet << ['Short row']
    sheet << ['This', 'row', 'has', 'more', 'columns', 'than', 'others']
  end
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.