Method: Writexlsx::Worksheet#write_row

Defined in:

lib/write_xlsx/worksheet.rb

#write_row(*args) ⇒ Object

:call-seq:

write_row(row, col, array [ , format ] )

Write a row of data starting from (row, col). Call write_col() if any of the elements of the array are in turn array. This allows the writing of 1D or 2D arrays of data in one go.

The write_row() method can be used to write a 1D or 2D array of data in one go. This is useful for converting the results of a database query into an Excel worksheet. You must pass a reference to the array of data rather than the array itself. The write() method is then called for each element of the data. For example:

array = ['awk', 'gawk', 'mawk']

worksheet.write_row(0, 0, array)

# The above example is equivalent to:
worksheet.write(0, 0, array[0])
worksheet.write(0, 1, array[1])
worksheet.write(0, 2, array[2])

Note: For convenience the write() method behaves in the same way as write_row() if it is passed an array reference. Therefore the following two method calls are equivalent:

worksheet.write_row('A1', array)    # Write a row of data
worksheet.write(    'A1', array)    # Same thing

As with all of the write methods the format parameter is optional. If a format is specified it is applied to all the elements of the data array.

Array references within the data will be treated as columns. This allows you to write 2D arrays of data in one go. For example:

eec =  [
            ['maggie', 'milly', 'molly', 'may'  ],
            [13,       14,      15,      16     ],
            ['shell',  'star',  'crab',  'stone']
       ]

worksheet.write_row('A1', eec)

Would produce a worksheet as follows:

 -----------------------------------------------------------
|   |    A    |    B    |    C    |    D    |    E    | ...
 -----------------------------------------------------------
| 1 | maggie  | 13      | shell   | ...     |  ...    | ...
| 2 | milly   | 14      | star    | ...     |  ...    | ...
| 3 | molly   | 15      | crab    | ...     |  ...    | ...
| 4 | may     | 16      | stone   | ...     |  ...    | ...
| 5 | ...     | ...     | ...     | ...     |  ...    | ...
| 6 | ...     | ...     | ...     | ...     |  ...    | ...

To write the data in a row-column order refer to the write_col() method below.

Any nil in the data will be ignored unless a format is applied to the data, in which case a formatted blank cell will be written. In either case the appropriate row or column value will still be incremented.

The write_row() method returns the first error encountered when writing the elements of the data or zero if no errors were encountered. See the return values described for the write() method.

See also the write_arrays.rb program in the examples directory of the distro.

# File 'lib/write_xlsx/worksheet.rb', line 1758

def write_row(*args)
  # Check for a cell reference in A1 notation and substitute row and column
  row, col, tokens, *options = row_col_notation(args)
  raise "Not an array ref in call to write_row()$!" unless tokens.respond_to?(:to_ary)

  tokens.each do |token|
    # Check for nested arrays
    if token.respond_to?(:to_ary)
      write_col(row, col, token, *options)
    else
      write(row, col, token, *options)
    end
    col += 1
  end
end