The QSqlField class manipulates the fields in SQL database tables and views. More...

#include <qsqlfield.h>

Collaboration diagram for QSqlField:

Public Types
enum	RequiredStatus { Unknown = -1 , Optional = 0 , Required = 1 }
	Specifies whether the field is required or optional. More...

Public Member Functions
	QSqlField (const QString &fieldName=QString(), QMetaType type=QMetaType(), const QString &tableName=QString())

	QSqlField (const QSqlField &other)
	Constructs a copy of other.

QSqlField &	operator= (const QSqlField &other)
	Sets the field equal to other.

	QSqlField (QSqlField &&other) noexcept=default

	~QSqlField ()
	Destroys the object and frees any allocated resources.

void	swap (QSqlField &other) noexcept

bool	operator== (const QSqlField &other) const
	Returns `true` if the field is equal to other; otherwise returns false.

bool	operator!= (const QSqlField &other) const
	Returns `true` if the field is unequal to other; otherwise returns false.

void	setValue (const QVariant &value)
	Sets \l value to value.

QVariant	value () const
	Returns the value of \l value.

void	setName (const QString &name)
	Sets \l name to name.

QString	name () const
	Returns the value of \l name.

void	setTableName (const QString &tableName)
	Sets \l tableName to tableName.

QString	tableName () const
	Returns the \l tableName.

bool	isNull () const
	Returns `true` if the field's value is NULL; otherwise returns false.

void	setReadOnly (bool readOnly)
	Sets \l readOnly to readOnly.

bool	isReadOnly () const
	Returns the value of \l readOnly.

void	clear ()
	Clears the value of the field and sets it to NULL.

bool	isAutoValue () const
	Returns the value of \l autoValue.

QMetaType	metaType () const
	Returns the value of \l metaType.

void	setMetaType (QMetaType type)
	Sets \l metaType to type.

void	setRequiredStatus (RequiredStatus status)
	Sets \l requiredStatus to required.

void	setRequired (bool required)
	Sets the required status of this field to \l Required if required is true; otherwise sets it to \l Optional.

void	setLength (int fieldLength)
	Sets \l length to fieldLength.

void	setPrecision (int precision)
	Sets \l precision to precision.

void	setDefaultValue (const QVariant &value)
	Sets \l defaultValue to value.

void	setGenerated (bool gen)
	Sets \l generated to gen.

void	setAutoValue (bool autoVal)
	Sets \l autoValue to autoVal.

RequiredStatus	requiredStatus () const
	Returns the value of \l requiredStatus.

int	length () const
	Returns the value of \l length.

int	precision () const
	Returns the value of \l precision.

QVariant	defaultValue () const
	Sets the value of \l defaultValue.

bool	isGenerated () const
	Returns the value of \l generated.

bool	isValid () const
	Returns `true` if the field's variant type is valid; otherwise returns `false`.

Properties
QVariant	value

QVariant	defaultValue

QString	name
	This property holds the name of the field.

QString	tableName

QMetaType	metaType

RequiredStatus	requiredStatus

bool	readOnly

bool	generated

bool	autoValue

int	length

int	precision

Detailed Description

The QSqlField class manipulates the fields in SQL database tables and views.

\inmodule QtSql

QSqlField represents the characteristics of a single column in a database table or view, such as the data type and column name. A field also contains the value of the database column, which can be viewed or changed.

Field data values are stored as QVariants. Using an incompatible type is not permitted. For example:

QSqlField field("age", QMetaType::fromType<int>());

field.setValue(QPixmap()); // WRONG

However, the field will attempt to cast certain data types to the field data type where possible:

QSqlField field("age", QMetaType::fromType<int>());

field.setValue(QString("123")); // casts QString to int

QSqlField objects are rarely created explicitly in application code. They are usually accessed indirectly through \l{QSqlRecord}s that already contain a list of fields. For example:

\dots

A QSqlField object can provide some meta-data about the field, for example, its name(), variant type(), length(), precision(), defaultValue(), typeID(), and its requiredStatus(), isGenerated() and isReadOnly(). The field's data can be checked to see if it isNull(), and its value() retrieved. When editing the data can be set with setValue() or set to NULL with clear().

See also: QSqlRecord

Definition at line 18 of file qsqlfield.h.

Member Enumeration Documentation

◆ RequiredStatus

enum QSqlField::RequiredStatus

Specifies whether the field is required or optional.

\value Required The field must be specified when inserting records. \value Optional The fields doesn't have to be specified when inserting records. \value Unknown The database driver couldn't determine whether the field is required or optional.

See also: requiredStatus

