src/sql/kernel/qsqlrecord.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/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 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  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() : ref(1)
  67 {
  68 }
  69
  70 QSqlRecordPrivate::QSqlRecordPrivate(const QSqlRecordPrivate &other): fields(other.fields), ref(1)
  71 {
  72 }
  73
  74 /*! \internal
  75     Just for compat
  76 */
  77 QString QSqlRecordPrivate::createField(int index, const QString &prefix) const
  78 {
  79     QString f;
  80     if (!prefix.isEmpty())
  81         f = prefix + QLatin1Char('.');
  82     f += fields.at(index).name();
  83     return f;
  84 }
  85
  86 /*!
  87     \class QSqlRecord
  88     \brief The QSqlRecord class encapsulates a database record.
  89
  90     \ingroup database
  91     \ingroup shared
  92     \inmodule QtSql
  93
  94     The QSqlRecord class encapsulates the functionality and
  95     characteristics of a database record (usually a row in a table or
  96     view within the database). QSqlRecord supports adding and
  97     removing fields as well as setting and retrieving field values.
  98
  99     The values of a record's fields' can be set by name or position
 100     with setValue(); if you want to set a field to null use
 101     setNull(). To find the position of a field by name use indexOf(),
 102     and to find the name of a field at a particular position use
 103     fieldName(). Use field() to retrieve a QSqlField object for a
 104     given field. Use contains() to see if the record contains a
 105     particular field name.
 106
 107     When queries are generated to be executed on the database only
 108     those fields for which isGenerated() is true are included in the
 109     generated SQL.
 110
 111     A record can have fields added with append() or insert(), replaced
 112     with replace(), and removed with remove(). All the fields can be
 113     removed with clear(). The number of fields is given by count();
 114     all their values can be cleared (to null) using clearValues().
 115
 116     \sa QSqlField, QSqlQuery::record()
 117 */
 118
 119
 120 /*!
 121     Constructs an empty record.
 122
 123     \sa isEmpty(), append(), insert()
 124 */
 125
 126 QSqlRecord::QSqlRecord()
 127 {
 128     d = new QSqlRecordPrivate();
 129 }
 130
 131 /*!
 132     Constructs a copy of \a other.
 133
 134     QSqlRecord is \l{implicitly shared}. This means you can make copies
 135     of a record in \l{constant time}.
 136 */
 137
 138 QSqlRecord::QSqlRecord(const QSqlRecord& other)
 139 {
 140     d = other.d;
 141     d->ref.ref();
 142 }
 143
 144 /*!
 145     Sets the record equal to \a other.
 146
 147     QSqlRecord is \l{implicitly shared}. This means you can make copies
 148     of a record in \l{constant time}.
 149 */
 150
 151 QSqlRecord& QSqlRecord::operator=(const QSqlRecord& other)
 152 {
 153     qAtomicAssign(d, other.d);
 154     return *this;
 155 }
 156
 157 /*!
 158     Destroys the object and frees any allocated resources.
 159 */
 160
 161 QSqlRecord::~QSqlRecord()
 162 {
 163     if (!d->ref.deref())
 164         delete d;
 165 }
 166
 167 /*!
 168     \fn bool QSqlRecord::operator!=(const QSqlRecord &other) const
 169
 170     Returns true if this object is not identical to \a other;
 171     otherwise returns false.
 172
 173     \sa operator==()
 174 */
 175
 176 /*!
 177     Returns true if this object is identical to \a other (i.e., has
 178     the same fields in the same order); otherwise returns false.
 179
 180     \sa operator!=()
 181 */
 182 bool QSqlRecord::operator==(const QSqlRecord &other) const
 183 {
 184     return d->fields == other.d->fields;
 185 }
 186
 187 /*!
 188     Returns the value of the field located at position \a index in
 189     the record. If \a index is out of bounds, an invalid QVariant
 190     is returned.
 191
 192     \sa fieldName(), isNull()
 193 */
 194
 195 QVariant QSqlRecord::value(int index) const
 196 {
 197     return d->fields.value(index).value();
 198 }
 199
 200 /*!
 201     \overload
 202
 203     Returns the value of the field called \a name in the record. If
 204     field \a name does not exist an invalid variant is returned.
 205
 206     \sa indexOf()
 207 */
 208
 209 QVariant QSqlRecord::value(const QString& name) const
 210 {
 211     return value(indexOf(name));
 212 }
 213
 214 /*!
 215     Returns the name of the field at position \a index. If the field
 216     does not exist, an empty string is returned.
 217
 218     \sa indexOf()
 219 */
 220
 221 QString QSqlRecord::fieldName(int index) const
 222 {
 223     return d->fields.value(index).name();
 224 }
 225
 226 /*!
 227     Returns the position of the field called \a name within the
 228     record, or -1 if it cannot be found. Field names are not
 229     case-sensitive. If more than one field matches, the first one is
 230     returned.
 231
 232     \sa fieldName()
 233 */
 234
 235 int QSqlRecord::indexOf(const QString& name) const
 236 {
 237     QString nm = name.toUpper();
 238     for (int i = 0; i < count(); ++i) {
 239         if (d->fields.at(i).name().toUpper() == nm) // TODO: case-insensitive comparison
 240             return i;
 241     }
 242     return -1;
 243 }
 244
 245 /*!
 246     Returns the field at position \a index. If the \a index
 247     is out of range, function returns
 248     a \l{default-constructed value}.
 249  */
 250 QSqlField QSqlRecord::field(int index) const
 251 {
 252     return d->fields.value(index);
 253 }
 254
 255 /*! \overload
 256     Returns the field called \a name.
 257  */
 258 QSqlField QSqlRecord::field(const QString &name) const
 259 {
 260     return field(indexOf(name));
 261 }
 262
 263
 264 /*!
 265     Append a copy of field \a field to the end of the record.
 266
 267     \sa insert(), replace(), remove()
 268 */
 269
 270 void QSqlRecord::append(const QSqlField& field)
 271 {
 272     detach();
 273     d->fields.append(field);
 274 }
 275
 276 /*!
 277     Inserts the field \a field at position \a pos in the record.
 278
 279     \sa append(), replace(), remove()
 280  */
 281 void QSqlRecord::insert(int pos, const QSqlField& field)
 282 {
 283    detach();
 284    d->fields.insert(pos, field);
 285 }
 286
 287 /*!
 288     Replaces the field at position \a pos with the given \a field. If
 289     \a pos is out of range, nothing happens.
 290
 291     \sa append(), insert(), remove()
 292 */
 293
 294 void QSqlRecord::replace(int pos, const QSqlField& field)
 295 {
 296     if (!d->contains(pos))
 297         return;
 298
 299     detach();
 300     d->fields[pos] = field;
 301 }
 302
 303 /*!
 304     Removes the field at position \a pos. If \a pos is out of range,
 305     nothing happens.
 306
 307     \sa append(), insert(), replace()
 308 */
 309
 310 void QSqlRecord::remove(int pos)
 311 {
 312     if (!d->contains(pos))
 313         return;
 314
 315     detach();
 316     d->fields.remove(pos);
 317 }
 318
 319 /*!
 320     Removes all the record's fields.
 321
 322     \sa clearValues(), isEmpty()
 323 */
 324
 325 void QSqlRecord::clear()
 326 {
 327     detach();
 328     d->fields.clear();
 329 }
 330
 331 /*!
 332     Returns true if there are no fields in the record; otherwise
 333     returns false.
 334
 335     \sa append(), insert(), clear()
 336 */
 337
 338 bool QSqlRecord::isEmpty() const
 339 {
 340     return d->fields.isEmpty();
 341 }
 342
 343
 344 /*!
 345     Returns true if there is a field in the record called \a name;
 346     otherwise returns false.
 347 */
 348
 349 bool QSqlRecord::contains(const QString& name) const
 350 {
 351     return indexOf(name) >= 0;
 352 }
 353
 354 /*!
 355     Clears the value of all fields in the record and sets each field
 356     to null.
 357
 358     \sa setValue()
 359 */
 360
 361 void QSqlRecord::clearValues()
 362 {
 363     detach();
 364     int count = d->fields.count();
 365     for (int i = 0; i < count; ++i)
 366         d->fields[i].clear();
 367 }
 368
 369 /*!
 370     Sets the generated flag for the field called \a name to \a
 371     generated. If the field does not exist, nothing happens. Only
 372     fields that have \a generated set to true are included in the SQL
 373     that is generated by QSqlQueryModel for example.
 374
 375     \sa isGenerated()
 376 */
 377
 378 void QSqlRecord::setGenerated(const QString& name, bool generated)
 379 {
 380     setGenerated(indexOf(name), generated);
 381 }
 382
 383 /*!
 384     \overload
 385
 386     Sets the generated flag for the field \a index to \a generated.
 387
 388     \sa isGenerated()
 389 */
 390
 391 void QSqlRecord::setGenerated(int index, bool generated)
 392 {
 393     if (!d->contains(index))
 394         return;
 395     detach();
 396     d->fields[index].setGenerated(generated);
 397 }
 398
 399 /*!
 400     \overload
 401
 402     Returns true if the field \a index is null or if there is no field at
 403     position \a index; otherwise returns false.
 404 */
 405 bool QSqlRecord::isNull(int index) const
 406 {
 407     return d->fields.value(index).isNull();
 408 }
 409
 410 /*!
 411     Returns true if the field called \a name is null or if there is no
 412     field called \a name; otherwise returns false.
 413
 414     \sa setNull()
 415 */
 416 bool QSqlRecord::isNull(const QString& name) const
 417 {
 418     return isNull(indexOf(name));
 419 }
 420
 421 /*!
 422     Sets the value of field \a index to null. If the field does not exist,
 423     nothing happens.
 424
 425     \sa setValue()
 426 */
 427 void QSqlRecord::setNull(int index)
 428 {
 429     if (!d->contains(index))
 430         return;
 431     detach();
 432     d->fields[index].clear();
 433 }
 434
 435 /*!
 436     \overload
 437
 438     Sets the value of the field called \a name to null. If the field
 439     does not exist, nothing happens.
 440 */
 441 void QSqlRecord::setNull(const QString& name)
 442 {
 443     setNull(indexOf(name));
 444 }
 445
 446
 447 /*!
 448     Returns true if the record has a field called \a name and this
 449     field is to be generated (the default); otherwise returns false.
 450
 451     \sa setGenerated()
 452 */
 453 bool QSqlRecord::isGenerated(const QString& name) const
 454 {
 455     return isGenerated(indexOf(name));
 456 }
 457
 458 /*! \overload
 459
 460     Returns true if the record has a field at position \a index and this
 461     field is to be generated (the default); otherwise returns false.
 462
 463     \sa setGenerated()
 464 */
 465 bool QSqlRecord::isGenerated(int index) const
 466 {
 467     return d->fields.value(index).isGenerated();
 468 }
 469
 470 /*!
 471     Returns the number of fields in the record.
 472
 473     \sa isEmpty()
 474 */
 475
 476 int QSqlRecord::count() const
 477 {
 478     return d->fields.count();
 479 }
 480
 481 /*!
 482     Sets the value of the field at position \a index to \a val. If the
 483     field does not exist, nothing happens.
 484
 485     \sa setNull()
 486 */
 487
 488 void QSqlRecord::setValue(int index, const QVariant& val)
 489 {
 490     if (!d->contains(index))
 491         return;
 492     detach();
 493     d->fields[index].setValue(val);
 494 }
 495
 496
 497 /*!
 498     \overload
 499
 500     Sets the value of the field called \a name to \a val. If the field
 501     does not exist, nothing happens.
 502 */
 503
 504 void QSqlRecord::setValue(const QString& name, const QVariant& val)
 505 {
 506     setValue(indexOf(name), val);
 507 }
 508
 509
 510 /*! \internal
 511 */
 512 void QSqlRecord::detach()
 513 {
 514     qAtomicDetach(d);
 515 }
 516
 517 #ifndef QT_NO_DEBUG_STREAM
 518 QDebug operator<<(QDebug dbg, const QSqlRecord &r)
 519 {
 520     dbg << "QSqlRecord(" << r.count() << ')';
 521     for (int i = 0; i < r.count(); ++i)
 522         dbg << '\n' << QString::fromLatin1("%1:").arg(i, 2) << r.field(i) << r.value(i).toString();
 523     return dbg;
 524 }
 525 #endif
 526
 527 QT_END_NAMESPACE