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

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