class CSV::Table - RDoc Documentation

# 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:

- `[]`

- `[]=`

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

### Attributes

mode[R]

The current access mode for indexing and iteration.

table[R]

Internal data format used to compare equality.

### Public Class Methods

CSV::Table.new(array_of_rows, headers = nil) → csv_table click to toggle source

Returns a new CSV::Table object.

- Argument `array_of_rows` must be an Array of `CSV::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

table << row_or_array → self click to toggle source

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

table == other_table → true or false click to toggle source

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 966
    def ==(other)
      return @table == other.table if other.is_a? CSV::Table
      @table == other
    end

table[n] → row or column_data click to toggle source
table[range] → array_of_rows or array_of_column_data
table[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]

    # 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

table[n] = row → row click to toggle source
table[n] = field_or_array_of_fields → field_or_array_of_fields
table[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"]

    # 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_dup click to toggle source

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

by_col! → self click to toggle source

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

by_col_or_row → table_dup click to toggle source

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

by_col_or_row! → self click to toggle source

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

by_row → table_dup click to toggle source

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

by_row! → self click to toggle source

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

delete(*indexes) → deleted_values click to toggle source
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"]]

    # 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 click to toggle source

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
        deleted = []
        headers.each do |header|
          deleted << delete(header) if yield([header, self[header]])
        end
      end

      self # for chaining
    end

dig(index_or_header, *index_or_headers) click to toggle source

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 1022
    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 click to toggle source

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 931
    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 click to toggle source

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

inspect → string click to toggle source

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 1049
    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 click to toggle source

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

to_a → array_of_arrays click to toggle source

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 979
    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 click to toggle source

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

Also aliased as: to_s
to_s(write_headers: true, limit: nil, **options)
Alias for: to_csv
values_at(*indexes) → array_of_rows click to toggle source
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"]]

    # 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