xlsxrb 0.1.5 → 0.1.7

data/lib/xlsxrb/elements/worksheet.rb

@@ -5,15 +5,33 @@
 module Xlsxrb
   module Elements
     # Represents a single worksheet in a workbook.
+    #
+    # @example Access cells and rows
+    #   sheet = workbook.sheet(0)
+    #   cell = sheet["A1"]
+    #   sheet.each_row { |row| puts row.to_a.inspect }
+    #
+    # @api public
     Worksheet = Data.define(:name, :rows, :columns, :charts, :unmapped_data, :errors) do
       include Enumerable
 
+      # @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
 
+      # Returns a Hash mapping Excel cell references (e.g. "A1") to Cell objects.
+      #
+      # @return [Hash<String, Elements::Cell>]
+      #: () -> Hash[String, Elements::Cell]
       def cells_hash
         h = {}
         rows.each do |r|
@@ -25,51 +43,131 @@ module Xlsxrb
         h
       end
 
+      # Returns all cells ordered by row and column index.
+      #
+      # @return [Array<Elements::Cell>]
+      # @api public
+      #: () -> Array[Elements::Cell]
       def cells
         # Ensure ordered traversal
         cells_hash.values.sort_by { |c| [c.row_index, c.column_index] }
       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
+      #: (String | Symbol ref) -> Elements::Cell?
       def [](ref)
         cells_hash[ref.to_s.upcase]
       end
 
+      # Iterate over cells in the worksheet.
+      #
+      # @example
+      #   sheet.each do |cell|
+      #     puts cell.value
+      #   end
+      #
+      # @yield [cell]
+      # @yieldparam cell [Elements::Cell]
+      # @return [Enumerator, void]
+      # @api public
+      #: () { (Elements::Cell) -> void } -> void
+      #: | () -> Enumerator[Elements::Cell, void]
       def each(&)
         return to_enum(:each) unless block_given?
 
         cells.each(&)
       end
 
+      # Iterate over cells in the worksheet.
+      #
+      # @example
+      #   sheet.each_cell do |cell|
+      #     puts "#{cell.ref}: #{cell.value}"
+      #   end
+      #
+      # @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?
 
         cells.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
 
+      # Returns whether the worksheet is valid according to OOXML specifications.
+      #
+      # @return [Boolean]
+      #: () -> bool
       def valid?
         errors.empty?
       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
+      #: (Integer index) -> Elements::Row?
       def row_at(index)
         rows.find { |r| r.index == index }
       end
 
+      # Returns the first row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      #: () -> Elements::Row?
       def first_row
         rows.min_by(&:index)
       end
 
+      # Returns the last row in the sheet, or nil.
+      #
+      # @return [Elements::Row, nil]
+      # @api public
+      #: () -> Elements::Row?
       def last_row
         rows.max_by(&:index)
       end
 
-      # Returns cell value at Excel-style reference (e.g. "A1").
+      # 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
+      #: (String ref) -> untyped
       def cell_value(ref)
         parsed = Cell.parse_ref(ref)
         return nil unless parsed
@@ -84,11 +182,16 @@ module Xlsxrb
 
       # 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 +227,12 @@ module Xlsxrb
         with(rows: new_rows)
       end
 
+      # 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/ooxml/shared_strings_parser.rb

@@ -9,13 +9,20 @@ module Xlsxrb
     # SAX-based parser for xl/sharedStrings.xml.
     # Returns an Array of strings (index = SST index).
     class SharedStringsParser
+      XML_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"', "&apos;" => "'" }.freeze
+
       # Parses all shared strings and returns an Array of strings.
-      def self.parse(xml_string, part_name: "xl/sharedStrings.xml")
+      def self.parse(xml_string, _part_name: "xl/sharedStrings.xml")
         return [] if xml_string.nil? || xml_string.empty?
 
+        if xml_string.include?("<!DOCTYPE") || xml_string.include?("<!ENTITY")
+          listener = Class.new { include REXML::SAX2Listener }.new
+          XmlParser.parse(xml_string, listener)
+        end
+
         strings = []
