class Xlsxrb::StreamRow

Streaming row implementation that parses cells on-demand / lazily. Provides O(1) memory consumption even for rows with tens of thousands of columns.

@example Streaming cells one-by-one (O(1) memory)

row.each_cell do |cell|
  puts "#{cell.ref}: #{cell.value}"
end

@example Random access or array conversion (cached on-demand)

cell = row[0]
values = row.to_a

@api public

Attributes

collapsed [R] untyped

custom_height [R] untyped

height [R] untyped

hidden [R] untyped

index [R] untyped

outline_level [R] untyped

pad_empty_cells [R] untyped

style_index [R] untyped

Public Class Methods

fast_create (index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil, style_index = nil, styles = nil, date1904 = false, collapsed = false, pad_empty_cells = false)

(untyped index, untyped xml_bytes, untyped from, untyped to, untyped shared_strings, ?untyped prefix, ?untyped height, ?untyped hidden, ?untyped custom_height, ?untyped outline_level, ?untyped style_index, ?untyped styles, ?untyped date1904, ?untyped collapsed, ?untyped pad_empty_cells) → untyped

Source

# File lib/xlsxrb/stream_row.rb, line 60
def self.fast_create(index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil, style_index = nil, styles = nil, date1904 = false, collapsed = false, pad_empty_cells = false)
  inst = allocate
  inst.instance_variable_set(:@index, index)
  inst.instance_variable_set(:@xml, xml_bytes)
  inst.instance_variable_set(:@from, from)
  inst.instance_variable_set(:@to, to)
  inst.instance_variable_set(:@shared_strings, shared_strings)
  inst.instance_variable_set(:@prefix, prefix)
  inst.instance_variable_set(:@height, height)
  inst.instance_variable_set(:@hidden, hidden)
  inst.instance_variable_set(:@custom_height, custom_height)
  inst.instance_variable_set(:@collapsed, collapsed)
  inst.instance_variable_set(:@outline_level, outline_level)
  inst.instance_variable_set(:@style_index, style_index)
  inst.instance_variable_set(:@styles, styles)
  inst.instance_variable_set(:@date1904, date1904 ? true : false)
  inst.instance_variable_set(:@pad_empty_cells, pad_empty_cells ? true : false)
  inst.instance_variable_set(:@cells, nil)
  inst
end

rubocop:disable Style/OptionalBooleanParameter

new (index:, xml_bytes:, from:, to:, shared_strings:, prefix: "", height: nil, hidden: false, custom_height: false, collapsed: false, outline_level: nil, style_index: nil, styles: nil, date1904: false, pad_empty_cells: false)

(index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?style_index: Integer | nil, ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?pad_empty_cells: bool) → void

Source

# File lib/xlsxrb/stream_row.rb, line 39
def initialize(index:, xml_bytes:, from:, to:, shared_strings:, prefix: "", height: nil, hidden: false,
               custom_height: false, collapsed: false, outline_level: nil, style_index: nil, styles: nil, date1904: false, pad_empty_cells: false)
  @index = index
  @xml = xml_bytes
  @from = from
  @to = to
  @shared_strings = shared_strings
  @prefix = prefix
  @height = height
  @hidden = hidden
  @custom_height = custom_height
  @collapsed = collapsed
  @outline_level = outline_level
  @style_index = style_index
  @styles = styles
  @date1904 = date1904 ? true : false
  @pad_empty_cells = pad_empty_cells ? true : false
  @cells = nil
end

@param index [Integer] 0-based row index. @param xml_bytes [String] Raw ASCII-8BIT XML bytes. @param from [Integer] Byte offset where cells start. @param to [Integer] Byte offset where cells end. @param shared_strings [Array<String>] Shared strings table. @param prefix [String] XML namespace prefix (e.g. “x:” or “”). @param height [Float, Integer, nil] Row height in points. @param hidden [Boolean] Whether the row is hidden. @param custom_height [Boolean] Whether custom height is set. @param collapsed [Boolean] Whether the row is collapsed. @param outline_level [Integer, nil] Grouping/outline level. @param style_index [Integer, nil] Style index. @param date1904 [Boolean] Whether the 1904 date system is active. @param pad_empty_cells [Boolean] Whether missing cells in this row are padded.

Public Instance Methods

[] (col_index)

(Integer | Symbol col_index) → untyped

Source

