class DBI::Row
DBI::Row is the representation of a row in a result set returned by the database.
It is responsible for containing and representing the result set, converting it to native Ruby types, and providing methods to sanely move through itself.
The DBI::Row class is a delegate of Array, rather than a subclass, because there are times when it should act like an Array, and others when it should act like a Hash (and still others where it should act like String, Regexp, etc). It also needs to store metadata about the row, such as column data type and index information, that users can then access.
Attributes
Public Class Methods
::new(columns, column_types, size_or_array=nil)
Returns a new DBI::Row object using
columns
. The size_or_array
argument may either
be an Integer or an Array. If it is not provided, it defaults to the
length of columns
.
Column types is a corresponding Array of Class/Module objects that conform to the DBI::Type interface. These will be used to convert types as they are returned.
DBI::Row is a delegate of the Array class, so all of the Array instance methods are available to your DBI::Row object (keeping in mind that initialize, [], and []= have been explicitly overridden).
# File lib/dbi/row.rb, line 33 def initialize(columns, column_types, size_or_array=nil, convert_types=true) @column_types = column_types @convert_types = convert_types size_or_array ||= columns.size # The '@column_map' is used to map column names to integer values so # that users can reference row values by name or number. @column_map = {} @column_names = columns columns.each_with_index { |c,i| @column_map[c] = i } case size_or_array when Integer super(@arr = Array.new(size_or_array)) when Array super(@arr = size_or_array.dup) set_values(size_or_array.dup) else raise TypeError, "parameter must be either Integer or Array" end end
Public Instance Methods
row row row row[arg, arg] row[arg, arg, …]
Sample: ::new, [“Daniel”, “Berger”, “36”])
Retrieves row elements. Exactly what it retrieves depends on the kind and number of arguments used.
Zero arguments will raise an ArgumentError.
One argument will return a single result. This can be a String, Symbol, Integer, Range or Regexp and the appropriate result will be returned. Strings, Symbols and Regexps act like hash lookups, while Integers and Ranges act like Array index lookups.
Two arguments will act like the second form of Array#[], i.e it takes two integers, with the first number the starting point and the second number the length, and returns an array of values.
If three or more arguments are provided, an array of results is returned. The behavior for each argument is that of a single argument, i.e. Strings, Symbols, and Regexps act like hash lookups, while Integers and Ranges act like Array index lookups.
If no results are found, or an unhandled type is passed, then nil (or a nil element) is returned.
# File lib/dbi/row.rb, line 157 def [](*args) begin case args.length when 0 err = "wrong # of arguments(#{args.size} for at least 1)" raise ArgumentError, err when 1 case args[0] when Array args[0].collect { |e| self[e] } when Regexp self[@column_names.grep(args[0])] else @arr[conv_param(args[0])] end # We explicitly check for a length of 2 in order to properly # simulate the second form of Array#[]. when 2 @arr[conv_param(args[0]), conv_param(args[1])] else results = [] args.flatten.each{ |arg| case arg when Integer results.push(@arr[arg]) when Regexp results.push(self[@column_names.grep(arg)]) else results.push(self[conv_param(arg)]) end } results.flatten end rescue TypeError nil end end
Assign a value to a Row object by element. You can assign using a single element reference, or by using a start and length similar to the second form of Array#[]=.
row = “kirk” row = “haines” row[0, 2] = “test”
# File lib/dbi/row.rb, line 203 def []=(key, value_or_length, obj=nil) if obj @arr[conv_param(key), conv_param(value_or_length)] = obj else @arr[conv_param(key)] = value_or_length end end
# File lib/dbi/row.rb, line 213 def __getobj__ @arr end
# File lib/dbi/row.rb, line 217 def __setobj__(obj) @delegate_dc_obj = @arr = obj end
Value of the field named field_name
or nil if not found.
# File lib/dbi/row.rb, line 117 def by_field(field_name) begin @arr[@column_map[field_name.to_s]] rescue TypeError nil end end
Retrieve a value by index (rather than name).
Deprecated. Since Row delegates to Array, just use Row#at.
# File lib/dbi/row.rb, line 112 def by_index(index) @arr[index] end
Create a new row with 'new_values', reusing the field name hash. Initial cloning is done deeply, via Marshal.
# File lib/dbi/row.rb, line 100 def clone_with(new_values) obj = clone obj.set_values(new_values) return obj end
converts the types in the array to their specified representation from column types provided at construction time.
# File lib/dbi/row.rb, line 58 def convert_types(arr) return arr.dup unless @convert_types if arr.size != @column_types.size raise TypeError, "Type mapping is not consistent with result" end new_arr = [] arr.each_with_index do |item, i| new_arr.push((@column_types[i] || DBI::Type::Varchar).parse(item)) end return new_arr end
# File lib/dbi/row.rb, line 231 def dup row = self.class.allocate row.instance_variable_set :@column_types, @column_types row.instance_variable_set :@convert_types, @convert_types row.instance_variable_set :@column_map, @column_map row.instance_variable_set :@column_names, @column_names # this is the only one we actually dup... row.instance_variable_set :@arr, arr = @arr.dup row.instance_variable_set :@_dc_obj, arr row end
Yields a column value by name (rather than index), along with the column name itself.
# File lib/dbi/row.rb, line 80 def each_with_name @arr.each_with_index do |v, i| yield v, @column_names[i] end end
Replaces the contents of the internal array with new_values
.
elements are type converted at this time.
# File lib/dbi/row.rb, line 74 def set_values(new_values) @arr.replace(convert_types(new_values)) end
returns the underlying array (duplicated)
# File lib/dbi/row.rb, line 87 def to_a @arr.dup end
Returns the Row object as a hash, created by each_with_name.
# File lib/dbi/row.rb, line 92 def to_h hash = {} each_with_name{ |v, n| hash[n] = v} hash end