xlsxrb 0.1.13 → 0.1.15

data/lib/xlsxrb/stream_row.rb

@@ -19,7 +19,7 @@ module Xlsxrb
   class StreamRow
     [Enumerable].each { |m| include m }
 
-    attr_reader :index, :height, :hidden, :custom_height, :outline_level
+    attr_reader :index, :height, :hidden, :custom_height, :collapsed, :outline_level, :style_index, :pad_empty_cells
 
     # @param index [Integer] 0-based row index.
     # @param xml_bytes [String] Raw ASCII-8BIT XML bytes.
@@ -30,10 +30,14 @@ module Xlsxrb
     # @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 collapsed [Boolean] Whether the row is collapsed.
     # @param outline_level [Integer, nil] Grouping/outline level.
-    #: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?outline_level: Integer | nil) -> void
+    # @param style_index [Integer, nil] Style index.
+    # @param date1904 [Boolean] Whether the 1904 date system is active.
+    # @param pad_empty_cells [Boolean] Whether missing cells in this row are padded.
+    #: (index: Integer, xml_bytes: String, from: Integer, to: Integer, shared_strings: Array[String], ?prefix: String, ?height: Float | Integer | nil, ?hidden: bool, ?custom_height: bool, ?collapsed: bool, ?outline_level: Integer | nil, ?style_index: Integer | nil, ?styles: Hash[untyped, untyped]?, ?date1904: bool, ?pad_empty_cells: bool) -> void
     def initialize(index:, xml_bytes:, from:, to:, shared_strings:, prefix: "", height: nil, hidden: false,
-                   custom_height: false, outline_level: nil)
+                   custom_height: false, collapsed: false, outline_level: nil, style_index: nil, styles: nil, date1904: false, pad_empty_cells: false)
       @index = index
       @xml = xml_bytes
       @from = from
@@ -43,12 +47,17 @@ module Xlsxrb
       @height = height
       @hidden = hidden
       @custom_height = custom_height
+      @collapsed = collapsed
       @outline_level = outline_level
+      @style_index = style_index
+      @styles = styles
+      @date1904 = date1904 ? true : false
+      @pad_empty_cells = pad_empty_cells ? true : false
       @cells = nil
     end
 
     # rubocop:disable Style/OptionalBooleanParameter
-    def self.fast_create(index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil)
+    def self.fast_create(index, xml_bytes, from, to, shared_strings, prefix = "", height = nil, hidden = false, custom_height = false, outline_level = nil, style_index = nil, styles = nil, date1904 = false, collapsed = false, pad_empty_cells = false)
       inst = allocate
       inst.instance_variable_set(:@index, index)
       inst.instance_variable_set(:@xml, xml_bytes)
@@ -59,12 +68,80 @@ module Xlsxrb
       inst.instance_variable_set(:@height, height)
       inst.instance_variable_set(:@hidden, hidden)
       inst.instance_variable_set(:@custom_height, custom_height)
+      inst.instance_variable_set(:@collapsed, collapsed)
       inst.instance_variable_set(:@outline_level, outline_level)
+      inst.instance_variable_set(:@style_index, style_index)
+      inst.instance_variable_set(:@styles, styles)
+      inst.instance_variable_set(:@date1904, date1904 ? true : false)
+      inst.instance_variable_set(:@pad_empty_cells, pad_empty_cells ? true : false)
       inst.instance_variable_set(:@cells, nil)
       inst
     end
     # rubocop:enable Style/OptionalBooleanParameter
 
