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
118 Swaps this field with \a other. This function is very fast and
119 never fails.
120*/
121
122/*!
123 \since 6.0
124
125 \overload
126 Constructs an empty field called \a fieldName of type \a
127 type in \a table.
128*/
129QSqlField::QSqlField(const QString &fieldName, QMetaType type, const QString &table)
130 : val(QVariant(type, nullptr)),
131 d(new QSqlFieldPrivate(fieldName, type, table))
132{
133}
134
135/*!
136 Constructs a copy of \a other.
137*/
138
139QSqlField::QSqlField(const QSqlField &other)
140 = default;
141
142/*!
143 Sets the field equal to \a other.
144*/
145
146QSqlField& QSqlField::operator=(const QSqlField& other)
147 = default;
148
149/*! \fn bool QSqlField::operator!=(const QSqlField &other) const
150 Returns \c true if the field is unequal to \a other; otherwise returns
151 false.
152*/
153
154/*!
155 Returns \c true if the field is equal to \a other; otherwise returns
156 false.
157*/
158bool QSqlField::operator==(const QSqlField& other) const
159{
160 return ((d == other.d || *d == *other.d)
161 && val == other.val);
162}
163
164/*!
165 Destroys the object and frees any allocated resources.
166*/
167
168QSqlField::~QSqlField()
169 = default;
170
171/*!
172 Sets \l requiredStatus to \a required.
173*/
174void QSqlField::setRequiredStatus(RequiredStatus required)
175{
176 detach();
177 d->req = required;
178}
179
180/*! \fn void QSqlField::setRequired(bool required)
181
182 Sets the required status of this field to \l Required if \a
183 required is true; otherwise sets it to \l Optional.
184
185 \sa requiredStatus
186*/
187
188/*!
189 Sets \l length to \a fieldLength.
190*/
191void QSqlField::setLength(int fieldLength)
192{
193 detach();
194 d->len = fieldLength;
195}
196
197/*!
198 Sets \l precision to \a precision.
199*/
200void QSqlField::setPrecision(int precision)
201{
202 detach();
203 d->prec = precision;
204}
205
206/*!
207 \property QSqlField::defaultValue
208 \since 6.8
209
210 This property holds the default value for this field.
211 Only some database drivers supports this property. Currently
212 those are SQLite, PostgreSQL, Oracle and MySQL/MariaDB.
213*/
214
215/*!
216 Sets \l defaultValue to \a value.
217*/
218void QSqlField::setDefaultValue(const QVariant &value)
219{
220 detach();
221 d->def = value;
222}
223
224#if QT_DEPRECATED_SINCE(6, 8)
225/*!
226 \internal
227 \deprecated [6.8] This internal value is no longer used.
228*/
229void QSqlField::setSqlType(int type)
230{
231 detach();
232 d->tp = type;
233}
234#endif
235
236/*!
237 Sets \l generated to \a gen.
238*/
239void QSqlField::setGenerated(bool gen)
240{
241 detach();
242 d->gen = gen;
243}
244
245
246/*!
247 \property QSqlField::value
248 \since 6.8
249
250 This property holds the \a value as a QVariant
251
252 Setting a \a value to a read-only QSqlField is a no-op.
253 If the data type of \a value differs from the field's current
254 data type, an attempt is made to cast it to the proper type. This
255 preserves the data type of the field in the case of assignment,
256 e.g. a QString to an integer data type.
257
258 To set the value to NULL, use clear().
259*/
260
261/*!
262 \fn QVariant QSqlField::value() const
263
264 Returns the value of \l value.
265*/
266/*!
267 Sets \l value to \a value.
268*/
269void QSqlField::setValue(const QVariant& value)
270{
271 if (isReadOnly())
272 return;
273 val = value;
274}
275
276/*!
277 Clears the value of the field and sets it to NULL.
278 If the field is read-only, nothing happens.
279*/
280
281void QSqlField::clear()
282{
283 if (isReadOnly())
284 return;
285 val = QVariant(d->type, nullptr);
286}
287
288
289/*!
290 Sets \l name to \a name.
291*/
292void QSqlField::setName(const QString& name)
293{
294 detach();
295 d->nm = name;
296}
297
298/*!
299 Sets \l readOnly to \a readOnly.
300*/
301void QSqlField::setReadOnly(bool readOnly)
302{
303 detach();
304 d->ro = readOnly;
305}
306
307/*!
308 \property QSqlField::name
309
310 This property holds the name of the field.
311 This can be the column name or a user given alias.
312*/
313
314/*!
315 Returns the value of \l name.
316*/
317QString QSqlField::name() const
318{
319 return d->nm;
320}
321
322/*!
323 \property QSqlField::metaType
324 \since 6.8
325
326 This property holds the field's type as stored in the database.
327 Note that the actual value might have a different type,
328 Numerical values that are too large to store in a long
329 int or double are usually stored as strings to prevent
330 precision loss.
331
332 \sa QSqlDatabase::numericalPrecisionPolicy
333*/
334
335/*!
336 Returns the value of \l metaType.
337*/
338QMetaType QSqlField::metaType() const
339{
340 return d->type;
341}
342
343/*!
344 Sets \l metaType to \a type.
345*/
346void QSqlField::setMetaType(QMetaType type)
347{
348 detach();
349 d->type = type;
350 if (!val.isValid())
351 val = QVariant(type, nullptr);
352}
353
354/*!
355 \fn QVariant::Type QSqlField::type() const
356 \deprecated [6.0] Use metaType() instead.
357
358 Returns the field's type as stored in the database.
359 Note that the actual value might have a different type,
360 Numerical values that are too large to store in a long
361 int or double are usually stored as strings to prevent
362 precision loss.
363
364 \sa metaType
365*/
366
367/*!
368 \fn void QSqlField::setType(QVariant::Type type)
369 \deprecated [6.0] Use setMetaType() instead.
370
371 Sets the field's variant type to \a type.
372
373 \sa metaType
374*/
375
376/*!
377 \property QSqlField::readOnly
378 \since 6.8
379
380 When this property is \c true then this QSqlField cannot be modified.
381 A read-only field cannot have its value set with setValue() and
382 cannot be cleared to NULL with clear().
383*/
384
385/*!
386 Returns the value of \l readOnly.
387*/
388bool QSqlField::isReadOnly() const
389{
390 return d->ro;
391}
392
393/*!
394 Returns \c true if the field's value is NULL; otherwise returns
395 false.
396
397 \sa value
398*/
399bool QSqlField::isNull() const
400{
401 return val.isNull();
402}
403
404/*! \internal
405*/
406void QSqlField::detach()
407{
408 d.detach();
409}
410
411/*!
412 \property QSqlField::requiredStatus
413 \since 6.8
414
415 This property holds the RequiredStatus of the field.
416 An \c INSERT will fail if a required field does not have a value.
417
418 \sa RequiredStatus
419*/
420
421/*!
422 Returns the value of \l requiredStatus.
423*/
424QSqlField::RequiredStatus QSqlField::requiredStatus() const
425{
426 return d->req;
427}
428
429/*!
430 \property QSqlField::length
431 \since 6.8
432
433 This property holds the field's length.
434
435 If the value is negative, it means that the information
436 is not available from the database.
437 For strings this is the maximum number of characters the string
438 can hold; the meaning varies for other types.
439*/
440
441/*!
442 Returns the value of \l length.
443*/
444int QSqlField::length() const
445{
446 return d->len;
447}
448
449/*!
450 \property QSqlField::precision
451 \since 6.8
452
453 This property holds the field's precision; this is only meaningful
454 for numeric types.
455
456 If the returned value is negative, it means that the information
457 is not available from the database.
458*/
459/*!
460 Returns the value of \l precision.
461*/
462int QSqlField::precision() const
463{
464 return d->prec;
465}
466
467/*!
468 Sets the value of \l defaultValue.
469*/
470QVariant QSqlField::defaultValue() const
471{
472 return d->def;
473}
474
475#if QT_DEPRECATED_SINCE(6, 8)
476/*!
477 \internal
478 \deprecated [6.8] This internal value is no longer used.
479
480 Returns the type ID for the field.
481
482 If the returned value is negative, it means that the information
483 is not available from the database.
484*/
485int QSqlField::typeID() const
486{
487 return d->tp;
488}
489#endif
490
491/*!
492 \property QSqlField::generated
493 \since 6.8
494
495 This property holds the generated state. If \a generated is \c false,
496 no SQL will be generated for this field; otherwise, Qt classes such as
497 QSqlQueryModel and QSqlTableModel will generate SQL for this field.
498*/
499
500/*!
501 Returns the value of \l generated.
502*/
503bool QSqlField::isGenerated() const
504{
505 return d->gen;
506}
507
508/*!
509 Returns \c true if the field's variant type is valid; otherwise
510 returns \c false.
511*/
512bool QSqlField::isValid() const
513{
514 return d->type.isValid();
515}
516
517#ifndef QT_NO_DEBUG_STREAM
518QDebug operator<<(QDebug dbg, const QSqlField &f)
519{
520 QDebugStateSaver saver(dbg);
521 dbg.nospace();
522 dbg << "QSqlField(" << f.name() << ", " << f.metaType().name();
523 dbg << ", tableName: " << (f.tableName().isEmpty() ? QStringLiteral("(not specified)") : f.tableName());
524 if (f.length() >= 0)
525 dbg << ", length: " << f.length();
526 if (f.precision() >= 0)
527 dbg << ", precision: " << f.precision();
528 if (f.requiredStatus() != QSqlField::Unknown)
529 dbg << ", required: "
530 << (f.requiredStatus() == QSqlField::Required ? "yes" : "no");
531 dbg << ", generated: " << (f.isGenerated() ? "yes" : "no");
532 if (!f.defaultValue().isNull())
533 dbg << ", defaultValue: \"" << f.defaultValue() << '\"';
534 dbg << ", autoValue: " << f.isAutoValue()
535 << ", readOnly: " << f.isReadOnly() << ')';
536 return dbg;
537}
538#endif
539
540/*!
541 \property QSqlField::autoValue
542 \since 6.8
543
544 If the value is auto-generated by the database,
545 for example auto-increment primary key values, this value is \c true.
546
547 \note When using the ODBC driver, due to limitations in the ODBC API,
548 the \c isAutoValue() field is only populated in a QSqlField resulting from a
549 QSqlRecord obtained by executing a \c SELECT query. It is \c false in a QSqlField
550 resulting from a QSqlRecord returned from QSqlDatabase::record() or
551 QSqlDatabase::primaryIndex().
552*/
553
554/*!
555 Returns the value of \l autoValue.
556*/
557bool QSqlField::isAutoValue() const
558{
559 return d->autoval;
560}
561
562/*!
563 Sets \l autoValue to \a autoVal.
564*/
565void QSqlField::setAutoValue(bool autoVal)
566{
567 detach();
568 d->autoval = autoVal;
569}
570
571/*!
572 Sets \l tableName to \a tableName.
573*/
574void QSqlField::setTableName(const QString &tableName)
575{
576 detach();
577 d->table = tableName;
578}
579
580/*!
581 \property QSqlField::tableName
582 \since 6.8
583
584 This property holds the tableName of the field.
585
586 \note When using the QPSQL driver, due to limitations in the libpq library,
587 the \c tableName() field is not populated in a QSqlField resulting
588 from a QSqlRecord obtained by QSqlQuery::record() of a forward-only query.
589*/
590/*!
591 Returns the \l tableName.
592*/
593QString QSqlField::tableName() const
594{
595 return d->table;
596}
597
598QT_END_NAMESPACE
599
600#include "moc_qsqlfield.cpp"
601

Provided by KDAB

Privacy Policy
Learn Advanced QML with KDAB
Find out more

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