1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 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 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qsqlfield.h"

    43 #include "qatomic.h"

    44 #include "qdebug.h"

    45 

    46 QT_BEGIN_NAMESPACE

    47 

    48 class QSqlFieldPrivate

    49 {

    50 public:

    51     QSqlFieldPrivate(const QString &name,

    52               QVariant::Type type) :

    53         ref(1), nm(name), ro(false), type(type), req(QSqlField::Unknown),

    54         len(-1), prec(-1), tp(-1), gen(true), autoval(false)

    55     {

    56     }

    57 

    58     QSqlFieldPrivate(const QSqlFieldPrivate &other)

    59         : ref(1),

    60           nm(other.nm),

    61           ro(other.ro),

    62           type(other.type),

    63           req(other.req),

    64           len(other.len),

    65           prec(other.prec),

    66           def(other.def),

    67           tp(other.tp),

    68           gen(other.gen),

    69           autoval(other.autoval)

    70     {}

    71 

    72     bool operator==(const QSqlFieldPrivate& other) const

    73     {

    74         return (nm == other.nm

    75                 && ro == other.ro

    76                 && type == other.type

    77                 && req == other.req

    78                 && len == other.len

    79                 && prec == other.prec

    80                 && def == other.def

    81                 && gen == other.gen

    82                 && autoval == other.autoval);

    83     }

    84 

    85     QAtomicInt ref;

    86     QString nm;

    87     uint ro: 1;

    88     QVariant::Type type;

    89     QSqlField::RequiredStatus req;

    90     int len;

    91     int prec;

    92     QVariant def;

    93     int tp;

    94     uint gen: 1;

    95     uint autoval: 1;

    96 };

    97 

    98 

    99 /*!

   100     \class QSqlField

   101     \brief The QSqlField class manipulates the fields in SQL database tables

   102     and views.

   103 

   104     \ingroup database

   105     \ingroup shared

   106     \inmodule QtSql

   107 

   108     QSqlField represents the characteristics of a single column in a

   109     database table or view, such as the data type and column name. A

   110     field also contains the value of the database column, which can be

   111     viewed or changed.

   112 

   113     Field data values are stored as QVariants. Using an incompatible

   114     type is not permitted. For example:

   115 

   116     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 2

   117 

   118     However, the field will attempt to cast certain data types to the

   119     field data type where possible:

   120 

   121     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 3

   122 

   123     QSqlField objects are rarely created explicitly in application

   124     code. They are usually accessed indirectly through \l{QSqlRecord}s

   125     that already contain a list of fields. For example:

   126 

   127     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 4

   128     \dots

   129     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 5

   130     \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 6

   131 

   132     A QSqlField object can provide some meta-data about the field, for

   133     example, its name(), variant type(), length(), precision(),

   134     defaultValue(), typeID(), and its requiredStatus(),

   135     isGenerated() and isReadOnly(). The field's data can be

   136     checked to see if it isNull(), and its value() retrieved. When

   137     editing the data can be set with setValue() or set to NULL with

   138     clear().

   139 

   140     \sa QSqlRecord

   141 */

   142 

   143 /*!

   144     \enum QSqlField::RequiredStatus

   145 

   146     Specifies whether the field is required or optional.

   147 

   148     \value Required  The field must be specified when inserting records.

   149     \value Optional  The fields doesn't have to be specified when inserting records.

   150     \value Unknown  The database driver couldn't determine whether the field is required or

   151                     optional.

   152 

   153     \sa requiredStatus()

   154 */

   155 

   156 /*!

   157     Constructs an empty field called \a fieldName of variant type \a

   158     type.

   159 

   160     \sa setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly()

   161 */

   162 QSqlField::QSqlField(const QString& fieldName, QVariant::Type type)

   163 {

   164     d = new QSqlFieldPrivate(fieldName, type);

   165 }

   166 

   167 /*!

   168     Constructs a copy of \a other.

   169 */

   170 

   171 QSqlField::QSqlField(const QSqlField& other)

   172 {

   173     d = other.d;

   174     d->ref.ref();

   175     val = other.val;

   176 }

   177 

   178 /*!

   179     Sets the field equal to \a other.

   180 */

   181 

   182 QSqlField& QSqlField::operator=(const QSqlField& other)

   183 {

   184     qAtomicAssign(d, other.d);

   185     val = other.val;

   186     return *this;

   187 }

   188 

   189 

   190 /*! \fn bool QSqlField::operator!=(const QSqlField &other) const

   191     Returns true if the field is unequal to \a other; otherwise returns

   192     false.

   193 */

   194 

   195 /*!

   196     Returns true if the field is equal to \a other; otherwise returns

   197     false.

   198 */

   199 bool QSqlField::operator==(const QSqlField& other) const

   200 {

   201     return ((d == other.d || *d == *other.d)

   202             && val == other.val);

   203 }

   204 

   205 /*!

   206     Destroys the object and frees any allocated resources.

   207 */

   208 

   209 QSqlField::~QSqlField()

   210 {

   211     if (!d->ref.deref())

   212         delete d;

   213 }

   214 

   215 /*!

   216     Sets the required status of this field to \a required.

   217 

   218     \sa requiredStatus() setType() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly()

   219 */

   220 void QSqlField::setRequiredStatus(RequiredStatus required)

   221 {

   222     detach();

   223     d->req = required;

   224 }

   225 

   226 /*! \fn void QSqlField::setRequired(bool required)

   227 

   228     Sets the required status of this field to \l Required if \a

   229     required is true; otherwise sets it to \l Optional.

   230 

   231     \sa setRequiredStatus(), requiredStatus()

   232 */

   233 

   234 /*!

   235     Sets the field's length to \a fieldLength. For strings this is the

   236     maximum number of characters the string can hold; the meaning

   237     varies for other types.

   238 

   239     \sa length() setType() setRequiredStatus() setPrecision() setDefaultValue() setGenerated() setReadOnly()

   240 */

   241 void QSqlField::setLength(int fieldLength)

   242 {

   243     detach();

   244     d->len = fieldLength;

   245 }

   246 

   247 /*!

   248     Sets the field's \a precision. This only affects numeric fields.

   249 

   250     \sa precision() setType() setRequiredStatus() setLength() setDefaultValue() setGenerated() setReadOnly()

   251 */

   252 void QSqlField::setPrecision(int precision)

   253 {

   254     detach();

   255     d->prec = precision;

   256 }

   257 

   258 /*!

   259     Sets the default value used for this field to \a value.

   260 

   261     \sa defaultValue() value() setType() setRequiredStatus() setLength() setPrecision() setGenerated() setReadOnly()

   262 */

   263 void QSqlField::setDefaultValue(const QVariant &value)

   264 {

   265     detach();

   266     d->def = value;

   267 }

   268 

   269 /*!

   270     \internal

   271 */

   272 void QSqlField::setSqlType(int type)

   273 {

   274     detach();

   275     d->tp = type;

   276 }

   277 

   278 /*!

   279     Sets the generated state. If \a gen is false, no SQL will

   280     be generated for this field; otherwise, Qt classes such as

   281     QSqlQueryModel and QSqlTableModel will generate SQL for this

   282     field.

   283 

   284     \sa isGenerated() setType() setRequiredStatus() setLength() setPrecision() setDefaultValue() setReadOnly()

   285 */

   286 void QSqlField::setGenerated(bool gen)

   287 {

   288     detach();

   289     d->gen = gen;

   290 }

   291 

   292 

   293 /*!

   294     Sets the value of the field to \a value. If the field is read-only

   295     (isReadOnly() returns true), nothing happens.

   296 

   297     If the data type of \a value differs from the field's current

   298     data type, an attempt is made to cast it to the proper type. This

   299     preserves the data type of the field in the case of assignment,

   300     e.g. a QString to an integer data type.

   301 

   302     To set the value to NULL, use clear().

   303 

   304     \sa value() isReadOnly() defaultValue()

   305 */

   306 

   307 void QSqlField::setValue(const QVariant& value)

   308 {

   309     if (isReadOnly())

   310         return;

   311     val = value;

   312 }

   313 

   314 /*!

   315     Clears the value of the field and sets it to NULL.

   316     If the field is read-only, nothing happens.

   317 

   318     \sa setValue() isReadOnly() requiredStatus()

   319 */

   320 

   321 void QSqlField::clear()

   322 {

   323     if (isReadOnly())

   324         return;

   325     val = QVariant(type());

   326 }

   327 

   328 /*!

   329     Sets the name of the field to \a name.

   330 

   331     \sa name()

   332 */

   333 

   334 void QSqlField::setName(const QString& name)

   335 {

   336     detach();

   337     d->nm = name;

   338 }

   339 

   340 /*!

   341     Sets the read only flag of the field's value to \a readOnly. A

   342     read-only field cannot have its value set with setValue() and

   343     cannot be cleared to NULL with clear().

   344 */

   345 void QSqlField::setReadOnly(bool readOnly)

   346 {

   347     detach();

   348     d->ro = readOnly;

   349 }

   350 

   351 /*!

   352     \fn QVariant QSqlField::value() const

   353 

   354     Returns the value of the field as a QVariant.

   355 

   356     Use isNull() to check if the field's value is NULL.

   357 */

   358 

   359 /*!

   360     Returns the name of the field.

   361 

   362     \sa setName()

   363 */

   364 QString QSqlField::name() const

   365 {

   366     return d->nm;

   367 }

   368 

   369 /*!

   370     Returns the field's type as stored in the database.

   371     Note that the actual value might have a different type,

   372     Numerical values that are too large to store in a long

   373     int or double are usually stored as strings to prevent

   374     precision loss.

   375 

   376     \sa setType()

   377 */

   378 QVariant::Type QSqlField::type() const

   379 {

   380     return d->type;

   381 }

   382 

   383 /*!

   384     Set's the field's variant type to \a type.

   385 

   386     \sa type() setRequiredStatus() setLength() setPrecision() setDefaultValue() setGenerated() setReadOnly()

   387 */

   388 void QSqlField::setType(QVariant::Type type)

   389 {

   390     detach();

   391     d->type = type;

   392 }

   393 

   394 

   395 /*!

   396     Returns true if the field's value is read-only; otherwise returns

   397     false.

   398 

   399     \sa setReadOnly() type() requiredStatus() length() precision() defaultValue() isGenerated()

   400 */

   401 bool QSqlField::isReadOnly() const

   402 { return d->ro; }

   403 

   404 /*!

   405     Returns true if the field's value is NULL; otherwise returns

   406     false.

   407 

   408     \sa value()

   409 */

   410 bool QSqlField::isNull() const

   411 { return val.isNull(); }

   412 

   413 /*! \internal

   414 */

   415 void QSqlField::detach()

   416 {

   417     qAtomicDetach(d);

   418 }

   419 

   420 /*!

   421     Returns true if this is a required field; otherwise returns false.

   422     An \c INSERT will fail if a required field does not have a value.

   423 

   424     \sa setRequiredStatus() type() length() precision() defaultValue() isGenerated()

   425 */

   426 QSqlField::RequiredStatus QSqlField::requiredStatus() const

   427 {

   428     return d->req;

   429 }

   430 

   431 /*!

   432     Returns the field's length.

   433 

   434     If the returned value is negative, it means that the information

   435     is not available from the database.

   436 

   437     \sa setLength() type() requiredStatus() precision() defaultValue() isGenerated()

   438 */

   439 int QSqlField::length() const

   440 {

   441     return d->len;

   442 }

   443 

   444 /*!

   445     Returns the field's precision; this is only meaningful for numeric

   446     types.

   447 

   448     If the returned value is negative, it means that the information

   449     is not available from the database.

   450 

   451     \sa setPrecision() type() requiredStatus() length() defaultValue() isGenerated()

   452 */

   453 int QSqlField::precision() const

   454 {

   455     return d->prec;

   456 }

   457 

   458 /*!

   459     Returns the field's default value (which may be NULL).

   460 

   461     \sa setDefaultValue() type() requiredStatus() length() precision() isGenerated()

   462 */

   463 QVariant QSqlField::defaultValue() const

   464 {

   465     return d->def;

   466 }

   467 

   468 /*!

   469     \internal

   470 

   471     Returns the type ID for the field.

   472 

   473     If the returned value is negative, it means that the information

   474     is not available from the database.

   475 */

   476 int QSqlField::typeID() const

   477 {

   478     return d->tp;

   479 }

   480 

   481 /*!

   482     Returns true if the field is generated; otherwise returns

   483     false.

   484 

   485     \sa setGenerated() type() requiredStatus() length() precision() defaultValue()

   486 */

   487 bool QSqlField::isGenerated() const

   488 {

   489     return d->gen;

   490 }

   491 

   492 /*!

   493     Returns true if the field's variant type is valid; otherwise

   494     returns false.

   495 */

   496 bool QSqlField::isValid() const

   497 {

   498     return d->type != QVariant::Invalid;

   499 }

   500 

   501 #ifndef QT_NO_DEBUG_STREAM

   502 QDebug operator<<(QDebug dbg, const QSqlField &f)

   503 {

   504 #ifndef Q_BROKEN_DEBUG_STREAM

   505     dbg.nospace() << "QSqlField(" << f.name() << ", " << QVariant::typeToName(f.type());

   506     if (f.length() >= 0)

   507         dbg.nospace() << ", length: " << f.length();

   508     if (f.precision() >= 0)

   509         dbg.nospace() << ", precision: " << f.precision();

   510     if (f.requiredStatus() != QSqlField::Unknown)

   511         dbg.nospace() << ", required: "

   512                       << (f.requiredStatus() == QSqlField::Required ? "yes" : "no");

   513     dbg.nospace() << ", generated: " << (f.isGenerated() ? "yes" : "no");

   514     if (f.typeID() >= 0)

   515         dbg.nospace() << ", typeID: " << f.typeID();

   516     if (!f.defaultValue().isNull())

   517         dbg.nospace() << ", auto-value: \"" << f.defaultValue() << '\"';

   518     dbg.nospace() << ')';

   519     return dbg.space();

   520 #else

   521     qWarning("This compiler doesn't support streaming QSqlField to QDebug");

   522     return dbg;

   523     Q_UNUSED(f);

   524 #endif

   525 }

   526 #endif

   527 

   528 /*!

   529     \fn void QSqlField::setNull()

   530 

   531     Use clear() instead.

   532 */

   533 

   534 /*!

   535     Returns true if the value is auto-generated by the database,

   536     for example auto-increment primary key values.

   537 

   538     \sa setAutoValue()

   539 */

   540 bool QSqlField::isAutoValue() const

   541 {

   542     return d->autoval;

   543 }

   544 

   545 /*!

   546     Marks the field as an auto-generated value if \a autoVal

   547     is true.

   548 

   549     \sa isAutoValue()

   550  */

   551 void QSqlField::setAutoValue(bool autoVal)

   552 {

   553     detach();

   554     d->autoval = autoVal;

   555 }

   556 

   557 QT_END_NAMESPACE