Enumerator
Unknown
Optional
Required

Definition at line 22 of file qsqlfield.h.

Constructor & Destructor Documentation

◆ QSqlField() [1/3]

QSqlField::QSqlField	(	const QString &	fieldName = QString(),
		QMetaType	type = QMetaType(),
		const QString &	table = QString() )

explicit

Since: 6.0

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Constructs an empty field called fieldName of type type in table.

Definition at line 129 of file qsqlfield.cpp.

◆ QSqlField() [2/3]

QSqlField::QSqlField ( const QSqlField & other )

default

Constructs a copy of other.

◆ QSqlField() [3/3]

QSqlField::QSqlField ( QSqlField && other )

defaultnoexcept

◆ ~QSqlField()

QSqlField::~QSqlField ( )

default

Destroys the object and frees any allocated resources.

Member Function Documentation

◆ clear()

void QSqlField::clear ( )

Clears the value of the field and sets it to NULL.

If the field is read-only, nothing happens.

Definition at line 281 of file qsqlfield.cpp.

References isReadOnly(), and QSqlFieldPrivate::type.

Here is the call graph for this function:

◆ defaultValue()

QVariant QSqlField::defaultValue ( ) const

Sets the value of \l defaultValue.

Definition at line 470 of file qsqlfield.cpp.

References QSqlFieldPrivate::def.

◆ isAutoValue()

bool QSqlField::isAutoValue ( ) const

Returns the value of \l autoValue.

Definition at line 557 of file qsqlfield.cpp.

References QSqlFieldPrivate::autoval.

◆ isGenerated()

bool QSqlField::isGenerated ( ) const

Returns the value of \l generated.

Definition at line 503 of file qsqlfield.cpp.

References QSqlFieldPrivate::gen.

Referenced by QSqlRecord::isGenerated().

Here is the caller graph for this function:

◆ isNull()

bool QSqlField::isNull ( ) const

Returns true if the field's value is NULL; otherwise returns false.

See also: value

Definition at line 399 of file qsqlfield.cpp.

Referenced by QDB2Driver::formatValue(), QMYSQLDriver::formatValue(), QODBCDriver::formatValue(), QPSQLDriver::formatValue(), QSqlDriver::formatValue(), and QSqlRecord::isNull().

Here is the caller graph for this function:

◆ isReadOnly()

bool QSqlField::isReadOnly ( ) const

Returns the value of \l readOnly.

Definition at line 388 of file qsqlfield.cpp.

References QSqlFieldPrivate::ro.

Referenced by clear(), and setValue().

Here is the caller graph for this function:

◆ isValid()

bool QSqlField::isValid ( ) const

Returns true if the field's variant type is valid; otherwise returns false.

Definition at line 512 of file qsqlfield.cpp.

References QMetaType::isValid(), and QSqlFieldPrivate::type.

Here is the call graph for this function:

◆ length()

int QSqlField::length ( ) const

Returns the value of \l length.

Definition at line 444 of file qsqlfield.cpp.

References QSqlFieldPrivate::len.

◆ metaType()

QMetaType QSqlField::metaType ( ) const

Returns the value of \l metaType.

Definition at line 338 of file qsqlfield.cpp.

References QSqlFieldPrivate::type.

◆ name()

QString QSqlField::name ( ) const

Returns the value of \l name.

Definition at line 317 of file qsqlfield.cpp.

References QSqlFieldPrivate::nm.

◆ operator!=()

bool QSqlField::operator!= ( const QSqlField & other ) const

inline

Returns true if the field is unequal to other; otherwise returns false.

Definition at line 47 of file qsqlfield.h.

References operator==(), and other().

Here is the call graph for this function:

◆ operator=()

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

default

Sets the field equal to other.

◆ operator==()

bool QSqlField::operator== ( const QSqlField & other ) const

Returns true if the field is equal to other; otherwise returns false.

Definition at line 158 of file qsqlfield.cpp.

References other().

Here is the call graph for this function:

◆ precision()

int QSqlField::precision ( ) const

Returns the value of \l precision.

Definition at line 462 of file qsqlfield.cpp.

References QSqlFieldPrivate::prec.

◆ requiredStatus()

QSqlField::RequiredStatus QSqlField::requiredStatus ( ) const

Returns the value of \l requiredStatus.

Definition at line 424 of file qsqlfield.cpp.

References QSqlFieldPrivate::req.

◆ setAutoValue()

void QSqlField::setAutoValue ( bool autoVal )

Sets \l autoValue to autoVal.

Definition at line 565 of file qsqlfield.cpp.

References QSqlFieldPrivate::autoval.

