Class: Xlsxrb::StreamRow

Inherits:
Object
  • Object
show all
Defined in:
lib/xlsxrb/stream_row.rb,
sig/generated/xlsxrb/stream_row.rbs

Overview

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

Examples:

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

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

Random access or array conversion (cached on-demand)

cell = row[0]
values = row.to_a

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(index:, xml_bytes:, from:, to:, shared_strings:, prefix: "", height: nil, hidden: false, custom_height: false, outline_level: nil) ⇒ StreamRow

: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array, ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void

Parameters:

  • index (Integer) —

    0-based row index.

  • xml_bytes (String) —

    Raw ASCII-8BIT XML bytes.

  • from (Integer) —

    Byte offset where cells start.

  • to (Integer) —

    Byte offset where cells end.

  • shared_strings (Array<String>) —

    Shared strings table.

  • prefix (String) (defaults to: "") —

    XML namespace prefix (e.g. "x:" or "").

  • height (Float, Integer, nil) (defaults to: nil) —

    Row height in points.

  • hidden (Boolean) (defaults to: false) —

    Whether the row is hidden.

  • custom_height (Boolean) (defaults to: false) —

    Whether custom height is set.

  • outline_level (Integer, nil) (defaults to: nil) —

    Grouping/outline level.

  • index: (Integer)
  • xml_bytes: (String)
  • from: (Integer)
  • to: (Integer)
  • shared_strings: (Array[String])
  • prefix: (String) (defaults to: "")
  • height: (Float, Integer, nil) (defaults to: nil)
  • hidden: (Boolean) (defaults to: false)
  • custom_height: (Boolean) (defaults to: false)
  • outline_level: (Integer, nil) (defaults to: nil) 


35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/xlsxrb/stream_row.rb', line 35

def initialize(index:, xml_bytes:, from:, to:, shared_strings:, prefix: "", height: nil, hidden: false,
               custom_height: false, outline_level: nil)
  @index = index
  @xml = xml_bytes
  @from = from
  @to = to
  @shared_strings = shared_strings
  @prefix = prefix
  @height = height
  @hidden = hidden
  @custom_height = custom_height
  @outline_level = outline_level
  @cells = nil
end

Instance Attribute Details

#custom_height ⇒ Object (readonly)

Returns:

  • (Object) 


22
23
24
 
# File 'lib/xlsxrb/stream_row.rb', line 22

def custom_height
  @custom_height
end

#height ⇒ Object (readonly)

Returns:

  • (Object) 


22
23
24
 
# File 'lib/xlsxrb/stream_row.rb', line 22

def height
  @height
end

#hidden ⇒ Object (readonly)

Returns:

  • (Object) 


22
23
24
 
# File 'lib/xlsxrb/stream_row.rb', line 22

def hidden
  @hidden
end

#index ⇒ Object (readonly)

Returns:

  • (Object) 


22
23
24
 
# File 'lib/xlsxrb/stream_row.rb', line 22

def index
  @index
end

#outline_level ⇒ Object (readonly)

Returns:

  • (Object) 


22
23
24
 
# File 'lib/xlsxrb/stream_row.rb', line 22

def outline_level
  @outline_level
end

Class Method Details

.fast_create(index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil) ⇒ Object

rubocop:disable Style/OptionalBooleanParameter

Parameters:

  • index (Object)
  • xml_bytes (Object)
  • from (Object)
  • to (Object)
  • shared_strings (Object)
  • prefix (Object) (defaults to: "")
  • height (Object) (defaults to: nil)
  • hidden (Object) (defaults to: false)
  • custom_height (Object) (defaults to: false)
  • outline_level (Object) (defaults to: nil)

Returns:

  • (Object) 


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/xlsxrb/stream_row.rb', line 51

def self.fast_create(index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil)
  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(:@outline_level, outline_level)
  inst.instance_variable_set(:@cells, nil)
  inst
end

Instance Method Details

#[](col_index) ⇒ Elements::Cell, ...

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

