Class: CSV::Row

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

Overview

CSV::Row

A CSV::Row instance represents a CSV table row. (see class CSV).

The instance may have:

  • Fields: each is an object, not necessarily a String.

  • Headers: each serves a key, and also need not be a String.

Instance Methods

CSV::Row has three groups of instance methods:

  • Its own internally defined instance methods.

  • Methods included by module Enumerable.

  • Methods delegated to class Array.:

    • Array#empty?

    • Array#length

    • Array#size

Creating a CSV::Row Instance

Commonly, a new CSV::Row instance is created by parsing CSV source that has headers:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
table.each {|row| p row }

Output:

#<CSV::Row "Name":"foo" "Value":"0">
#<CSV::Row "Name":"bar" "Value":"1">
#<CSV::Row "Name":"baz" "Value":"2">

You can also create a row directly. See ::new.

Headers

Like a CSV::Table, a CSV::Row has headers.

A CSV::Row that was created by parsing CSV source inherits its headers from the table:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table.first
row.headers # => ["Name", "Value"]

You can also create a new row with headers; like the keys in a Hash, the headers need not be Strings:

row = CSV::Row.new([:name, :value], ['foo', 0])
row.headers # => [:name, :value]

The new row retains its headers even if added to a table that has headers:

table << row # => #<CSV::Table mode:col_or_row row_count:5>
row.headers # => [:name, :value]
row[:name] # => "foo"
row['Name'] # => nil

Accessing Fields

You may access a field in a CSV::Row with either its Integer index (Array-style) or its header (Hash-style).

Fetch a field using method #[]:

row = CSV::Row.new(['Name', 'Value'], ['foo', 0])
row[1] # => 0
row['Value'] # => 0

Set a field using method #[]=:

row = CSV::Row.new(['Name', 'Value'], ['foo', 0])
row # => #<CSV::Row "Name":"foo" "Value":0>
row[0] = 'bar'
row['Value'] = 1
row # => #<CSV::Row "Name":"bar" "Value":1>

Instance Method Summary collapse

Constructor Details

#initialize(headers, fields, header_row = false) ⇒ Row

:call-seq:

CSV::Row.new(headers, fields, header_row = false) -> csv_row

Returns the new CSV::Row instance constructed from arguments headers and fields; both should be Arrays; note that the fields need not be Strings:

row = CSV::Row.new(['Name', 'Value'], ['foo', 0])
row # => #<CSV::Row "Name":"foo" "Value":0>

If the Array lengths are different, the shorter is nil-filled:

row = CSV::Row.new(['Name', 'Value', 'Date', 'Size'], ['foo', 0])
row # => #<CSV::Row "Name":"foo" "Value":0 "Date":nil "Size":nil>

Each CSV::Row object is either a field row or a header row; by default, a new row is a field row; for the row created above:

row.field_row? # => true
row.header_row? # => false

If the optional argument header_row is given as true, the created row is a header row:

row = CSV::Row.new(['Name', 'Value'], ['foo', 0], header_row = true)
row # => #<CSV::Row "Name":"foo" "Value":0>
row.field_row? # => false
row.header_row? # => true



105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/csv/row.rb', line 105

def initialize(headers, fields, header_row = false)
  @header_row = header_row
  headers.each { |h| h.freeze if h.is_a? String }

  # handle extra headers or fields
  @row = if headers.size >= fields.size
    headers.zip(fields)
  else
    fields.zip(headers).each(&:reverse!)
  end
end

Instance Method Details

#<<(arg) ⇒ Object

:call-seq:

row << [header, value] -> self
row << hash -> self
row << value -> self

Adds a field to self; returns self:

If the argument is a 2-element Array [header, value], a field is added with the given header and value:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row << ['NAME', 'Bat']
row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" "NAME":"Bat">

If the argument is a Hash, each key-value pair is added as a field with header key and value value.

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row << {NAME: 'Bat', name: 'Bam'}
row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" NAME:"Bat" name:"Bam">

