In Files

Parent

Files

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

column_names[R]
field_names[R]

Public Class Methods

new(columns, column_types, size_or_array=nil, convert_types=true) click to toggle source

DBI::Row.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

[](*args) click to toggle source

Row#[]

row row row row[arg, arg] row[arg, arg, ...]

Sample: Row.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
[]=(key, value_or_length, obj=nil) click to toggle source

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
__getobj__() click to toggle source
# File lib/dbi/row.rb, line 213
def __getobj__
    @arr
end
__setobj__(obj) click to toggle source
# File lib/dbi/row.rb, line 217
def __setobj__(obj)
    @delegate_dc_obj = @arr = obj
end
by_field(field_name) click to toggle source

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
by_index(index) click to toggle source

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
clone() click to toggle source

See Object#clone.

clone and dup here, however, are both deep copies via Marshal.

# File lib/dbi/row.rb, line 227
def clone
    Marshal.load(Marshal.dump(self))
end
clone_with(new_values) click to toggle source

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
convert_types(arr) click to toggle source

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
dup() click to toggle source
# 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
each_with_name() click to toggle source

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
set_values(new_values) click to toggle source

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
to_a() click to toggle source

returns the underlying array (duplicated)

# File lib/dbi/row.rb, line 87
def to_a
    @arr.dup
end
to_h() click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.