# class CSV::Table

A CSV::Table is a two-dimensional data structure for representing CSV documents. Tables allow you to work with the data by row or column, manipulate the data, and even convert the results back to CSV, if needed.

All tables returned by CSV will be constructed from this class, if header row processing is activated.

### Attributes

mode[R]

The current access mode for indexing and iteration.

table[R]

Internal data format used to compare equality.

### Public Class Methods

new(array_of_rows) click to toggle source

Construct a new CSV::Table from `array_of_rows`, which are expected to be CSV::Row objects. All rows are assumed to have the same headers.

A CSV::Table object supports the following Array methods through delegation:

- empty?()

- length()

- size()

    # File lib/csv.rb, line 587
    def initialize(array_of_rows)
      @table = array_of_rows
      @mode  = :col_or_row
    end

### Public Instance Methods

<<(row_or_array) click to toggle source

Adds a new row to the bottom end of this table. You can provide an Array, which will be converted to a CSV::Row (inheriting the table's headers()), or a CSV::Row.

This method returns the table for chaining.

    # File lib/csv.rb, line 785
    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) click to toggle source

Returns `true` if all rows of this table ==() `other`'s rows.

    # File lib/csv.rb, line 871
    def ==(other)
      return @table == other.table if other.is_a? CSV::Table
      @table == other
    end

[](index_or_header) click to toggle source

In the default mixed mode, this method returns rows for index access and columns for header access. You can force the index association by first calling #by_col!() or #by_row!().

Columns are returned as an Array of values. Altering that Array has no effect on the table.

    # File lib/csv.rb, line 701
    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

[]=(index_or_header, value) click to toggle source

In the default mixed mode, this method assigns rows for index access and columns for header access. You can force the index association by first calling #by_col!() or #by_row!().

Rows may be set to an Array of values (which will inherit the table's headers()) or a CSV::Row.

Columns may be set to a single value, which is copied to each row of the column, or an Array of values. Arrays of values are assigned to rows top to bottom in row major order. Excess values are ignored and if the Array does not have a value for each row the extra rows will receive a `nil`.

Assigning to an existing column or row clobbers the data. Assigning to new columns creates them at the right end of the table.

    # File lib/csv.rb, line 726
    def []=(index_or_header, value)
      if @mode == :row or  # by index
         (@mode == :col_or_row and index_or_header.is_a? Integer)
        if value.is_a? Array
          @table[index_or_header] = Row.new(headers, value)
        else
          @table[index_or_header] = value
        end
      else                 # set column
        if value.is_a? Array  # multiple values
          @table.each_with_index do |row, i|
            if row.header_row?
              row[index_or_header] = index_or_header
            else
              row[index_or_header] = value[i]
            end
          end
        else                  # repeated value
          @table.each do |row|
            if row.header_row?
              row[index_or_header] = index_or_header
            else
              row[index_or_header] = value
            end
          end
        end
      end
    end

by_col() click to toggle source

Returns a duplicate table object, in column mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.

This method returns the duplicate table for chaining. Don't chain destructive methods (like []=()) this way though, since you are working with a duplicate.

    # File lib/csv.rb, line 613
    def by_col
      self.class.new(@table.dup).by_col!
    end

by_col!() click to toggle source

Switches the mode of this table to column mode. All calls to indexing and iteration methods will work with columns until the mode is changed again.

This method returns the table and is safe to chain.

    # File lib/csv.rb, line 623
    def by_col!
      @mode = :col

      self
    end

by_col_or_row() click to toggle source

Returns a duplicate table object, in mixed mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.

This method returns the duplicate table for chaining. Don't chain destructive methods (like []=()) this way though, since you are working with a duplicate.

    # File lib/csv.rb, line 638
    def by_col_or_row
      self.class.new(@table.dup).by_col_or_row!
    end

by_col_or_row!() click to toggle source

Switches the mode of this table to mixed mode. All calls to indexing and iteration methods will use the default intelligent indexing system until the mode is changed again. In mixed mode an index is assumed to be a row reference while anything else is assumed to be column access by headers.

This method returns the table and is safe to chain.

    # File lib/csv.rb, line 650
    def by_col_or_row!
      @mode = :col_or_row

      self
    end

by_row() click to toggle source

Returns a duplicate table object, in row mode. This is handy for chaining in a single call without changing the table mode, but be aware that this method can consume a fair amount of memory for bigger data sets.

This method returns the duplicate table for chaining. Don't chain destructive methods (like []=()) this way though, since you are working with a duplicate.

    # File lib/csv.rb, line 665
    def by_row
      self.class.new(@table.dup).by_row!
    end

by_row!() click to toggle source

Switches the mode of this table to row mode. All calls to indexing and iteration methods will work with rows until the mode is changed again.

This method returns the table and is safe to chain.

    # File lib/csv.rb, line 675
    def by_row!
      @mode = :row

      self
    end

delete(index_or_header) click to toggle source

Removes and returns the indicated column or row. In the default mixed mode indices refer to rows and everything else is assumed to be a column header. Use #by_col!() or #by_row!() to force the lookup.

    # File lib/csv.rb, line 813
    def delete(index_or_header)
      if @mode == :row or  # by index
         (@mode == :col_or_row and index_or_header.is_a? Integer)
        @table.delete_at(index_or_header)
      else                 # by header
        @table.map { |row| row.delete(index_or_header).last }
      end
    end

delete_if(&block) click to toggle source

Removes any column or row for which the block returns `true`. In the default mixed mode or row mode, iteration is the standard row major walking of rows. In column mode, iteration will `yield` two element tuples containing the column name and an Array of values for that column.

This method returns the table for chaining.

If no block is given, an Enumerator is returned.

    # File lib/csv.rb, line 832
    def delete_if(&block)
      block or return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size }

      if @mode == :row or @mode == :col_or_row  # by index
        @table.delete_if(&block)
      else                                      # by header
        deleted = []
        headers.each do |header|
          deleted << delete(header) if block[[header, self[header]]]
        end
      end

      self  # for chaining
    end