Otherwise, the given value is added as a field with no header.

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row << 'Bag'
row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" nil:"Bag">



389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/csv/row.rb', line 389

def <<(arg)
  if arg.is_a?(Array) and arg.size == 2  # appending a header and name
    @row << arg
  elsif arg.is_a?(Hash)                  # append header and name pairs
    arg.each { |pair| @row << pair }
  else                                   # append field value
    @row << [nil, arg]
  end

  self  # for chaining
end

#==(other) ⇒ Object

:call-seq:

row == other -> true or false

Returns true if other is a /CSV::Row that has the same fields (headers and values) in the same order as self; otherwise returns false:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
other_row = table[0]
row == other_row # => true
other_row = table[1]
row == other_row # => false



633
634
635
636
 
# File 'lib/csv/row.rb', line 633

def ==(other)
  return @row == other.row if other.is_a? CSV::Row
  @row == other
end

#[]=(*args) ⇒ Object

:call-seq:

row[index] = value -> value
row[header, offset] = value -> value
row[header] = value -> value

Assigns the field value for the given index or header; returns value.

Assign field value by Integer index:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row[0] = 'Bat'
row[1] = 3
row # => #<CSV::Row "Name":"Bat" "Value":3>

Counts backward from the last column if index is negative:

row[-1] = 4
row[-2] = 'Bam'
row # => #<CSV::Row "Name":"Bam" "Value":4>

Extends the row with nil:nil if positive index is not in the row:

row[4] = 5
row # => #<CSV::Row "Name":"bad" "Value":4 nil:nil nil:nil nil:5>

Raises IndexError if negative index is too small (too far from zero).

Assign field value by header (first found):

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row['Name'] = 'Bat'
row # => #<CSV::Row "Name":"Bat" "Name":"Bar" "Name":"Baz">

Assign field value by header, ignoring offset leading fields:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row['Name', 2] = 4
row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":4>

Append new field by (new) header:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row['New'] = 6
row# => #<CSV::Row "Name":"foo" "Value":"0" "New":6>



339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/csv/row.rb', line 339

def []=(*args)
  value = args.pop

  if args.first.is_a? Integer
    if @row[args.first].nil?  # extending past the end with index
      @row[args.first] = [nil, value]
      @row.map! { |pair| pair.nil? ? [nil, nil] : pair }
    else                      # normal index assignment
      @row[args.first][1] = value
    end
  else
    index = index(*args)
    if index.nil?             # appending a field
      self << [args.first, value]
    else                      # normal header assignment
      @row[index][1] = value
    end
  end
end

#deconstruct ⇒ Object

:call-seq:

row.deconstruct -> array

Returns the new Array suitable for pattern matching containing the values of the row.



682
683
684
 
# File 'lib/csv/row.rb', line 682

def deconstruct
  fields
end

#deconstruct_keys(keys) ⇒ Object

:call-seq:

row.deconstruct_keys(keys) -> hash

Returns the new Hash suitable for pattern matching containing only the keys specified as an argument.



667
668
669
670
671
672
673
 
# File 'lib/csv/row.rb', line 667

def deconstruct_keys(keys)
  if keys.nil?
    to_h
  else
    keys.to_h { |key| [key, self[key]] }
  end
end

#delete(header_or_index, minimum_index = 0) ⇒ Object

:call-seq:

delete(index) -> [header, value] or nil
delete(header) -> [header, value] or empty_array
delete(header, offset) -> [header, value] or empty_array

Removes a specified field from self; returns the 2-element Array [header, value] if the field exists.

If an Integer argument index is given, removes and returns the field at offset index, or returns nil if the field does not exist:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.delete(1) # => ["Name", "Bar"]
row.delete(50) # => nil

Otherwise, if the single argument header is given, removes and returns the first-found field with the given header, of returns a new empty Array if the field does not exist:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.delete('Name') # => ["Name", "Foo"]
row.delete('NAME') # => []

