Class: DBI::Row

### Home Classes Methods

### In Files

- lib/dbi/row.rb

### Parent

DelegateClass(Array)

### Methods

- ::new
- #[]
- #[]=
- #__getobj__
- #__setobj__
- #by_field
- #by_index
- #clone
- #clone_with
- #convert_types
- #dup
- #each_with_name
- #set_values
- #to_a
- #to_h

### Files

- ChangeLog
- LICENSE
- README

### Class/Module Index

Quicksearch

- DBI
- DBI::BaseDatabase
- DBI::BaseDriver
- DBI::BaseStatement
- DBI::Binary
- DBI::ColumnInfo
- DBI::DataError
- DBI::DatabaseError
- DBI::DatabaseHandle
- DBI::Date
- DBI::DriverHandle
- DBI::Error
- DBI::Handle
- DBI::HandleTracer
- DBI::IntegrityError
- DBI::InterfaceError
- DBI::InternalError
- DBI::NotImplementedError
- DBI::NotSupportedError
- DBI::OperationalError
- DBI::ProgrammingError
- DBI::Row
- DBI::SQL
- DBI::SQL::PreparedStatement
- DBI::StatementHandle
- DBI::Time
- DBI::Timestamp
- DBI::Type
- DBI::Type::Boolean
- DBI::Type::Decimal
- DBI::Type::Float
- DBI::Type::Integer
- DBI::Type::Null
- DBI::Type::Timestamp
- DBI::Type::Varchar
- DBI::TypeUtil
- DBI::Utils
- DBI::Utils::ConvParam
- DBI::Utils::TableFormatter
- DBI::Utils::XMLFormatter
- DBI::Warning
- Class

No matching classes.

# 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 226
    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 230
    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.