Class: Xlsxrb::Elements::Row

Inherits:
Data
  • Object
show all
Includes:
Enumerable
Defined in:
lib/xlsxrb/elements/row.rb,
sig/generated/xlsxrb/elements/row.rbs

Overview

Represents a single row in a worksheet. All row and column indices are 0-based.

Examples:

Access cell by index or symbol

row = sheet.row_at(0)
cell = row[0]       # cell at column 0
row.to_a            # array of cell values

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil, unmapped_data: EMPTY_HASH, errors: nil) ⇒ Row

Returns a new instance of Row.

Signature:

  • (index: Integer, ?cells: Array[Elements::Cell], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil, ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void

Parameters:

  • index (Integer) —

    0-based row index.

  • cells (Array<Elements::Cell>) (defaults to: EMPTY_CELLS) —

    Cells in this row.

  • 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.

  • unmapped_data (Hash) (defaults to: EMPTY_HASH) —

    Additional metadata.

  • errors (Array<String>, nil) (defaults to: nil) —

    Validation errors.



28
29
30
31
32
33
34
35
36
 
# File 'lib/xlsxrb/elements/row.rb', line 28

def initialize(index:, cells: EMPTY_CELLS, height: nil, hidden: false, custom_height: false, outline_level: nil,
               unmapped_data: EMPTY_HASH, errors: nil)
  computed_errors = errors || self.class.validate(index, cells)
  computed_errors = computed_errors.freeze unless computed_errors.frozen?
  cells = cells.freeze unless cells.frozen?
  super(index: index, cells: cells, height: height, hidden: hidden,
        custom_height: custom_height, outline_level: outline_level,
        unmapped_data: unmapped_data, errors: computed_errors)
end

Instance Attribute Details

#cells ⇒ Object (readonly)

Returns the value of attribute cells

Returns:

  • (Object) —

    the current value of cells



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def cells
  @cells
end

#custom_height ⇒ Object (readonly)

Returns the value of attribute custom_height

Returns:

  • (Object) —

    the current value of custom_height



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def custom_height
  @custom_height
end

#errors ⇒ Object (readonly)

Returns the value of attribute errors

Returns:

  • (Object) —

    the current value of errors



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def errors
  @errors
end

#height ⇒ Object (readonly)

Returns the value of attribute height

Returns:

  • (Object) —

    the current value of height



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def height
  @height
end

#hidden ⇒ Object (readonly)

Returns the value of attribute hidden

Returns:

  • (Object) —

    the current value of hidden



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def hidden
  @hidden
end

#index ⇒ Object (readonly)

Returns the value of attribute index

Returns:

  • (Object) —

    the current value of index



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def index
  @index
end

#outline_level ⇒ Object (readonly)

Returns the value of attribute outline_level

Returns:

  • (Object) —

    the current value of outline_level



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def outline_level
  @outline_level
end

#unmapped_data ⇒ Object (readonly)

Returns the value of attribute unmapped_data

Returns:

  • (Object) —

    the current value of unmapped_data



16
17
18
 
# File 'lib/xlsxrb/elements/row.rb', line 16

def unmapped_data
  @unmapped_data
end

Class Method Details

.members ⇒ [ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]

Returns:

  • ([ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]) 


34
 
# File 'sig/generated/xlsxrb/elements/row.rbs', line 34

def self.members: () -> [ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]

.new(index, cells, height, hidden, custom_height, outline_level, unmapped_data, errors) ⇒ instance .new(index:, cells:, height:, hidden:, custom_height:, outline_level:, unmapped_data:, errors:) ⇒ instance

Overloads:

  • .new(index, cells, height, hidden, custom_height, outline_level, unmapped_data, errors) ⇒ instance

    Parameters:

    • index (Object)
    • cells (Object)
    • height (Object)
    • hidden (Object)
    • custom_height (Object)
    • outline_level (Object)
    • unmapped_data (Object)
    • errors (Object)

    Returns:

    • (instance)
  • .new(index:, cells:, height:, hidden:, custom_height:, outline_level:, unmapped_data:, errors:) ⇒ instance

    Parameters:

    • index: (Object)
    • cells: (Object)
    • height: (Object)
    • hidden: (Object)
    • custom_height: (Object)
    • outline_level: (Object)
    • unmapped_data: (Object)
    • errors: (Object)

    Returns:

    • (instance) 


31
32
 
# File 'sig/generated/xlsxrb/elements/row.rbs', line 31

def self.new: (untyped index, untyped cells, untyped height, untyped hidden, untyped custom_height, untyped outline_level, untyped unmapped_data, untyped errors) -> instance
| (index: untyped, cells: untyped, height: untyped, hidden: untyped, custom_height: untyped, outline_level: untyped, unmapped_data: untyped, errors: untyped) -> instance

.validate(index, cells) ⇒ Array<String>

Validates row index and cells against OOXML limits.

Signature:

  • (untyped index, untyped cells) -> Array[String]

Parameters:

Returns:

  • (Array<String>) —

    List of errors.



161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/xlsxrb/elements/row.rb', line 161

def self.validate(index, cells)
  return EMPTY_ERRORS if index.is_a?(Integer) && index >= 0 && index < 1_048_576 && cells.is_a?(Array)

  errs = []
  if !index.is_a?(Integer) || index.negative?
    errs << "index must be a non-negative Integer (got #{index.inspect})"
  elsif index >= 1_048_576
    errs << "index must be < 1048576 (got #{index}, max row is 1048576)"
  end
  errs << "cells must be an Array (got #{cells.class})" unless cells.is_a?(Array)
  errs
end

Instance Method Details

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

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

Examples:

row[0]          #=> Cell at column 0
row[:height]    #=> 25.0
row[:cells]     #=> [Cell, Cell, ...]

Signature:

  • (Integer | Symbol col_index) -> untyped

Parameters:

  • col_index (Integer, Symbol) —

    Column index or attribute symbol.

Returns:



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

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(column_index) ⇒ Elements::Cell?

Returns the cell at the given 0-based column index, or nil.

Signature:

  • (Integer column_index) -> Elements::Cell?

Parameters:

  • column_index (Integer) —

    0-based column index.

Returns:



137
138
139
 
# File 'lib/xlsxrb/elements/row.rb', line 137

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

#each {|cell| ... } ⇒ Enumerator, void

Iterate over cells in this row.

Examples:

row.each do |cell|
  puts cell.value
end

Signature:

  • () { (Elements::Cell) -> void } -> void

  • | () -> Enumerator[Elements::Cell, void]

Yields:

  • (cell)

Yield Parameters:

Returns:

  • (Enumerator, void) 


79
80
81
82
83
 
# File 'lib/xlsxrb/elements/row.rb', line 79

def each(&)
  return to_enum(:each) unless block_given?

  cells.each(&)
end

#each_cell {|cell| ... } ⇒ Enumerator, void

Iterate over cells in this row.

Examples:

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

Signature:

  • () { (Elements::Cell) -> void } -> void

  • | () -> Enumerator[Elements::Cell, void]

Yields:

  • (cell)

Yield Parameters:

Returns:

  • (Enumerator, void) 


98
99
100
101
102
 
# File 'lib/xlsxrb/elements/row.rb', line 98

def each_cell(&)
  return to_enum(:each_cell) unless block_given?

  cells.each(&)
end

#members ⇒ [ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]

Returns:

  • ([ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]) 


36
 
# File 'sig/generated/xlsxrb/elements/row.rbs', line 36

def members: () -> [ :index, :cells, :height, :hidden, :custom_height, :outline_level, :unmapped_data, :errors ]

#to_a ⇒ Array<Object>

Convert row cells to an Array of raw values.

Examples:

row.to_a #=> ["ID", "Name", "Total"]

Signature:

  • () -> Array[untyped]

Returns:

  • (Array<Object>) 


112
113
114
115
116
117
118
119
120
121
 
# File 'lib/xlsxrb/elements/row.rb', line 112

def to_a
  return [] if cells.empty?

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

#valid? ⇒ Boolean

Returns whether the row is valid according to OOXML specifications.

Signature:

  • () -> bool

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/xlsxrb/elements/row.rb', line 127

def valid?
  errors.empty?
end

#values ⇒ Array<Object>

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

Signature:

  • () -> Array[untyped]

Returns:

  • (Array<Object>) 


146
147
148
149
150
151
152
153
 
# File 'lib/xlsxrb/elements/row.rb', line 146

def values
  return [] if cells.empty?

  max_col = cells.max_by(&:column_index).column_index
  result = Array.new(max_col + 1)
  cells.each { |c| result[c.column_index] = c.value }
  result
end