◆ setDefaultValue()

void QSqlField::setDefaultValue ( const QVariant & value )

Sets \l defaultValue to value.

Definition at line 218 of file qsqlfield.cpp.

References QSqlFieldPrivate::def, and value.

◆ setGenerated()

void QSqlField::setGenerated ( bool gen )

Sets \l generated to gen.

Definition at line 239 of file qsqlfield.cpp.

References QSqlFieldPrivate::gen.

Referenced by QSqlQueryModel::insertColumns().

Here is the caller graph for this function:

◆ setLength()

void QSqlField::setLength ( int fieldLength )

Sets \l length to fieldLength.

Definition at line 191 of file qsqlfield.cpp.

References QSqlFieldPrivate::len.

◆ setMetaType()

void QSqlField::setMetaType ( QMetaType type )

Sets \l metaType to type.

Definition at line 346 of file qsqlfield.cpp.

References QSqlFieldPrivate::type.

Referenced by qCreateParamString(), and QMimerSQLResult::record().

Here is the caller graph for this function:

◆ setName()

void QSqlField::setName ( const QString & name )

Sets \l name to name.

Definition at line 292 of file qsqlfield.cpp.

References name, and QSqlFieldPrivate::nm.

Referenced by QMimerSQLResult::record(), and QPSQLResult::record().

Here is the caller graph for this function:

◆ setPrecision()

void QSqlField::setPrecision ( int precision )

Sets \l precision to precision.

Definition at line 200 of file qsqlfield.cpp.

References QSqlFieldPrivate::prec, and precision.

Referenced by QMimerSQLDriver::record().

Here is the caller graph for this function:

◆ setReadOnly()

void QSqlField::setReadOnly ( bool readOnly )

Sets \l readOnly to readOnly.

Definition at line 301 of file qsqlfield.cpp.

References readOnly, and QSqlFieldPrivate::ro.

Referenced by QSqlQueryModel::insertColumns().

Here is the caller graph for this function:

◆ setRequired()

void QSqlField::setRequired ( bool required )

inline

Sets the required status of this field to \l Required if required is true; otherwise sets it to \l Optional.

See also: requiredStatus

Definition at line 80 of file qsqlfield.h.

References Required.

Referenced by QMimerSQLDriver::record().

Here is the caller graph for this function:

◆ setRequiredStatus()

void QSqlField::setRequiredStatus ( RequiredStatus status )

Sets \l requiredStatus to required.

Definition at line 174 of file qsqlfield.cpp.

References QSqlFieldPrivate::req.

◆ setTableName()

void QSqlField::setTableName ( const QString & tableName )

Sets \l tableName to tableName.

Definition at line 574 of file qsqlfield.cpp.

References QSqlFieldPrivate::table, and tableName.

◆ setValue()

void QSqlField::setValue ( const QVariant & value )

Sets \l value to value.

Definition at line 269 of file qsqlfield.cpp.

References isReadOnly(), and value.

Referenced by QSqlField_snippets(), and QMimerSQLResult::record().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ swap()

void QSqlField::swap ( QSqlField & other )

inlinenoexcept

Since: 6.6

Swaps this field with other. This function is very fast and never fails.

Definition at line 44 of file qsqlfield.h.

References d, other(), and swap().

Referenced by swap().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ tableName()

QString QSqlField::tableName ( ) const

Returns the \l tableName.

Definition at line 593 of file qsqlfield.cpp.

References QSqlFieldPrivate::table.

◆ value()

QVariant QSqlField::value ( ) const

inline

Returns the value of \l value.

Definition at line 50 of file qsqlfield.h.

Property Documentation

◆ autoValue

QSqlField::autoValue

readwrite

Since: 6.8

If the value is auto-generated by the database, for example auto-increment primary key values, this value is true.

Note: When using the ODBC driver, due to limitations in the ODBC API, the isAutoValue() field is only populated in a QSqlField resulting from a QSqlRecord obtained by executing a SELECT query. It is false in a QSqlField resulting from a QSqlRecord returned from QSqlDatabase::record() or QSqlDatabase::primaryIndex().

Definition at line 32 of file qsqlfield.h.

◆ defaultValue

QSqlField::defaultValue

readwrite

Since: 6.8

This property holds the default value for this field. Only some database drivers supports this property. Currently those are SQLite, PostgreSQL, Oracle and MySQL/MariaDB.

Definition at line 25 of file qsqlfield.h.

◆ generated

QSqlField::generated

readwrite

Since: 6.8

This property holds the generated state. If generated is false, no SQL will be generated for this field; otherwise, Qt classes such as QSqlQueryModel and QSqlTableModel will generate SQL for this field.

