Class: CSV::Table
- Inherits:
-
Object
- Object
- CSV::Table
- 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
-
#mode ⇒ Object
readonly
The current access mode for indexing and iteration.
Instance Method Summary collapse
-
#<<(row_or_array) ⇒ Object
Adds a new row to the bottom end of this table.
-
#==(other) ⇒ Object
Returns
true
if all rows of this table ==()other
‘s rows. -
#[](index_or_header) ⇒ Object
In the default mixed mode, this method returns rows for index access and columns for header access.
-
#[]=(index_or_header, value) ⇒ Object
In the default mixed mode, this method assigns rows for index access and columns for header access.
-
#by_col ⇒ Object
Returns a duplicate table object, in column mode.
-
#by_col! ⇒ Object
Switches the mode of this table to column mode.
-
#by_col_or_row ⇒ Object
Returns a duplicate table object, in mixed mode.
-
#by_col_or_row! ⇒ Object
Switches the mode of this table to mixed mode.
-
#by_row ⇒ Object
Returns a duplicate table object, in row mode.
-
#by_row! ⇒ Object
Switches the mode of this table to row mode.
-
#delete(index_or_header) ⇒ Object
Removes and returns the indicated column or row.
-
#delete_if(&block) ⇒ Object
Removes any column or row for which the block returns
true
. -
#each(&block) ⇒ Object
In the default mixed mode or row mode, iteration is the standard row major walking of rows.
-
#headers ⇒ Object
Returns the headers for the first row of this table (assumed to match all other rows).
-
#initialize(array_of_rows) ⇒ Table
constructor
Construct a new CSV::Table from
array_of_rows
, which are expected to be CSV::Row objects. -
#inspect ⇒ Object
Shows the mode and size of this table in a US-ASCII String.
-
#push(*rows) ⇒ Object
A shortcut for appending multiple rows.
-
#to_a ⇒ Object
Returns the table as an Array of Arrays.
-
#to_csv(write_headers: true, **options) ⇒ Object
(also: #to_s)
Returns the table as a complete CSV String.
-
#values_at(*indices_or_headers) ⇒ Object
The mixed mode default is to treat a list of indices as row access, returning the rows indicated.
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()
589 590 591 592 |
# File 'lib/csv.rb', line 589 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.
595 596 597 |
# File 'lib/csv.rb', line 595 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.
787 788 789 790 791 792 793 794 795 |
# 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) ⇒ Object
Returns true
if all rows of this table ==() other
‘s rows.
873 874 875 876 |
# File 'lib/csv.rb', line 873 def ==(other) return @table == other.table if other.is_a? CSV::Table @table == other 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.
703 704 705 706 707 708 709 710 |
# 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) ⇒ 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.
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 |
# 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 ⇒ 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.
615 616 617 |
# File 'lib/csv.rb', line 615 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.
625 626 627 628 629 |
# File 'lib/csv.rb', line 625 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.
640 641 642 |
# 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! ⇒ 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.
652 653 654 655 656 |
# File 'lib/csv.rb', line 652 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.
667 668 669 |
# File 'lib/csv.rb', line 667 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.
677 678 679 680 681 |
# File 'lib/csv.rb', line 677 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.
815 816 817 818 819 820 821 822 |
# 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) ⇒ 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, 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.
834 835 836 837 838 839 840 841 842 843 844 845 846 847 |
# 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) ⇒ Object
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.
860 861 862 863 864 865 866 867 868 869 870 |
# 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 ⇒ 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.
687 688 689 690 691 692 693 |
# File 'lib/csv.rb', line 687 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.
907 908 909 |
# File 'lib/csv.rb', line 907 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.
804 805 806 807 808 |
# File 'lib/csv.rb', line 804 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.
882 883 884 885 886 887 888 |
# 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) ⇒ 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
.
897 898 899 900 901 902 903 |
# File 'lib/csv.rb', line 897 def to_csv(write_headers: true, **) array = write_headers ? [headers.to_csv()] : [] @table.each do |row| array.push(row.fields.to_csv()) unless row.header_row? end return array.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.
766 767 768 769 770 771 772 773 774 775 776 777 778 |
# 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 |