-        each_event(xml_string, part_name: part_name) do |event|
-          strings << event.args[0] if event.type == :sst_item
+        fast_scan(xml_string) do |str|
+          strings << str
         end
         strings
       end
@@ -25,53 +32,110 @@ module Xlsxrb
         return enum_for(:each_event, xml_string, part_name: part_name) unless block
         return if xml_string.nil? || xml_string.empty?
 
-        listener = EventListener.new(part_name, &block)
-        XmlParser.parse(xml_string, listener)
+        index = 0
+        fast_scan(xml_string) do |str|
+          block.call(Event.new(
+                       type: :sst_item,
+                       args: [str],
+                       source: { part: part_name, index: index }
+                     ))
+          index += 1
+        end
       end
 
-      # SAX listener for generating events from shared string table.
-      class EventListener
-        include REXML::SAX2Listener
-
-        def initialize(part_name, &block)
-          @part_name = part_name
-          @block = block
-          @in_si = false
-          @in_t = false
-          @current_text = +""
-          @index = 0
-        end
+      def self.fast_scan(xml_src)
+        xml = xml_src.b
+        sst_start = xml.index("<sst")
+        return unless sst_start
 
-        def start_element(_uri, localname, _qname, _attrs)
-          case localname
-          when "si"
-            @in_si = true
-            @current_text = +""
-          when "t"
-            @in_t = true
+        sst_open_end = xml.index(">", sst_start)
+        return unless sst_open_end
+        return if xml.getbyte(sst_open_end - 1) == 47 # self-closing <sst/>
+
+        sst_end = xml.index("</sst>", sst_open_end)
+        sst_end ||= xml.bytesize
+
+        pos = sst_open_end + 1
+        while pos < sst_end
+          si_start = xml.index("<si", pos)
+          break unless si_start && si_start < sst_end
+
+          si_open_end = xml.index(">", si_start + 3)
+          break unless si_open_end
+
+          # Self-closing <si/>
+          if xml.getbyte(si_open_end - 1) == 47
+            yield ""
+            pos = si_open_end + 1
+            next
           end
-        end
 
-        def end_element(_uri, localname, _qname)
-          case localname
-          when "si"
-            @in_si = false
-            frozen_str = @current_text.freeze
-            @block.call(Event.new(
-                          type: :sst_item,
-                          args: [frozen_str],
-                          source: { part: @part_name, index: @index }
-                        ))
-            @index += 1
-          when "t"
-            @in_t = false
+          si_end = xml.index("</si>", si_open_end + 1)
+          break unless si_end
+
+          # Fast path: check for simple single <t>...</t> inside <si>
+          first_t = xml.index("<t", si_open_end + 1)
+          if first_t && first_t < si_end
+            t_open_end = xml.index(">", first_t + 2)
+            if t_open_end && t_open_end < si_end
+              if xml.getbyte(t_open_end - 1) == 47 # <t/>
+                str = ""
+              else
+                t_end = xml.index("</t>", t_open_end + 1)
+                if t_end && t_end <= si_end
+                  next_t = xml.index("<t", t_end + 4)
+                  if next_t && next_t < si_end
+                    # Multiple <t> tags (rich text runs)
+                    str = extract_multi_t(xml, si_open_end + 1, si_end)
+                  else
+                    raw_str = xml.byteslice(t_open_end + 1, t_end - t_open_end - 1).force_encoding("UTF-8")
+                    str = raw_str.include?("&") ? raw_str.gsub(/&(?:amp|lt|gt|quot|apos);/, XML_ENTITIES) : raw_str
+                  end
+                else
+                  str = ""
+                end
+              end
+            else
+              str = ""
+            end
+          else
+            str = ""
           end
+
+          yield str.freeze
+          pos = si_end + 5
         end
+      end
+
+      private_class_method :fast_scan
+
+      def self.extract_multi_t(xml, from, to)
+        buf = +""
+        pos = from
+        while pos < to
+          t_start = xml.index("<t", pos)
+          break unless t_start && t_start < to
 
