Class Ruport::Data::Table
In: lib/ruport/data/table.rb
Parent: Object

Overview

This class is one of the core classes for building and working with data in Ruport. The idea is to get your data into a standard form, regardless of its source (a database, manual arrays, ActiveRecord, CSVs, etc.).

Table is intended to be used as the data store for structured, tabular data.

Once your data is in a Table object, it can be manipulated to suit your needs, then used to build a report.

Methods

Included Modules

Enumerable Ruport::Renderer::Hooks

Classes and Modules

Module Ruport::Data::Table::FromCSV

External Aliases

dup -> clone
  NOTE: does not respect tainted status

Attributes

column_names  [R]  This Table‘s column names
data  [R]  This Table‘s data

Public Class methods

Creates a new table based on the supplied options.

Valid options:

:data:An Array of Arrays representing the records in this Table.
:column_names:An Array containing the column names for this Table.
:filters:A proc or array of procs that set up conditions to filter the data being added to the table.
:transforms:A proc or array of procs that perform transformations on the data being added to the table.
:record_class:Specify the class of the table‘s records.

Example:

  table = Table.new :data => [[1,2,3], [3,4,5]],
                    :column_names => %w[a b c]

Public Instance methods

Used to merge two Tables by rows. Raises an ArgumentError if the Tables don‘t have identical columns.

Example:

  inky = Table.new :data => [[1,2], [3,4]],
                   :column_names => %w[a b]

  blinky = Table.new :data => [[5,6]],
                     :column_names => %w[a b]

  sue = inky + blinky
  sue.data #=> [[1,2],[3,4],[5,6]]

Used to add extra data to the Table. row can be an Array, Hash or Record. It also can be anything that implements a meaningful to_hash or to_ary.

Example:

  data = Table.new :data => [[1,2], [3,4]],
                   :column_names => %w[a b]
  data << [8,9]
  data << { :a => 4, :b => 5}
  data << Record.new [5,6], :attributes => %w[a b]
==(other)

Alias for eql?

Adds an extra column to the Table.

Available Options:

:default:The default value to use for the column in existing rows. Set to nil if not specified.
:position:Inserts the column at the indicated position number.
:before:Inserts the new column before the column indicated (by name).
:after:Inserts the new column after the column indicated (by name).

If a block is provided, it will be used to build up the column.

Example:

  data = Table("a","b") { |t| t << [1,2] << [3,4] }

  # basic usage, column full of 1's
  data.add_column 'new_column', :default => 1

  # new empty column before new_column
  data.add_column 'new_col2', :before => 'new_column'

  # new column placed just after column a
  data.add_column 'new_col3', :position => 1

  # new column built via a block, added at the end of the table
  data.add_column("new_col4") { |r| r.a + r.b }

Add multiple extra columns to the Table. See add_column for a list of available options.

Example:

  data = Table("a","b") { |t| t << [1,2] << [3,4] }

  data.add_columns ['new_column_1','new_column_2'], :default => 1

Returns an array of values for the given column name.

Example:

  table = [[1,2],[3,4],[5,6]].to_table(%w[col1 col2])
  table.column("col1")   #=> [1,3,5]

Sets the column names for this table. new_column_names should be an array listing the names of the columns.

Example:

  table = Table.new :data => [[1,2,3], [3,4,5]],
                    :column_names => %w[a b c]

  table.column_names = %w[e f g]

Compares this Table to another Table and returns true if both the data and column_names are equal.

Example:

  one = Table.new :data => [[1,2], [3,4]],
                  :column_names => %w[a b]

  two = Table.new :data => [[1,2], [3,4]],
                  :column_names => %w[a b]

  one.eql?(two) #=> true

Create a copy of the Table. Records will be copied as well.

Example:

  one = Table.new :data => [[1,2], [3,4]],
                  :column_names => %w[a b]
  two = one.dup

Provides a shortcut for the as() method by converting a call to as(:format_name) into a call to to_format_name

Also converts a call to rows_with_columnname to a call to rows_with(:columnname => args[0]).

Returns the record class constant being used by the table.

Generates a sub table in place, modifying the receiver. See documentation for sub_table.

Removes the given column from the table. May use name or position.

Example:

   table.remove_column(0) #=> removes the first column
   table.remove_column("apple") #=> removes column named apple

Removes multiple columns from the table. May use name or position Will autosplat arrays.

Example: table.remove_columns(‘a’,’b’,’c’) table.remove_columns([0,1])

Renames a column. Will update Record attributes as well.

Example:

  old_values = table.map { |r| r.a }
  table.rename_column("a","zanzibar")
  new_values = table.map { |r| r.zanzibar }
  old_values == new_values #=> true
  table.column_names.include?("a") #=> false

Renames multiple columns. Takes either a hash of "old" => "new" names or two arrays of names %w[old names],%w[new names].

Example:

  table.column_names #=> ["a", "b"]
  table.rename_columns ["a", "b"], ["c", "d"]
  table.column_names #=> ["c", "d"]

  table.column_names #=> ["a", "b"]
  table.rename_columns {"a" => "c", "b" => "d"}
  table.column_names #=> ["c", "d"]

