# class SQLite3::ResultSet

The ResultSet object encapsulates the enumerability of a query's output. It is a simple cursor over the data that the query returns. It will very rarely (if ever) be instantiated directly. Instead, client's should obtain a ResultSet instance via SQLite3::Statement#execute.

### Public Class Methods

new(db, stmt) click to toggle source

Create a new ResultSet attached to the given database, using the given sql text.

    # File lib/sqlite3/resultset.rb, line 72
    def initialize db, stmt
      @db   = db
      @stmt = stmt
    end

### Public Instance Methods

close() click to toggle source

Closes the statement that spawned this result set. Use with caution! Closing a result set will automatically close any other result sets that were spawned from the same statement.

    # File lib/sqlite3/resultset.rb, line 153
    def close
      @stmt.close
    end

closed?() click to toggle source

Queries whether the underlying statement has been closed or not.

    # File lib/sqlite3/resultset.rb, line 158
    def closed?
      @stmt.closed?
    end

columns() click to toggle source

Returns the names of the columns returned by this result set.

    # File lib/sqlite3/resultset.rb, line 168
    def columns
      @stmt.columns
    end

each() { |node| ... } click to toggle source

Required by the Enumerable mixin. Provides an internal iterator over the rows of the result set.

    # File lib/sqlite3/resultset.rb, line 136
    def each
      while node = self.next
        yield node
      end
    end

each_hash() { |node| ... } click to toggle source

Provides an internal iterator over the rows of the result set where each row is yielded as a hash.

    # File lib/sqlite3/resultset.rb, line 144
    def each_hash
      while node = next_hash
        yield node
      end
    end

eof?() click to toggle source

Query whether the cursor has reached the end of the result set or not.

    # File lib/sqlite3/resultset.rb, line 86
    def eof?
      @stmt.done?
    end

next() click to toggle source

Obtain the next row from the cursor. If there are no more rows to be had, this will return `nil`. If type translation is active on the corresponding database, the values in the row will be translated according to their types.

The returned value will be an array, unless SQLite3::Database#results_as_hash has been set to `true`, in which case the returned value will be a hash.

For arrays, the column names are accessible via the `fields` property, and the column types are accessible via the `types` property.

For hashes, the column names are the keys of the hash, and the column types are accessible via the `types` property.

    # File lib/sqlite3/resultset.rb, line 103
    def next
      if @db.results_as_hash
        return next_hash
      end

      row = @stmt.step
      return nil if @stmt.done?

      if @db.type_translation
        row = @stmt.types.zip(row).map do |type, value|
          @db.translator.translate( type, value )
        end
      end

      if row.respond_to?(:fields)
        # FIXME: this can only happen if the translator returns something
        # that responds to `fields`.  Since we're removing the translator
        # in 2.0, we can remove this branch in 2.0.
        row = ArrayWithTypes.new(row)
      else
        # FIXME: the `fields` and `types` methods are deprecated on this
        # object for version 2.0, so we can safely remove this branch
        # as well.
        row = ArrayWithTypesAndFields.new(row)
      end

      row.fields = @stmt.columns
      row.types = @stmt.types
      row
    end

next_hash() click to toggle source

Return the next row as a hash

    # File lib/sqlite3/resultset.rb, line 173
    def next_hash
      row = @stmt.step
      return nil if @stmt.done?

      # FIXME: type translation is deprecated, so this can be removed
      # in 2.0
      if @db.type_translation
        row = @stmt.types.zip(row).map do |type, value|
          @db.translator.translate( type, value )
        end
      end

      # FIXME: this can be switched to a regular hash in 2.0
      row = HashWithTypesAndFields[*@stmt.columns.zip(row).flatten]

      # FIXME: these methods are deprecated for version 2.0, so we can remove
      # this code in 2.0
      row.fields = @stmt.columns
      row.types = @stmt.types
      row
    end

reset( *bind_params ) click to toggle source

Reset the cursor, so that a result set which has reached end-of-file can be rewound and reiterated.

    # File lib/sqlite3/resultset.rb, line 79
    def reset( *bind_params )
      @stmt.reset!
      @stmt.bind_params( *bind_params )
      @eof = false
    end

types() click to toggle source

Returns the types of the columns returned by this result set.

    # File lib/sqlite3/resultset.rb, line 163
    def types
      @stmt.types
    end