Class: FasterCSV::Table

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

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(array_of_rows) ⇒ Table

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



406
407
408
409
# File 'lib/faster_csv.rb', line 406

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

Instance Attribute Details

#modeObject (readonly)

The current access mode for indexing and iteration.



412
413
414
# File 'lib/faster_csv.rb', line 412

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 FasterCSV::Row (inheriting the table’s headers()), or a FasterCSV::Row.

This method returns the table for chaining.



604
605
606
607
608
609
610
611
612
# File 'lib/faster_csv.rb', line 604

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.



683
684
685
# File 'lib/faster_csv.rb', line 683

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.



520
521
522
523
524
525
526
527
# File 'lib/faster_csv.rb', line 520

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 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.



545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
# File 'lib/faster_csv.rb', line 545

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_colObject

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.



432
433
434
# File 'lib/faster_csv.rb', line 432

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.



442
443
444
445
446
# File 'lib/faster_csv.rb', line 442

def by_col!
  @mode = :col
  
  self
end

#by_col_or_rowObject

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.



457
458
459
# File 'lib/faster_csv.rb', line 457

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.



469
470
471
472
473
# File 'lib/faster_csv.rb', line 469

def by_col_or_row!
  @mode = :col_or_row
  
  self
end

#by_rowObject

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.



484
485
486
# File 'lib/faster_csv.rb', line 484

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.



494
495
496
497
498
# File 'lib/faster_csv.rb', line 494

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.



632
633
634
635
636
637
638
639
# File 'lib/faster_csv.rb', line 632

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.



649
650
651
652
653
654
655
656
657
658
659
660
661
# File 'lib/faster_csv.rb', line 649

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.



672
673
674
675
676
677
678
679
680
# File 'lib/faster_csv.rb', line 672

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

#headersObject

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



504
505
506
507
508
509
510
# File 'lib/faster_csv.rb', line 504

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

#inspectObject



716
717
718
# File 'lib/faster_csv.rb', line 716

def inspect
  "#<#{self.class} mode:#{@mode} row_count:#{to_a.size}>"
end

#push(*rows) ⇒ Object

A shortcut for appending multiple rows. Equivalent to:

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

This method returns the table for chaining.



621
622
623
624
625
# File 'lib/faster_csv.rb', line 621

def push(*rows)
  rows.each { |row| self << row }
  
  self  # for chaining
end

#to_aObject

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



691
692
693
694
695
696
697
698
699
# File 'lib/faster_csv.rb', line 691

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.



705
706
707
708
709
710
711
712
713
# File 'lib/faster_csv.rb', line 705

def to_csv(options = Hash.new)
  @table.inject([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.



583
584
585
586
587
588
589
590
591
592
593
594
595
# File 'lib/faster_csv.rb', line 583

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