Method: Writeexcel::Worksheet#write_col

Defined in:
lib/writeexcel/worksheet.rb

#write_col(*args) ⇒ Object

:call-seq:

write_column(row, col   , array[, format])
write_column(A1_notation, array[, format])

Write a column of data starting from (row, col). Call write_row() 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.

Returns: the first encountered error value or zero for no errors

The write_col() 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. The write() method is then called for each element of the data. For example:

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

worksheet.write_col(0, 0, array)

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

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 within the data will be treated as rows. 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_col('A1', eec)

Would produce a worksheet as follows:

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

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

Any nil values 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.

As noted above the write() method can be used as a synonym for write_row() and write_row() handles nested array as columns. Therefore, the following two method calls are equivalent although the more explicit call to write_col() would be preferable for maintainability:

worksheet.write_col('A1', array)     # Write a column of data
worksheet.write(    'A1', [ array ]) # Same thing

The write_col() 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 above.

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



3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
 
# File 'lib/writeexcel/worksheet.rb', line 3211

def write_col(*args)
  # Check for a cell reference in A1 notation and substitute row and column
  args = row_col_notation(args)

  # Catch non array refs passed by user.
  raise "Not an array ref in call to write_row()" unless args[2].respond_to?(:to_ary)

  row, col, tokens, options = args
  error   = false
  if tokens
    tokens.each do |token|
      # write() will deal with any nested arrays
      ret = write(row, col, token, options)

      # Return only the first error encountered, if any.
      error ||= ret
      row += 1
    end
  end
  error || 0
end