Class: CSV::Table

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Enumerable
Defined in:
lib/csv/table.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

Instance Method Summary collapse

Constructor Details

#initialize(array_of_rows, headers: nil) ⇒ Table

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

The optional headers parameter can be set to Array of headers. If headers aren’t set, headers are fetched from CSV::Row objects. Otherwise, headers() method will return headers being set in headers argument.

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

  • empty?()

  • length()

  • size()



31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/csv/table.rb', line 31

def initialize(array_of_rows, headers: nil)
  @table = array_of_rows
  @headers = headers
  unless @headers
    if @table.empty?
      @headers = []
    else
      @headers = @table.first.headers
    end
  end

  @mode  = :col_or_row
end

Instance Attribute Details

#mode ⇒ Object (readonly)

The current access mode for indexing and iteration.



46
47
48
 
# File 'lib/csv/table.rb', line 46

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.



243
244
245
246
247
248
249
250
251
 
# File 'lib/csv/table.rb', line 243

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.



344
345
346
347
 
# File 'lib/csv/table.rb', line 344

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.



155
156
157
158
159
160
161
162
 
# File 'lib/csv/table.rb', line 155

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.



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/csv/table.rb', line 180

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
    unless index_or_header.is_a? Integer
      index = @headers.index(index_or_header) || @headers.size
      @headers[index] = index_or_header
    end
    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.



66
67
68
 
# File 'lib/csv/table.rb', line 66

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.



76
77
78
79
80
 
# File 'lib/csv/table.rb', line 76

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.



91
92
93
 
# File 'lib/csv/table.rb', line 91

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.



103
104
105
106
107
 
# File 'lib/csv/table.rb', line 103

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.



118
119
120
 
# File 'lib/csv/table.rb', line 118

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.



128
129
130
131
132
 
# File 'lib/csv/table.rb', line 128

def by_row!
  @mode = :row

  self
end

#delete(*indexes_or_headers) ⇒ Object

Removes and returns the indicated columns or rows. In the default mixed mode indices refer to rows and everything else is assumed to be a column headers. Use by_col!() or by_row!() to force the lookup.



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/csv/table.rb', line 271

def delete(*indexes_or_headers)
  if indexes_or_headers.empty?
    raise ArgumentError, "wrong number of arguments (given 0, expected 1+)"
  end
  deleted_values = indexes_or_headers.map do |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
      if index_or_header.is_a? Integer
        @headers.delete_at(index_or_header)
      else
        @headers.delete(index_or_header)
      end
      @table.map { |row| row.delete(index_or_header).last }
    end
  end
  if indexes_or_headers.size == 1
    deleted_values[0]
  else
    deleted_values
  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.



305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/csv/table.rb', line 305

def delete_if(&block)
  return enum_for(__method__) { @mode == :row or @mode == :col_or_row ? size : headers.size } unless block_given?

  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 yield([header, self[header]])
    end
  end

  self # for chaining
end

#dig(index_or_header, *index_or_headers) ⇒ Object

Extracts the nested value specified by the sequence of index or header objects by calling dig at each step, returning nil if any intermediate step is nil.



383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'lib/csv/table.rb', line 383

def dig(index_or_header, *index_or_headers)
  value = self[index_or_header]
  if value.nil?
    nil
  elsif index_or_headers.empty?
    value
  else
    unless value.respond_to?(:dig)
      raise TypeError, "#{value.class} does not have \#dig method"
    end
    value.dig(*index_or_headers)
  end
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.



331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/csv/table.rb', line 331

def each(&block)
  return enum_for(__method__) { @mode == :col ? headers.size : size } unless block_given?

  if @mode == :col
    headers.each { |header| yield([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). The headers Array passed to CSV::Table.new is returned for empty tables.



139
140
141
142
143
144
145
 
# File 'lib/csv/table.rb', line 139

def headers
  if @table.empty?
    @headers.dup
  else
    @table.first.headers
  end
end

#inspect ⇒ Object

Shows the mode and size of this table in a US-ASCII String.



398
399
400
 
# File 'lib/csv/table.rb', line 398

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.



260
261
262
263
264
 
# File 'lib/csv/table.rb', line 260

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.



353
354
355
356
357
358
359
360
 
# File 'lib/csv/table.rb', line 353

def to_a
  array = [headers]
  @table.each do |row|
    array.push(row.fields) unless row.header_row?
  end

  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.



369
370
371
372
373
374
375
376
 
# File 'lib/csv/table.rb', line 369

def to_csv(write_headers: true, **options)
  array = write_headers ? [headers.to_csv(**options)] : []
  @table.each do |row|
    array.push(row.fields.to_csv(**options)) unless row.header_row?
  end

  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.



222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/csv/table.rb', line 222

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