xlsxrb 0.1.6 → 0.1.8

data/lib/xlsxrb/elements/worksheet.rb

@@ -4,91 +4,110 @@
 
 module Xlsxrb
   module Elements
-    # Represents a single worksheet in a workbook.
-    Worksheet = Data.define(:name, :rows, :columns, :charts, :unmapped_data, :errors) do
-      include Enumerable
-
+    # Represents a single fully parsed, in-memory worksheet in a workbook.
+    # Provides coordinate random access (sheet["A1"]), row lookups (row_at),
+    # and immutable cell updates (update_cell).
+    #
+    # @example Access cells and rows
+    #   sheet = workbook.sheet(0).load
+    #   cell = sheet["A1"]
+    #   row = sheet.row_at(0)
+    #
+    # @api public
+    class Worksheet
+      [Enumerable, CoordinateAccess].each { |m| include m }
+
+      attr_reader :name, :rows, :columns, :charts, :unmapped_data, :errors
+
+      # @param name [String] The worksheet name (max 31 characters).
+      # @param rows [Array<Elements::Row>] Rows in the sheet.
+      # @param columns [Array<Elements::Column>] Column definitions.
+      # @param charts [Array<Hash>] Charts in the sheet.
+      # @param unmapped_data [Hash] Additional metadata for round-tripping.
+      # @param errors [Array<String>, nil] Validation errors.
+      #: (name: String, ?rows: Array[Elements::Row], ?columns: Array[Elements::Column], ?charts: Array[Hash[Symbol, untyped]], ?unmapped_data: Hash[untyped, untyped], ?errors: Array[String]?) -> void
       def initialize(name:, rows: [], columns: [], charts: [], unmapped_data: {}, errors: nil)
-        computed_errors = errors || self.class.validate(name, rows)
-        super(name: name, rows: rows.freeze, columns: columns.freeze, charts: charts.freeze,
-              unmapped_data: unmapped_data, errors: computed_errors.freeze)
-      end
-
-      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
-
-      def cells
-        # Ensure ordered traversal
-        cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
-      end
-
-      def [](ref)
-        cells_hash[ref.to_s.upcase]
+        @name = name
+        @rows = (rows || []).freeze
+        @columns = (columns || []).freeze
+        @charts = (charts || []).freeze
+        @unmapped_data = (unmapped_data || {}).freeze
+        computed_errors = errors || self.class.validate(@name, @rows)
+        @errors = computed_errors.freeze
       end
 
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each do |row|
+      #     puts row.to_a.inspect
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Row) -> void } -> void
+      #: | () -> Enumerator[Elements::Row, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
-        cells.each(&)
-      end
-
-      def each_cell(&)
-        return to_enum(:each_cell) unless block_given?
-
-        cells.each(&)
+        rows.each(&)
       end
 
+      # Iterate over rows in the worksheet.
+      #
+      # @example
+      #   sheet.each_row do |row|
+      #     puts "Row #{row.index}: #{row.to_a.inspect}"
+      #   end
+      #
+      # @yield [row]
+      # @yieldparam row [Elements::Row]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Row) -> void } -> void
+      #: | () -> Enumerator[Elements::Row, void]
       def each_row(&)
         return to_enum(:each_row) unless block_given?
 
         rows.each(&)
       end
 
-      def valid?
-        errors.empty?
-      end
-
-      # Returns the row at the given 0-based index, or nil.
-      def row_at(index)
-        rows.find { |r| r.index == index }
-      end
-
-      def first_row
-        rows.min_by(&:index)
-      end
+      # Iterate over all cells across rows.
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Cell) -> void } -> void
+      #: | () -> Enumerator[Elements::Cell, void]
+      def each_cell(&)
+        return to_enum(:each_cell) unless block_given?
 
-      def last_row
-        rows.max_by(&:index)
+        cells.each(&)
       end
 
-      # Returns cell value at Excel-style reference (e.g. "A1").
-      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
+      # Returns whether the worksheet is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      #: () -> bool
+      def valid?
+        errors.empty?
       end
 
       # Returns a new Worksheet with the specified cell updated.
       #
+      # @example
+      #   new_sheet = sheet.update_cell("B1", value: "Updated")
+      #
       # @param ref [String] The cell reference (e.g. "B1").
       # @param value [Object] The new cell value.
       # @param style_index [Integer, String, nil] Optional new style index.
       # @param formula [Elements::Formula, nil] Optional new formula.
       # @return [Worksheet] A new Worksheet instance.
+      # @api public
+      #: (String ref, ?value: untyped, ?style_index: Integer | String | nil, ?formula: Elements::Formula?) -> Elements::Worksheet
       def update_cell(ref, value: nil, style_index: nil, formula: nil)
         parsed = Cell.parse_ref(ref)
         raise ArgumentError, "invalid cell reference: #{ref}" unless parsed