-        def characters(text)
-          @current_text << text if @in_si && @in_t
+          t_open_end = xml.index(">", t_start + 2)
+          break unless t_open_end
+
+          if xml.getbyte(t_open_end - 1) == 47
+            pos = t_open_end + 1
+            next
+          end
+
+          t_end = xml.index("</t>", t_open_end + 1)
+          break unless t_end && t_end <= to
+
+          raw_chunk = xml.byteslice(t_open_end + 1, t_end - t_open_end - 1).force_encoding("UTF-8")
+          raw_chunk = raw_chunk.gsub(/&(?:amp|lt|gt|quot|apos);/, XML_ENTITIES) if raw_chunk.include?("&")
+          buf << raw_chunk
+          pos = t_end + 4
         end
+        buf
       end
+
+      private_class_method :extract_multi_t
     end
   end
 end

data/lib/xlsxrb/ooxml/worksheet_parser.rb

@@ -393,8 +393,7 @@ module Xlsxrb
           if raw.include?(".")
             raw.to_f
           else
-            int_val = raw.to_i
-            int_val.to_s == raw ? int_val : raw.to_f
+            raw.to_i
           end
         end
       end
@@ -482,19 +481,53 @@ module Xlsxrb
             next
           end
 
-          row_tag = xml.byteslice(row_start, tag_end - row_start)
           row_index = 0
-          r_val = tag_attr(row_tag, ' r="')
-          row_index = r_val.to_i - 1 if r_val
+          has_custom_attrs = false
+          ri = row_start + 4
+          while ri < tag_end
+            rb = xml.getbyte(ri)
+            if rb == 114 && xml.getbyte(ri + 1) == 61 && xml.getbyte(ri + 2) == 34 # r="
+              ri += 3
+              while ri < tag_end
+                cb = xml.getbyte(ri)
+                break unless cb.between?(48, 57)
+
+                row_index = (row_index * 10) + (cb - 48)
+                ri += 1
+
+              end
+              row_index -= 1
+            elsif [104, 99, 111].include?(rb) # 'h', 'c', 'o' for ht, customHeight, hidden, outlineLevel
+              has_custom_attrs = true
+              ri += 1
+            else
+              ri += 1
+            end
+          end
+
+          attrs = if has_custom_attrs
+                    row_tag = xml.byteslice(row_start, tag_end - row_start)
+                    extract_row_attrs(row_tag)
+                  else
+                    EMPTY_HASH
+                  end
 
-          attrs = extract_row_attrs(row_tag)
           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)
 
-          block.call({ index: row_index, cells: cells, attrs: attrs, unmapped: EMPTY_ARRAY, source: row_source })
+          row_obj = Elements::Row.new(
+            index: row_index,
+            cells: cells,
+            height: attrs[:height],
+            hidden: attrs[:hidden] || false,
+            custom_height: attrs[:custom_height] || false,
+            outline_level: attrs[:outline_level],
+            errors: Elements::EMPTY_ERRORS
+          )
+          block.call(row_obj)
 
           pos = row_end + 6
         end
@@ -519,18 +552,90 @@ module Xlsxrb
           c_tag_end = xml.index(">", c_start + 2)
           break unless c_tag_end
 
