Parent

Included Modules

Class Index [+]

Quicksearch

FasterCSV::Table

A FasterCSV::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 FasterCSV will be constructed from this class, if header row processing is activated.

Attributes

mode[R]

The current access mode for indexing and iteration.

table[R]

Internal data format used to compare equality.

Public Class Methods

new(array_of_rows) click to toggle source

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

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

  • empty?()

  • length()

  • size()

     # File lib/faster_csv.rb, line 426
426:       def initialize(array_of_rows)
427:         @table = array_of_rows
428:         @mode  = :col_or_row
429:       end

Public Instance Methods

<<(row_or_array) click to toggle source

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

This method returns the table for chaining.

     # File lib/faster_csv.rb, line 624
624:       def <<(row_or_array)
625:         if row_or_array.is_a? Array  # append Array
626:           @table << Row.new(headers, row_or_array)
627:         else                         # append Row
628:           @table << row_or_array
629:         end
630: 
631:         self  # for chaining
632:       end
==(other) click to toggle source

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

     # File lib/faster_csv.rb, line 703
703:       def ==(other)
704:         @table == other.table
705:       end
[](index_or_header) click to toggle source

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.

     # File lib/faster_csv.rb, line 540
540:       def [](index_or_header)
541:         if @mode == :row or  # by index
542:            (@mode == :col_or_row and index_or_header.is_a? Integer)
543:           @table[index_or_header]
544:         else                 # by header
545:           @table.map { |row| row[index_or_header] }
546:         end
547:       end
[]=(index_or_header, value) click to toggle source

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 FasterCSV::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/faster_csv.rb, line 565
565:       def []=(index_or_header, value)
566:         if @mode == :row or  # by index
567:            (@mode == :col_or_row and index_or_header.is_a? Integer)
568:           if value.is_a? Array
569:             @table[index_or_header] = Row.new(headers, value)
570:           else
571:             @table[index_or_header] = value
572:           end
573:         else                 # set column
574:           if value.is_a? Array  # multiple values
575:             @table.each_with_index do |row, i|
576:               if row.header_row?
577:                 row[index_or_header] = index_or_header
578:               else
579:                 row[index_or_header] = value[i]
580:               end
581:             end
582:           else                  # repeated value
583:             @table.each do |row|
584:               if row.header_row?
585:                 row[index_or_header] = index_or_header
586:               else
587:                 row[index_or_header] = value
588:               end
589:             end
590:           end
591:         end
592:       end
by_col() click to toggle source

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.

     # File lib/faster_csv.rb, line 452
452:       def by_col
453:         self.class.new(@table.dup).by_col!
454:       end
by_col!() click to toggle source

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/faster_csv.rb, line 462
462:       def by_col!
463:         @mode = :col
464: 
465:         self
466:       end
by_col_or_row() click to toggle source

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/faster_csv.rb, line 477
477:       def by_col_or_row
478:         self.class.new(@table.dup).by_col_or_row!
479:       end
by_col_or_row!() click to toggle source

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/faster_csv.rb, line 489
489:       def by_col_or_row!
490:         @mode = :col_or_row
491: 
492:         self
493:       end
by_row() click to toggle source

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.

     # File lib/faster_csv.rb, line 504
504:       def by_row
505:         self.class.new(@table.dup).by_row!
506:       end
by_row!() click to toggle source

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/faster_csv.rb, line 514
514:       def by_row!
515:         @mode = :row
516: 
517:         self
518:       end
delete(index_or_header) click to toggle source

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/faster_csv.rb, line 652
652:       def delete(index_or_header)
653:         if @mode == :row or  # by index
654:            (@mode == :col_or_row and index_or_header.is_a? Integer)
655:           @table.delete_at(index_or_header)
656:         else                 # by header
657:           @table.map { |row| row.delete(index_or_header).last }
658:         end
659:       end
delete_if(&block) click to toggle source

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.

     # File lib/faster_csv.rb, line 669
669:       def delete_if(&block)
670:         if @mode == :row or @mode == :col_or_row  # by index
671:           @table.delete_if(&block)
672:         else                                      # by header
673:           to_delete = Array.new
674:           headers.each_with_index do |header, i|
675:             to_delete << header if block[[header, self[header]]]
676:           end
677:           to_delete.map { |header| delete(header) }
678:         end
679: 
680:         self  # for chaining
681:       end
each(&block) click to toggle source

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.

     # File lib/faster_csv.rb, line 692
692:       def each(&block)
693:         if @mode == :col
694:           headers.each { |header| block[[header, self[header]]] }
695:         else
696:           @table.each(&block)
697:         end
698: 
699:         self  # for chaining
700:       end
headers() click to toggle source

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

     # File lib/faster_csv.rb, line 524
524:       def headers
525:         if @table.empty?
526:           Array.new
527:         else
528:           @table.first.headers
529:         end
530:       end
inspect() click to toggle source
     # File lib/faster_csv.rb, line 740
740:       def inspect
741:         "#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>"
742:       end
push(*rows) click to toggle source

A shortcut for appending multiple rows. Equivalent to:

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

This method returns the table for chaining.

     # File lib/faster_csv.rb, line 641
641:       def push(*rows)
642:         rows.each { |row| self << row }
643: 
644:         self  # for chaining
645:       end
to_a() click to toggle source

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

     # File lib/faster_csv.rb, line 711
711:       def to_a
712:         @table.inject([headers]) do |array, row|
713:           if row.header_row?
714:             array
715:           else
716:             array + [row.fields]
717:           end
718:         end
719:       end
to_csv(options = Hash.new) click to toggle source

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/faster_csv.rb, line 728
728:       def to_csv(options = Hash.new)
729:         wh = options.fetch(:write_headers, true)
730:         @table.inject(wh ? [headers.to_csv(options)] : [ ]) do |rows, row|
731:           if row.header_row?
732:             rows
733:           else
734:             rows + [row.fields.to_csv(options)]
735:           end
736:         end.join
737:       end
Also aliased as: to_s
to_s(options = Hash.new) click to toggle source
Alias for: to_csv
values_at(*indices_or_headers) click to toggle source

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/faster_csv.rb, line 603
603:       def values_at(*indices_or_headers)
604:         if @mode == :row or  # by indices
605:            ( @mode == :col_or_row and indices_or_headers.all? do |index|
606:                                         index.is_a?(Integer)         or
607:                                         ( index.is_a?(Range)         and
608:                                           index.first.is_a?(Integer) and
609:                                           index.last.is_a?(Integer) )
610:                                       end )
611:           @table.values_at(*indices_or_headers)
612:         else                 # by headers
613:           @table.map { |row| row.values_at(*indices_or_headers) }
614:         end
615:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.