@@ -124,6 +143,66 @@ module Xlsxrb
         with(rows: new_rows)
       end
 
+      # Returns a new Worksheet with attributes replaced (Data-like behavior).
+      #
+      # @param changes [Hash]
+      # @return [Worksheet]
+      # @api public
+      #: (**untyped) -> Elements::Worksheet
+      def with(**changes)
+        new_name = changes.key?(:name) ? changes[:name] : name
+        new_rows = changes.key?(:rows) ? changes[:rows] : rows
+        new_cols = changes.key?(:columns) ? changes[:columns] : columns
+        new_charts = changes.key?(:charts) ? changes[:charts] : charts
+        new_unmapped = changes.key?(:unmapped_data) ? changes[:unmapped_data] : unmapped_data
+        new_errors = changes.key?(:errors) ? changes[:errors] : errors
+
+        self.class.new(
+          name: new_name,
+          rows: new_rows,
+          columns: new_cols,
+          charts: new_charts,
+          unmapped_data: new_unmapped,
+          errors: new_errors
+        )
+      end
+
+      # Support pattern matching.
+      #: (Array[Symbol]?) -> Hash[Symbol, untyped]
+      def deconstruct_keys(_keys)
+        { name: name, rows: rows, columns: columns, charts: charts, unmapped_data: unmapped_data, errors: errors }
+      end
+
+      # Compare worksheets for equality.
+      #: (untyped other) -> bool
+      def ==(other)
+        return false unless other.is_a?(Worksheet)
+
+        name == other.name && rows == other.rows && columns == other.columns && charts == other.charts
+      end
+      alias eql? ==
+
+      #: () -> Integer
+      def hash
+        [self.class, name, rows, columns, charts].hash
+      end
+
+      # Returns self when load is called on an already in-memory Worksheet.
+      #
+      # @return [Elements::Worksheet]
+      # @api public
+      #: () -> Elements::Worksheet
+      def load
+        self
+      end
+      alias to_worksheet load
+
+      # Validates worksheet name and rows against OOXML limits.
+      #
+      # @param name [String]
+      # @param rows [Array<Elements::Row>]
+      # @return [Array<String>] List of errors.
+      #: (untyped name, untyped rows) -> Array[String]
       def self.validate(name, rows)
         errs = []
         if name.nil? || !name.is_a?(String) || name.empty?

data/lib/xlsxrb/elements.rb

@@ -6,6 +6,7 @@ require_relative "elements/types"
 require_relative "elements/cell"
 require_relative "elements/row"
 require_relative "elements/column"
+require_relative "elements/coordinate_access"
 require_relative "elements/worksheet"
 require_relative "elements/workbook"
 

data/lib/xlsxrb/ooxml/worksheet_parser.rb

@@ -515,17 +515,17 @@ module Xlsxrb
           row_end = xml.index("</row>", tag_end + 1)
           break unless row_end
 