Definition at line 31 of file qsqlfield.h.

◆ length

QSqlField::length

readwrite

Since: 6.8

This property holds the field's length.

If the value is negative, it means that the information is not available from the database. For strings this is the maximum number of characters the string can hold; the meaning varies for other types.

Definition at line 33 of file qsqlfield.h.

◆ metaType

QSqlField::metaType

readwrite

Since: 6.8

This property holds the field's type as stored in the database. Note that the actual value might have a different type, Numerical values that are too large to store in a long int or double are usually stored as strings to prevent precision loss.

See also: QSqlDatabase::numericalPrecisionPolicy

Definition at line 28 of file qsqlfield.h.

Referenced by QDB2Driver::formatValue(), QIBaseDriver::formatValue(), QMYSQLDriver::formatValue(), QOCIDriver::formatValue(), QODBCDriver::formatValue(), QPSQLDriver::formatValue(), QSqlDriver::formatValue(), and QMimerSQLResult::record().

◆ name

QSqlField::name

readwrite

This property holds the name of the field.

This can be the column name or a user given alias.

Definition at line 26 of file qsqlfield.h.

Referenced by QSqlRecord::fieldName(), QSqlRecord::indexOf(), and setName().

◆ precision

QSqlField::precision

readwrite

Since: 6.8

This property holds the field's precision; this is only meaningful for numeric types.

If the returned value is negative, it means that the information is not available from the database.

Definition at line 34 of file qsqlfield.h.

Referenced by QMYSQLDriver::formatValue(), and setPrecision().

◆ readOnly

QSqlField::readOnly

readwrite

Since: 6.8

When this property is true then this QSqlField cannot be modified. A read-only field cannot have its value set with setValue() and cannot be cleared to NULL with clear().

Definition at line 30 of file qsqlfield.h.

Referenced by setReadOnly().

◆ requiredStatus

QSqlField::requiredStatus

readwrite

Since: 6.8

This property holds the RequiredStatus of the field. An INSERT will fail if a required field does not have a value.

See also: RequiredStatus

Definition at line 29 of file qsqlfield.h.

◆ tableName

QSqlField::tableName

readwrite

Since: 6.8

This property holds the tableName of the field.

Note: When using the QPSQL driver, due to limitations in the libpq library, the tableName() field is not populated in a QSqlField resulting from a QSqlRecord obtained by QSqlQuery::record() of a forward-only query.

Definition at line 27 of file qsqlfield.h.

Referenced by setTableName().

◆ value

QSqlField::value

readwrite

Since: 6.8

This property holds the value as a QVariant

Setting a value to a read-only QSqlField is a no-op. If the data type of value differs from the field's current data type, an attempt is made to cast it to the proper type. This preserves the data type of the field in the case of assignment, e.g. a QString to an integer data type.

To set the value to NULL, use clear().

Definition at line 24 of file qsqlfield.h.

Referenced by QDB2Driver::formatValue(), QIBaseDriver::formatValue(), QMYSQLDriver::formatValue(), QOCIDriver::formatValue(), QODBCDriver::formatValue(), QPSQLDriver::formatValue(), QSqlDriver::formatValue(), setDefaultValue(), setValue(), and QSqlRecord::value().

The documentation for this class was generated from the following files:

qtbase/src/sql/kernel/qsqlfield.h (e65dc193327c207d71e20fa14a5dbf1a988afd60)
qtbase/src/sql/kernel/qsqlfield.cpp (90217f37caeb3102ddf728dd96378115a0769941)

Public Types

Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ RequiredStatus

Constructor & Destructor Documentation

◆ QSqlField() [1/3]

◆ QSqlField() [2/3]

◆ QSqlField() [3/3]

◆ ~QSqlField()

Member Function Documentation

◆ clear()

◆ defaultValue()

◆ isAutoValue()

◆ isGenerated()

◆ isNull()

◆ isReadOnly()

◆ isValid()

◆ length()

◆ metaType()

◆ name()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ precision()

◆ requiredStatus()

◆ setAutoValue()

◆ setDefaultValue()

◆ setGenerated()

◆ setLength()

◆ setMetaType()

◆ setName()

◆ setPrecision()

◆ setReadOnly()

◆ setRequired()

◆ setRequiredStatus()

◆ setTableName()

◆ setValue()

◆ swap()

◆ tableName()

◆ value()

Property Documentation

◆ autoValue

◆ defaultValue

◆ generated

◆ length

◆ metaType

◆ name

◆ precision

◆ readOnly

◆ requiredStatus

◆ tableName

◆ value