-          # Extract tag substring for bounded attribute search
-          c_tag = xml.byteslice(c_start, c_tag_end - c_start)
-          ref = tag_attr(c_tag, ' r="')
-          type = tag_attr(c_tag, ' t="')
-          style_str = tag_attr(c_tag, ' s="')
-          style_index = style_str&.to_i
+          # Zero-allocation attribute scan directly within the tag
+          type = nil
+          style_index = nil
+          col_idx = nil
+          row_idx = nil
+
+          ai = c_start + 2
+          while ai < c_tag_end
+            b = xml.getbyte(ai)
+            if [32, 9, 10, 13].include?(b)
+              ai += 1
+              next
+            end
+
+            if b == 114 && xml.getbyte(ai + 1) == 61 && xml.getbyte(ai + 2) == 34 # r="
+              ai += 3
+              col_idx = 0
+              while ai < c_tag_end
+                cb = xml.getbyte(ai)
+                if cb.between?(65, 90)
+                  col_idx = (col_idx * 26) + (cb - 64)
+                  ai += 1
+                elsif cb.between?(97, 122)
+                  col_idx = (col_idx * 26) + (cb - 96)
+                  ai += 1
+                else
+                  break
+                end
+              end
+              col_idx -= 1
+              row_idx = 0
+              while ai < c_tag_end
+                cb = xml.getbyte(ai)
+                break unless cb.between?(48, 57)
+
+                row_idx = (row_idx * 10) + (cb - 48)
+                ai += 1
+
+              end
+              row_idx -= 1
+              ai += 1 if xml.getbyte(ai) == 34
+            elsif b == 116 && xml.getbyte(ai + 1) == 61 && xml.getbyte(ai + 2) == 34 # t="
+              ai += 3
+              type_b = xml.getbyte(ai)
+              if type_b == 115 && xml.getbyte(ai + 1) == 34 # "s"
+                type = "s"
+                ai += 2
+              elsif type_b == 98 && xml.getbyte(ai + 1) == 34 # "b"
+                type = "b"
+                ai += 2
+              elsif type_b == 101 && xml.getbyte(ai + 1) == 34 # "e"
+                type = "e"
+                ai += 2
+              else
+                t_end = xml.index('"', ai)
+                type = xml.byteslice(ai, t_end - ai) if t_end
+                ai = t_end ? t_end + 1 : c_tag_end
+              end
+            elsif b == 115 && xml.getbyte(ai + 1) == 61 && xml.getbyte(ai + 2) == 34 # s="
+              ai += 3
+              style_index = 0
+              while ai < c_tag_end
+                cb = xml.getbyte(ai)
+                break unless cb.between?(48, 57)
+
+                style_index = (style_index * 10) + (cb - 48)
+                ai += 1
+
+              end
+              ai += 1 if xml.getbyte(ai) == 34
+            else
+              ai += 1
+            end
+          end
 
           # Self-closing <c ... />
           if xml.getbyte(c_tag_end - 1) == 47
-            cell_source = row_source.dup
-            cell_source[:cell] = ref
-            cells << { ref: ref, type: type, style_index: style_index, value: nil, source: cell_source }
+            cells << Elements::Cell.new(
+              row_index: row_idx || row_source[:row],
+              column_index: col_idx || cells.size,
+              value: nil,
+              style_index: style_index,
+              errors: Elements::EMPTY_ERRORS
+            )
             pos = c_tag_end + 1
             next
           end
@@ -554,8 +659,21 @@ module Xlsxrb
                 v_val_start = tag_pos + 3
                 v_end = xml.index("</v>", v_val_start)
                 if v_end
-                  raw_value = xml.byteslice(v_val_start, v_end - v_val_start)
-                  value = resolve_fast_value(raw_value, type, shared_strings)
+                  if type == "s"
+                    # Zero-allocation integer parse for SST index
+                    s_idx = 0
+                    v_i = v_val_start
+                    while v_i < v_end
+                      s_idx = (s_idx * 10) + (xml.getbyte(v_i) - 48)
+                      v_i += 1
+                    end
+                    value = shared_strings[s_idx] || ""
+                  elsif type == "b"
+                    value = xml.getbyte(v_val_start) == 49 # '1'
+                  else
+                    raw_value = xml.byteslice(v_val_start, v_end - v_val_start)
+                    value = resolve_fast_value(raw_value, type, shared_strings)
+                  end
                   cpos = v_end + 4
                 else
                   cpos = tag_pos + 3
@@ -603,11 +721,14 @@ module Xlsxrb
           end
 
           val_to_use = inline_str || value
-          cell_source = row_source.dup
-          cell_source[:cell] = ref
-          cell = { ref: ref, type: type, style_index: style_index, value: val_to_use, source: cell_source }
-          cell[:formula] = formula if formula
-          cells << cell
+          cells << Elements::Cell.new(
+            row_index: row_idx || row_source[:row],
+            column_index: col_idx || cells.size,
+            value: val_to_use,
+            formula: formula,
+            style_index: style_index,
+            errors: Elements::EMPTY_ERRORS
+          )
 
           pos = c_end + 4
         end