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