A CSV::Row is part Array and part Hash. It retains an order for the fields and allows duplicates just as an Array would, but also allows you to access fields by name just as you could if they were in a Hash.
All rows returned by CSV will be constructed from this class, if header row processing is activated.
Internal data format used to compare equality.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 30
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
Constructs a new CSV::Row from headers and fields, which are expected to be Arrays. If one Array is shorter than the other, it will be padded with nil objects.
The optional header_row parameter can be set to true to indicate, via CSV::Row.header_row?() and CSV::Row.field_row?(), that this is a header row. Otherwise, the row assumes to be a field row.
A CSV::Row object supports the following Array methods through delegation:
-
empty?()
-
length()
-
size()
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 310
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
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">
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 522
def ==(other)
return @row == other.row if other.is_a? CSV::Row
@row == other
end
Returns true if this row contains the same headers and fields in the same order as other.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 260
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
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>
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 372
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
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) # => []
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 397
def delete_if(&block)
return enum_for(__method__) { size } unless block_given?
@row.delete_if(&block)
self # for chaining
end
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>
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 582
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
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
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 508
def each(&block)
return enum_for(__method__) { size } unless block_given?
@row.each(&block)
self # for chaining
end
Yields each pair of the row as header and field tuples (much like iterating over a Hash). This method returns the row for chaining.
If no block is given, an Enumerator is returned.
Support for Enumerable.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 179
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
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'"
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 124
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
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.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 494
def field?(data)
fields.include? data
end
Returns true if data matches a field in this row, and false otherwise.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 69
def field_row?
not header_row?
end
Returns true if this is a field row, false otherwise.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 451
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
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"]
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 200
def has_key?(header)
!!@row.assoc(header)
end
Returns true if there is a field with the given header, false otherwise.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 61
def header_row?
@header_row
end
Returns true if this is a header row, false otherwise.
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 81
def headers
@row.map(&:first)
end
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"]
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 483
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
This method will return the index of a field with the provided header. The offset can be used to locate duplicate header names, as described in CSV::Row.field().
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 51
def initialize_copy(other)
super_return_value = super
@row = @row.collect(&:dup)
super_return_value
end
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 607
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
Returns an ASCII-compatible String showing:
-
ClassCSV::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\">"
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 331
def push(*args)
args.each { |arg| self << arg }
self # for chaining
end
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">
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 561
def to_csv(**options)
fields.to_csv(**options)
end
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"
# File tmp/rubies/ruby-3.0.5/lib/csv/row.rb, line 542
def to_h
hash = {}
each do |key, _value|
hash[key] = self[key] unless hash.key?(key)
end
hash
end
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"}