QSqlResult Class

The QSqlResult class provides an abstract interface for accessing data from specific SQL databases. More…

List of all members, including inherited members

Public Functions

Protected Types

Protected Functions

Detailed Description

A QSqlResult runs one statement and walks its rows. QSqlQuery does this for applications; QSqlResult is there to be subclassed by a driver, which returns an object of its subclass from QSqlDriver::createResult().

A subclass implements data(), isNull(), reset(), fetch(), fetchFirst(), fetchLast(), size() and numRowsAffected(). A driver that prepares statements also implements prepare() and exec(), and most drivers implement record() and lastInsertId().

The base class keeps the values that are bound to the placeholders of a prepared statement. savePrepare() reads the statement: it finds the placeholders outside of quoted text and comments, and rewrites named placeholders as ?, so that a driver only has to bind by position. executedQuery() is the rewritten statement and boundValues() the values in the order of the placeholders. A name that appears several times has one value, which is bound at each of its positions.

See also QSqlDriver and QSqlQuery.

Differences from Qt

Member Type Documentation

[protected] enum QSqlResult::BindingSyntax

The way the placeholders of a prepared statement were written.

Member Function Documentation

[explicit, protected] QSqlResult::QSqlResult(const QSqlDriver *db)

Constructs a result for the driver db. The result does not own the driver, which has to outlive it.

[virtual] QSqlResult::~QSqlResult()

Destroys the result.

[protected] void QSqlResult::addBindValue(const QVariant &val, QSql::ParamType type)

Binds the value val of the kind type to the next placeholder: the first one after prepare(), then the second, and so on.

See also bindValue() and resetBindCount().

[protected] int QSqlResult::at() const

Returns the position of the current row, counted from 0, or QSql::BeforeFirstRow or QSql::AfterLastRow.

See also setAt() and isValid().

[protected] BindingSyntax QSqlResult::bindingSyntax() const

Returns the way the placeholders of the prepared statement were written. A statement with both kinds counts as one with names.

[virtual, protected] void QSqlResult::bindValue(int index, const QVariant &val, QSql::ParamType type)

Binds the value val of the kind type to the placeholder at position index, counted from 0.

See also addBindValue() and boundValue().

[virtual, protected] void QSqlResult::bindValue(const QString &placeholder, const QVariant &val, QSql::ParamType type)

This is an overloaded function.

Binds the value val of the kind type to every placeholder called placeholder, which is written with its colon, as in ":id". Nothing happens if the statement has no such placeholder.

[protected] QSql::ParamType QSqlResult::bindValueType(const QString &placeholder) const

Returns the kind of the value that is bound to the placeholder called placeholder.

[protected] QSql::ParamType QSqlResult::bindValueType(int index) const

This is an overloaded function.

Returns the kind of the value that is bound to the placeholder at position index.

[protected] QVariant QSqlResult::boundValue(const QString &placeholder) const

Returns the value that is bound to the placeholder called placeholder, or an invalid QVariant if there is none.

[protected] QVariant QSqlResult::boundValue(int index) const

This is an overloaded function.

Returns the value that is bound to the placeholder at position index.

[protected] int QSqlResult::boundValueCount() const

Returns the number of bound values.

See also boundValues().

[protected] QString QSqlResult::boundValueName(int index) const

Returns the name of the placeholder at position index, or an empty string if it has none.

See also boundValueNames().

[protected] QStringList QSqlResult::boundValueNames() const

Returns the names of the placeholders in the order in which they appear in the statement. A positional placeholder has an empty name.

See also boundValueName().

[protected] QVariantList QSqlResult::boundValues() const

Returns the bound values in the order of the placeholders in the statement.

See also boundValueCount() and boundValueNames().

[protected] void QSqlResult::clear()

Forgets the statement, its placeholders, the bound values and the last error, and marks the result as inactive.

[virtual, protected] QVariant QSqlResult::data(int i)

Returns the value of the field at position i of the current row. Called only for a valid row and a position inside the record.

[virtual, protected] void QSqlResult::detachFromResultSet()

Releases the rows of the statement, so that the database is free for other statements, and keeps the prepared statement. The base implementation does nothing.

See also QSqlQuery::finish().

[protected] const QSqlDriver * QSqlResult::driver() const

Returns the driver of the result, or nullptr if the driver has been destroyed.

[virtual, protected] bool QSqlResult::exec()

Runs the prepared statement with the bound values and returns true on success. The base implementation fails with an error, as it does not emulate prepared statements.

See also prepare().

[virtual, protected] bool QSqlResult::execBatch(bool arrayBind = false)

Runs the prepared statement once for each row of a batch: every bound value is a QVariantList, and the statement is run with the first items of the lists, then with the second, and so on. Returns true if every run succeeded. arrayBind is ignored. Afterwards, the bound values are the lists again.

See also QSqlQuery::execBatch().

[protected] QString QSqlResult::executedQuery() const

