class CSV::Table
CSV::Table¶ ↑
A CSV::Table instance represents CSV data. (see class CSV).
The instance may have:
-
Rows: each is a Table::Row object.
-
Headers: names for the columns.
Instance Methods¶ ↑
CSV::Table has three groups of instance methods:
-
Its own internally defined instance methods.
-
Methods included by module Enumerable.
-
Methods delegated to class Array.:
-
Array#empty?
-
Array#length
-
Array#size
-
Creating a CSV::Table Instance¶ ↑
Commonly, a new CSV::Table instance is created by parsing CSV source using headers:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.class # => CSV::Table
You can also create an instance directly. See ::new
.
Headers¶ ↑
If a table has headers, the headers serve as labels for the columns of data. Each header serves as the label for its column.
The headers for a CSV::Table object are stored as an Array of Strings.
Commonly, headers are defined in the first row of CSV source:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.headers # => ["Name", "Value"]
If no headers are defined, the Array is empty:
table = CSV::Table.new([]) table.headers # => []
Access Modes¶ ↑
CSV::Table provides three modes for accessing table data:
-
Row mode.
-
Column mode.
-
Mixed mode (the default for a new table).
The access mode for aCSV::Table instance affects the behavior of some of its instance methods:
Row Mode¶ ↑
Set a table to row mode with method by_row!
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_row! # => #<CSV::Table mode:row row_count:4>
Specify a single row by an Integer index:
# Get a row. table[1] # => #<CSV::Row "Name":"bar" "Value":"1"> # Set a row, then get it. table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3]) table[1] # => #<CSV::Row "Name":"bam" "Value":3>
Specify a sequence of rows by a Range:
# Get rows. table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">] # Set rows, then get them. table[1..2] = [ CSV::Row.new(['Name', 'Value'], ['bat', 4]), CSV::Row.new(['Name', 'Value'], ['bad', 5]), ] table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
Column Mode¶ ↑
Set a table to column mode with method by_col!
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col! # => #<CSV::Table mode:col row_count:4>
Specify a column by an Integer index:
# Get a column. table[0] # Set a column, then get it. table[0] = ['FOO', 'BAR', 'BAZ'] table[0] # => ["FOO", "BAR", "BAZ"]
Specify a column by its String header:
# Get a column. table['Name'] # => ["FOO", "BAR", "BAZ"] # Set a column, then get it. table['Name'] = ['Foo', 'Bar', 'Baz'] table['Name'] # => ["Foo", "Bar", "Baz"]
Mixed Mode¶ ↑
In mixed mode, you can refer to either rows or columns:
-
An Integer index refers to a row.
-
A Range index refers to multiple rows.
-
A String index refers to a column.
Set a table to mixed mode with method by_col_or_row!
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
Specify a single row by an Integer index:
# Get a row. table[1] # => #<CSV::Row "Name":"bar" "Value":"1"> # Set a row, then get it. table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3]) table[1] # => #<CSV::Row "Name":"bam" "Value":3>
Specify a sequence of rows by a Range:
# Get rows. table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">] # Set rows, then get them. table[1] = CSV::Row.new(['Name', 'Value'], ['bat', 4]) table[2] = CSV::Row.new(['Name', 'Value'], ['bad', 5]) table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
Specify a column by its String header:
# Get a column. table['Name'] # => ["foo", "bat", "bad"] # Set a column, then get it. table['Name'] = ['Foo', 'Bar', 'Baz'] table['Name'] # => ["Foo", "Bar", "Baz"]
Attributes
The current access mode for indexing and iteration.
Internal data format used to compare equality.
Public Class Methods
Returns a new CSV::Table object.
-
Argument
array_of_rows
must be an Array ofCSV::Row
objects. -
Argument
headers
, if given, may be an Array of Strings.
Create an empty CSV::Table object:
table = CSV::Table.new([]) table # => #<CSV::Table mode:col_or_row row_count:1>
Create a non-empty CSV::Table object:
rows = [ CSV::Row.new([], []), CSV::Row.new([], []), CSV::Row.new([], []), ] table = CSV::Table.new(rows) table # => #<CSV::Table mode:col_or_row row_count:4>
If argument headers
is an Array of Strings, those Strings become the table's headers:
table = CSV::Table.new([], headers: ['Name', 'Age']) table.headers # => ["Name", "Age"]
If argument headers
is not given and the table has rows, the headers are taken from the first row:
rows = [ CSV::Row.new(['Foo', 'Bar'], []), CSV::Row.new(['foo', 'bar'], []), CSV::Row.new(['FOO', 'BAR'], []), ] table = CSV::Table.new(rows) table.headers # => ["Foo", "Bar"]
If argument headers
is not given and the table is empty (has no rows), the headers are also empty:
table = CSV::Table.new([]) table.headers # => []
Raises an exception if argument array_of_rows
is not an Array object:
# Raises NoMethodError (undefined method `first' for :foo:Symbol): CSV::Table.new(:foo)
Raises an exception if an element of array_of_rows
is not a CSV::Table object:
# Raises NoMethodError (undefined method `headers' for :foo:Symbol): CSV::Table.new([:foo])
# File lib/csv/table.rb, line 199 def initialize(array_of_rows, headers: nil) @table = array_of_rows @headers = headers unless @headers if @table.empty? @headers = [] else @headers = @table.first.headers end end @mode = :col_or_row end
Public Instance Methods
If row_or_array
is a CSV::Row object, it is appended to the table:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table << CSV::Row.new(table.headers, ['bat', 3]) table[3] # => #<CSV::Row "Name":"bat" "Value":3>
If row_or_array
is an Array, it is used to create a new CSV::Row object which is then appended to the table:
table << ['bam', 4] table[4] # => #<CSV::Row "Name":"bam" "Value":4>
# File lib/csv/table.rb, line 762 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
Returns true
if all each row of self
==
the corresponding row of other_table
, otherwise, false
.
The access mode does no affect the result.
Equal tables:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) other_table = CSV.parse(source, headers: true) table == other_table # => true
Different row count:
other_table.delete(2) table == other_table # => false
Different last row:
other_table << ['bat', 3] table == other_table # => false
# File lib/csv/table.rb, line 965 def ==(other) return @table == other.table if other.is_a? CSV::Table @table == other end
Returns data from the table; does not modify the table.
- Fetch a Row by Its Integer Index
-
Form:
table[n]
,n
an integer. -
Access mode:
:row
or:col_or_row
. -
Return value: nth row of the table, if that row exists; otherwise
nil
.
Returns the nth row of the table if that row exists:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_row! # => #<CSV::Table mode:row row_count:4> table[1] # => #<CSV::Row "Name":"bar" "Value":"1"> table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4> table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
Counts backward from the last row if n
is negative:
table[-1] # => #<CSV::Row "Name":"baz" "Value":"2">
Returns nil
if n
is too large or too small:
table[4] # => nil table[-4] # => nil
Raises an exception if the access mode is :row
and n
is not an Integer:
table.by_row! # => #<CSV::Table mode:row row_count:4> # Raises TypeError (no implicit conversion of String into Integer): table['Name']
- Fetch a Column by Its Integer Index
-
Form:
table[n]
,n
an Integer. -
Access mode:
:col
. -
Return value: nth column of the table, if that column exists; otherwise an Array of
nil
fields of lengthself.size
.
Returns the nth column of the table if that column exists:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col! # => #<CSV::Table mode:col row_count:4> table[1] # => ["0", "1", "2"]
Counts backward from the last column if n
is negative:
table[-2] # => ["foo", "bar", "baz"]
Returns an Array of nil
fields if n
is too large or too small:
table[4] # => [nil, nil, nil] table[-4] # => [nil, nil, nil]
- Fetch Rows by Range
-
Form:
table[range]
,range
a Range object. -
Access mode:
:row
or:col_or_row
. -
Return value: rows from the table, beginning at row
range.start
, if those rows exists.
Returns rows from the table, beginning at row range.first
, if those rows exist:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_row! # => #<CSV::Table mode:row row_count:4> rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1"> rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">] table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4> rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1"> rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
If there are too few rows, returns all from range.start
to the end:
rows = table[1..50] # => #<CSV::Row "Name":"bar" "Value":"1"> rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
Special case: if range.start == table.size
, returns an empty Array:
table[table.size..50] # => []
If range.end
is negative, calculates the ending index from the end:
rows = table[0..-1] rows # => [#<CSV::Row "Name":"foo" "Value":"0">, #<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
If range.start
is negative, calculates the starting index from the end:
rows = table[-1..2] rows # => [#<CSV::Row "Name":"baz" "Value":"2">]
If range.start
is larger than table.size
, returns nil
:
table[4..4] # => nil
- Fetch Columns by Range
-
Form:
table[range]
,range
a Range object. -
Access mode:
:col
. -
Return value: column data from the table, beginning at column
range.start
, if those columns exist.
Returns column values from the table, if the column exists; the values are arranged by row:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col! table[0..1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
Special case: if range.start == headers.size
, returns an Array (size: table.size
) of empty Arrays:
table[table.headers.size..50] # => [[], [], []]
If range.end
is negative, calculates the ending index from the end:
table[0..-1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
If range.start
is negative, calculates the starting index from the end:
table[-2..2] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
If range.start
is larger than table.size
, returns an Array of nil
values:
table[4..4] # => [nil, nil, nil]
- Fetch a Column by Its String Header
-
Form:
table[header]
,header
a String header. -
Access mode:
:col
or:col_or_row
-
Return value: column data from the table, if that
header
exists.
Returns column values from the table, if the column exists:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col! # => #<CSV::Table mode:col row_count:4> table['Name'] # => ["foo", "bar", "baz"] table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4> col = table['Name'] col # => ["foo", "bar", "baz"]
Modifying the returned column values does not modify the table:
col[0] = 'bat' col # => ["bat", "bar", "baz"] table['Name'] # => ["foo", "bar", "baz"]
Returns an Array of nil
values if there is no such column:
table['Nosuch'] # => [nil, nil, nil]
# File lib/csv/table.rb, line 514 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
Puts data onto the table.
- Set a Row by Its Integer Index
-
Form:
table[n] = row
,n
an Integer,row
a CSV::Row instance or an Array of fields. -
Access mode:
:row
or:col_or_row
. -
Return value:
row
.
If the row exists, it is replaced:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) new_row = CSV::Row.new(['Name', 'Value'], ['bat', 3]) table.by_row! # => #<CSV::Table mode:row row_count:4> return_value = table[0] = new_row return_value.equal?(new_row) # => true # Returned the row table[0].to_h # => {"Name"=>"bat", "Value"=>3}
With access mode :col_or_row
:
table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4> table[0] = CSV::Row.new(['Name', 'Value'], ['bam', 4]) table[0].to_h # => {"Name"=>"bam", "Value"=>4}
With an Array instead of a CSV::Row, inherits headers from the table:
array = ['bad', 5] return_value = table[0] = array return_value.equal?(array) # => true # Returned the array table[0].to_h # => {"Name"=>"bad", "Value"=>5}
If the row does not exist, extends the table by adding rows: assigns rows with nil
as needed:
table.size # => 3 table[5] = ['bag', 6] table.size # => 6 table[3] # => nil table[4]# => nil table[5].to_h # => {"Name"=>"bag", "Value"=>6}
Note that the nil
rows are actually nil
, not a row of nil
fields.
- Set a Column by Its Integer Index
-
Form:
table[n] = array_of_fields
,n
an Integer,array_of_fields
an Array of String fields. -
Access mode:
:col
. -
Return value:
array_of_fields
.
If the column exists, it is replaced:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) new_col = [3, 4, 5] table.by_col! # => #<CSV::Table mode:col row_count:4> return_value = table[1] = new_col return_value.equal?(new_col) # => true # Returned the column table[1] # => [3, 4, 5] # The rows, as revised: table.by_row! # => #<CSV::Table mode:row row_count:4> table[0].to_h # => {"Name"=>"foo", "Value"=>3} table[1].to_h # => {"Name"=>"bar", "Value"=>4} table[2].to_h # => {"Name"=>"baz", "Value"=>5} table.by_col! # => #<CSV::Table mode:col row_count:4>
If there are too few values, fills with nil
values:
table[1] = [0] table[1] # => [0, nil, nil]
If there are too many values, ignores the extra values:
table[1] = [0, 1, 2, 3, 4] table[1] # => [0, 1, 2]
If a single value is given, replaces all fields in the column with that value:
table[1] = 'bat' table[1] # => ["bat", "bat", "bat"]
- Set a Column by Its String Header
-
Form:
table[header] = field_or_array_of_fields
,header
a String header,field_or_array_of_fields
a field value or an Array of String fields. -
Access mode:
:col
or:col_or_row
. -
Return value:
field_or_array_of_fields
.
If the column exists, it is replaced:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) new_col = [3, 4, 5] table.by_col! # => #<CSV::Table mode:col row_count:4> return_value = table['Value'] = new_col return_value.equal?(new_col) # => true # Returned the column table['Value'] # => [3, 4, 5] # The rows, as revised: table.by_row! # => #<CSV::Table mode:row row_count:4> table[0].to_h # => {"Name"=>"foo", "Value"=>3} table[1].to_h # => {"Name"=>"bar", "Value"=>4} table[2].to_h # => {"Name"=>"baz", "Value"=>5} table.by_col! # => #<CSV::Table mode:col row_count:4>
If there are too few values, fills with nil
values:
table['Value'] = [0] table['Value'] # => [0, nil, nil]
If there are too many values, ignores the extra values:
table['Value'] = [0, 1, 2, 3, 4] table['Value'] # => [0, 1, 2]
If the column does not exist, extends the table by adding columns:
table['Note'] = ['x', 'y', 'z'] table['Note'] # => ["x", "y", "z"] # The rows, as revised: table.by_row! table[0].to_h # => {"Name"=>"foo", "Value"=>0, "Note"=>"x"} table[1].to_h # => {"Name"=>"bar", "Value"=>1, "Note"=>"y"} table[2].to_h # => {"Name"=>"baz", "Value"=>2, "Note"=>"z"} table.by_col!
If a single value is given, replaces all fields in the column with that value:
table['Value'] = 'bat' table['Value'] # => ["bat", "bat", "bat"]
# File lib/csv/table.rb, line 649 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 unless index_or_header.is_a? Integer index = @headers.index(index_or_header) || @headers.size @headers[index] = index_or_header end 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
Returns a duplicate of self
, in column mode (see Column Mode):
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.mode # => :col_or_row dup_table = table.by_col dup_table.mode # => :col dup_table.equal?(table) # => false # It's a dup
This may be used to chain method calls without changing the mode (but also will affect performance and memory usage):
dup_table.by_col['Name']
Also note that changes to the duplicate table will not affect the original.
# File lib/csv/table.rb, line 242 def by_col self.class.new(@table.dup).by_col! end
Sets the mode for self
to column mode (see Column Mode); returns self
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.mode # => :col_or_row table1 = table.by_col! table.mode # => :col table1.equal?(table) # => true # Returned self
# File lib/csv/table.rb, line 257 def by_col! @mode = :col self end
Returns a duplicate of self
, in mixed mode (see Mixed Mode):
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true).by_col! table.mode # => :col dup_table = table.by_col_or_row dup_table.mode # => :col_or_row dup_table.equal?(table) # => false # It's a dup
This may be used to chain method calls without changing the mode (but also will affect performance and memory usage):
dup_table.by_col_or_row['Name']
Also note that changes to the duplicate table will not affect the original.
# File lib/csv/table.rb, line 280 def by_col_or_row self.class.new(@table.dup).by_col_or_row! end
Sets the mode for self
to mixed mode (see Mixed Mode); returns self
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true).by_col! table.mode # => :col table1 = table.by_col_or_row! table.mode # => :col_or_row table1.equal?(table) # => true # Returned self
# File lib/csv/table.rb, line 295 def by_col_or_row! @mode = :col_or_row self end
Returns a duplicate of self
, in row mode (see Row Mode):
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.mode # => :col_or_row dup_table = table.by_row dup_table.mode # => :row dup_table.equal?(table) # => false # It's a dup
This may be used to chain method calls without changing the mode (but also will affect performance and memory usage):
dup_table.by_row[1]
Also note that changes to the duplicate table will not affect the original.
# File lib/csv/table.rb, line 318 def by_row self.class.new(@table.dup).by_row! end
Sets the mode for self
to row mode (see Row Mode); returns self
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.mode # => :col_or_row table1 = table.by_row! table.mode # => :row table1.equal?(table) # => true # Returned self
# File lib/csv/table.rb, line 333 def by_row! @mode = :row self end
If the access mode is :row
or :col_or_row
, and each argument is either an Integer or a Range, returns deleted rows. Otherwise, returns deleted columns data.
In either case, the returned values are in the order specified by the arguments. Arguments may be repeated.
Returns rows as an Array of CSV::Row objects.
One index:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) deleted_values = table.delete(0) deleted_values # => [#<CSV::Row "Name":"foo" "Value":"0">]
Two indexes:
table = CSV.parse(source, headers: true) deleted_values = table.delete(2, 0) deleted_values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
Returns columns data as column Arrays.
One header:
table = CSV.parse(source, headers: true) deleted_values = table.delete('Name') deleted_values # => ["foo", "bar", "baz"]
Two headers:
table = CSV.parse(source, headers: true) deleted_values = table.delete('Value', 'Name') deleted_values # => [["0", "1", "2"], ["foo", "bar", "baz"]]
# File lib/csv/table.rb, line 834 def delete(*indexes_or_headers) if indexes_or_headers.empty? raise ArgumentError, "wrong number of arguments (given 0, expected 1+)" end deleted_values = indexes_or_headers.map do |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 if index_or_header.is_a? Integer @headers.delete_at(index_or_header) else @headers.delete(index_or_header) end @table.map { |row| row.delete(index_or_header).last } end end if indexes_or_headers.size == 1 deleted_values[0] else deleted_values end end
Removes rows or columns for which the block returns a truthy value; returns self
.
Removes rows when the access mode is :row
or :col_or_row
; calls the block with each CSV::Row object:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_row! # => #<CSV::Table mode:row row_count:4> table.size # => 3 table.delete_if {|row| row['Name'].start_with?('b') } table.size # => 1
Removes columns when the access mode is :col
; calls the block with each column as a 2-element array containing the header and an Array of column fields:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_col! # => #<CSV::Table mode:col row_count:4> table.headers.size # => 2 table.delete_if {|column_data| column_data[1].include?('2') } table.headers.size # => 1
Returns a new Enumerator if no block is given:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.delete_if # => #<Enumerator: #<CSV::Table mode:col_or_row row_count:4>:delete_if>
# File lib/csv/table.rb, line 887 def delete_if(&block) return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size } unless block_given? if @mode == :row or @mode == :col_or_row # by index @table.delete_if(&block) else # by header headers.each do |header| delete(header) if yield([header, self[header]]) end end self # for chaining end
Extracts the nested value specified by the sequence of index
or header
objects by calling dig at each step, returning nil if any intermediate step is nil.
# File lib/csv/table.rb, line 1021 def dig(index_or_header, *index_or_headers) value = self[index_or_header] if value.nil? nil elsif index_or_headers.empty? value else unless value.respond_to?(:dig) raise TypeError, "#{value.class} does not have \#dig method" end value.dig(*index_or_headers) end end
Calls the block with each row or column; returns self
.
When the access mode is :row
or :col_or_row
, calls the block with each CSV::Row object:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.by_row! # => #<CSV::Table mode:row row_count:4> table.each {|row| p row }
Output:
#<CSV::Row "Name":"foo" "Value":"0"> #<CSV::Row "Name":"bar" "Value":"1"> #<CSV::Row "Name":"baz" "Value":"2">
When the access mode is :col
, calls the block with each column as a 2-element array containing the header and an Array of column fields:
table.by_col! # => #<CSV::Table mode:col row_count:4> table.each {|column_data| p column_data }
Output:
["Name", ["foo", "bar", "baz"]] ["Value", ["0", "1", "2"]]
Returns a new Enumerator if no block is given:
table.each # => #<Enumerator: #<CSV::Table mode:col row_count:4>:each>
# File lib/csv/table.rb, line 930 def each(&block) return enum_for(__method__) { @mode == :col ? headers.size : size } unless block_given? if @mode == :col headers.each.with_index do |header, i| yield([header, @table.map {|row| row[header, i]}]) end else @table.each(&block) end self # for chaining end
Returns a new Array containing the String headers for the table.
If the table is not empty, returns the headers from the first row:
rows = [ CSV::Row.new(['Foo', 'Bar'], []), CSV::Row.new(['FOO', 'BAR'], []), CSV::Row.new(['foo', 'bar'], []), ] table = CSV::Table.new(rows) table.headers # => ["Foo", "Bar"] table.delete(0) table.headers # => ["FOO", "BAR"] table.delete(0) table.headers # => ["foo", "bar"]
If the table is empty, returns a copy of the headers in the table itself:
table.delete(0) table.headers # => ["Foo", "Bar"]
# File lib/csv/table.rb, line 360 def headers if @table.empty? @headers.dup else @table.first.headers end end
Returns a US-ASCII
-encoded String showing table:
-
Class:
CSV::Table
. -
Access mode:
:row
,:col
, or:col_or_row
. -
Size:
Row
count, including the header row.
Example:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.inspect # => "#<CSV::Table mode:col_or_row row_count:4>\nName,Value\nfoo,0\nbar,1\nbaz,2\n"
# File lib/csv/table.rb, line 1048 def inspect inspected = +"#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>" summary = to_csv(limit: 5) inspected << "\n" << summary if summary.encoding.ascii_compatible? inspected end
A shortcut for appending multiple rows. Equivalent to:
rows.each {|row| self << row }
Each argument may be either a CSV::Row object or an Array:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) rows = [ CSV::Row.new(table.headers, ['bat', 3]), ['bam', 4] ] table.push(*rows) table[3..4] # => [#<CSV::Row "Name":"bat" "Value":3>, #<CSV::Row "Name":"bam" "Value":4>]
# File lib/csv/table.rb, line 788 def push(*rows) rows.each { |row| self << row } self # for chaining end
Returns the table as an Array of Arrays; the headers are in the first row:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.to_a # => [["Name", "Value"], ["foo", "0"], ["bar", "1"], ["baz", "2"]]
# File lib/csv/table.rb, line 978 def to_a array = [headers] @table.each do |row| array.push(row.fields) unless row.header_row? end array end
Returns the table as CSV string. See Options for Generating.
Defaults option write_headers
to true
:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.to_csv # => "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
Omits the headers if option write_headers
is given as false
(see Option write_headers):
table.to_csv(write_headers: false) # => "foo,0\nbar,1\nbaz,2\n"
Limit rows if option limit
is given like 2
:
table.to_csv(limit: 2) # => "Name,Value\nfoo,0\nbar,1\n"
# File lib/csv/table.rb, line 1004 def to_csv(write_headers: true, limit: nil, **options) array = write_headers ? [headers.to_csv(**options)] : [] limit ||= @table.size limit = @table.size + 1 + limit if limit < 0 limit = 0 if limit < 0 @table.first(limit).each do |row| array.push(row.fields.to_csv(**options)) unless row.header_row? end array.join("") end
If the access mode is :row
or :col_or_row
, and each argument is either an Integer or a Range, returns rows. Otherwise, returns columns data.
In either case, the returned values are in the order specified by the arguments. Arguments may be repeated.
Returns rows as an Array of CSV::Row objects.
No argument:
source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n" table = CSV.parse(source, headers: true) table.values_at # => []
One index:
values = table.values_at(0) values # => [#<CSV::Row "Name":"foo" "Value":"0">]
Two indexes:
values = table.values_at(2, 0) values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
One Range:
values = table.values_at(1..2) values # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
Ranges and indexes:
values = table.values_at(0..1, 1..2, 0, 2) pp values
Output:
[#<CSV::Row "Name":"foo" "Value":"0">, #<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">, #<CSV::Row "Name":"baz" "Value":"2">]
Returns columns data as row Arrays, each consisting of the specified columns data for that row:
values = table.values_at('Name') values # => [["foo"], ["bar"], ["baz"]] values = table.values_at('Value', 'Name') values # => [["0", "foo"], ["1", "bar"], ["2", "baz"]]
# File lib/csv/table.rb, line 734 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