Allows you to change the order of, or reduce the number of columns in a Table.

Example:

  a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
  a.reorder("b","c","a")
  a.column_names #=> ["b","c","a"]

  a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
  a.reorder(1,2,0)
  a.column_names #=> ["b","c","a"]

  a = Table.new :data => [[1,2,3],[4,5,6]], :column_names => %w[a b c]
  a.reorder(0,2)
  a.column_names #=> ["a","c"]

Allows you to specify a new column to replace an existing column in your table via a block.

Example:

>> a = Table(%w[a b c]) { |t| t << [1,2,3] << [4,5,6] } >> a.replace_column("c","c2") { |r| r.c * 2 + r.a }

>> puts a

   +------------+
   | a | b | c2 |
   +------------+
   | 1 | 2 |  7 |
   | 4 | 5 | 16 |
   +------------+

Get an array of records from the Table limited by the criteria specified.

Example:

  table = Table.new :data => [[1,2,3], [1,4,6], [4,5,6]],
                    :column_names => %w[a b c]
  table.rows_with(:a => 1)           #=> [[1,2,3], [1,4,6]]
  table.rows_with(:a => 1, :b => 4)  #=> [[1,4,6]]
  table.rows_with_a(1)               #=> [[1,2,3], [1,4,6]]
  table.rows_with(%w[a b]) {|a,b| [a,b] == [1,4] }  #=> [[1,4,6]]

Calculates sums. If a column name or index is given, it will try to convert each element of that column to an integer or float and add them together.

If a block is given, it yields each Record so that you can do your own calculation.

Example:

  table = [[1,2],[3,4],[5,6]].to_table(%w[col1 col2])
  table.sigma("col1") #=> 9
  table.sigma(0)      #=> 9
  table.sigma { |r| r.col1 + r.col2 } #=> 21
  table.sigma { |r| r.col2 + 1 } #=> 15

Returns a sorted table. If col_names is specified, the block is ignored and the table is sorted by the named columns.

The second argument specifies sorting options. Currently only :order is supported. Default order is ascending, to sort decending use :order => :descending

Example:

  table = [[4, 3], [2, 5], [7, 1]].to_table(%w[col1 col2 ])

  # returns a new table sorted by col1
  table.sort_rows_by {|r| r["col1"]}

  # returns a new table sorted by col1, in descending order
  table.sort_rows_by(nil, :order => :descending) {|r| r["col1"]}

  # returns a new table sorted by col2
  table.sort_rows_by(["col2"])

  # returns a new table sorted by col2, descending order
  table.sort_rows_by("col2", :order => :descending)

  # returns a new table sorted by col1, then col2
  table.sort_rows_by(["col1", "col2"])

  # returns a new table sorted by col1, then col2, in descending order
  table.sort_rows_by(["col1", "col2"], :order => descending)

Same as Table#sort_rows_by, but self modifying. See sort_rows_by for documentation.

Generates a sub table

Examples:

  table = [[1,2,3,4],[5,6,7,8],[9,10,11,12]].to_table(%w[a b c d])

Using column_names and a range:

   sub_table = table.sub_table(%w[a b],1..-1)
   sub_table == [[5,6],[9,10]].to_table(%w[a b]) #=> true

Using just column_names:

   sub_table = table.sub_table(%w[a d])
   sub_table == [[1,4],[5,8],[9,12]].to_table(%w[a d]) #=> true

Using column_names and a block:

   sub_table = table.sub_table(%w[d b]) { |r| r.a < 6 }
   sub_table == [[4,2],[8,6]].to_table(%w[d b]) #=> true

Using a range for row reduction:

   sub_table = table.sub_table(1..-1)
   sub_table == [[5,6,7,8],[9,10,11,12]].to_table(%w[a b c d]) #=> true

Using just a block:

   sub_table = table.sub_table { |r| r.c > 10 }
   sub_table == [[9,10,11,12]].to_table(%w[a b c d]) #=> true
sub_table!(columns=column_names,range=nil,&block)

Alias for reduce

sum(column=nil)

Alias for sigma

Exchanges one column with another.

Example:

  >> a = Table(%w[a b c]) { |t| t << [1,2,3] << [4,5,6] }
  >> puts a
     +-----------+
     | a | b | c |
     +-----------+
     | 1 | 2 | 3 |
     | 4 | 5 | 6 |
     +-----------+
  >> a.swap_column("a","c")
  >> puts a
     +-----------+
     | c | b | a |
     +-----------+
     | 3 | 2 | 1 |
     | 6 | 5 | 4 |
     +-----------+

Convert the Table into a Group using the supplied group name.

  data = Table.new :data => [[1,2], [3,4]],
                   :column_names => %w[a b]
  group = data.to_group("my_group")

Uses Ruport‘s built-in text formatter to render this Table into a String.

Example:

  data = Table.new :data => [[1,2], [3,4]],
                   :column_names => %w[a b]
  puts data.to_s

[Validate]