: (Integer | Symbol col_index) -> untyped

Parameters:

  • col_index (Integer, Symbol) —

    Column index or attribute symbol.

Returns:



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/xlsxrb/stream_row.rb', line 119

def [](col_index)
  case col_index
  when Symbol
    case col_index
    when :cells then cells
    when :index then index
    when :height then height
    when :hidden then hidden
    when :custom_height then custom_height
    when :outline_level then outline_level
    when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
    end
  else
    cells[col_index]
  end
end

#cell_at(col_index) ⇒ Elements::Cell?

Access a cell by 0-based column index.

: (Integer col_index) -> Elements::Cell?

Parameters:

  • col_index (Integer) —

    0-based column index.

Returns:



142
143
144
 
# File 'lib/xlsxrb/stream_row.rb', line 142

def cell_at(col_index)
  cells.find { |c| c.column_index == col_index }
end

#cells ⇒ Array<Elements::Cell>

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

: () -> Array

Returns:



103
104
105
106
107
108
109
110
111
 
# File 'lib/xlsxrb/stream_row.rb', line 103

def cells
  @cells ||= begin
    arr = []
    Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix) do |c|
      arr << c
    end
    arr.freeze
  end
end

#each ⇒ void #each ⇒ Enumerator[Elements::Cell, void]

Iterate over cells in this streaming row.

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

Overloads:

  • #each ⇒ void

    This method returns an undefined value.

  • #each ⇒ Enumerator[Elements::Cell, void]

    Returns:

Yields:

  • (cell)

Yield Parameters:

Returns:

  • (Enumerator, void) 


94
95
96
 
# File 'lib/xlsxrb/stream_row.rb', line 94

def each(&)
  each_cell(&)
end

#each_cell ⇒ void #each_cell ⇒ Enumerator[Elements::Cell, void]

Iterate over cells in this streaming row one by one.

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

Overloads:

  • #each_cell ⇒ void

    This method returns an undefined value.

  • #each_cell ⇒ Enumerator[Elements::Cell, void]

    Returns:

Yields:

  • (cell)

Yield Parameters:

Returns:

  • (Enumerator, void) 


76
77
78
79
80
81
82
83
84
 
# File 'lib/xlsxrb/stream_row.rb', line 76

def each_cell(&block)
  return enum_for(:each_cell) unless block

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

#errors ⇒ Array<String>

Validation errors for compatibility with Elements::Row.

: () -> Array

Returns:

  • (Array<String>) 


194
195
196
 
# File 'lib/xlsxrb/stream_row.rb', line 194

def errors
  Elements::EMPTY_ERRORS
end

#inspect ⇒ String

Human-readable representation.

: () -> String

Returns:

  • (String) 


203
204
205
 
# File 'lib/xlsxrb/stream_row.rb', line 203

def inspect
  "#<#{self.class.name} index=#{index} height=#{height.inspect} hidden=#{hidden}>"
end

#to_a ⇒ Array<Object>

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

: () -> Array

Returns:

  • (Array<Object>) 


151
152
153
154
155
156
157
158
159
160
 
# File 'lib/xlsxrb/stream_row.rb', line 151

def to_a
  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.value
  end
  arr
end

#unmapped_data ⇒ Hash

Unmapped metadata for compatibility with Elements::Row.

: () -> Hash[untyped, untyped]

Returns:

  • (Hash) 


185
186
187
 
# File 'lib/xlsxrb/stream_row.rb', line 185

def unmapped_data
  Elements::EMPTY_HASH
end

#valid? ⇒ Boolean

Returns whether the row is valid according to OOXML specifications.

: () -> bool

Returns:

  • (Boolean) 


176
177
178
 
# File 'lib/xlsxrb/stream_row.rb', line 176

def valid?
  true
end

#values ⇒ Array<Object>

Returns cell values as an Array.

: () -> Array

Returns:

  • (Array<Object>) 


167
168
169
 
# File 'lib/xlsxrb/stream_row.rb', line 167

def values
  to_a
end