Class: CSV::Table

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/csv.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(array_of_rows) ⇒ Table

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()



539
540
541
542
 
# File 'lib/csv.rb', line 539

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

Instance Attribute Details

#mode ⇒ Object (readonly)

The current access mode for indexing and iteration.



545
546
547
 
# File 'lib/csv.rb', line 545

def mode
  @mode
end

Instance Method Details

#<<(row_or_array) ⇒ Object

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.



737
738
739
740
741
742
743
744
745
 
# File 'lib/csv.rb', line 737

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) ⇒ Object

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



816
817
818
 
# File 'lib/csv.rb', line 816

def ==(other)
  @table == other.table
end

#[](index_or_header) ⇒ Object

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.



653
654
655
656
657
658
659
660
 
# File 'lib/csv.rb', line 653

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

#[]=(index_or_header, value) ⇒ Object

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.



678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
 
# File 'lib/csv.rb', line 678

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 ⇒ Object

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.



565
566
567
 
# File 'lib/csv.rb', line 565

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

#by_col! ⇒ Object

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.



575
576
577
578
579
 
# File 'lib/csv.rb', line 575

def by_col!
  @mode = :col

  self
end

#by_col_or_row ⇒ Object

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.



590
591
592
 
# File 'lib/csv.rb', line 590

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

#by_col_or_row! ⇒ Object

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.



602
603
604
605
606
 
# File 'lib/csv.rb', line 602

def by_col_or_row!
  @mode = :col_or_row

  self
end

#by_row ⇒ Object

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.



617
618
619
 
# File 'lib/csv.rb', line 617

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

#by_row! ⇒ Object

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.



627
628
629
630
631
 
# File 'lib/csv.rb', line 627

def by_row!
  @mode = :row

  self
end

#delete(index_or_header) ⇒ Object

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.



765
766
767
768
769
770
771
772
 
# File 'lib/csv.rb', line 765

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) ⇒ Object

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, interation will yield two element tuples containing the column name and an Array of values for that column.

This method returns the table for chaining.



782
783
784
785
786
787
788
789
790
791
792
793
794
 
# File 'lib/csv.rb', line 782

def delete_if(&block)
  if @mode == :row or @mode == :col_or_row  # by index
    @table.delete_if(&block)
  else                                      # by header
    to_delete = Array.new
    headers.each_with_index do |header, i|
      to_delete << header if block[[header, self[header]]]
    end
    to_delete.map { |header| delete(header) }
  end

  self  # for chaining
end

#each(&block) ⇒ Object

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

This method returns the table for chaining.



805
806
807
808
809
810
811
812
813
 
# File 'lib/csv.rb', line 805

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

  self  # for chaining
end

#headers ⇒ Object

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



637
638
639
640
641
642
643
 
# File 'lib/csv.rb', line 637

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

#inspect ⇒ Object

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



854
855
856
 
# File 'lib/csv.rb', line 854

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

#push(*rows) ⇒ Object

A shortcut for appending multiple rows. Equivalent to:

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

This method returns the table for chaining.



754
755
756
757
758
 
# File 'lib/csv.rb', line 754

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

  self  # for chaining
end

#to_a ⇒ Object

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



824
825
826
827
828
829
830
831
832
 
# File 'lib/csv.rb', line 824

def to_a
  @table.inject([headers]) do |array, row|
    if row.header_row?
      array
    else
      array + [row.fields]
    end
  end
end

#to_csv(options = Hash.new) ⇒ Object 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 Table.headers(), unless you explicitly pass :write_headers => false.



841
842
843
844
845
846
847
848
849
850
 
# File 'lib/csv.rb', line 841

def to_csv(options = Hash.new)
  wh = options.fetch(:write_headers, true)
  @table.inject(wh ? [headers.to_csv(options)] : [ ]) do |rows, row|
    if row.header_row?
      rows
    else
      rows + [row.fields.to_csv(options)]
    end
  end.join('')
end

#values_at(*indices_or_headers) ⇒ Object

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.



716
717
718
719
720
721
722
723
724
725
726
727
728
 
# File 'lib/csv.rb', line 716

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