# File lib/xlsxrb/stream_row.rb, line 208
def [](col_index)
  case col_index
  when Symbol
    case col_index
    when :cells then cells
    when :values then values
    when :raw_values then raw_values
    when :formatted_values then formatted_values
    when :formulas then formulas
    when :index then index
    when :height then height
    when :hidden then hidden
    when :custom_height then custom_height
    when :collapsed then collapsed
    when :outline_level then outline_level
    when :style_index then style_index
    when :date1904 then date1904?
    when :hidden? then hidden?
    when :collapsed? then collapsed?
    when :custom_height? then custom_height?
    when :pad_empty_cells then @pad_empty_cells
    when :pad_empty_cells? then pad_empty_cells?
    when :attributes then attributes
    when :attrs
      h = { height: height, hidden: hidden, custom_height: custom_height, collapsed: collapsed, outline_level: outline_level }
      h[:style_index] = style_index if style_index
      h
    end
  else
    cells[col_index]
  end
end

Access a cell by 0-based column index, or access row attributes via Symbol.

@param col_index [Integer, Symbol] Column index or attribute symbol. @return [Elements::Cell, Object, nil] @api public

attributes ()

() → Hash[Symbol, untyped]

Source

# File lib/xlsxrb/stream_row.rb, line 114
def attributes
  h = {
    index: @index,
    height: @height,
    hidden: @hidden,
    custom_height: @custom_height,
    collapsed: @collapsed,
    outline_level: @outline_level
  }
  h[:style_index] = @style_index if @style_index
  h.freeze
end

Returns a frozen Hash of row attributes.

@return [Hash{Symbol => Object}] @api public

cell_at (col_index)

(Integer col_index) → Elements::Cell?

Source

# File lib/xlsxrb/stream_row.rb, line 247
def cell_at(col_index)
  cells.find { |c| c.column_index == col_index }
end

Access a cell by 0-based column index.

@param col_index [Integer] 0-based column index. @return [Elements::Cell, nil] @api public

cells ()

() → Array[Elements::Cell]

Source

# File lib/xlsxrb/stream_row.rb, line 180
def cells
  @cells ||= begin
    arr = []
    Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix, @styles, @date1904) do |c|
      arr << c
    end
    if @pad_empty_cells && !arr.empty?
      max_col = arr.map(&:column_index).max || 0
      if arr.size < max_col + 1
        cell_map = {}
        arr.each { |c| cell_map[c.column_index] = c }
        padded = Array.new(max_col + 1)
        (0..max_col).each do |c_idx|
          padded[c_idx] = cell_map[c_idx] || Elements::Cell.fast_create(@index, c_idx, nil, nil, nil, nil, nil, @date1904)
        end
        arr = padded
      end
    end
    arr.freeze
  end
end

Returns all cells as an Array. Cached on first access.

@return [Array<Elements::Cell>] @api public

collapsed? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 96
def collapsed?
  @collapsed == true
end

Returns whether the row is collapsed.

@return [Boolean] @api public

custom_height? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 105
def custom_height?
  @custom_height == true
end

Returns whether custom height is set.

@return [Boolean] @api public

date1904? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 132
def date1904?
  @date1904 ? true : false
end

Returns whether the row uses the 1904 date system.

@return [Boolean] @api public

each (&)

() { (Elements::Cell) → void } → void
() → Enumerator[Elements::Cell, void]

Source

# File lib/xlsxrb/stream_row.rb, line 171
def each(&)
  each_cell(&)
end

Iterate over cells in this streaming row.

@yield [cell] @yieldparam cell [Elements::Cell] @return [Enumerator, void] @api public

each_cell (&block)

() { (Elements::Cell) → void } → void
() → Enumerator[Elements::Cell, void]

Source

# File lib/xlsxrb/stream_row.rb, line 153
def each_cell(&block)
  return enum_for(:each_cell) unless block

  if @cells || @pad_empty_cells
    cells.each(&block)
  else
    Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix, @styles, @date1904, &block)
  end
end

Iterate over cells in this streaming row one by one.

@yield [cell] @yieldparam cell [Elements::Cell] @return [Enumerator, void] @api public

empty? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 368
def empty?
  vals = values
  return true if vals.empty?

  vals.all? { |v| v.nil? || (v.is_a?(String) && v.empty?) }
end

Returns whether the row contains no cell values (or all cell values are nil or empty strings).

@return [Boolean] @api public

errors ()

() → Array[String]

Source

