123456789_123456789_123456789_123456789_123456789_

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.rb

Overview

A 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.

Class Method Summary

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

Constructor Details

.new(array_of_rows) ⇒ Table

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

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

  • empty?()

  • length()

  • size()

[ GitHub ] 

  


# File 'lib/csv.rb', line 589



def initialize(array_of_rows)
  @table = array_of_rows
  @mode  = :col_or_row
end


  







Instance Attribute Details



  

    #mode   (readonly)
  



  

    

The current access mode for indexing and iteration.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 595



attr_reader :mode


  








  

    #table   (readonly, protected)
  



  

    

Internal data format used to compare equality.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 598



attr_reader :table


  







Instance Method Details



  

    #<<(row_or_array)  
  



  

    

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



This method returns the table for chaining.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 787



def <<(row_or_array)
  if row_or_array.is_a? Array  # append Array
    @table << Row.new(headers, row_or_array)
  else                         # append Row
    @table << row_or_array
  end

  self  # for chaining
end


  








  

    #==(other)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 873



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


  








  

    #[](index_or_header)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 703



def [](index_or_header)
  if @mode == :row or  # by index
     (@mode == :col_or_row and (index_or_header.is_a?(Integer) or index_or_header.is_a?(Range)))
    @table[index_or_header]
  else                 # by header
    @table.map { |row| row[index_or_header] }
  end
end


  








  

    #[]=(index_or_header, value)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 728



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


  








  

    #by_col  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 615



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


  








  

    #by_col!  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 625



def by_col!
  @mode = :col

  self
end


  








  

    #by_col_or_row  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 640



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


  








  

    #by_col_or_row!  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 652



def by_col_or_row!
  @mode = :col_or_row

  self
end


  








  

    #by_row  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 667



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


  








  

    #by_row!  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 677



def by_row!
  @mode = :row

  self
end


  








  

    #delete(index_or_header)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 815



def delete(index_or_header)
  if @mode == :row or  # by index
     (@mode == :col_or_row and index_or_header.is_a? Integer)
    @table.delete_at(index_or_header)
  else                 # by header
    @table.map { |row| row.delete(index_or_header).last }
  end
end


  








  

    #delete_if(&block)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 834



def delete_if(&block)
  block or return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size }

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

  self  # for chaining
end


  








  

    #each(&block)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 860



def each(&block)
  block or return enum_for(__method__) { @mode == :col ? headers.size : size }

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

  self  # for chaining
end


  








  

    #headers  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 687



def headers
  if @table.empty?
    Array.new
  else
    @table.first.headers
  end
end


  








  

    #inspect  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 907



def inspect
  "#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>".encode("US-ASCII")
end


  








  

    #push(*rows)  
  



  

    

A shortcut for appending multiple rows.  Equivalent to:



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



This method returns the table for chaining.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 804



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

  self  # for chaining
end


  








  

    #to_a  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 882



def to_a
  array = [headers]
  @table.each do |row|
    array.push(row.fields) unless row.header_row?
  end
  return array
end


  








  

    #to_csv(write_headers: true, **options)  
    Also known as: #to_s
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 897



def to_csv(write_headers: true, **options)
  array = write_headers ? [headers.to_csv(options)] : []
  @table.each do |row|
    array.push(row.fields.to_csv(options)) unless row.header_row?
  end
  return array.join('')
end


  








  

    #to_s(write_headers: true, **options)  
  



  

    

Alias for #to_csv.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 904



alias_method :to_s, :to_csv


  








  

    #values_at(*indices_or_headers)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/csv.rb', line 766



def values_at(*indices_or_headers)
  if @mode == :row or  # by indices
     ( @mode == :col_or_row and indices_or_headers.all? do |index|
                                  index.is_a?(Integer)         or
                                  ( index.is_a?(Range)         and
                                    index.first.is_a?(Integer) and
                                    index.last.is_a?(Integer) )
                                end )
    @table.values_at(*indices_or_headers)
  else                 # by headers
    @table.map { |row| row.values_at(*indices_or_headers) }
  end
end