each(&block) click to toggle source

In the default mixed mode or row mode, iteration is the standard row major walking of rows. In column mode, iteration will `yield` two element tuples containing the column name and an Array of values for that column.

This method returns the table for chaining.

If no block is given, an Enumerator is returned.

    # File lib/csv.rb, line 858
    def each(&block)
      block or return enum_for(__method__) { @mode == :col ? headers.size : size }

      if @mode == :col
        headers.each { |header| block[[header, self[header]]] }
      else
        @table.each(&block)
      end

      self  # for chaining
    end

headers() click to toggle source

Returns the headers for the first row of this table (assumed to match all other rows). An empty Array is returned for empty tables.

    # File lib/csv.rb, line 685
    def headers
      if @table.empty?
        Array.new
      else
        @table.first.headers
      end
    end

inspect() click to toggle source

Shows the mode and size of this table in a US-ASCII String.

    # File lib/csv.rb, line 905
    def inspect
      "#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>".encode("US-ASCII")
    end

push(*rows) click to toggle source

A shortcut for appending multiple rows. Equivalent to:

    rows.each { |row| self << row }

This method returns the table for chaining.

    # File lib/csv.rb, line 802
    def push(*rows)
      rows.each { |row| self << row }

      self  # for chaining
    end

to_a() click to toggle source

Returns the table as an Array of Arrays. Headers will be the first row, then all of the field rows will follow.

    # File lib/csv.rb, line 880
    def to_a
      array = [headers]
      @table.each do |row|
        array.push(row.fields) unless row.header_row?
      end
      return array
    end

to_csv(write_headers: true, **options) click to toggle source

Returns the table as a complete CSV String. Headers will be listed first, then all of the field rows.

This method assumes you want the #headers, unless you explicitly pass `:write_headers => false`.

    # File lib/csv.rb, line 895
    def to_csv(write_headers: true, **options)
      array = write_headers ? [headers.to_csv(options)] : []
      @table.each do |row|
        array.push(row.fields.to_csv(options)) unless row.header_row?
      end
      return array.join('')
    end

Also aliased as: to_s
to_s(write_headers: true, **options)
Alias for: to_csv
values_at(*indices_or_headers) click to toggle source

The mixed mode default is to treat a list of indices as row access, returning the rows indicated. Anything else is considered columnar access. For columnar access, the return set has an Array for each row with the values indicated by the headers in each Array. You can force column or row mode using #by_col!() or #by_row!().

You cannot mix column and row access.

    # File lib/csv.rb, line 764
    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