If argument header and Integer argument offset are given, removes and returns the first-found field with the given header whose index is at least as large as offset:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.delete('Name', 1) # => ["Name", "Bar"]
row.delete('NAME', 1) # => []



451
452
453
454
455
456
457
458
459
 
# File 'lib/csv/row.rb', line 451

def delete(header_or_index, minimum_index = 0)
  if header_or_index.is_a? Integer                 # by index
    @row.delete_at(header_or_index)
  elsif i = index(header_or_index, minimum_index)  # by header
    @row.delete_at(i)
  else
    [ ]
  end
end

#delete_if(&block) ⇒ Object

:call-seq:

row.delete_if {|header, value| ... } -> self

Removes fields from self as selected by the block; returns self.

Removes each field for which the block returns a truthy value:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.delete_if {|header, value| value.start_with?('B') } # => true
row # => #<CSV::Row "Name":"Foo">
row.delete_if {|header, value| header.start_with?('B') } # => false

If no block is given, returns a new Enumerator:

row.delete_if # => #<Enumerator: #<CSV::Row "Name":"Foo">:delete_if>



476
477
478
479
480
481
482
 
# File 'lib/csv/row.rb', line 476

def delete_if(&block)
  return enum_for(__method__) { size } unless block_given?

  @row.delete_if(&block)

  self  # for chaining
end

#dig(index_or_header, *indexes) ⇒ Object

:call-seq:

row.dig(index_or_header, *identifiers) -> object

Finds and returns the object in nested object that is specified by index_or_header and specifiers.

The nested objects may be instances of various classes. See Dig Methods.

Examples:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.dig(1) # => "0"
row.dig('Value') # => "0"
row.dig(5) # => nil



715
716
717
718
719
720
721
722
723
724
725
726
727
 
# File 'lib/csv/row.rb', line 715

def dig(index_or_header, *indexes)
  value = field(index_or_header)
  if value.nil?
    nil
  elsif indexes.empty?
    value
  else
    unless value.respond_to?(:dig)
      raise TypeError, "#{value.class} does not have \#dig method"
    end
    value.dig(*indexes)
  end
end

#each(&block) ⇒ Object Also known as: each_pair

:call-seq:

row.each {|header, value| ... } -> self

Calls the block with each header-value pair; returns self:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.each {|header, value| p [header, value] }

Output:

["Name", "Foo"]
["Name", "Bar"]
["Name", "Baz"]

If no block is given, returns a new Enumerator:

row.each # => #<Enumerator: #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz">:each>



610
611
612
613
614
615
616
 
# File 'lib/csv/row.rb', line 610

def each(&block)
  return enum_for(__method__) { size } unless block_given?

  @row.each(&block)

  self  # for chaining
end

#fetch(header, *varargs) ⇒ Object

:call-seq:

fetch(header) -> value
fetch(header, default) -> value
fetch(header) {|row| ... } -> value

Returns the field value as specified by header.

With the single argument header, returns the field value for that header (first found):

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.fetch('Name') # => "Foo"

Raises exception KeyError if the header does not exist.

With arguments header and default given, returns the field value for the header (first found) if the header exists, otherwise returns default:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.fetch('Name', '') # => "Foo"
row.fetch(:nosuch, '') # => ""

With argument header and a block given, returns the field value for the header (first found) if the header exists; otherwise calls the block and returns its return value:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.fetch('Name') {|header| fail 'Cannot happen' } # => "Foo"
row.fetch(:nosuch) {|header| "Header '#{header} not found'" } # => "Header 'nosuch not found'"

Raises:

  • (ArgumentError) 


258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/csv/row.rb', line 258

def fetch(header, *varargs)
  raise ArgumentError, "Too many arguments" if varargs.length > 1
  pair = @row.assoc(header)
  if pair
    pair.last
  else
    if block_given?
      yield header
    elsif varargs.empty?
      raise KeyError, "key not found: #{header}"
    else
      varargs.first
    end
  end
end

#field(header_or_index, minimum_index = 0) ⇒ Object Also known as: []

:call-seq:

field(index) -> value
field(header) -> value
field(header, offset) -> value