+    # Returns whether the row is hidden.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def hidden?
+      @hidden == true
+    end
+
+    # Returns whether the row is collapsed.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def collapsed?
+      @collapsed == true
+    end
+
+    # Returns whether custom height is set.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def custom_height?
+      @custom_height == true
+    end
+
+    # Returns a frozen Hash of row attributes.
+    #
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    #: () -> Hash[Symbol, untyped]
+    def attributes
+      h = {
+        index: @index,
+        height: @height,
+        hidden: @hidden,
+        custom_height: @custom_height,
+        collapsed: @collapsed,
+        outline_level: @outline_level
+      }
+      h[:style_index] = @style_index if @style_index
+      h.freeze
+    end
+
+    # Returns whether the row uses the 1904 date system.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def date1904?
+      @date1904 ? true : false
+    end
+
+    # Returns whether missing cells in this row are padded.
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def pad_empty_cells?
+      @pad_empty_cells ? true : false
+    end
+
     # Iterate over cells in this streaming row one by one.
     #
     # @yield [cell]
@@ -76,10 +153,10 @@ module Xlsxrb
     def each_cell(&block)
       return enum_for(:each_cell) unless block
 
-      if @cells
-        @cells.each(&block)
+      if @cells || @pad_empty_cells
+        cells.each(&block)
       else
-        Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix, &block)
+        Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix, @styles, @date1904, &block)
       end
     end
 
@@ -103,9 +180,21 @@ module Xlsxrb
     def cells
       @cells ||= begin
         arr = []
-        Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix) do |c|
+        Ooxml::WorksheetParser.fast_scan_cells_direct(@xml, @from, @to, @shared_strings, @index, @prefix, @styles, @date1904) do |c|
           arr << c
         end
+        if @pad_empty_cells && !arr.empty?
+          max_col = arr.map(&:column_index).max || 0
+          if arr.size < max_col + 1
+            cell_map = {}
+            arr.each { |c| cell_map[c.column_index] = c }
+            padded = Array.new(max_col + 1)
+            (0..max_col).each do |c_idx|
+              padded[c_idx] = cell_map[c_idx] || Elements::Cell.fast_create(@index, c_idx, nil, nil, nil, nil, nil, @date1904)
+            end
+            arr = padded
+          end
+        end
         arr.freeze
       end
     end
@@ -121,12 +210,28 @@ module Xlsxrb
       when Symbol
         case col_index
         when :cells then cells
+        when :values then values
+        when :raw_values then raw_values
+        when :formatted_values then formatted_values
+        when :formulas then formulas
         when :index then index
         when :height then height
         when :hidden then hidden
         when :custom_height then custom_height
+        when :collapsed then collapsed
         when :outline_level then outline_level
-        when :attrs then { height: height, hidden: hidden, custom_height: custom_height, outline_level: outline_level }
+        when :style_index then style_index
+        when :date1904 then date1904?
+        when :hidden? then hidden?
+        when :collapsed? then collapsed?
+        when :custom_height? then custom_height?
+        when :pad_empty_cells then @pad_empty_cells
+        when :pad_empty_cells? then pad_empty_cells?
+        when :attributes then attributes
+        when :attrs
+          h = { height: height, hidden: hidden, custom_height: custom_height, collapsed: collapsed, outline_level: outline_level }
+          h[:style_index] = style_index if style_index
+          h
         end
       else
         cells[col_index]
@@ -143,29 +248,107 @@ module Xlsxrb
       cells.find { |c| c.column_index == col_index }
     end
 
+    # Convert row cells to a coordinate-keyed Hash (e.g. {"A1" => "value", "B1" => 123}).
+    #
+    # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+    # @return [Hash{String => Object}]
+    # @api public
+    #: (?type_cast: bool) -> Hash[String, untyped]
+    def to_h(type_cast: false)
+      result = {}
+      each_cell do |c|
+        val = c.value
+        if type_cast && val.is_a?(Numeric)
+          fmt_type = if c.style_index && @styles
+                       NumberFormatter.format_type_for(c.style_index, @styles)
+                     elsif c.format_code
+                       NumberFormatter.format_type(c.format_code)
+                     end
+          begin
+            case fmt_type
+            when :date
+              val = Ooxml::Utils.serial_to_date(val, date1904: @date1904)
+            when :datetime, :time
+              val = Ooxml::Utils.serial_to_datetime(val, date1904: @date1904)
+            end
+          rescue StandardError
+            # Keep val numeric on failure
+          end
+        end
+        result[c.ref] = val
+      end
+      result
+    end
+
     # Convert row cells to an Array of raw values (sparse columns get nil).
     #
     # @return [Array<Object>]
     # @api public
     #: () -> Array[untyped]
     def to_a
