QSqlCursor(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

💖 NAME 💖

QSqlCursor — browsing and editing of SQL tables and views ✨

(and yeah bestie, this is the manual page for QSqlCursor(3qt), section 3qt, qt-style, no cap 💅)

🦋 SYNOPSIS 🦋

#include <qsqlcursor.h>

It inherits from QSqlRecord and QSqlQuery.

It gets inherited by QSqlSelectCursor.

👑 Public Members 👑

okay so here's the whole lineup, literally every single one, don't skip 🫶

QSqlCursor ( const QString & name = QString::null, bool autopopulate =
    TRUE, QSqlDatabase * db = 0 )
QSqlCursor ( const QSqlCursor & other )
QSqlCursor & operator= ( const QSqlCursor & other )
~QSqlCursor ()
enum Mode { ReadOnly = 0, Insert = 1, Update = 2, Delete = 4, Writable =
    7 }
virtual QSqlIndex primaryIndex ( bool setFromCursor = TRUE ) const
virtual QSqlIndex index ( const QStringList & fieldNames ) const
QSqlIndex index ( const QString & fieldName ) const
QSqlIndex index ( const char * fieldName ) const
virtual void setPrimaryIndex ( const QSqlIndex & idx )
virtual void append ( const QSqlFieldInfo & fieldInfo )
virtual void insert ( int pos, const QSqlFieldInfo & fieldInfo )
virtual void remove ( int pos )
virtual void clear ()
virtual void setGenerated ( const QString & name, bool generated )
virtual void setGenerated ( int i, bool generated )
virtual QSqlRecord * editBuffer ( bool copy = FALSE )
virtual QSqlRecord * primeInsert ()
virtual QSqlRecord * primeUpdate ()
virtual QSqlRecord * primeDelete ()
virtual int insert ( bool invalidate = TRUE )
virtual int update ( bool invalidate = TRUE )
virtual int del ( bool invalidate = TRUE )
virtual void setMode ( int mode )
int mode () const
virtual void setCalculated ( const QString & name, bool calculated )
bool isCalculated ( const QString & name ) const
virtual void setTrimmed ( const QString & name, bool trim )
bool isTrimmed ( const QString & name ) const
bool isReadOnly () const
bool canInsert () const
bool canUpdate () const
bool canDelete () const
bool select ()
bool select ( const QSqlIndex & sort )
bool select ( const QSqlIndex & filter, const QSqlIndex & sort )
virtual bool select ( const QString & filter, const QSqlIndex & sort =
    QSqlIndex ( ) )
virtual void setSort ( const QSqlIndex & sort )
QSqlIndex sort () const
virtual void setFilter ( const QString & filter )
QString filter () const
virtual void setName ( const QString & name, bool autopopulate = TRUE )
QString name () const
bool isNull ( int i ) const
bool isNull ( const QString & name ) const

🙈 Protected Members 🙈

the backstage crew, still iconic 🌸

virtual QVariant calculateField ( const QString & name )
virtual int update ( const QString & filter, bool invalidate = TRUE )
virtual int del ( const QString & filter, bool invalidate = TRUE )
virtual QString toString ( const QString & prefix, QSqlField * field,
    const QString & fieldSep ) const
virtual QString toString ( QSqlRecord * rec, const QString & prefix,
    const QString & fieldSep, const QString & sep ) const
virtual QString toString ( const QSqlIndex & i, QSqlRecord * rec, const
    QString & prefix, const QString & fieldSep, const QString & sep )
    const

✨ DESCRIPTION ✨

The QSqlCursor class provides browsing and editing of SQL tables and views. that's the whole job, and it eats 💅

A QSqlCursor is a database record (peep QSqlRecord) that corresponds to a table or view inside an SQL database (peep QSqlDatabase). There are two buffers in a cursor, bestie: one for browsing and one for editing records. Each buffer contains a list of fields which correspond to the fields in the table or view. two buffers, one cursor, no drama 🎀

When it's positioned on a valid record, the browse buffer contains the values of the current record's fields from the database. The edit buffer is separate, and it's the one used for editing existing records and inserting new records.

For browsing data, a cursor has to first select() data from the database. After a successful select() the cursor is active (isActive() returns TRUE), but it is initially not positioned on a valid record (isValid() returns FALSE). To position the cursor on a valid record, use one of the navigation functions: next(), prev(), first(), last(), or seek(). Once you're positioned on a valid record, data can be retrieved from the browse buffer using value(). If a navigation function is not successful, it returns FALSE, the cursor will no longer be positioned on a valid record, and the values returned by value() are undefined. ⚠️ so like, don't trust them, fr fr.

For example:

QSqlCursor cur( "staff" ); // Specify the table/view name
cur.select(); // We'll retrieve every record
while ( cur.next() ) {
    qDebug( cur.value( "id" ).toString() + ": " +
            cur.value( "surname" ).toString() + " " +
            cur.value( "salary" ).toString() );
}

In the example above, a cursor is created specifying a table or view name in the database. Then select() is called, which can be optionally parameterised to filter and order the records retrieved. Each record in the cursor is retrieved using next(). When next() returns FALSE, there are no more records to process, and the loop terminates. so clean, so satisfying 🌈

For editing records (rows of data), a cursor contains a separate edit buffer which is independent of the fields used when browsing. The functions insert(), update() and del() operate on the edit buffer. This allows the cursor to be repositioned to other records while simultaneously maintaining a separate buffer for edits. You can get a pointer to the edit buffer using editBuffer(). The primeInsert(), primeUpdate() and primeDelete() functions also return a pointer to the edit buffer and prepare it for insert, update and delete respectively. Edit operations only affect a single row at a time. Note that update() and del() require that the table or view contain a primaryIndex() to ensure that edit operations affect a unique record within the database. 👑

For example:

QSqlCursor cur( "prices" );
cur.select( "id=202" );
if ( cur.next() ) {
    QSqlRecord *buffer = cur.primeUpdate();
    double price = buffer->value( "price" ).toDouble();
    double newprice = price * 1.05;
    buffer->setValue( "price", newprice );
    cur.update();
}

To edit an existing database record, first move to the record you wish to update. Call primeUpdate() to get the pointer to the cursor's edit buffer. Then use this pointer to modify the values in the edit buffer. Finally, call update() to save the changes to the database. The values in the edit buffer will be used to locate the appropriate record when updating the database (see primaryIndex()). it's giving careful, methodical, main character energy 💖

Similarly, when deleting an existing database record, first move to the record you wish to delete. Then, call primeDelete() to get the pointer to the edit buffer. Finally, call del() to delete the record from the database. Again, the values in the edit buffer will be used to locate and delete the appropriate record.

To insert a new record, call primeInsert() to get the pointer to the edit buffer. Use this pointer to populate the edit buffer with new values and then insert() the record into the database. ✨ new row, who dis ✨

After calling insert(), update() or del(), the cursor is no longer positioned on a valid record and can no longer be navigated (isValid() return FALSE). The reason for this is that any changes made to the database will not be visible until select() is called to refresh the cursor. You can change this behavior by passing FALSE to insert(), update() or del() which will prevent the cursor from becoming invalid. The edits will still not be visible when navigating the cursor until select() is called. so like, refresh your vibe check before you expect to see anything new, iykyk 💀

QSqlCursor contains virtual methods which allow editing behavior to be customized by subclasses. This allows custom cursors to be created that encapsulate the editing behavior of a database table for an entire application. For example, a cursor can be customized to always auto-number primary index fields, or provide fields with suitable default values, when inserting new records. QSqlCursor generates SQL statements which are sent to the database engine; you can control which fields are included in these statements using setGenerated(). build your own, bestie 🧚

Note that QSqlCursor does not inherit from QObject. This means that you are responsible for destroying instances of this class yourself. However if you create a QSqlCursor and use it in a QDataTable, QDataBrowser or a QDataView these classes will usually take ownership of the cursor and destroy it when they don't need it anymore. The documentation for QDataTable, QDataBrowser and QDataView explicitly states which calls take ownership of the cursor. so like, read before you yeet 🫶

See also Database Classes.

🎀 Member Type Documentation 🎀

QSqlCursor::Mode

This enum type describes how QSqlCursor operates on records in the database.

  • QSqlCursor::ReadOnly — the cursor can only SELECT records from the database.
  • QSqlCursor::Insert — the cursor can INSERT records into the database.
  • QSqlCursor::Update — the cursor can UPDATE records in the database.
  • QSqlCursor::Delete — the cursor can DELETE records from the database.
  • QSqlCursor::Writable — the cursor can INSERT, UPDATE and DELETE records in the database.

👑 MEMBER FUNCTION DOCUMENTATION 👑

QSqlCursor::QSqlCursor ( const QString & name = QString::null, bool autopopulate = TRUE, QSqlDatabase * db = 0 )

Constructs a cursor on database db using table or view name.

If autopopulate is TRUE (the default), the name of the cursor must correspond to an existing table or view name in the database so that field information can be automatically created. If the table or view does not exist, the cursor will not be functional. 😭

The cursor is created with an initial mode of QSqlCursor::Writable (meaning that records can be inserted, updated or deleted using the cursor). If the cursor does not have a unique primary index, update and deletes cannot be performed.

Note that autopopulate refers to populating the cursor with meta-data, e.g. the names of the table's fields, not with retrieving data. The select() function is used to populate the cursor with data.

See also setName() and setMode().

QSqlCursor::QSqlCursor ( const QSqlCursor & other )

Constructs a copy of other.

QSqlCursor::~QSqlCursor ()

Destroys the object and frees any allocated resources.

void QSqlCursor::append ( const QSqlFieldInfo & fieldInfo ) [virtual]

Append a copy of field fieldInfo to the end of the cursor. Note that all references to the cursor edit buffer become invalidated. ⚠️ so don't be holding onto that pointer, bestie.

QVariant QSqlCursor::calculateField ( const QString & name ) [virtual protected]

Protected virtual function which is called whenever a field needs to be calculated. If calculated fields are being used, derived classes must reimplement this function and return the appropriate value for field name. The default implementation returns an invalid QVariant.

See also setCalculated().

Examples:

bool QSqlCursor::canDelete () const

TRUE if this cursor is gonna actually do deletes for you, FALSE if it's not. That's the whole vibe check.

See also setMode().

bool QSqlCursor::canInsert () const

TRUE when the cursor is down to insert stuff, FALSE when it's giving "not today".

See also setMode().

bool QSqlCursor::canUpdate () const

TRUE if the cursor will perform updates, FALSE otherwise. Bestie, it's the same trio, just a different verb. 💅

See also setMode().

void QSqlCursor::clear () [virtual]

Nukes every field out of the cursor. Poof. Gone. 🫧

Heads up: all references to the cursor edit buffer become invalidated — so any pointers you were holding onto are now just decorative.

Reimplemented from QSqlRecord.

int QSqlCursor::del ( bool invalidate = TRUE ) [virtual]

Deletes a record from the database using the cursor's primary index plus whatever is sitting in the cursor edit buffer. Returns the number of records that got deleted. Need error info? That's lastError()'s whole job.

Only records matching the filter criteria set by the cursor's primary index get deleted. And if the cursor has no primary index at all? Then no delete happens and you get 0 back. Sad but true. 😭

If invalidate is TRUE (which is the default), the current cursor can no longer be navigated. You have to make a new select() call before you can move to a valid record. Like so:

QSqlCursor cur( "prices" );
cur.select( "id=999" );
if ( cur.next() ) {
    cur.primeDelete();
    cur.del();
}

So in that example, a cursor gets created on the 'prices' table and positioned onto the record about to be deleted. First primeDelete() runs to populate the edit buffer with the current cursor values — say an id of 999 — and then del() is called to actually delete that record from the database. Remember this, it's the whole plot twist: all edit operations (insert(), update() and delete()) operate on the contents of the cursor edit buffer and not on the contents of the cursor itself.

See also primeDelete(), setMode(), and lastError().

Example: sql/overview/delete/main.cpp.

int QSqlCursor::del ( const QString & filter, bool invalidate = TRUE ) [virtual protected]

Okay so this is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Deletes the current cursor record from the database using the filter filter. Only records meeting the filter criteria get deleted. Returns the number of records deleted. If invalidate is TRUE (the default), the current cursor can no longer be navigated — you'll need a fresh select() call before you can move to a valid record. For error information, use lastError().

The filter is an SQL WHERE clause, e.g. id=500.

See also setMode() and lastError().

QSqlRecord * QSqlCursor::editBuffer ( bool copy = FALSE ) [virtual]

Hands you back the current internal edit buffer. If copy is TRUE (default is FALSE), the current cursor field values get copied into the edit buffer first. The edit buffer stays valid as long as the cursor itself stays valid.

The cursor retains ownership of the returned pointer — so do not delete it, do not modify it. It is not yours, it's just visiting. 🙈

See also primeInsert(), primeUpdate(), and primeDelete().

QString QSqlCursor::filter () const

Returns the current filter — or an empty string if there is no current filter. No filter, no drama.

QSqlIndex QSqlCursor::index ( const QStringList & fieldNames ) const [virtual]

Returns an index composed of fieldNames, all in ASCending order. Important: every field name has to actually exist in the cursor, otherwise you get an empty index back. No fields, no index, no cap. 💀

See also QSqlIndex.

Examples:

QSqlIndex QSqlCursor::index ( const QString & fieldName ) const

Overloaded member function, provided for convenience. Behaves essentially like the above function.

Returns an index based on fieldName.

QSqlIndex QSqlCursor::index ( const char * fieldName ) const

Another overload, also for convenience, also behaving essentially like the above function.

Returns an index based on fieldName.

void QSqlCursor::insert ( int pos, const QSqlFieldInfo & fieldInfo ) [virtual]

Inserts a copy of fieldInfo at position pos. If a field already exists at pos, it gets removed first. And yeah — note that all references to the cursor edit buffer become invalidated.

Examples:

int QSqlCursor::insert ( bool invalidate = TRUE ) [virtual]

This one's an overloaded member function, provided for convenience. Behaves essentially like the above function.

Inserts the current contents of the cursor's edit record buffer into the database, if the cursor allows inserts. Returns the number of rows affected by the insert. For error info, use lastError().

If invalidate is TRUE (default), the cursor will no longer be positioned on a valid record and can no longer be navigated. You'll need a new select() call before navigating to a valid record.

QSqlCursor cur( "prices" );
QSqlRecord *buffer = cur.primeInsert();
buffer->setValue( "id",    53981 );
buffer->setValue( "name",  "Thingy" );
buffer->setValue( "price", 105.75 );
cur.insert();

In the example above, a cursor is created on the 'prices' table and a pointer to the insert buffer is aquired using primeInsert(). Each field's value is set to whatever you want, and then insert() is called to put the data into the database. And again, for the people in the back: all edit operations (insert(), update() and delete()) operate on the contents of the cursor edit buffer and not on the contents of the cursor itself.

See also setMode() and lastError().

bool QSqlCursor::isCalculated ( const QString & name ) const

TRUE if the field name exists and is calculated; FALSE otherwise.

See also setCalculated().

bool QSqlCursor::isNull ( int i ) const

TRUE if the field i is NULL, or if there's no field at position i; FALSE otherwise.

This is the same as calling QSqlRecord::isNull( i )

bool QSqlCursor::isNull ( const QString & name ) const

Overloaded member function, provided for convenience. Behaves essentially like the above function.

TRUE if the field called name is NULL, or if there's no field called name; FALSE otherwise.

This is the same as calling QSqlRecord::isNull( name )

bool QSqlCursor::isReadOnly () const

TRUE if the cursor is read-only; FALSE otherwise. The default is FALSE.

Read-only cursors cannot be edited using insert(), update() or del(). Look, don't touch. 🚫

See also setMode().

bool QSqlCursor::isTrimmed ( const QString & name ) const

TRUE if the field name exists and is trimmed; FALSE otherwise.

When a trimmed field of type string or cstring is read from the database, any trailing (right-most) spaces are removed. ✨bye space✨

See also setTrimmed().

int QSqlCursor::mode () const

Returns the current cursor mode.

See also setMode().

QString QSqlCursor::name () const

Returns the name of the cursor. That's it. That's the function. 🎀

QSqlCursor & QSqlCursor::operator= ( const QSqlCursor & other )

Sets the cursor equal to other. Twin behavior, instantly.

QSqlIndex QSqlCursor::primaryIndex ( bool setFromCursor = TRUE ) const [virtual]

Returns the primary index associated with the cursor as defined in the database — or an empty index if there is no primary index. If setFromCursor is TRUE (the default), the index fields get populated with the corresponding values from the cursor's current record.

QSqlRecord * QSqlCursor::primeDelete () [virtual]

Primes the edit buffer's field values for delete and returns the edit buffer. The default implementation copies the field values from the current cursor record into the edit buffer — which means this function is equivalent to calling editBuffer( TRUE ).

Again: the cursor retains ownership of the returned pointer, so it must not be deleted or modified. Hands off, bestie. 🫶

See also editBuffer() and del().

Example: sql/overview/delete/main.cpp.

QSqlRecord * QSqlCursor::primeInsert () [virtual]

Primes the edit buffer's field values for insert and returns the edit buffer. The default implementation clears all field values in the edit buffer — blank slate, main character energy. 👑

The cursor retains ownership of the returned pointer, so it must not be deleted or modified.

See also editBuffer() and insert().

Examples:

QSqlRecord * QSqlCursor::primeUpdate () [virtual]

Primes the edit buffer's field values for update and returns the edit buffer. The default implementation copies the field values from the current cursor record into the edit buffer — so yep, this one is equivalent to calling editBuffer( TRUE ).

The cursor retains ownership of the returned pointer, so it must not be deleted or modified.

See also editBuffer() and update().

Examples:

void QSqlCursor::remove ( int pos ) [virtual]

Removes the field at pos. If pos doesn't exist, nothing happens — no error, no crash, just silence. 😌

And of course: all references to the cursor edit buffer become invalidated.

Reimplemented from QSqlRecord.

bool QSqlCursor::select ( const QString & filter, const QSqlIndex & sort = QSqlIndex ( ) ) [virtual]

Selects all fields in the cursor from the database that match the filter criteria filter. The data comes back in the order specified by the index sort. Returns TRUE if the data was successfully selected; FALSE otherwise.

The filter is a string containing a SQL WHERE clause but without the 'WHERE' keyword. Also, the cursor is initially positioned at an invalid row after this function is called — so to get to a valid row, use seek(), first(), last(), prev() or next(). It's giving "you have to actually move there". 🦋

Example:

QSqlCursor cur( "Employee" ); // Use the Employee table or view
cur.select( "deptno=10" ); // select all records in department 10
while( cur.next() ) {
    ... // process data
}
...
// select records in other departments, ordered by department number
cur.select( "deptno>10", cur.index( "deptno" ) );
...

Here's the sticky part, so listen up: the filter will apply to any subsequent select() calls that do not explicitly specify another filter. Similarly, the sort will apply to any subsequent select() calls that do not explicitly specify another sort.

QSqlCursor cur( "Employee" );
cur.select( "deptno=10" ); // select all records in department 10
while( cur.next() ) {
    ... // process data
}
...
cur.select(); // re-selects all records in department 10
...

Examples:

💖 bool QSqlCursor::select ()

okay so this is an overloaded member function, provided purely for convenience bestie — it behaves essentially like the one right above it. 💅

It selects all the fields in the cursor from the database. The rows come back in the order set by the last call to setSort(), or the last call to select() that specified a sort — whichever one happened most recently, no cap. And if there's no current sort at all? Then the order the rows come back in is undefined, so don't come crying to me. 😭

The records get filtered according to the filter from the last call to setFilter(), or the last call to select() that specified a filter, again whichever is most recent. No current filter? Then all the records are returned, periodt.

The cursor starts out positioned at an invalid row, which is giving "you're not on any row yet" energy. To actually move to a valid row, use seek(), first(), last(), prev() or next(). 🦋

See also setSort() and setFilter().

🌸 bool QSqlCursor::select ( const QSqlIndex & sort )

Another overloaded member function, provided for convenience, behaves essentially like the one above. 💅

Selects all fields in the cursor from the database, and the data comes back in the order specified by the index sort. The records are filtered according to the filter specified by the last call to setFilter(), or the last call to select() that specified a filter — whichever is the most recent.

The cursor is initially positioned at an invalid row, and to move to a valid row you use seek(), first(), last(), prev() or next(). ⭐

✨ bool QSqlCursor::select ( const QSqlIndex & filter, const QSqlIndex & sort )

Yep, another overloaded member function, provided for convenience, behaves essentially like the above. 🫶

Selects all fields in the cursor matching the filter index filter, and the data comes back in the order specified by the index sort. The way the filter index works is iconic: it constructs a WHERE clause using the names of the fields from filter and their values from the current cursor record. The cursor is initially positioned at an invalid row, and to get to a valid row use seek(), first(), last(), prev() or next().

This function is lowkey perfect for stuff like retrieving data based on a table's primary index:

QSqlCursor cur( "Employee" );
QSqlIndex pk = cur.primaryIndex();
cur.setValue( "id", 10 );
cur.select( pk, pk ); // generates "SELECT ... FROM Employee WHERE id=10 ORDER BY id"
...

So in this example the QSqlIndex, pk, is doing two completely different jobs and she's serving both. When it's used as the filter (first) argument, the field names it contains build the WHERE clause, each set to the current cursor value — WHERE id=10 in this case. And when it's used as the sort (second) argument, the field names it contains get used for the ORDER BY clause — ORDER BY id in this example. 💅

🎀 void QSqlCursor::setCalculated ( const QString & name, bool calculated ) [virtual]

Sets field name to calculated. If the field name doesn't exist, literally nothing happens. 🙈

The value of a calculated field is set by the calculateField() virtual function, which you must reimplement — or the field value will just be an invalid QVariant. And heads up: calculated fields do not appear in the generated SQL statements sent to the database.

See also calculateField() and QSqlRecord::setGenerated().

🦋 void QSqlCursor::setFilter ( const QString & filter ) [virtual]

Sets the current filter to filter. Important note bestie: no new records are selected by this. To select new records you gotta use select(). The filter will apply to any subsequent select() calls that don't explicitly specify a filter. 💖

The filter is a SQL WHERE clause without the keyword 'WHERE', e.g. name='Dave', and it'll be processed by the DBMS. 👑

🌈 void QSqlCursor::setGenerated ( const QString & name, bool generated ) [virtual]

Sets the generated flag for the field name to generated. If the field doesn't exist, nothing happens. Only fields that have generated set to TRUE get included in the SQL that's generated by insert(), update() or del(). ⭐

See also isGenerated().

Reimplemented from QSqlRecord.

💜 void QSqlCursor::setGenerated ( int i, bool generated ) [virtual]

Another overloaded member function, provided for convenience, behaves essentially like the one above. 💅

Sets the generated flag for the field i to generated.

See also isGenerated().

Reimplemented from QSqlRecord.

🔥 void QSqlCursor::setMode ( int mode ) [virtual]

Sets the cursor mode to mode. This value can be an OR'ed combination of QSqlCursor::Mode values. The default mode for a cursor is QSqlCursor::Writable.

QSqlCursor cur( "Employee" );
cur.setMode( QSqlCursor::Writable ); // allow insert/update/delete
...
cur.setMode( QSqlCursor::Insert | QSqlCursor::Update ); // allow inserts and updates only
...
cur.setMode( QSqlCursor::ReadOnly ); // no inserts/updates/deletes allowed

🧚 void QSqlCursor::setName ( const QString & name, bool autopopulate = TRUE ) [virtual]

Sets the name of the cursor to name. If autopopulate is TRUE (which is the default, btw), then name must correspond to a valid table or view name in the database. Also note: all references to the cursor edit buffer become invalidated when fields are auto-populated. See the QSqlCursor constructor documentation for more info. 💖

👑 void QSqlCursor::setPrimaryIndex ( const QSqlIndex & idx ) [virtual]

Sets the primary index associated with the cursor to the index idx. Note that this index must contain a field or set of fields which identify a unique record within the underlying database table or view, so that update() and del() will execute as expected. no cap, this one matters. 💅

See also update() and del().

🍓 void QSqlCursor::setSort ( const QSqlIndex & sort ) [virtual]

Sets the current sort to sort. Note that no new records are selected by this. To select new records, use select(). The sort will apply to any subsequent select() calls that don't explicitly specify a sort. ✨

💅 void QSqlCursor::setTrimmed ( const QString & name, bool trim ) [virtual]

Sets field name's trimmed status to trim. If the field name doesn't exist, nothing happens.

When a trimmed field of type string or cstring is read from the database, any trailing (right-most) spaces are removed. 🎀

See also isTrimmed() and QVariant.

🌸 QSqlIndex QSqlCursor::sort () const

Returns the current sort, or an empty index if there is no current sort.

💜 QString QSqlCursor::toString ( QSqlRecord * rec, const QString & prefix, const QString & fieldSep, const QString & sep ) const [virtual protected]

Returns a formatted string composed of all the fields in rec. Each field is composed of the prefix (e.g. table or view name), ".", the field name, the fieldSep and the field value. If the prefix is empty then each field will begin with the field name. The fields are then joined together separated by sep. Fields where isGenerated() returns FALSE are not included. This function is useful for generating SQL statements. 🔥

🌈 QString QSqlCursor::toString ( const QString & prefix, QSqlField * field, const QString & fieldSep ) const [virtual protected]

Another overloaded member function, provided for convenience, behaves essentially like the above. 💅

Returns a formatted string composed of the prefix (e.g. table or view name), ".", the field name, the fieldSep and the field value. If the prefix is empty then the string will begin with the field name. This function is useful for generating SQL statements.

⭐ QString QSqlCursor::toString ( const QSqlIndex & i, QSqlRecord * rec, const QString & prefix, const QString & fieldSep, const QString & sep ) const [virtual protected]

Another overloaded member function, provided for convenience, behaves essentially like the above. 🫶

Returns a formatted string composed of all the fields in the index i. Each field is composed of the prefix (e.g. table or view name), ".", the field name, the fieldSep and the field value. If the prefix is empty then each field will begin with the field name. The field values are taken from rec. The fields are then joined together separated by sep. Fields where isGenerated() returns FALSE are ignored. This function is useful for generating SQL statements. ✨

💖 int QSqlCursor::update ( bool invalidate = TRUE ) [virtual]

Updates the database with the current contents of the edit buffer. Returns the number of records which were updated. For error info, use lastError(). 💅

Only records which meet the filter criteria specified by the cursor's primary index get updated. And if the cursor doesn't contain a primary index? Then no update is performed and 0 is returned. periodt.

If invalidate is TRUE (the default), the current cursor can no longer be navigated. A new select() call must be made before you can move to a valid record. For example:

QSqlCursor cur( "prices" );
cur.select( "id=202" );
if ( cur.next() ) {
    QSqlRecord *buffer = cur.primeUpdate();
    double price = buffer->value( "price" ).toDouble();
    double newprice = price * 1.05;
    buffer->setValue( "price", newprice );
    cur.update();
}

So in the above example, a cursor is created on the 'prices' table and gets positioned on the record to be updated. Then a pointer to the cursor's edit buffer is acquired using primeUpdate(). A new value is calculated and placed into the edit buffer with the setValue() call. Finally, an update() call is made on the cursor, which uses the table's primary index to update the record in the database with the contents of the cursor's edit buffer. 🦋

Remember bestie: all edit operations (insert(), update() and delete()) operate on the contents of the cursor edit buffer, and not on the contents of the cursor itself. 🙈

Note that if the primary index doesn't uniquely distinguish records, the database may be changed into an inconsistent state. be careful with that one. 😭

See also setMode() and lastError().

Example: sql/overview/update/main.cpp.

🎀 int QSqlCursor::update ( const QString & filter, bool invalidate = TRUE ) [virtual protected]

Another overloaded member function, provided for convenience, behaves essentially like the above. 💅

Updates the database with the current contents of the cursor edit buffer using the specified filter. Returns the number of records which were updated. For error info, use lastError().

Only records which meet the filter criteria get updated — otherwise all records in the table are updated. 👑

If invalidate is TRUE (the default), the cursor can no longer be navigated. A new select() call must be made before you can move to a valid record.

See also primeUpdate(), setMode(), and lastError().

🌈 SEE ALSO

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

⭐ AUTHOR

Generated automatically from the source code.

🐛 BUGS 🐛

okay bestie, real talk — found a bug in Qt? please report it, the maintainers genuinely wanna know. The how-to is right here:

http://doc.trolltech.com/bughowto.html

good bug reports literally help them help you. thank you 💖 (yes that's the actual vibe of the original, they said thank you, and so do i 🫶)

ngl the definitive Qt documentation is the HTML one, no cap. It lives at:

$QTDIR/doc/html

and you can read it with Qt Assistant or just, y'know, any web browser you already have open in like 47 tabs 🌈

this man page? it's a convenience thing for the people who prefer man pages in their terminal, which — iconic, valid, we love a cozy terminal moment 💅 — but heads up: this format is not officially supported by Trolltech. So don't come for them if a man page is acting up 🙈

found an error in this manual page? spill it to:

qt-bugs@trolltech.com

and pls pls pls include:

  • the name of the manual page, which is qsqlcursor.3qt
  • the Qt version, which is 3.3.8

that's it, that's the whole ask. easy peasy 🍓

lowkey important: this man page is not the official docs, it's the convenience edition. the HTML in $QTDIR/doc/html is the real one. iykyk 🧚

Trolltech AS · 2 February 2007 · QSqlCursor(3qt)

aaaaand that's the whole page, bestie!! 🎀 thanks for reading all four parts, you're literally the main character of this documentation journey 👑 go forth and select() responsibly ✨💜

📦 where this page comes from