Returns the statement as it is given to the database: the text of lastQuery() with a ? in the place of each named placeholder.

See also lastQuery().

[virtual, protected] bool QSqlResult::fetch(int i)

Moves to the row at position i, counted from 0, and returns true if there is such a row. An implementation calls setAt().

[virtual, protected] bool QSqlResult::fetchFirst()

Moves to the first row and returns true if there is one.

[virtual, protected] bool QSqlResult::fetchLast()

Moves to the last row and returns true if there is one.

[virtual, protected] bool QSqlResult::fetchNext()

Moves to the row after the current one and returns true if there is one. The base implementation calls fetch().

[virtual, protected] bool QSqlResult::fetchPrevious()

Moves to the row before the current one and returns true if there is one. The base implementation calls fetch().

[virtual] QVariant QSqlResult::handle() const

Returns the handle of the statement in the client library of the database, for code that calls the library directly. The base implementation returns an invalid QVariant.

[protected] bool QSqlResult::hasOutValues() const

Returns true if one of the bound values is an output value; otherwise returns false.

[protected] bool QSqlResult::isActive() const

Returns true if a statement was run with success and is not finished; otherwise returns false.

See also setActive().

[protected] bool QSqlResult::isForwardOnly() const

Returns true if the rows are only read forwards; otherwise returns false.

See also setForwardOnly().

[virtual, protected] bool QSqlResult::isNull(int i)

Returns true if the field at position i of the current row is null; otherwise returns false.

[protected] bool QSqlResult::isSelect() const

Returns true if the statement returns rows; otherwise returns false.

See also setSelect().

[protected] bool QSqlResult::isValid() const

Returns true if the result is positioned on a row; otherwise returns false.

See also at().

[protected] QSqlError QSqlResult::lastError() const

Returns the last error of the result.

See also setLastError().

[virtual, protected] QVariant QSqlResult::lastInsertId() const

Returns the identifier that the database gave the row that the last statement inserted. The base implementation returns an invalid QVariant.

[protected] QString QSqlResult::lastQuery() const

Returns the text of the statement, as it was given to prepare() or reset().

See also setQuery() and executedQuery().

[virtual, protected] bool QSqlResult::nextResult()

Moves to the next result set of a statement that has several, and returns true if there is one. The base implementation returns false.

[protected] QSql::NumericalPrecisionPolicy QSqlResult::numericalPrecisionPolicy() const

Returns how numbers of high precision are returned.

See also setNumericalPrecisionPolicy().

[virtual, protected] int QSqlResult::numRowsAffected()

Returns the number of rows that the last statement changed, or -1 if it is not known.

[virtual, protected] bool QSqlResult::prepare(const QString &query)

Prepares the statement query, which may have placeholders, and returns true on success. A driver implements this by giving executedQuery() to the database; the statement has been read by savePrepare() before. The base implementation fails with an error.

See also exec() and savePrepare().

[virtual, protected] QSqlRecord QSqlResult::record() const

Returns the fields of the rows of the statement, without values. The base implementation returns an empty record.

[virtual, protected] bool QSqlResult::reset(const QString &sqlquery)

Runs the SQL statement sqlquery, without preparing it first, and returns true on success. An implementation calls setActive() and setSelect(), and setLastError() on failure.

[protected] void QSqlResult::resetBindCount()

Makes the next addBindValue() bind the first placeholder again.

[virtual, protected] bool QSqlResult::savePrepare(const QString &sqlquery)

Reads the statement sqlquery: remembers its text, finds its placeholders, discards the bound values of the statement before, and then calls prepare(). Returns what prepare() returns.

See also prepare(), executedQuery() and boundValueNames().

[virtual, protected] void QSqlResult::setActive(bool active)

Sets whether a statement is running to active. Called by subclasses.

See also isActive().

[virtual, protected] void QSqlResult::setAt(int index)

Sets the position of the current row to index. Called by subclasses from fetch() and its relatives.

See also at().

[virtual, protected] void QSqlResult::setForwardOnly(bool forward)

Sets whether the rows are only read forwards to forward. A driver may then keep less of the rows in memory.

See also isForwardOnly().

[virtual, protected] void QSqlResult::setLastError(const QSqlError &error)

Sets the last error of the result to error. Called by subclasses.

See also lastError().

[virtual, protected] void QSqlResult::setNumericalPrecisionPolicy(QSql::NumericalPrecisionPolicy policy)

Sets how numbers of high precision are returned to policy.

See also numericalPrecisionPolicy().

[virtual, protected] void QSqlResult::setQuery(const QString &query)

Sets the text of the statement to query. Called by QSqlQuery before it runs a statement.

See also lastQuery().

[virtual, protected] void QSqlResult::setSelect(bool select)

Sets whether the statement returns rows to select. Called by subclasses.

See also isSelect().

[virtual, protected] int QSqlResult::size()

Returns the number of rows of a SELECT statement, or -1 if it is not known.