module Xlsxrb::Elements::CoordinateAccess

Mixin providing coordinate-based and random-access cell/row lookups for in-memory worksheet structures.

Expects the including class to provide a #rows method returning an ‘Array<Elements::Row>`.

@api public

Public Instance Methods

(String | Symbol ref) → Elements::Cell?

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 47
def [](ref)
  cells_hash[ref.to_s.upcase]
end

Access a cell by its Excel-style reference (e.g. “A1”).

@example

sheet["A1"] #=> #<Elements::Cell value="Hello">

@param ref [String, Symbol] Cell reference (e.g. “A1” or :A1). @return [Elements::Cell, nil] @api public

cell_value (ref)

(String ref) → untyped

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 88
def cell_value(ref)
  parsed = Cell.parse_ref(ref)
  return nil unless parsed

  row_idx, col_idx = parsed
  row = row_at(row_idx)
  return nil unless row

  cell = row.cell_at(col_idx)
  cell&.value
end

Returns the raw cell value at the given Excel-style reference (e.g. “A1”).

@example

sheet.cell_value("A1") #=> "Sales Report"

@param ref [String] Cell reference (e.g. “A1”). @return [Object, nil] @api public

cells ()

() → Array[Elements::Cell]

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 34
def cells
  cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
end

Returns all cells ordered by row and column index.

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

cells_hash ()

() → Hash[String, Elements::Cell]

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 18
def cells_hash
  h = {}
  rows.each do |r|
    r.cells.each do |c|
      ref = "#{Cell.column_letter(c.column_index)}#{c.row_index + 1}"
      h[ref] = c
    end
  end
  h
end

Returns a Hash mapping Excel cell references (e.g. “A1”) to Cell objects.

@return [Hash<String, Elements::Cell>]

first_row ()

() → Elements::Row?

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 66
def first_row
  rows.min_by(&:index)
end

Returns the first row in the sheet, or nil.

@return [Elements::Row, nil] @api public

last_row ()

() → Elements::Row?

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 75
def last_row
  rows.max_by(&:index)
end

Returns the last row in the sheet, or nil.

@return [Elements::Row, nil] @api public

row_at (index)

(Integer index) → Elements::Row?

Source

# File lib/xlsxrb/elements/coordinate_access.rb, line 57
def row_at(index)
  rows.find { |r| r.index == index }
end

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

@param index [Integer] 0-based row index. @return [Elements::Row, nil] @api public