1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtSql module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qsqlrecord.h"
45 #include "qstringlist.h"
47 #include "qsqlfield.h"
53 class QSqlRecordPrivate
57 QSqlRecordPrivate(const QSqlRecordPrivate &other);
59 inline bool contains(int index) { return index >= 0 && index < fields.count(); }
60 QString createField(int index, const QString &prefix) const;
62 QVector<QSqlField> fields;
66 QSqlRecordPrivate::QSqlRecordPrivate()
71 QSqlRecordPrivate::QSqlRecordPrivate(const QSqlRecordPrivate &other): fields(other.fields)
79 QString QSqlRecordPrivate::createField(int index, const QString &prefix) const
82 if (!prefix.isEmpty())
83 f = prefix + QLatin1Char('.');
84 f += fields.at(index).name();
90 \brief The QSqlRecord class encapsulates a database record.
96 The QSqlRecord class encapsulates the functionality and
97 characteristics of a database record (usually a row in a table or
98 view within the database). QSqlRecord supports adding and
99 removing fields as well as setting and retrieving field values.
101 The values of a record's fields' can be set by name or position
102 with setValue(); if you want to set a field to null use
103 setNull(). To find the position of a field by name use indexOf(),
104 and to find the name of a field at a particular position use
105 fieldName(). Use field() to retrieve a QSqlField object for a
106 given field. Use contains() to see if the record contains a
107 particular field name.
109 When queries are generated to be executed on the database only
110 those fields for which isGenerated() is true are included in the
113 A record can have fields added with append() or insert(), replaced
114 with replace(), and removed with remove(). All the fields can be
115 removed with clear(). The number of fields is given by count();
116 all their values can be cleared (to null) using clearValues().
118 \sa QSqlField, QSqlQuery::record()
123 Constructs an empty record.
125 \sa isEmpty(), append(), insert()
128 QSqlRecord::QSqlRecord()
130 d = new QSqlRecordPrivate();
134 Constructs a copy of \a other.
136 QSqlRecord is \l{implicitly shared}. This means you can make copies
137 of a record in \l{constant time}.
140 QSqlRecord::QSqlRecord(const QSqlRecord& other)
147 Sets the record equal to \a other.
149 QSqlRecord is \l{implicitly shared}. This means you can make copies
150 of a record in \l{constant time}.
153 QSqlRecord& QSqlRecord::operator=(const QSqlRecord& other)
155 qAtomicAssign(d, other.d);
160 Destroys the object and frees any allocated resources.
163 QSqlRecord::~QSqlRecord()
170 \fn bool QSqlRecord::operator!=(const QSqlRecord &other) const
172 Returns true if this object is not identical to \a other;
173 otherwise returns false.
179 Returns true if this object is identical to \a other (i.e., has
180 the same fields in the same order); otherwise returns false.
184 bool QSqlRecord::operator==(const QSqlRecord &other) const
186 return d->fields == other.d->fields;
190 Returns the value of the field located at position \a index in
191 the record. If \a index is out of bounds, an invalid QVariant
194 \sa fieldName() isNull()
197 QVariant QSqlRecord::value(int index) const
199 return d->fields.value(index).value();
205 Returns the value of the field called \a name in the record. If
206 field \a name does not exist an invalid variant is returned.
211 QVariant QSqlRecord::value(const QString& name) const
213 return value(indexOf(name));
217 Returns the name of the field at position \a index. If the field
218 does not exist, an empty string is returned.
223 QString QSqlRecord::fieldName(int index) const
225 return d->fields.value(index).name();
229 Returns the position of the field called \a name within the
230 record, or -1 if it cannot be found. Field names are not
231 case-sensitive. If more than one field matches, the first one is
237 int QSqlRecord::indexOf(const QString& name) const
239 QString nm = name.toUpper();
240 for (int i = 0; i < count(); ++i) {
241 if (d->fields.at(i).name().toUpper() == nm) // TODO: case-insensitive comparison
252 const QSqlField* QSqlRecord::fieldPtr(int index) const
254 if (!d->contains(index))
257 return &d->fields.at(index);
265 const QSqlField* QSqlRecord::fieldPtr(const QString& name) const
267 int i = indexOf(name);
271 return &d->fields.at(i);
276 Returns the field at position \a index. If the position is out of
277 range, an empty field is returned.
279 QSqlField QSqlRecord::field(int index) const
281 return d->fields.value(index);
285 Returns the field called \a name.
287 QSqlField QSqlRecord::field(const QString &name) const
289 return field(indexOf(name));
294 Append a copy of field \a field to the end of the record.
296 \sa insert() replace() remove()
299 void QSqlRecord::append(const QSqlField& field)
302 d->fields.append(field);
306 Inserts the field \a field at position \a pos in the record.
308 \sa append() replace() remove()
310 void QSqlRecord::insert(int pos, const QSqlField& field)
313 d->fields.insert(pos, field);
317 Replaces the field at position \a pos with the given \a field. If
318 \a pos is out of range, nothing happens.
320 \sa append() insert() remove()
323 void QSqlRecord::replace(int pos, const QSqlField& field)
325 if (!d->contains(pos))
329 d->fields[pos] = field;
333 Removes the field at position \a pos. If \a pos is out of range,
336 \sa append() insert() replace()
339 void QSqlRecord::remove(int pos)
341 if (!d->contains(pos))
345 d->fields.remove(pos);
349 Removes all the record's fields.
351 \sa clearValues() isEmpty()
354 void QSqlRecord::clear()
361 Returns true if there are no fields in the record; otherwise
364 \sa append() insert() clear()
367 bool QSqlRecord::isEmpty() const
369 return d->fields.isEmpty();
374 Returns true if there is a field in the record called \a name;
375 otherwise returns false.
378 bool QSqlRecord::contains(const QString& name) const
380 return indexOf(name) >= 0;
384 Clears the value of all fields in the record and sets each field
390 void QSqlRecord::clearValues()
393 int count = d->fields.count();
394 for (int i = 0; i < count; ++i)
395 d->fields[i].clear();
399 Sets the generated flag for the field called \a name to \a
400 generated. If the field does not exist, nothing happens. Only
401 fields that have \a generated set to true are included in the SQL
402 that is generated by QSqlQueryModel for example.
407 void QSqlRecord::setGenerated(const QString& name, bool generated)
409 setGenerated(indexOf(name), generated);
415 Sets the generated flag for the field \a index to \a generated.
420 void QSqlRecord::setGenerated(int index, bool generated)
422 if (!d->contains(index))
425 d->fields[index].setGenerated(generated);
431 Returns true if the field \a index is null or if there is no field at
432 position \a index; otherwise returns false.
434 bool QSqlRecord::isNull(int index) const
436 return d->fields.value(index).isNull();
440 Returns true if the field called \a name is null or if there is no
441 field called \a name; otherwise returns false.
445 bool QSqlRecord::isNull(const QString& name) const
447 return isNull(indexOf(name));
451 Sets the value of field \a index to null. If the field does not exist,
456 void QSqlRecord::setNull(int index)
458 if (!d->contains(index))
461 d->fields[index].clear();
467 Sets the value of the field called \a name to null. If the field
468 does not exist, nothing happens.
470 void QSqlRecord::setNull(const QString& name)
472 setNull(indexOf(name));
477 Returns true if the record has a field called \a name and this
478 field is to be generated (the default); otherwise returns false.
482 bool QSqlRecord::isGenerated(const QString& name) const
484 return isGenerated(indexOf(name));
489 Returns true if the record has a field at position \a index and this
490 field is to be generated (the default); otherwise returns false.
494 bool QSqlRecord::isGenerated(int index) const
496 return d->fields.value(index).isGenerated();
501 Returns a list of all the record's field names as a string
504 In the unlikely event that you used this function in Qt 3, you
505 can simulate it using the rest of the QSqlRecord public API.
508 QString QSqlRecord::toString(const QString& prefix, const QString& sep) const
512 for (int i = 0; i < count(); ++i) {
513 if (!d->fields.value(i).isGenerated()) {
515 pflist += sep + QLatin1Char(' ');
516 pflist += d->createField(i, prefix);
524 Returns a list of all the record's field names, each having the
527 In the unlikely event that you used this function in Qt 3, you
528 can simulate it using the rest of the QSqlRecord public API.
531 QStringList QSqlRecord::toStringList(const QString& prefix) const
534 for (int i = 0; i < count(); ++i) {
535 if (!d->fields.value(i).isGenerated())
536 s += d->createField(i, prefix);
540 #endif // QT3_SUPPORT
543 Returns the number of fields in the record.
548 int QSqlRecord::count() const
550 return d->fields.count();
554 Sets the value of the field at position \a index to \a val. If the
555 field does not exist, nothing happens.
560 void QSqlRecord::setValue(int index, const QVariant& val)
562 if (!d->contains(index))
565 d->fields[index].setValue(val);
572 Sets the value of the field called \a name to \a val. If the field
573 does not exist, nothing happens.
576 void QSqlRecord::setValue(const QString& name, const QVariant& val)
578 setValue(indexOf(name), val);
584 void QSqlRecord::detach()
589 #ifndef QT_NO_DEBUG_STREAM
590 QDebug operator<<(QDebug dbg, const QSqlRecord &r)
592 dbg << "QSqlRecord(" << r.count() << ')';
593 for (int i = 0; i < r.count(); ++i)
594 dbg << '\n' << QString::fromLatin1("%1:").arg(i, 2) << r.field(i) << r.value(i).toString();
600 \fn int QSqlRecord::position(const QString& name) const
602 Use indexOf() instead.