1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qsqlfield.h"
5#include "qdebug.h"
6
7QT_BEGIN_NAMESPACE
8
9class QSqlFieldPrivate : public QSharedData
10{
11public:
12 QSqlFieldPrivate(const QString &name,
13 QMetaType type, const QString &tableName) :
14 nm(name), table(tableName), def(QVariant()), type(type),
15 req(QSqlField::Unknown), len(-1), prec(-1), tp(-1),
16 ro(false), gen(true), autoval(false)
17 {}
18
19 bool operator==(const QSqlFieldPrivate& other) const
20 {
21 return (nm == other.nm
22 && table == other.table
23 && def == other.def
24 && type == other.type
25 && req == other.req
26 && len == other.len
27 && prec == other.prec
28 && ro == other.ro
29 && gen == other.gen
30 && autoval == other.autoval);
31 }
32
33 QString nm;
34 QString table;
35 QVariant def;
36 QMetaType type;
37 QSqlField::RequiredStatus req;
38 int len;
39 int prec;
40 int tp;
41 bool ro: 1;
42 bool gen: 1;
43 bool autoval: 1;
44};
45QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QSqlFieldPrivate)
46
47
48/*!
49 \class QSqlField
50 \brief The QSqlField class manipulates the fields in SQL database tables
51 and views.
52
53 \ingroup database
54 \ingroup shared
55 \inmodule QtSql
56
57 QSqlField represents the characteristics of a single column in a
58 database table or view, such as the data type and column name. A
59 field also contains the value of the database column, which can be
60 viewed or changed.
61
62 Field data values are stored as QVariants. Using an incompatible
63 type is not permitted. For example:
64
65 \snippet sqldatabase/sqldatabase.cpp 2
66
67 However, the field will attempt to cast certain data types to the
68 field data type where possible:
69
70 \snippet sqldatabase/sqldatabase.cpp 3
71
72 QSqlField objects are rarely created explicitly in application
73 code. They are usually accessed indirectly through \l{QSqlRecord}s
74 that already contain a list of fields. For example:
75
76 \snippet sqldatabase/sqldatabase.cpp 4
77 \dots
78 \snippet sqldatabase/sqldatabase.cpp 5
79 \snippet sqldatabase/sqldatabase.cpp 6
80
81 A QSqlField object can provide some meta-data about the field, for
82 example, its name(), variant type(), length(), precision(),
83 defaultValue(), typeID(), and its requiredStatus(),
84 isGenerated() and isReadOnly(). The field's data can be
85 checked to see if it isNull(), and its value() retrieved. When
86 editing the data can be set with setValue() or set to NULL with
87 clear().
88
89 \sa QSqlRecord
90*/
91
92/*!
93 \enum QSqlField::RequiredStatus
94
95 Specifies whether the field is required or optional.
96
97 \value Required The field must be specified when inserting records.
98 \value Optional The fields doesn't have to be specified when inserting records.
99 \value Unknown The database driver couldn't determine whether the field is required or
100 optional.
101
102 \sa requiredStatus
103*/
104
105/*!
106 \fn QSqlField::QSqlField(const QString &fieldName, QVariant::Type type, const QString &table)
107 \deprecated [6.0] Use the constructor taking a QMetaType instead.
108 \overload
109
110 Constructs an empty field called \a fieldName of variant type \a
111 type in \a table.
112*/
113
114/*!
115 \fn void QSqlField::swap(QSqlField &other)
116 \since 6.6
117 \memberswap{field}
118*/
119
120/*!
121 \since 6.0
122
123 \overload
124 Constructs an empty field called \a fieldName of type \a
125 type in \a table.
126*/
127QSqlField::QSqlField(const QString &fieldName, QMetaType type, const QString &table)
128 : val(QVariant(type, nullptr)),
129 d(new QSqlFieldPrivate(fieldName, type, table))
130{
131}
132
133/*!
134 Constructs a copy of \a other.
135*/
136
137QSqlField::QSqlField(const QSqlField &other)
138 = default;
139
140/*!
141 Sets the field equal to \a other.
142*/
143
144QSqlField& QSqlField::operator=(const QSqlField& other)
145 = default;
146
147/*! \fn bool QSqlField::operator!=(const QSqlField &other) const
148 Returns \c true if the field is unequal to \a other; otherwise returns
149 false.
150*/
151
152/*!
153 Returns \c true if the field is equal to \a other; otherwise returns
154 false.
155*/
156bool QSqlField::operator==(const QSqlField& other) const
157{
158 return ((d == other.d || *d == *other.d)
159 && val == other.val);
160}
161
162/*!
163 Destroys the object and frees any allocated resources.
164*/
165
166QSqlField::~QSqlField()
167 = default;
168
169/*!
170 Sets \l requiredStatus to \a required.
171*/
172void QSqlField::setRequiredStatus(RequiredStatus required)
173{
174 detach();
175 d->req = required;
176}
177
178/*! \fn void QSqlField::setRequired(bool required)
179
180 Sets the required status of this field to \l Required if \a
181 required is true; otherwise sets it to \l Optional.
182
183 \sa requiredStatus
184*/
185
186/*!
187 Sets \l length to \a fieldLength.
188*/
189void QSqlField::setLength(int fieldLength)
190{
191 detach();
192 d->len = fieldLength;
193}
194
195/*!
196 Sets \l precision to \a precision.
197*/
198void QSqlField::setPrecision(int precision)
199{
200 detach();
201 d->prec = precision;
202}
203
204/*!
205 \property QSqlField::defaultValue
206 \since 6.8
207
208 This property holds the default value for this field.
209 Only some database drivers supports this property. Currently
210 those are SQLite, PostgreSQL, Oracle and MySQL/MariaDB.
211*/
212
213/*!
214 Sets \l defaultValue to \a value.
215*/
216void QSqlField::setDefaultValue(const QVariant &value)
217{
218 detach();
219 d->def = value;
220}
221
222#if QT_DEPRECATED_SINCE(6, 8)
223/*!
224 \internal
225 \deprecated [6.8] This internal value is no longer used.
226*/
227void QSqlField::setSqlType(int type)
228{
229 detach();
230 d->tp = type;
231}
232#endif
233
234/*!
235 Sets \l generated to \a gen.
236*/
237void QSqlField::setGenerated(bool gen)
238{
239 detach();
240 d->gen = gen;
241}
242
243
244/*!
245 \property QSqlField::value
246 \since 6.8
247
248 This property holds the \a value as a QVariant
249
250 Setting a \a value to a read-only QSqlField is a no-op.
251 If the data type of \a value differs from the field's current
252 data type, an attempt is made to cast it to the proper type. This
253 preserves the data type of the field in the case of assignment,
254 e.g. a QString to an integer data type.
255
256 To set the value to NULL, use clear().
257*/
258
259/*!
260 \fn QVariant QSqlField::value() const
261
262 Returns the value of \l value.
263*/
264/*!
265 Sets \l value to \a value.
266*/
267void QSqlField::setValue(const QVariant& value)
268{
269 if (isReadOnly())
270 return;
271 val = value;
272}
273
274/*!
275 Clears the value of the field and sets it to NULL.
276 If the field is read-only, nothing happens.
277*/
278
279void QSqlField::clear()
280{
281 if (isReadOnly())
282 return;
283 val = QVariant(d->type, nullptr);
284}
285
286
287/*!
288 Sets \l name to \a name.
289*/
290void QSqlField::setName(const QString& name)
291{
292 detach();
293 d->nm = name;
294}
295
296/*!
297 Sets \l readOnly to \a readOnly.
298*/
299void QSqlField::setReadOnly(bool readOnly)
300{
301 detach();
302 d->ro = readOnly;
303}
304
305/*!
306 \property QSqlField::name
307
308 This property holds the name of the field.
309 This can be the column name or a user given alias.
310*/
311
312/*!
313 Returns the value of \l name.
314*/
315QString QSqlField::name() const
316{
317 return d->nm;
318}
319
320/*!
321 \property QSqlField::metaType
322 \since 6.8
323
324 This property holds the field's type as stored in the database.
325 Note that the actual value might have a different type,
326 Numerical values that are too large to store in a long
327 int or double are usually stored as strings to prevent
328 precision loss.
329
330 \sa QSqlDatabase::numericalPrecisionPolicy
331*/
332
333/*!
334 Returns the value of \l metaType.
335*/
336QMetaType QSqlField::metaType() const
337{
338 return d->type;
339}
340
341/*!
342 Sets \l metaType to \a type.
343*/
344void QSqlField::setMetaType(QMetaType type)
345{
346 detach();
347 d->type = type;
348 if (!val.isValid())
349 val = QVariant(type, nullptr);
350}
351
352/*!
353 \fn QVariant::Type QSqlField::type() const
354 \deprecated [6.0] Use metaType() instead.
355
356 Returns the field's type as stored in the database.
357 Note that the actual value might have a different type,
358 Numerical values that are too large to store in a long
359 int or double are usually stored as strings to prevent
360 precision loss.
361
362 \sa metaType
363*/
364
365/*!
366 \fn void QSqlField::setType(QVariant::Type type)
367 \deprecated [6.0] Use setMetaType() instead.
368
369 Sets the field's variant type to \a type.
370
371 \sa metaType
372*/
373
374/*!
375 \property QSqlField::readOnly
376 \since 6.8
377
378 When this property is \c true then this QSqlField cannot be modified.
379 A read-only field cannot have its value set with setValue() and
380 cannot be cleared to NULL with clear().
381*/
382
383/*!
384 Returns the value of \l readOnly.
385*/
386bool QSqlField::isReadOnly() const
387{
388 return d->ro;
389}
390
391/*!
392 Returns \c true if the field's value is NULL; otherwise returns
393 false.
394
395 \sa value
396*/
397bool QSqlField::isNull() const
398{
399 return val.isNull();
400}
401
402/*! \internal
403*/
404void QSqlField::detach()
405{
406 d.detach();
407}
408
409/*!
410 \property QSqlField::requiredStatus
411 \since 6.8
412
413 This property holds the RequiredStatus of the field.
414 An \c INSERT will fail if a required field does not have a value.
415
416 \sa RequiredStatus
417*/
418
419/*!
420 Returns the value of \l requiredStatus.
421*/
422QSqlField::RequiredStatus QSqlField::requiredStatus() const
423{
424 return d->req;
425}
426
427/*!
428 \property QSqlField::length
429 \since 6.8
430
431 This property holds the field's length.
432
433 If the value is negative, it means that the information
434 is not available from the database.
435 For strings this is the maximum number of characters the string
436 can hold; the meaning varies for other types.
437*/
438
439/*!
440 Returns the value of \l length.
441*/
442int QSqlField::length() const
443{
444 return d->len;
445}
446
447/*!
448 \property QSqlField::precision
449 \since 6.8
450
451 This property holds the field's precision; this is only meaningful
452 for numeric types.
453
454 If the returned value is negative, it means that the information
455 is not available from the database.
456*/
457/*!
458 Returns the value of \l precision.
459*/
460int QSqlField::precision() const
461{
462 return d->prec;
463}
464
465/*!
466 Sets the value of \l defaultValue.
467*/
468QVariant QSqlField::defaultValue() const
469{
470 return d->def;
471}
472
473#if QT_DEPRECATED_SINCE(6, 8)
474/*!
475 \internal
476 \deprecated [6.8] This internal value is no longer used.
477
478 Returns the type ID for the field.
479
480 If the returned value is negative, it means that the information
481 is not available from the database.
482*/
483int QSqlField::typeID() const
484{
485 return d->tp;
486}
487#endif
488
489/*!
490 \property QSqlField::generated
491 \since 6.8
492
493 This property holds the generated state. If \a generated is \c false,
494 no SQL will be generated for this field; otherwise, Qt classes such as
495 QSqlQueryModel and QSqlTableModel will generate SQL for this field.
496*/
497
498/*!
499 Returns the value of \l generated.
500*/
501bool QSqlField::isGenerated() const
502{
503 return d->gen;
504}
505
506/*!
507 Returns \c true if the field's variant type is valid; otherwise
508 returns \c false.
509*/
510bool QSqlField::isValid() const
511{
512 return d->type.isValid();
513}
514
515#ifndef QT_NO_DEBUG_STREAM
516QDebug operator<<(QDebug dbg, const QSqlField &f)
517{
518 QDebugStateSaver saver(dbg);
519 dbg.nospace();
520 dbg << "QSqlField(" << f.name() << ", " << f.metaType().name();
521 dbg << ", tableName: " << (f.tableName().isEmpty() ? QStringLiteral("(not specified)") : f.tableName());
522 if (f.length() >= 0)
523 dbg << ", length: " << f.length();
524 if (f.precision() >= 0)
525 dbg << ", precision: " << f.precision();
526 if (f.requiredStatus() != QSqlField::Unknown)
527 dbg << ", required: "
528 << (f.requiredStatus() == QSqlField::Required ? "yes" : "no");
529 dbg << ", generated: " << (f.isGenerated() ? "yes" : "no");
530 if (!f.defaultValue().isNull())
531 dbg << ", defaultValue: \"" << f.defaultValue() << '\"';
532 dbg << ", autoValue: " << f.isAutoValue()
533 << ", readOnly: " << f.isReadOnly() << ')';
534 return dbg;
535}
536#endif
537
538/*!
539 \property QSqlField::autoValue
540 \since 6.8
541
542 If the value is auto-generated by the database,
543 for example auto-increment primary key values, this value is \c true.
544
545 \note When using the ODBC driver, due to limitations in the ODBC API,
546 the \c isAutoValue() field is only populated in a QSqlField resulting from a
547 QSqlRecord obtained by executing a \c SELECT query. It is \c false in a QSqlField
548 resulting from a QSqlRecord returned from QSqlDatabase::record() or
549 QSqlDatabase::primaryIndex().
550*/
551
552/*!
553 Returns the value of \l autoValue.
554*/
555bool QSqlField::isAutoValue() const
556{
557 return d->autoval;
558}
559
560/*!
561 Sets \l autoValue to \a autoVal.
562*/
563void QSqlField::setAutoValue(bool autoVal)
564{
565 detach();
566 d->autoval = autoVal;
567}
568
569/*!
570 Sets \l tableName to \a tableName.
571*/
572void QSqlField::setTableName(const QString &tableName)
573{
574 detach();
575 d->table = tableName;
576}
577
578/*!
579 \property QSqlField::tableName
580 \since 6.8
581
582 This property holds the tableName of the field.
583
584 \note When using the QPSQL driver, due to limitations in the libpq library,
585 the \c tableName() field is not populated in a QSqlField resulting
586 from a QSqlRecord obtained by QSqlQuery::record() of a forward-only query.
587*/
588/*!
589 Returns the \l tableName.
590*/
591QString QSqlField::tableName() const
592{
593 return d->table;
594}
595
596QT_END_NAMESPACE
597
598#include "moc_qsqlfield.cpp"
599

source code of qtbase/src/sql/kernel/qsqlfield.cpp