Class: CSV::Table

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, Forwardable
Instance Chain: self, Enumerable
Inherits:	Object
Defined in:	lib/csv/table.rb

Overview

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:

#[]
#[]=
#delete
#delete_if
#each
#values_at

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"]

Class Method Summary

.new(array_of_rows, headers = nil) ⇒ Table constructor

Returns a new CSV::Table object.

Instance Attribute Summary

#mode readonly

The current access mode for indexing and iteration.
#table readonly protected

Internal data format used to compare equality.

Instance Method Summary

#<<(row_or_array) ⇒ self

If row_or_array is a CSV::Row object, it is appended to the table:
#==(other_table) ⇒ Boolean

Returns true if all each row of self == the corresponding row of other_table, otherwise, false.
#[](n) ⇒ row, column_data

Returns data from the table; does not modify the table.
#[]=(n, row) ⇒ row

Puts data onto the table.
#by_col ⇒ Table

Returns a duplicate of self, in column mode (see Column Mode):
#by_col! ⇒ self

Sets the mode for self to column mode (see Column Mode); returns self:
#by_col_or_row ⇒ Table

Returns a duplicate of self, in mixed mode (see Mixed Mode):
#by_col_or_row! ⇒ self

Sets the mode for self to mixed mode (see Mixed Mode); returns self:
#by_row ⇒ Table

Returns a duplicate of self, in row mode (see Row Mode):
#by_row! ⇒ self

Sets the mode for self to row mode (see Row Mode); returns self:
#delete(*indexes) ⇒ deleted_values

If the access mode is :row or :col_or_row, and each argument is either an Integer or a Range, returns deleted rows.
#delete_if {|row_or_column| ... } ⇒ self

Removes rows or columns for which the block returns a truthy value; returns self.
#dig(index_or_header, *index_or_headers)

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.
#each({|row_or_column| ... ) ⇒ self

Calls the block with each row or column; returns self.
#headers ⇒ array_of_headers

Returns a new Array containing the String headers for the table.
#inspect ⇒ String

Returns a US-ASCII-encoded String showing table: - Class: Table.
#push(*rows_or_arrays) ⇒ self

A shortcut for appending multiple rows.
#to_a ⇒ array_of_arrays

Returns the table as an Array of Arrays; the headers are in the first row:
#to_csv(**options) ⇒ csv_string (also: #to_s)

Returns the table as CSV string.
#to_s(write_headers: true, limit: nil, **options)

Alias for #to_csv.
#values_at(*indexes) ⇒ array_of_rows

If the access mode is :row or :col_or_row, and each argument is either an Integer or a Range, returns rows.

Constructor Details

.new(array_of_rows, headers = nil) ⇒ `Table`

Returns a new CSV::Table object.

Argument array_of_rows must be an Array of 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])

[ GitHub ]

# 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

Instance Attribute Details

#mode (readonly)

The current access mode for indexing and iteration.

[ GitHub ]

# File 'lib/csv/table.rb', line 214


attr_reader :mode

#table (readonly, protected)

Internal data format used to compare equality.

[ GitHub ]

# File 'lib/csv/table.rb', line 217


attr_reader :table

Instance Method Details

#<<(row_or_array) ⇒ `self`

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>

[ GitHub ]

# 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

#==(other_table) ⇒ `Boolean`

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

[ GitHub ]

# File 'lib/csv/table.rb', line 965


def ==(other)
  return @table == other.table if other.is_a? CSV::Table
  @table == other
end

#[](n) ⇒ `row`, `column_data` #[](range) ⇒ `array_of_rows`, `array_of_column_data` #[](header) ⇒ `array_of_column_data`

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 length self.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]

[ GitHub ]

# 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

#[]=(n, row) ⇒ `row` #[]=(n, field_or_array_of_fields) ⇒ `field_or_array_of_fields` #[]=(header, field_or_array_of_fields) ⇒ `field_or_array_of_fields`

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"]

[ GitHub ]

# 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

#by_col ⇒ `Table`

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.

[ GitHub ]

# File 'lib/csv/table.rb', line 242


def by_col
  self.class.new(@table.dup).by_col!
end

#by_col! ⇒ `self`

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

[ GitHub ]

# File 'lib/csv/table.rb', line 257


def by_col!
  @mode = :col

  self
end

#by_col_or_row ⇒ `Table`

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.

[ GitHub ]

# File 'lib/csv/table.rb', line 280


def by_col_or_row
  self.class.new(@table.dup).by_col_or_row!
end

#by_col_or_row! ⇒ `self`

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

[ GitHub ]

# File 'lib/csv/table.rb', line 295


def by_col_or_row!
  @mode = :col_or_row

  self
end

#by_row ⇒ `Table`

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.

[ GitHub ]

# File 'lib/csv/table.rb', line 318


def by_row
  self.class.new(@table.dup).by_row!