# File lib/xlsxrb/stream_row.rb, line 389
def errors
  Elements::EMPTY_ERRORS
end

Validation errors for compatibility with Elements::Row.

@return [Array<String>] @api public

formatted_values ()

() → Array[String?]

Source

# File lib/xlsxrb/stream_row.rb, line 327
def formatted_values
  return [] if cells.empty?

  max_col = cells.map(&:column_index).max || 0
  arr = Array.new(max_col + 1)
  cells.each do |cell|
    arr[cell.column_index] = cell.formatted_value
  end
  arr
end

Convert row cells to an Array of formatted string representations (sparse columns get nil).

@return [Array<String, nil>] @api public

formulas ()

() → Array[String?]

Source

# File lib/xlsxrb/stream_row.rb, line 343
def formulas
  return [] if cells.empty?

  max_col = cells.map(&:column_index).max || 0
  arr = Array.new(max_col + 1)
  cells.each do |cell|
    arr[cell.column_index] = cell.formula_expression
  end
  arr
end

Convert row cells to an Array of formula expressions without leading ‘=’ (sparse columns get nil).

@return [Array<String, nil>] @api public

hidden? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 87
def hidden?
  @hidden == true
end

Returns whether the row is hidden.

@return [Boolean] @api public

inspect ()

() → String

Source

# File lib/xlsxrb/stream_row.rb, line 398
def inspect
  "#<#{self.class.name} index=#{index} height=#{height.inspect} hidden=#{hidden}>"
end

Human-readable representation.

@return [String] @api public

pad_empty_cells? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 141
def pad_empty_cells?
  @pad_empty_cells ? true : false
end

Returns whether missing cells in this row are padded.

@return [Boolean] @api public

raw_values ()

() → Array[String?]

Source

# File lib/xlsxrb/stream_row.rb, line 311
def raw_values
  return [] if cells.empty?

  max_col = cells.map(&:column_index).max || 0
  arr = Array.new(max_col + 1)
  cells.each do |cell|
    arr[cell.column_index] = cell.raw_value
  end
  arr
end

Convert row cells to an Array of raw string values (sparse columns get nil).

@return [Array<String, nil>] @api public

to_a ()

() → Array[untyped]

Source

# File lib/xlsxrb/stream_row.rb, line 288
def to_a
  values
end

Convert row cells to an Array of raw values (sparse columns get nil).

@return [Array<Object>] @api public

to_h (type_cast: false)

(?type_cast: bool) → Hash[String, untyped]

Source

# File lib/xlsxrb/stream_row.rb, line 257
def to_h(type_cast: false)
  result = {}
  each_cell do |c|
    val = c.value
    if type_cast && val.is_a?(Numeric)
      fmt_type = if c.style_index && @styles
                   NumberFormatter.format_type_for(c.style_index, @styles)
                 elsif c.format_code
                   NumberFormatter.format_type(c.format_code)
                 end
      begin
        case fmt_type
        when :date
          val = Ooxml::Utils.serial_to_date(val, date1904: @date1904)
        when :datetime, :time
          val = Ooxml::Utils.serial_to_datetime(val, date1904: @date1904)
        end
      rescue StandardError
        # Keep val numeric on failure
      end
    end
    result[c.ref] = val
  end
  result
end

Convert row cells to a coordinate-keyed Hash (e.g. {“A1” => “value”, “B1” => 123}).

@param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances. @return [Hash{String => Object}] @api public

unmapped_data ()

() → Hash[untyped, untyped]

Source

# File lib/xlsxrb/stream_row.rb, line 380
def unmapped_data
  @style_index ? { style_index: @style_index } : Elements::EMPTY_HASH
end

Unmapped metadata for compatibility with Elements::Row.

@return [Hash] @api public

valid? ()

() → bool

Source

# File lib/xlsxrb/stream_row.rb, line 359
def valid?
  true
end

Returns whether the row is valid according to OOXML specifications.

@return [Boolean] @api public

values (type_cast: false)

(?type_cast: bool) → Array[untyped]

Source

# File lib/xlsxrb/stream_row.rb, line 298
def values(type_cast: false)
  if @cells
    values_from_cells(type_cast)
  else
    Ooxml::WorksheetParser.fast_scan_row_values(@xml, @from, @to, @shared_strings, @styles, @date1904, type_cast: type_cast)
  end
end

Returns cell values as an Array (sparse columns get nil).

@param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances. @return [Array<Object>] @api public