A CSV::Table is a two-dimensional data structure for representing CSV documents. Tables allow you to work with the data by row or column, manipulate the data, and even convert the results back to CSV, if needed.
All tables returned by CSV will be constructed from this class, if header row processing is activated.
The current access mode for indexing and iteration.
Internal data format used to compare equality.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 589
def initialize(array_of_rows)
@table = array_of_rows
@mode = :col_or_row
end
Construct a new CSV::Table from array_of_rows, which are expected to be CSV::Row objects. All rows are assumed to have the same headers.
A CSV::Table object supports the following Array methods through delegation:
-
empty?()
-
length()
-
size()
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 787
def <<(row_or_array)
if row_or_array.is_a? Array # append Array
@table << Row.new(headers, row_or_array)
else # append Row
@table << row_or_array
end
self # for chaining
end
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 873
def ==(other)
return @table == other.table if other.is_a? CSV::Table
@table == other
end
Returns true if all rows of this table ==() other‘s rows.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 703
def [](index_or_header)
if @mode == :row or # by index
(@mode == :col_or_row and (index_or_header.is_a?(Integer) or index_or_header.is_a?(Range)))
@table[index_or_header]
else # by header
@table.map { |row| row[index_or_header] }
end
end
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 728
def []=(index_or_header, value)
if @mode == :row or # by index
(@mode == :col_or_row and index_or_header.is_a? Integer)
if value.is_a? Array
@table[index_or_header] = Row.new(headers, value)
else
@table[index_or_header] = value
end
else # set column
if value.is_a? Array # multiple values
@table.each_with_index do |row, i|
if row.header_row?
row[index_or_header] = index_or_header
else
row[index_or_header] = value[i]
end
end
else # repeated value
@table.each do |row|
if row.header_row?
row[index_or_header] = index_or_header
else
row[index_or_header] = value
end
end
end
end
end
In the default mixed mode, this method assigns rows for index access and columns for header access. You can force the index association by first calling by_col!() or by_row!().
Rows may be set to an Array of values (which will inherit the table’s headers()) or a CSV::Row.
Columns may be set to a single value, which is copied to each row of the column, or an Array of values. Arrays of values are assigned to rows top to bottom in row major order. Excess values are ignored and if the Array does not have a value for each row the extra rows will receive a nil.
Assigning to an existing column or row clobbers the data. Assigning to new columns creates them at the right end of the table.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 615
def by_col
self.class.new(@table.dup).by_col!
end
Returns a duplicate table object, in column mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.
This method returns the duplicate table for chaining. Don’t chain destructive methods (like []=()) this way though, since you are working with a duplicate.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 625
def by_col!
@mode = :col
self
end
Switches the mode of this table to column mode. All calls to indexing and iteration methods will work with columns until the mode is changed again.
This method returns the table and is safe to chain.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 640
def by_col_or_row
self.class.new(@table.dup).by_col_or_row!
end
Returns a duplicate table object, in mixed mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.
This method returns the duplicate table for chaining. Don’t chain destructive methods (like []=()) this way though, since you are working with a duplicate.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 652
def by_col_or_row!
@mode = :col_or_row
self
end
Switches the mode of this table to mixed mode. All calls to indexing and iteration methods will use the default intelligent indexing system until the mode is changed again. In mixed mode an index is assumed to be a row reference while anything else is assumed to be column access by headers.
This method returns the table and is safe to chain.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 667
def by_row
self.class.new(@table.dup).by_row!
end
Returns a duplicate table object, in row mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.
This method returns the duplicate table for chaining. Don’t chain destructive methods (like []=()) this way though, since you are working with a duplicate.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 677
def by_row!
@mode = :row
self
end
Switches the mode of this table to row mode. All calls to indexing and iteration methods will work with rows until the mode is changed again.
This method returns the table and is safe to chain.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 815
def delete(index_or_header)
if @mode == :row or # by index
(@mode == :col_or_row and index_or_header.is_a? Integer)
@table.delete_at(index_or_header)
else # by header
@table.map { |row| row.delete(index_or_header).last }
end
end
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 834
def delete_if(&block)
block or return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size }
if @mode == :row or @mode == :col_or_row # by index
@table.delete_if(&block)
else # by header
deleted = []
headers.each do |header|
deleted << delete(header) if block[[header, self[header]]]
end
end
self # for chaining
end
Removes any column or row for which the block returns true. In the default mixed mode or row mode, iteration is the standard row major walking of rows. In column mode, iteration will yield two element tuples containing the column name and an Array of values for that column.
This method returns the table for chaining.
If no block is given, an Enumerator is returned.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 860
def each(&block)
block or return enum_for(__method__) { @mode == :col ? headers.size : size }
if @mode == :col
headers.each { |header| block[[header, self[header]]] }
else
@table.each(&block)
end
self # for chaining
end
In the default mixed mode or row mode, iteration is the standard row major walking of rows. In column mode, iteration will yield two element tuples containing the column name and an Array of values for that column.
This method returns the table for chaining.
If no block is given, an Enumerator is returned.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 687
def headers
if @table.empty?
Array.new
else
@table.first.headers
end
end
Returns the headers for the first row of this table (assumed to match all other rows). An empty Array is returned for empty tables.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 907
def inspect
"#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>".encode("US-ASCII")
end
Shows the mode and size of this table in a US-ASCII String.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 804
def push(*rows)
rows.each { |row| self << row }
self # for chaining
end
A shortcut for appending multiple rows. Equivalent to:
rows.each { |row| self << row }
This method returns the table for chaining.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 882
def to_a
array = [headers]
@table.each do |row|
array.push(row.fields) unless row.header_row?
end
return array
end
Returns the table as an Array of Arrays. Headers will be the first row, then all of the field rows will follow.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 897
def to_csv(write_headers: true, **options)
array = write_headers ? [headers.to_csv(options)] : []
@table.each do |row|
array.push(row.fields.to_csv(options)) unless row.header_row?
end
return array.join('')
end
Returns the table as a complete CSV String. Headers will be listed first, then all of the field rows.
This method assumes you want the Table.headers(), unless you explicitly pass :write_headers => false.
# File tmp/rubies/ruby-2.5.9/lib/csv.rb, line 766
def values_at(*indices_or_headers)
if @mode == :row or # by indices
( @mode == :col_or_row and indices_or_headers.all? do |index|
index.is_a?(Integer) or
( index.is_a?(Range) and
index.first.is_a?(Integer) and
index.last.is_a?(Integer) )
end )
@table.values_at(*indices_or_headers)
else # by headers
@table.map { |row| row.values_at(*indices_or_headers) }
end
end
The mixed mode default is to treat a list of indices as row access, returning the rows indicated. Anything else is considered columnar access. For columnar access, the return set has an Array for each row with the values indicated by the headers in each Array. You can force column or row mode using by_col!() or by_row!().
You cannot mix column and row access.