-          row_source = { part: part_name, row: row_index }
-          cells = fast_parse_cells_direct(xml, tag_end + 1, row_end, shared_strings, row_source)
-
-          row_obj = Elements::Row.new(
+          { part: part_name, row: row_index }
+          row_obj = StreamRow.new(
             index: row_index,
-            cells: cells,
+            xml_bytes: xml,
+            from: tag_end + 1,
+            to: row_end,
+            shared_strings: shared_strings,
             height: attrs[:height],
             hidden: attrs[:hidden] || false,
             custom_height: attrs[:custom_height] || false,
-            outline_level: attrs[:outline_level],
-            errors: Elements::EMPTY_ERRORS
+            outline_level: attrs[:outline_level]
           )
           block.call(row_obj)
 
@@ -537,7 +537,13 @@ module Xlsxrb
 
       def self.fast_parse_cells_direct(xml, from, to, shared_strings, row_source)
         cells = []
+        fast_scan_cells_direct(xml, from, to, shared_strings, row_source) { |c| cells << c }
+        cells
+      end
+
+      def self.fast_scan_cells_direct(xml, from, to, shared_strings, row_source, &block)
         pos = from
+        cell_count = 0
 
         while pos < to
           c_start = xml.index("<c", pos)
@@ -589,7 +595,6 @@ module Xlsxrb
 
                 row_idx = (row_idx * 10) + (cb - 48)
                 ai += 1
-
               end
               row_idx -= 1
               ai += 1 if xml.getbyte(ai) == 34
@@ -619,7 +624,6 @@ module Xlsxrb
 
                 style_index = (style_index * 10) + (cb - 48)
                 ai += 1
-
               end
               ai += 1 if xml.getbyte(ai) == 34
             else
@@ -629,13 +633,15 @@ module Xlsxrb
 
           # Self-closing <c ... />
           if xml.getbyte(c_tag_end - 1) == 47
-            cells << Elements::Cell.new(
+            cell_obj = Elements::Cell.new(
               row_index: row_idx || row_source[:row],
-              column_index: col_idx || cells.size,
+              column_index: col_idx || cell_count,
               value: nil,
               style_index: style_index,
               errors: Elements::EMPTY_ERRORS
             )
+            cell_count += 1
+            block.call(cell_obj)
             pos = c_tag_end + 1
             next
           end
@@ -721,19 +727,19 @@ module Xlsxrb
           end
 
           val_to_use = inline_str || value
-          cells << Elements::Cell.new(
+          cell_obj = Elements::Cell.new(
             row_index: row_idx || row_source[:row],
-            column_index: col_idx || cells.size,
+            column_index: col_idx || cell_count,
             value: val_to_use,
             formula: formula,
             style_index: style_index,
             errors: Elements::EMPTY_ERRORS
           )
+          cell_count += 1
+          block.call(cell_obj)
 
           pos = c_end + 4
         end
-
-        cells
       end
 
       private_class_method :fast_parse_cells_direct

data/lib/xlsxrb/stream_row.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Xlsxrb
+  # 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
+  class StreamRow
+    [Enumerable].each { |m| include m }
+
+    attr_reader :index, :height, :hidden, :custom_height, :outline_level
+
+    # @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 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 outline_level [Integer, nil] Grouping/outline level.
+    #: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    def initialize(index:, xml_bytes:, from:, to:, shared_strings:, height: nil, hidden: false,
+                   custom_height: false, outline_level: nil)
+      @index = index
+      @xml = xml_bytes
+      @from = from
+      @to = to
+      @shared_strings = shared_strings
+      @height = height
+      @hidden = hidden
+      @custom_height = custom_height
+      @outline_level = outline_level
+      @cells_cache = nil
+    end
+
+    # Iterate over cells in this streaming row one by one.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    #: () { (Elements::Cell) -> void } -> void
+    #: | () -> Enumerator[Elements::Cell, void]
+    def each_cell(&)
+      return enum_for(:each_cell) unless block_given?
+
+      if @cells
+        @cells.each(&)
+      else
+        Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, { row: @index }, &)
+      end
+    end
+
+    # Iterate over cells in this streaming row.
+    #
+    # @yield [cell]
+    # @yieldparam cell [Elements::Cell]
+    # @return [Enumerator, void]
+    # @api public
+    #: () { (Elements::Cell) -> void } -> void
+    #: | () -> Enumerator[Elements::Cell, void]
+    def each(&)
+      each_cell(&)
+    end
+
+    # Returns all cells as an Array. Cached on first access.
+    #
+    # @return [Array<Elements::Cell>]
+    # @api public
+    #: () -> Array[Elements::Cell]
+    def cells
+      @cells ||= each_cell.to_a.freeze
+    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
+    #: (Integer | Symbol col_index) -> untyped
+    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
+
+    # Access a cell by 0-based column index.
+    #
+    # @param col_index [Integer] 0-based column index.
+    # @return [Elements::Cell, nil]
+    # @api public
+    #: (Integer col_index) -> Elements::Cell?
+    def cell_at(col_index)
+      cells.find { |c| c.column_index == col_index }
+    end
+
+    # Convert row cells to an Array of raw values (sparse columns get nil).
+    #
+    # @return [Array<Object>]
+    # @api public
+    #: () -> Array[untyped]
+    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
+
+    # Returns cell values as an Array.
+    #
+    # @return [Array<Object>]
+    # @api public
+    #: () -> Array[untyped]
+    def values
+      to_a
+    end
+
+    # Returns whether the row is valid according to OOXML specifications.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def valid?
+      true
+    end
+
+    # Unmapped metadata for compatibility with Elements::Row.
+    #
+    # @return [Hash]
+    # @api public
+    #: () -> Hash[untyped, untyped]
+    def unmapped_data
+      Elements::EMPTY_HASH
+    end
+
+    # Validation errors for compatibility with Elements::Row.
+    #
+    # @return [Array<String>]
+    # @api public
+    #: () -> Array[String]
+    def errors
+      Elements::EMPTY_ERRORS
+    end
+
+    # Human-readable representation.
+    #
+    # @return [String]
+    # @api public
+    #: () -> String
+    def inspect
+      "#<#{self.class.name} index=#{index} height=#{height.inspect} hidden=#{hidden}>"
+    end
+  end
+end

data/lib/xlsxrb/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Xlsxrb
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end