end

#by_row! ⇒ `self`

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

[ GitHub ]

# File 'lib/csv/table.rb', line 333


def by_row!
  @mode = :row

  self
end

#delete(indexes) ⇒ `deleted_values` #delete(headers) ⇒ `deleted_values`

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"]]

[ GitHub ]

# 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

#delete_if {|row_or_column| ... } ⇒ `self`

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>

[ GitHub ]

# 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

#dig(index_or_header, *index_or_headers)

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.

[ GitHub ]

# 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

#each({|row_or_column| ... ) ⇒ `self`

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>

[ GitHub ]

# 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

#headers ⇒ `array_of_headers`

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"]

[ GitHub ]

# File 'lib/csv/table.rb', line 360


def headers
  if @table.empty?
    @headers.dup
  else
    @table.first.headers
  end
end

#inspect ⇒ String

Returns a US-ASCII-encoded String showing table:

Class: 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"

[ GitHub ]

# 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

#push(*rows_or_arrays) ⇒ `self`

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>]

[ GitHub ]

# File 'lib/csv/table.rb', line 788


def push(*rows)
  rows.each { |row| self << row }

  self # for chaining
end

#to_a ⇒ `array_of_arrays`

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"]]

[ GitHub ]

# 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

#to_csv(**options) ⇒ `csv_string` Also known as: #to_s

Returns the table as CSV string. See [Options for Generating](../CSV.html#class-CSV-label-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](../CSV.html#class-CSV-label-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"

[ GitHub ]

# 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

#to_s(write_headers: true, limit: nil, **options)

Alias for #to_csv.

[ GitHub ]

# File 'lib/csv/table.rb', line 1015


alias_method :to_s, :to_csv

#values_at(indexes) ⇒ `array_of_rows` #values_at(headers) ⇒ `array_of_columns_data`

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"]]

[ GitHub ]

# 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

Class: CSV::Table

Overview

Instance Methods

Creating a CSV::Table Instance

Headers

Access Modes

Row Mode

Column Mode

Mixed Mode

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(array_of_rows, headers = nil) ⇒ Table

Instance Attribute Details

#mode (readonly)

#table (readonly, protected)

Instance Method Details

#<<(row_or_array) ⇒ self

#==(other_table) ⇒ Boolean

#[](n) ⇒ row, column_data #[](range) ⇒ array_of_rows, array_of_column_data #[](header) ⇒ array_of_column_data

#[]=(n, row) ⇒ row #[]=(n, field_or_array_of_fields) ⇒ field_or_array_of_fields #[]=(header, field_or_array_of_fields) ⇒ field_or_array_of_fields

#by_col ⇒ Table

#by_col! ⇒ self

#by_col_or_row ⇒ Table

#by_col_or_row! ⇒ self

#by_row ⇒ Table

#by_row! ⇒ self

#delete(*indexes) ⇒ deleted_values #delete(*headers) ⇒ deleted_values

#delete_if {|row_or_column| ... } ⇒ self

#dig(index_or_header, *index_or_headers)

#each({|row_or_column| ... ) ⇒ self

#headers ⇒ array_of_headers

#inspect ⇒ String

#push(*rows_or_arrays) ⇒ self

#to_a ⇒ array_of_arrays

#to_csv(**options) ⇒ csv_string Also known as: #to_s

#to_s(write_headers: true, limit: nil, **options)

#values_at(*indexes) ⇒ array_of_rows #values_at(*headers) ⇒ array_of_columns_data

.new(array_of_rows, headers = nil) ⇒ `Table`

#<<(row_or_array) ⇒ `self`

#==(other_table) ⇒ `Boolean`

#[](n) ⇒ `row`, `column_data` #[](range) ⇒ `array_of_rows`, `array_of_column_data` #[](header) ⇒ `array_of_column_data`

#[]=(n, row) ⇒ `row` #[]=(n, field_or_array_of_fields) ⇒ `field_or_array_of_fields` #[]=(header, field_or_array_of_fields) ⇒ `field_or_array_of_fields`

#by_col ⇒ `Table`

#by_col! ⇒ `self`

#by_col_or_row ⇒ `Table`

#by_col_or_row! ⇒ `self`

#by_row ⇒ `Table`

#by_row! ⇒ `self`

#delete(indexes) ⇒ `deleted_values` #delete(headers) ⇒ `deleted_values`

#delete_if {|row_or_column| ... } ⇒ `self`

#each({|row_or_column| ... ) ⇒ `self`

#headers ⇒ `array_of_headers`

#push(*rows_or_arrays) ⇒ `self`

#to_a ⇒ `array_of_arrays`

#to_csv(**options) ⇒ `csv_string` Also known as: #to_s

#values_at(indexes) ⇒ `array_of_rows` #values_at(headers) ⇒ `array_of_columns_data`