src/sql/kernel/qsqlrecord.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtSql module of the Qt Toolkit.
   8 **
   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.
  17 **
  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.
  21 **
  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.
  29 **
  30 ** Other Usage
  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.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qsqlrecord.h"
  43
  44 #include "qdebug.h"
  45 #include "qstringlist.h"
  46 #include "qatomic.h"
  47 #include "qsqlfield.h"
  48 #include "qstring.h"
  49 #include "qvector.h"
  50
  51 QT_BEGIN_NAMESPACE
  52
  53 class QSqlRecordPrivate
  54 {
  55 public:
  56     QSqlRecordPrivate();
  57     QSqlRecordPrivate(const QSqlRecordPrivate &other);
  58
  59     inline bool contains(int index) { return index >= 0 && index < fields.count(); }
  60     QString createField(int index, const QString &prefix) const;
  61
  62     QVector<QSqlField> fields;
  63     QAtomicInt ref;
  64 };
  65
  66 QSqlRecordPrivate::QSqlRecordPrivate()
  67 {
  68     ref = 1;
  69 }
  70
  71 QSqlRecordPrivate::QSqlRecordPrivate(const QSqlRecordPrivate &other): fields(other.fields)
  72 {
  73     ref = 1;
  74 }
  75
  76 /*! \internal
  77     Just for compat
  78 */
  79 QString QSqlRecordPrivate::createField(int index, const QString &prefix) const
  80 {
  81     QString f;
  82     if (!prefix.isEmpty())
  83         f = prefix + QLatin1Char('.');
  84     f += fields.at(index).name();
  85     return f;
  86 }
  87
  88 /*!
  89     \class QSqlRecord
  90     \brief The QSqlRecord class encapsulates a database record.
  91
  92     \ingroup database
  93     \ingroup shared
  94     \inmodule QtSql
  95
  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.
 100
 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.
 108
 109     When queries are generated to be executed on the database only
 110     those fields for which isGenerated() is true are included in the
 111     generated SQL.
 112
 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().
 117
 118     \sa QSqlField, QSqlQuery::record()
 119 */
 120
 121
 122 /*!
 123     Constructs an empty record.
 124
 125     \sa isEmpty(), append(), insert()
 126 */
 127
 128 QSqlRecord::QSqlRecord()
 129 {
 130     d = new QSqlRecordPrivate();
 131 }
 132
 133 /*!
 134     Constructs a copy of \a other.
 135
 136     QSqlRecord is \l{implicitly shared}. This means you can make copies
 137     of a record in \l{constant time}.
 138 */
 139
 140 QSqlRecord::QSqlRecord(const QSqlRecord& other)
 141 {
 142     d = other.d;
 143     d->ref.ref();
 144 }
 145
 146 /*!
 147     Sets the record equal to \a other.
 148
 149     QSqlRecord is \l{implicitly shared}. This means you can make copies
 150     of a record in \l{constant time}.
 151 */
 152
 153 QSqlRecord& QSqlRecord::operator=(const QSqlRecord& other)
 154 {
 155     qAtomicAssign(d, other.d);
 156     return *this;
 157 }
 158
 159 /*!
 160     Destroys the object and frees any allocated resources.
 161 */
 162
 163 QSqlRecord::~QSqlRecord()
 164 {
 165     if (!d->ref.deref())
 166         delete d;
 167 }
 168
 169 /*!
 170     \fn bool QSqlRecord::operator!=(const QSqlRecord &other) const
 171
 172     Returns true if this object is not identical to \a other;
 173     otherwise returns false.
 174
 175     \sa operator==()
 176 */
 177
 178 /*!
 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.
 181
 182     \sa operator!=()
 183 */
 184 bool QSqlRecord::operator==(const QSqlRecord &other) const
 185 {
 186     return d->fields == other.d->fields;
 187 }
 188
 189 /*!
 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
 192     is returned.
 193
 194     \sa fieldName() isNull()
 195 */
 196
 197 QVariant QSqlRecord::value(int index) const
 198 {
 199     return d->fields.value(index).value();
 200 }
 201
 202 /*!
 203     \overload
 204
 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.
 207
 208     \sa indexOf()
 209 */
 210
 211 QVariant QSqlRecord::value(const QString& name) const
 212 {
 213     return value(indexOf(name));
 214 }
 215
 216 /*!
 217     Returns the name of the field at position \a index. If the field
 218     does not exist, an empty string is returned.
 219
 220     \sa indexOf()
 221 */
 222
 223 QString QSqlRecord::fieldName(int index) const
 224 {
 225     return d->fields.value(index).name();
 226 }
 227
 228 /*!
 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
 232     returned.
 233
 234     \sa fieldName()
 235 */
 236
 237 int QSqlRecord::indexOf(const QString& name) const
 238 {
 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
 242             return i;
 243     }
 244     return -1;
 245 }
 246
 247 /*!
 248     Returns the field at position \a index. If the position is out of
 249     range, an empty field is returned.
 250  */
 251 QSqlField QSqlRecord::field(int index) const
 252 {
 253     return d->fields.value(index);
 254 }
 255
 256 /*! \overload
 257     Returns the field called \a name.
 258  */
 259 QSqlField QSqlRecord::field(const QString &name) const
 260 {
 261     return field(indexOf(name));
 262 }
 263
 264
 265 /*!
 266     Append a copy of field \a field to the end of the record.
 267
 268     \sa insert() replace() remove()
 269 */
 270
 271 void QSqlRecord::append(const QSqlField& field)
 272 {
 273     detach();
 274     d->fields.append(field);
 275 }
 276
 277 /*!
 278     Inserts the field \a field at position \a pos in the record.
 279
 280     \sa append() replace() remove()
 281  */
 282 void QSqlRecord::insert(int pos, const QSqlField& field)
 283 {
 284    detach();
 285    d->fields.insert(pos, field);
 286 }
 287
 288 /*!
 289     Replaces the field at position \a pos with the given \a field. If
 290     \a pos is out of range, nothing happens.
 291
 292     \sa append() insert() remove()
 293 */
 294
 295 void QSqlRecord::replace(int pos, const QSqlField& field)
 296 {
 297     if (!d->contains(pos))
 298         return;
 299
 300     detach();
 301     d->fields[pos] = field;
 302 }
 303
 304 /*!
 305     Removes the field at position \a pos. If \a pos is out of range,
 306     nothing happens.
 307
 308     \sa append() insert() replace()
 309 */
 310
 311 void QSqlRecord::remove(int pos)
 312 {
 313     if (!d->contains(pos))
 314         return;
 315
 316     detach();
 317     d->fields.remove(pos);
 318 }
 319
 320 /*!
 321     Removes all the record's fields.
 322
 323     \sa clearValues() isEmpty()
 324 */
 325
 326 void QSqlRecord::clear()
 327 {
 328     detach();
 329     d->fields.clear();
 330 }
 331
 332 /*!
 333     Returns true if there are no fields in the record; otherwise
 334     returns false.
 335
 336     \sa append() insert() clear()
 337 */
 338
 339 bool QSqlRecord::isEmpty() const
 340 {
 341     return d->fields.isEmpty();
 342 }
 343
 344
 345 /*!
 346     Returns true if there is a field in the record called \a name;
 347     otherwise returns false.
 348 */
 349
 350 bool QSqlRecord::contains(const QString& name) const
 351 {
 352     return indexOf(name) >= 0;
 353 }
 354
 355 /*!
 356     Clears the value of all fields in the record and sets each field
 357     to null.
 358
 359     \sa setValue()
 360 */
 361
 362 void QSqlRecord::clearValues()
 363 {
 364     detach();
 365     int count = d->fields.count();
 366     for (int i = 0; i < count; ++i)
 367         d->fields[i].clear();
 368 }
 369
 370 /*!
 371     Sets the generated flag for the field called \a name to \a
 372     generated. If the field does not exist, nothing happens. Only
 373     fields that have \a generated set to true are included in the SQL
 374     that is generated by QSqlQueryModel for example.
 375
 376     \sa isGenerated()
 377 */
 378
 379 void QSqlRecord::setGenerated(const QString& name, bool generated)
 380 {
 381     setGenerated(indexOf(name), generated);
 382 }
 383
 384 /*!
 385     \overload
 386
 387     Sets the generated flag for the field \a index to \a generated.
 388
 389     \sa isGenerated()
 390 */
 391
 392 void QSqlRecord::setGenerated(int index, bool generated)
 393 {
 394     if (!d->contains(index))
 395         return;
 396     detach();
 397     d->fields[index].setGenerated(generated);
 398 }
 399
 400 /*!
 401     \overload
 402
 403     Returns true if the field \a index is null or if there is no field at
 404     position \a index; otherwise returns false.
 405 */
 406 bool QSqlRecord::isNull(int index) const
 407 {
 408     return d->fields.value(index).isNull();
 409 }
 410
 411 /*!
 412     Returns true if the field called \a name is null or if there is no
 413     field called \a name; otherwise returns false.
 414
 415     \sa setNull()
 416 */
 417 bool QSqlRecord::isNull(const QString& name) const
 418 {
 419     return isNull(indexOf(name));
 420 }
 421
 422 /*!
 423     Sets the value of field \a index to null. If the field does not exist,
 424     nothing happens.
 425
 426     \sa setValue()
 427 */
 428 void QSqlRecord::setNull(int index)
 429 {
 430     if (!d->contains(index))
 431         return;
 432     detach();
 433     d->fields[index].clear();
 434 }
 435
 436 /*!
 437     \overload
 438
 439     Sets the value of the field called \a name to null. If the field
 440     does not exist, nothing happens.
 441 */
 442 void QSqlRecord::setNull(const QString& name)
 443 {
 444     setNull(indexOf(name));
 445 }
 446
 447
 448 /*!
 449     Returns true if the record has a field called \a name and this
 450     field is to be generated (the default); otherwise returns false.
 451
 452     \sa setGenerated()
 453 */
 454 bool QSqlRecord::isGenerated(const QString& name) const
 455 {
 456     return isGenerated(indexOf(name));
 457 }
 458
 459 /*! \overload
 460
 461     Returns true if the record has a field at position \a index and this
 462     field is to be generated (the default); otherwise returns false.
 463
 464     \sa setGenerated()
 465 */
 466 bool QSqlRecord::isGenerated(int index) const
 467 {
 468     return d->fields.value(index).isGenerated();
 469 }
 470
 471 /*!
 472     Returns the number of fields in the record.
 473
 474     \sa isEmpty()
 475 */
 476
 477 int QSqlRecord::count() const
 478 {
 479     return d->fields.count();
 480 }
 481
 482 /*!
 483     Sets the value of the field at position \a index to \a val. If the
 484     field does not exist, nothing happens.
 485
 486     \sa setNull()
 487 */
 488
 489 void QSqlRecord::setValue(int index, const QVariant& val)
 490 {
 491     if (!d->contains(index))
 492         return;
 493     detach();
 494     d->fields[index].setValue(val);
 495 }
 496
 497
 498 /*!
 499     \overload
 500
 501     Sets the value of the field called \a name to \a val. If the field
 502     does not exist, nothing happens.
 503 */
 504
 505 void QSqlRecord::setValue(const QString& name, const QVariant& val)
 506 {
 507     setValue(indexOf(name), val);
 508 }
 509
 510
 511 /*! \internal
 512 */
 513 void QSqlRecord::detach()
 514 {
 515     qAtomicDetach(d);
 516 }
 517
 518 #ifndef QT_NO_DEBUG_STREAM
 519 QDebug operator<<(QDebug dbg, const QSqlRecord &r)
 520 {
 521     dbg << "QSqlRecord(" << r.count() << ')';
 522     for (int i = 0; i < r.count(); ++i)
 523         dbg << '\n' << QString::fromLatin1("%1:").arg(i, 2) << r.field(i) << r.value(i).toString();
 524     return dbg;
 525 }
 526 #endif
 527
 528 /*!
 529     \fn int QSqlRecord::position(const QString& name) const
 530
 531     Use indexOf() instead.
 532 */
 533
 534 QT_END_NAMESPACE