Returns the field value for the given index or header.

Fetch field value by Integer index:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.field(0) # => "foo"
row.field(1) # => "bar"

Counts backward from the last column if index is negative:

row.field(-1) # => "0"
row.field(-2) # => "foo"

Returns nil if index is out of range:

row.field(2) # => nil
row.field(-3) # => nil

Fetch field value by header (first found):

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.field('Name') # => "Foo"

Fetch field value by header, ignoring offset leading fields:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.field('Name', 2) # => "Baz"

Returns nil if the header does not exist.



203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/csv/row.rb', line 203

def field(header_or_index, minimum_index = 0)
  # locate the pair
  finder = (header_or_index.is_a?(Integer) || header_or_index.is_a?(Range)) ? :[] : :assoc
  pair   = @row[minimum_index..-1].public_send(finder, header_or_index)

  # return the field if we have a pair
  if pair.nil?
    nil
  else
    header_or_index.is_a?(Range) ? pair.map(&:last) : pair.last
  end
end

#field?(data) ⇒ Boolean

:call-seq:

row.field?(value) -> true or false

Returns true if value is a field in this row, false otherwise:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.field?('Bar') # => true
row.field?('BAR') # => false

Returns:

  • (Boolean) 


589
590
591
 
# File 'lib/csv/row.rb', line 589

def field?(data)
  fields.include? data
end

#field_row? ⇒ Boolean

:call-seq:

row.field_row? -> true or false

Returns true if this is a field row, false otherwise.

Returns:

  • (Boolean) 


148
149
150
 
# File 'lib/csv/row.rb', line 148

def field_row?
  not header_row?
end

#fields(*headers_and_or_indices) ⇒ Object Also known as: values_at

:call-seq:

self.fields(*specifiers) -> array_of_fields

Returns field values per the given specifiers, which may be any mixture of:

  • Integer index.

  • Range of Integer indexes.

  • 2-element Array containing a header and offset.

  • Header.

  • Range of headers.

For specifier in one of the first four cases above, returns the result of self.field(specifier); see #field.

Although there may be any number of specifiers, the examples here will illustrate one at a time.

When the specifier is an Integer index, returns self.field(index)L

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.fields(1) # => ["Bar"]

When the specifier is a Range of Integers range, returns self.field(range):

row.fields(1..2) # => ["Bar", "Baz"]

When the specifier is a 2-element Array array, returns self.field(array)L

row.fields('Name', 1) # => ["Foo", "Bar"]

When the specifier is a header header, returns self.field(header)L

row.fields('Name') # => ["Foo"]

When the specifier is a Range of headers range, forms a new Range new_range from the indexes of range.start and range.end, and returns self.field(new_range):

source = "Name,NAME,name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.fields('Name'..'NAME') # => ["Foo", "Bar"]

Returns all fields if no argument given:

row.fields # => ["Foo", "Bar", "Baz"]



530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
 
# File 'lib/csv/row.rb', line 530

def fields(*headers_and_or_indices)
  if headers_and_or_indices.empty?  # return all fields--no arguments
    @row.map(&:last)
  else                              # or work like values_at()
    all = []
    headers_and_or_indices.each do |h_or_i|
      if h_or_i.is_a? Range
        index_begin = h_or_i.begin.is_a?(Integer) ? h_or_i.begin :
                                                    index(h_or_i.begin)
        index_end   = h_or_i.end.is_a?(Integer)   ? h_or_i.end :
                                                    index(h_or_i.end)
        new_range   = h_or_i.exclude_end? ? (index_begin...index_end) :
                                            (index_begin..index_end)
        all.concat(fields.values_at(new_range))
      else
        all << field(*Array(h_or_i))
      end
    end
    return all
  end
end

#has_key?(header) ⇒ Boolean Also known as: include?, key?, member?, header?

:call-seq:

row.has_key?(header) -> true or false

Returns true if there is a field with the given header, false otherwise.

Returns:

  • (Boolean) 


