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
-
.new(array_of_rows) ⇒ Table
constructor
Construct a new
Table
fromarray_of_rows
, which are expected to be Row objects.
Instance Attribute Summary
Instance Method Summary
-
#<<(row_or_array)
Adds a new row to the bottom end of this table.
-
#==(other)
Returns
true
if all rows of this table ==()other
's rows. -
#[](index_or_header)
In the default mixed mode, this method returns rows for index access and columns for header access.
-
#[]=(index_or_header, value)
In the default mixed mode, this method assigns rows for index access and columns for header access.
-
#by_col
Returns a duplicate table object, in column mode.
-
#by_col!
Switches the mode of this table to column mode.
-
#by_col_or_row
Returns a duplicate table object, in mixed mode.
-
#by_col_or_row!
Switches the mode of this table to mixed mode.
-
#by_row
Returns a duplicate table object, in row mode.
-
#by_row!
Switches the mode of this table to row mode.
-
#delete(index_or_header)
Removes and returns the indicated column or row.
-
#delete_if(&block)
Removes any column or row for which the block returns
true
. -
#each(&block)
In the default mixed mode or row mode, iteration is the standard row major walking of rows.
-
#headers
Returns the headers for the first row of this table (assumed to match all other rows).
-
#inspect
Shows the mode and size of this table in a US-ASCII ::String.
-
#push(*rows)
A shortcut for appending multiple rows.
-
#to_a
Returns the table as an ::Array of Arrays.
-
#to_csv(options = Hash.new)
(also: #to_s)
Returns the table as a complete ::CSV String.
-
#to_s(options = Hash.new)
Alias for #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.
Constructor Details
.new(array_of_rows) ⇒ Table
# File 'lib/csv.rb', line 582
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.
# File 'lib/csv.rb', line 588
attr_reader :mode
#table (readonly, protected)
Internal data format used to compare equality.
# File 'lib/csv.rb', line 591
attr_reader :table
Instance Method Details
#<<(row_or_array)
#==(other)
Returns true
if all rows of this table ==() other
's rows.
# File 'lib/csv.rb', line 859
def ==(other) @table == other.table end
#[](index_or_header)
# File 'lib/csv.rb', line 696
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.
# File 'lib/csv.rb', line 721
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.
#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.
# File 'lib/csv.rb', line 618
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.
# File 'lib/csv.rb', line 633
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.
# File 'lib/csv.rb', line 645
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.
#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.
# File 'lib/csv.rb', line 670
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.
# File 'lib/csv.rb', line 808
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.
# File 'lib/csv.rb', line 825
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)
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.
# File 'lib/csv.rb', line 848
def each(&block) 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.
#inspect
Shows the mode and size of this table in a US-ASCII ::String.
# File 'lib/csv.rb', line 897
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.
# File 'lib/csv.rb', line 797
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.
# File 'lib/csv.rb', line 867
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) 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
.
# File 'lib/csv.rb', line 884
def to_csv( = Hash.new) wh = .fetch(:write_headers, true) @table.inject(wh ? [headers.to_csv( )] : [ ]) do |rows, row| if row.header_row? rows else rows + [row.fields.to_csv( )] end end.join('') end
#to_s(options = Hash.new)
Alias for #to_csv.
# File 'lib/csv.rb', line 894
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.
# File 'lib/csv.rb', line 759
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