+      values
+    end
+
+    # Returns cell values as an Array (sparse columns get nil).
+    #
+    # @param type_cast [Boolean] Whether to coerce date/time serial numbers into Date/Time instances.
+    # @return [Array<Object>]
+    # @api public
+    #: (?type_cast: bool) -> Array[untyped]
+    def values(type_cast: false)
+      if @cells
+        values_from_cells(type_cast)
+      else
+        Ooxml::WorksheetParser.fast_scan_row_values(@xml, @from, @to, @shared_strings, @styles, @date1904, type_cast: type_cast)
+      end
+    end
+
+    # Convert row cells to an Array of raw string values (sparse columns get nil).
+    #
+    # @return [Array<String, nil>]
+    # @api public
+    #: () -> Array[String?]
+    def raw_values
       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
+        arr[cell.column_index] = cell.raw_value
       end
       arr
     end
 
-    # Returns cell values as an Array.
+    # Convert row cells to an Array of formatted string representations (sparse columns get nil).
     #
-    # @return [Array<Object>]
+    # @return [Array<String, nil>]
     # @api public
-    #: () -> Array[untyped]
-    def values
-      to_a
+    #: () -> Array[String?]
+    def formatted_values
+      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.formatted_value
+      end
+      arr
+    end
+
+    # Convert row cells to an Array of formula expressions without leading '=' (sparse columns get nil).
+    #
+    # @return [Array<String, nil>]
+    # @api public
+    #: () -> Array[String?]
+    def formulas
+      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.formula_expression
+      end
+      arr
     end
 
     # Returns whether the row is valid according to OOXML specifications.
@@ -177,13 +360,25 @@ module Xlsxrb
       true
     end
 
+    # Returns whether the row contains no cell values (or all cell values are nil or empty strings).
+    #
+    # @return [Boolean]
+    # @api public
+    #: () -> bool
+    def empty?
+      vals = values
+      return true if vals.empty?
+
+      vals.all? { |v| v.nil? || (v.is_a?(String) && v.empty?) }
+    end
+
     # Unmapped metadata for compatibility with Elements::Row.
     #
     # @return [Hash]
     # @api public
     #: () -> Hash[untyped, untyped]
     def unmapped_data
-      Elements::EMPTY_HASH
+      @style_index ? { style_index: @style_index } : Elements::EMPTY_HASH
     end
 
     # Validation errors for compatibility with Elements::Row.
@@ -203,5 +398,37 @@ module Xlsxrb
     def inspect
       "#<#{self.class.name} index=#{index} height=#{height.inspect} hidden=#{hidden}>"
     end
+
+    private
+
+    #: (bool) -> Array[untyped]
+    def values_from_cells(type_cast)
+      return [] if @cells.nil? || @cells.empty?
+
+      max_col = @cells.map(&:column_index).max || 0
+      arr = Array.new(max_col + 1)
+      @cells.each do |c|
+        val = c.value
+        if type_cast && val.is_a?(Numeric)
+          fmt_type = if c.style_index && @styles
+                       NumberFormatter.format_type_for(c.style_index, @styles)
+                     elsif c.format_code
+                       NumberFormatter.format_type(c.format_code)
+                     end
+          begin
+            case fmt_type
+            when :date
+              val = Ooxml::Utils.serial_to_date(val, date1904: @date1904)
+            when :datetime, :time
+              val = Ooxml::Utils.serial_to_datetime(val, date1904: @date1904)
+            end
+          rescue StandardError
+            # Keep val numeric on failure
+          end
+        end
+        arr[c.column_index] = val
+      end
+      arr
+    end
   end
 end