279
280
281
 
# File 'lib/csv/row.rb', line 279

def has_key?(header)
  !!@row.assoc(header)
end

#header_row? ⇒ Boolean

:call-seq:

row.header_row? -> true or false

Returns true if this is a header row, false otherwise.

Returns:

  • (Boolean) 


140
141
142
 
# File 'lib/csv/row.rb', line 140

def header_row?
  @header_row
end

#headers ⇒ Object

:call-seq:

row.headers -> array_of_headers

Returns the headers for this row:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table.first
row.headers # => ["Name", "Value"]



160
161
162
 
# File 'lib/csv/row.rb', line 160

def headers
  @row.map(&:first)
end

#index(header, minimum_index = 0) ⇒ Object

:call-seq:

index(header) -> index
index(header, offset) -> index

Returns the index for the given header, if it exists; otherwise returns nil.

With the single argument header, returns the index of the first-found field with the given header:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.index('Name') # => 0
row.index('NAME') # => nil

With arguments header and offset, returns the index of the first-found field with given header, but ignoring the first offset fields:

row.index('Name', 1) # => 1
row.index('Name', 3) # => nil



573
574
575
576
577
578
 
# File 'lib/csv/row.rb', line 573

def index(header, minimum_index = 0)
  # find the pair
  index = headers[minimum_index..-1].index(header)
  # return the index at the right offset, if we found one
  index.nil? ? nil : index + minimum_index
end

#initialize_copy(other) ⇒ Object

:call-seq:

row.initialize_copy(other_row) -> self

Calls superclass method.



130
131
132
133
134
 
# File 'lib/csv/row.rb', line 130

def initialize_copy(other)
  super_return_value = super
  @row = @row.collect(&:dup)
  super_return_value
end

#inspect ⇒ Object

:call-seq:

row.inspect -> string

Returns an ASCII-compatible String showing:

  • Class CSV::Row.

  • Header-value pairs.

Example:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.inspect # => "#<CSV::Row \"Name\":\"foo\" \"Value\":\"0\">"



740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
 
# File 'lib/csv/row.rb', line 740

def inspect
  str = ["#<", self.class.to_s]
  each do |header, field|
    str << " " << (header.is_a?(Symbol) ? header.to_s : header.inspect) <<
           ":" << field.inspect
  end
  str << ">"
  begin
    str.join('')
  rescue  # any encoding error
    str.map do |s|
      e = Encoding::Converter.asciicompat_encoding(s.encoding)
      e ? s.encode(e) : s.force_encoding("ASCII-8BIT")
    end.join('')
  end
end

#push(*args) ⇒ Object

:call-seq:

row.push(*values) -> self

Appends each of the given values to self as a field; returns self:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.push('Bat', 'Bam')
row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" nil:"Bat" nil:"Bam">



410
411
412
413
414
 
# File 'lib/csv/row.rb', line 410

def push(*args)
  args.each { |arg| self << arg }

  self  # for chaining
end

#to_csv(**options) ⇒ Object Also known as: to_s

:call-seq:

row.to_csv -> csv_string

Returns the row as a CSV String. Headers are not included:

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.to_csv # => "foo,0\n"



694
695
696
 
# File 'lib/csv/row.rb', line 694

def to_csv(**options)
  fields.to_csv(**options)
end

#to_h ⇒ Object Also known as: to_hash

:call-seq:

row.to_h -> hash

Returns the new Hash formed by adding each header-value pair in self as a key-value pair in the Hash.

source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.to_h # => {"Name"=>"foo", "Value"=>"0"}

Header order is preserved, but repeated headers are ignored:

source = "Name,Name,Name\nFoo,Bar,Baz\n"
table = CSV.parse(source, headers: true)
row = table[0]
row.to_h # => {"Name"=>"Foo"}



653
654
655
656
657
658
659
 
# File 'lib/csv/row.rb', line 653

def to_h
  hash = {}
  each do |key, _value|
    hash[key] = self[key] unless hash.key?(key)
  end
  hash
end