src/declarative/qml/v8/qjsvalue.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtScript module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL-ONLY$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser
  11 ** General Public License version 2.1 as published by the Free Software
  12 ** Foundation and appearing in the file LICENSE.LGPL included in the
  13 ** packaging of this file.  Please review the following information to
  14 ** ensure the GNU Lesser General Public License version 2.1 requirements
  15 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** If you have questions regarding the use of this file, please contact
  18 ** us via http://www.qt-project.org/.
  19 **
  20 ** $QT_END_LICENSE$
  21 **
  22 ****************************************************************************/
  23
  24 #include "qscriptisolate_p.h"
  25 #include "qjsengine.h"
  26 #include "qv8engine_p.h"
  27 #include "qjsvalue.h"
  28 #include "qjsvalue_p.h"
  29 #include "qscript_impl_p.h"
  30 #include "qscriptshareddata_p.h"
  31 #include <QtCore/qregexp.h>
  32 #include <QtCore/qstring.h>
  33
  34 /*!
  35   \since 5.0
  36   \class QJSValue
  37
  38   \brief The QJSValue class acts as a container for Qt/JavaScript data types.
  39
  40   \ingroup qtjavascript
  41   \mainclass
  42
  43   QJSValue supports the types defined in the \l{ECMA-262}
  44   standard: The primitive types, which are Undefined, Null, Boolean,
  45   Number, and String; and the Object type. Additionally, built-in
  46   support is provided for Qt/C++ types such as QVariant and QObject.
  47
  48   For the object-based types (including Date and RegExp), use the
  49   newT() functions in QJSEngine (e.g. QJSEngine::newObject())
  50   to create a QJSValue of the desired type. For the primitive types,
  51   use one of the QJSValue constructor overloads.
  52
  53   The methods named isT() (e.g. isBool(), isUndefined()) can be
  54   used to test if a value is of a certain type. The methods named
  55   toT() (e.g. toBool(), toString()) can be used to convert a
  56   QJSValue to another type. You can also use the generic
  57   QJSValue_cast() function.
  58
  59   Object values have zero or more properties which are themselves
  60   QJSValues. Use setProperty() to set a property of an object, and
  61   call property() to retrieve the value of a property.
  62
  63   \snippet doc/src/snippets/code/src_script_qjsvalue.cpp 0
  64
  65   The attributes of a property can be queried by calling the
  66   propertyFlags() function.
  67
  68   If you want to iterate over the properties of a script object, use
  69   the QJSValueIterator class.
  70
  71   Object values have an internal \c{prototype} property, which can be
  72   accessed with prototype() and setPrototype().
  73
  74   Function objects (objects for which isCallable()) returns true) can
  75   be invoked by calling call(). Constructor functions can be used to
  76   construct new objects by calling callAsConstructor().
  77
  78   Use equals() or strictlyEquals() to compare a QJSValue to another.
  79
  80   Note that a QJSValue for which isObject() is true only carries a
  81   reference to an actual object; copying the QJSValue will only
  82   copy the object reference, not the object itself. If you want to
  83   clone an object (i.e. copy an object's properties to another
  84   object), you can do so with the help of a \c{for-in} statement in
  85   script code, or QJSValueIterator in C++.
  86
  87   \sa QJSEngine, QJSValueIterator
  88 */
  89
  90 /*!
  91     \enum QJSValue::SpecialValue
  92
  93     This enum is used to specify a single-valued type.
  94
  95     \value UndefinedValue An undefined value.
  96
  97     \value NullValue A null value.
  98 */
  99
 100 /*!
 101     \enum QJSValue::PropertyFlag
 102
 103     This enum describes the attributes of a property.
 104
 105     \value ReadOnly The property is read-only. Attempts by Qt Script code to write to the property will be ignored.
 106
 107     \value Undeletable Attempts by Qt Script code to \c{delete} the property will be ignored.
 108
 109     \value SkipInEnumeration The property is not to be enumerated by a \c{for-in} enumeration.
 110 */
 111
 112 QT_BEGIN_NAMESPACE
 113
 114 /*!
 115     Constructs an invalid value.
 116 */
 117 QJSValue::QJSValue()
 118     : d_ptr(InvalidValue())
 119 {
 120 }
 121
 122 /*!
 123   Constructs a new QJSValue with a boolean \a value.
 124 */
 125 QJSValue::QJSValue(bool value)
 126     : d_ptr(new QJSValuePrivate(value))
 127 {
 128 }
 129
 130 /*!
 131   Constructs a new QJSValue with a number \a value.
 132 */
 133 QJSValue::QJSValue(int value)
 134     : d_ptr(new QJSValuePrivate(value))
 135 {
 136 }
 137
 138 /*!
 139   Constructs a new QJSValue with a number \a value.
 140 */
 141 QJSValue::QJSValue(uint value)
 142     : d_ptr(new QJSValuePrivate(value))
 143 {
 144 }
 145
 146 /*!
 147   Constructs a new QJSValue with a number \a value.
 148 */
 149 QJSValue::QJSValue(double value)
 150     : d_ptr(new QJSValuePrivate(value))
 151 {
 152 }
 153
 154 /*!
 155   Constructs a new QJSValue with a string \a value.
 156 */
 157 QJSValue::QJSValue(const QString& value)
 158     : d_ptr(new QJSValuePrivate(value))
 159 {
 160 }
 161
 162 /*!
 163   Constructs a new QJSValue with a special \a value.
 164 */
 165 QJSValue::QJSValue(SpecialValue value)
 166     : d_ptr(new QJSValuePrivate(value))
 167 {
 168 }
 169
 170 /*!
 171   Constructs a new QJSValue with a string \a value.
 172 */
 173 QJSValue::QJSValue(const QLatin1String &value)
 174     : d_ptr(new QJSValuePrivate(value))
 175 {
 176 }
 177
 178 /*!
 179   Constructs a new QJSValue with a string \a value.
 180 */
 181 #ifndef QT_NO_CAST_FROM_ASCII
 182 QJSValue::QJSValue(const char *value)
 183     : d_ptr(new QJSValuePrivate(QString::fromAscii(value)))
 184 {
 185 }
 186 #endif
 187
 188 /*!
 189     Block automatic convertion to bool
 190     \internal
 191 */
 192 QJSValue::QJSValue(void* d)
 193 {
 194     Q_UNUSED(d);
 195     Q_ASSERT(false);
 196 }
 197
 198 /*!
 199     Constructs a new QJSValue from private
 200     \internal
 201 */
 202 QJSValue::QJSValue(QJSValuePrivate* d)
 203     : d_ptr(d)
 204 {
 205 }
 206
 207 /*!
 208     Constructs a new QJSValue from private
 209     \internal
 210 */
 211 QJSValue::QJSValue(QScriptPassPointer<QJSValuePrivate> d)
 212     : d_ptr(d.give())
 213 {
 214 }
 215
 216 #ifdef QT_DEPRECATED
 217
 218 /*!
 219   \obsolete
 220
 221   Constructs a new QJSValue with the boolean \a value and
 222   registers it with the script \a engine.
 223 */
 224 QJSValue::QJSValue(QJSEngine* engine, bool value)
 225 {
 226     if (engine) {
 227         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 228         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 229     } else {
 230         d_ptr = new QJSValuePrivate(value);
 231     }
 232 }
 233
 234 /*!
 235   \obsolete
 236
 237   Constructs a new QJSValue with the integer \a value and
 238   registers it with the script \a engine.
 239 */
 240 QJSValue::QJSValue(QJSEngine* engine, int value)
 241 {
 242     if (engine) {
 243         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 244         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 245     } else {
 246         d_ptr = new QJSValuePrivate(value);
 247     }
 248 }
 249
 250 /*!
 251   \obsolete
 252
 253   Constructs a new QJSValue with the unsigned integer \a value and
 254   registers it with the script \a engine.
 255  */
 256 QJSValue::QJSValue(QJSEngine* engine, uint value)
 257 {
 258     if (engine) {
 259         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 260         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 261     } else {
 262         d_ptr = new QJSValuePrivate(value);
 263     }
 264 }
 265
 266 /*!
 267   \obsolete
 268
 269   Constructs a new QJSValue with the double \a value and
 270   registers it with the script \a engine.
 271 */
 272 QJSValue::QJSValue(QJSEngine* engine, double value)
 273 {
 274     if (engine) {
 275         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 276         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 277     } else {
 278         d_ptr = new QJSValuePrivate(value);
 279     }
 280 }
 281
 282 /*!
 283   \obsolete
 284
 285   Constructs a new QJSValue with the string \a value and
 286   registers it with the script \a engine.
 287 */
 288 QJSValue::QJSValue(QJSEngine* engine, const QString& value)
 289 {
 290     if (engine) {
 291         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 292         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 293     } else {
 294         d_ptr = new QJSValuePrivate(value);
 295     }
 296 }
 297
 298 /*!
 299   \obsolete
 300
 301   Constructs a new QJSValue with the string \a value and
 302   registers it with the script \a engine.
 303 */
 304 QJSValue::QJSValue(QJSEngine* engine, const char* value)
 305 {
 306     if (engine) {
 307         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 308         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), QString::fromUtf8(value));
 309     } else {
 310         d_ptr = new QJSValuePrivate(QString::fromUtf8(value));
 311     }
 312 }
 313
 314 /*!
 315   \obsolete
 316
 317   Constructs a new QJSValue with the special \a value and
 318   registers it with the script \a engine.
 319 */
 320 QJSValue::QJSValue(QJSEngine* engine, SpecialValue value)
 321 {
 322     if (engine) {
 323         QScriptIsolate api(QV8Engine::get(engine), QScriptIsolate::NotNullEngine);
 324         d_ptr = new QJSValuePrivate(QV8Engine::get(engine), value);
 325     } else {
 326         d_ptr = new QJSValuePrivate(value);
 327     }
 328 }
 329
 330 #endif // QT_DEPRECATED
 331
 332 /*!
 333   Constructs a new QJSValue that is a copy of \a other.
 334
 335   Note that if \a other is an object (i.e., isObject() would return
 336   true), then only a reference to the underlying object is copied into
 337   the new script value (i.e., the object itself is not copied).
 338 */
 339 QJSValue::QJSValue(const QJSValue& other)
 340     : d_ptr(other.d_ptr)
 341 {
 342 }
 343
 344 /*!
 345     Destroys this QJSValue.
 346 */
 347 QJSValue::~QJSValue()
 348 {
 349 }
 350
 351 #ifdef QT_DEPRECATED
 352
 353 /*!
 354   \obsolete
 355
 356   Returns true if this QJSValue is valid; otherwise returns
 357   false.
 358 */
 359 bool QJSValue::isValid() const
 360 {
 361     Q_D(const QJSValue);
 362     QScriptIsolate api(d->engine());
 363     return d->isValid();
 364 }
 365
 366 #endif // QT_DEPRECATED
 367
 368 /*!
 369   Returns true if this QJSValue is of the primitive type Boolean;
 370   otherwise returns false.
 371
 372   \sa toBool()
 373 */
 374 bool QJSValue::isBool() const
 375 {
 376     Q_D(const QJSValue);
 377     QScriptIsolate api(d->engine());
 378     return d->isBool();
 379 }
 380
 381 /*!
 382   Returns true if this QJSValue is of the primitive type Number;
 383   otherwise returns false.
 384
 385   \sa toNumber()
 386 */
 387 bool QJSValue::isNumber() const
 388 {
 389     Q_D(const QJSValue);
 390     QScriptIsolate api(d->engine());
 391     return d->isNumber();
 392 }
 393
 394 /*!
 395   Returns true if this QJSValue is of the primitive type Null;
 396   otherwise returns false.
 397
 398   \sa QJSEngine::nullValue()
 399 */
 400 bool QJSValue::isNull() const
 401 {
 402     Q_D(const QJSValue);
 403     QScriptIsolate api(d->engine());
 404     return d->isNull();
 405 }
 406
 407 /*!
 408   Returns true if this QJSValue is of the primitive type String;
 409   otherwise returns false.
 410
 411   \sa toString()
 412 */
 413 bool QJSValue::isString() const
 414 {
 415     Q_D(const QJSValue);
 416     QScriptIsolate api(d->engine());
 417     return d->isString();
 418 }
 419
 420 /*!
 421   Returns true if this QJSValue is of the primitive type Undefined;
 422   otherwise returns false.
 423
 424   \sa QJSEngine::undefinedValue()
 425 */
 426 bool QJSValue::isUndefined() const
 427 {
 428     Q_D(const QJSValue);
 429     QScriptIsolate api(d->engine());
 430     return d->isUndefined();
 431 }
 432
 433 /*!
 434   Returns true if this QJSValue is an object of the Error class;
 435   otherwise returns false.
 436 */
 437 bool QJSValue::isError() const
 438 {
 439     Q_D(const QJSValue);
 440     QScriptIsolate api(d->engine());
 441     return d->isError();
 442 }
 443
 444 /*!
 445   Returns true if this QJSValue is an object of the Array class;
 446   otherwise returns false.
 447
 448   \sa QJSEngine::newArray()
 449 */
 450 bool QJSValue::isArray() const
 451 {
 452     Q_D(const QJSValue);
 453     QScriptIsolate api(d->engine());
 454     return d->isArray();
 455  }
 456
 457 /*!
 458   Returns true if this QJSValue is of the Object type; otherwise
 459   returns false.
 460
 461   Note that function values, variant values, and QObject values are
 462   objects, so this function returns true for such values.
 463
 464   \sa toObject(), QJSEngine::newObject()
 465 */
 466 bool QJSValue::isObject() const
 467 {
 468     Q_D(const QJSValue);
 469     QScriptIsolate api(d->engine());
 470     return d->isObject();
 471 }
 472
 473 /*!
 474   Returns true if this QJSValue can be called a function, otherwise
 475   returns false.
 476
 477   \sa call()
 478 */
 479 bool QJSValue::isCallable() const
 480 {
 481     Q_D(const QJSValue);
 482     QScriptIsolate api(d->engine());
 483     return d->isCallable();
 484 }
 485
 486 #ifdef QT_DEPRECATED
 487
 488 /*!
 489   \obsolete
 490
 491   Use isCallable() instead.
 492 */
 493 bool QJSValue::isFunction() const
 494 {
 495     Q_D(const QJSValue);
 496     QScriptIsolate api(d->engine());
 497     return d->isCallable();
 498 }
 499
 500 #endif // QT_DEPRECATED
 501
 502 /*!
 503   Returns true if this QJSValue is a variant value;
 504   otherwise returns false.
 505
 506   \sa toVariant(), QJSEngine::newVariant()
 507 */
 508 bool QJSValue::isVariant() const
 509 {
 510     Q_D(const QJSValue);
 511     QScriptIsolate api(d->engine());
 512     return d->isVariant();
 513 }
 514
 515 /*!
 516   Returns the string value of this QJSValue, as defined in
 517   \l{ECMA-262} section 9.8, "ToString".
 518
 519   Note that if this QJSValue is an object, calling this function
 520   has side effects on the script engine, since the engine will call
 521   the object's toString() function (and possibly valueOf()) in an
 522   attempt to convert the object to a primitive value (possibly
 523   resulting in an uncaught script exception).
 524
 525   \sa isString()
 526 */
 527 QString QJSValue::toString() const
 528 {
 529     Q_D(const QJSValue);
 530     QScriptIsolate api(d->engine());
 531     return d->toString();
 532 }
 533
 534 /*!
 535   Returns the number value of this QJSValue, as defined in
 536   \l{ECMA-262} section 9.3, "ToNumber".
 537
 538   Note that if this QJSValue is an object, calling this function
 539   has side effects on the script engine, since the engine will call
 540   the object's valueOf() function (and possibly toString()) in an
 541   attempt to convert the object to a primitive value (possibly
 542   resulting in an uncaught script exception).
 543
 544   \sa isNumber(), toInteger(), toInt(), toUInt(), toUInt16()
 545 */
 546 double QJSValue::toNumber() const
 547 {
 548     Q_D(const QJSValue);
 549     QScriptIsolate api(d->engine());
 550     return d->toNumber();
 551 }
 552
 553 /*!
 554   Returns the boolean value of this QJSValue, using the conversion
 555   rules described in \l{ECMA-262} section 9.2, "ToBoolean".
 556
 557   Note that if this QJSValue is an object, calling this function
 558   has side effects on the script engine, since the engine will call
 559   the object's valueOf() function (and possibly toString()) in an
 560   attempt to convert the object to a primitive value (possibly
 561   resulting in an uncaught script exception).
 562
 563   \sa isBool()
 564 */
 565 bool QJSValue::toBool() const
 566 {
 567     Q_D(const QJSValue);
 568     QScriptIsolate api(d->engine());
 569     return d->toBool();
 570 }
 571
 572 #ifdef QT_DEPRECATED
 573
 574 /*!
 575   \obsolete
 576
 577   Returns the integer value of this QJSValue, using the conversion
 578   rules described in \l{ECMA-262} section 9.4, "ToInteger".
 579
 580   Note that if this QJSValue is an object, calling this function
 581   has side effects on the script engine, since the engine will call
 582   the object's valueOf() function (and possibly toString()) in an
 583   attempt to convert the object to a primitive value (possibly
 584   resulting in an uncaught script exception).
 585
 586   \sa toNumber()
 587 */
 588 double QJSValue::toInteger() const
 589 {
 590     Q_D(const QJSValue);
 591     QScriptIsolate api(d->engine());
 592     return d->toInteger();
 593 }
 594
 595 #endif // QT_DEPRECATED
 596
 597 /*!
 598   Returns the signed 32-bit integer value of this QJSValue, using
 599   the conversion rules described in \l{ECMA-262} section 9.5, "ToInt32".
 600
 601   Note that if this QJSValue is an object, calling this function
 602   has side effects on the script engine, since the engine will call
 603   the object's valueOf() function (and possibly toString()) in an
 604   attempt to convert the object to a primitive value (possibly
 605   resulting in an uncaught script exception).
 606
 607   \sa toNumber(), toUInt()
 608 */
 609 qint32 QJSValue::toInt() const
 610 {
 611     Q_D(const QJSValue);
 612     QScriptIsolate api(d->engine());
 613     return d->toInt32();
 614 }
 615
 616 /*!
 617   Returns the unsigned 32-bit integer value of this QJSValue, using
 618   the conversion rules described in \l{ECMA-262} section 9.6, "ToUint32".
 619
 620   Note that if this QJSValue is an object, calling this function
 621   has side effects on the script engine, since the engine will call
 622   the object's valueOf() function (and possibly toString()) in an
 623   attempt to convert the object to a primitive value (possibly
 624   resulting in an uncaught script exception).
 625
 626   \sa toNumber(), toInt()
 627 */
 628 quint32 QJSValue::toUInt() const
 629 {
 630     Q_D(const QJSValue);
 631     QScriptIsolate api(d->engine());
 632     return d->toUInt32();
 633 }
 634
 635 #ifdef QT_DEPRECATED
 636
 637 /*!
 638   \obsolete
 639
 640   Use toInt() instead.
 641 */
 642 qint32 QJSValue::toInt32() const
 643 {
 644     Q_D(const QJSValue);
 645     QScriptIsolate api(d->engine());
 646     return d->toInt32();
 647 }
 648
 649 /*!
 650   \obsolete
 651
 652   Use toUInt() instead.
 653 */
 654 quint32 QJSValue::toUInt32() const
 655 {
 656     Q_D(const QJSValue);
 657     QScriptIsolate api(d->engine());
 658     return d->toUInt32();
 659 }
 660
 661 /*!
 662   Returns the unsigned 16-bit integer value of this QJSValue, using
 663   the conversion rules described in \l{ECMA-262} section 9.7, "ToUint16".
 664
 665   Note that if this QJSValue is an object, calling this function
 666   has side effects on the script engine, since the engine will call
 667   the object's valueOf() function (and possibly toString()) in an
 668   attempt to convert the object to a primitive value (possibly
 669   resulting in an uncaught script exception).
 670
 671   \sa toNumber()
 672 */
 673 quint16 QJSValue::toUInt16() const
 674 {
 675     Q_D(const QJSValue);
 676     QScriptIsolate api(d->engine());
 677     return d->toUInt16();
 678 }
 679
 680 /*!
 681   \obsolete
 682
 683   This function is obsolete; use QJSEngine::toObject() instead.
 684 */
 685 QJSValue QJSValue::toObject() const
 686 {
 687     Q_D(const QJSValue);
 688     QScriptIsolate api(d->engine());
 689     return QJSValuePrivate::get(d->toObject());
 690 }
 691
 692 #endif // QT_DEPRECATED
 693
 694 /*!
 695   Returns the QVariant value of this QJSValue, if it can be
 696   converted to a QVariant; otherwise returns an invalid QVariant.
 697   The conversion is performed according to the following table:
 698
 699     \table
 700     \header \o Input Type \o Result
 701     \row    \o Undefined  \o An invalid QVariant.
 702     \row    \o Null       \o An invalid QVariant.
 703     \row    \o Boolean    \o A QVariant containing the value of the boolean.
 704     \row    \o Number     \o A QVariant containing the value of the number.
 705     \row    \o String     \o A QVariant containing the value of the string.
 706     \row    \o QVariant Object \o The result is the QVariant value of the object (no conversion).
 707     \row    \o QObject Object \o A QVariant containing a pointer to the QObject.
 708     \row    \o Date Object \o A QVariant containing the date value (toDateTime()).
 709     \row    \o RegExp Object \o A QVariant containing the regular expression value (toRegExp()).
 710     \row    \o Array Object \o The array is converted to a QVariantList. Each element is converted to a QVariant, recursively; cyclic references are not followed.
 711     \row    \o Object     \o The object is converted to a QVariantMap. Each property is converted to a QVariant, recursively; cyclic references are not followed.
 712     \endtable
 713
 714   \sa isVariant()
 715 */
 716 QVariant QJSValue::toVariant() const
 717 {
 718     Q_D(const QJSValue);
 719     QScriptIsolate api(d->engine());
 720     return d->toVariant();
 721 }
 722
 723 /*!
 724   Calls this QJSValue as a function, passing \a args as arguments
 725   to the function, and using the globalObject() as the "this"-object.
 726   Returns the value returned from the function.
 727
 728   If this QJSValue is not callable, call() does nothing and
 729   returns an undefined QJSValue.
 730
 731   Calling call() can cause an exception to occur in the script engine;
 732   in that case, call() returns the value that was thrown (typically an
 733   \c{Error} object). You can call
 734   QJSEngine::hasUncaughtException() to determine if an exception
 735   occurred.
 736
 737   \sa isCallable(), callWithInstance(), callAsConstructor()
 738 */
 739 QJSValue QJSValue::call(const QJSValueList &args)
 740 {
 741     Q_D(QJSValue);
 742     QScriptIsolate api(d->engine());
 743     return d->call(/*thisObject=*/0, args);
 744 }
 745
 746 /*!
 747   Calls this QJSValue as a function, using \a instance as
 748   the `this' object in the function call, and passing \a args
 749   as arguments to the function. Returns the value returned from
 750   the function.
 751
 752   If this QJSValue is not a function, call() does nothing
 753   and returns an invalid QJSValue.
 754
 755   Note that if \a instance is not an object, the global object
 756   (see \l{QJSEngine::globalObject()}) will be used as the
 757   `this' object.
 758
 759   Calling call() can cause an exception to occur in the script engine;
 760   in that case, call() returns the value that was thrown (typically an
 761   \c{Error} object). You can call
 762   QJSEngine::hasUncaughtException() to determine if an exception
 763   occurred.
 764
 765   \sa call()
 766 */
 767 QJSValue QJSValue::callWithInstance(const QJSValue &instance, const QJSValueList &args)
 768 {
 769     Q_D(QJSValue);
 770     QScriptIsolate api(d->engine());
 771     return d->call(QJSValuePrivate::get(instance), args);
 772 }
 773
 774 /*!
 775   Creates a new \c{Object} and calls this QJSValue as a
 776   constructor, using the created object as the `this' object and
 777   passing \a args as arguments. If the return value from the
 778   constructor call is an object, then that object is returned;
 779   otherwise the default constructed object is returned.
 780
 781   If this QJSValue is not a function, callAsConstructor() does
 782   nothing and returns an undefined QJSValue.
 783
 784   Calling this function can cause an exception to occur in the
 785   script engine; in that case, the value that was thrown
 786   (typically an \c{Error} object) is returned. You can call
 787   QJSEngine::hasUncaughtException() to determine if an exception
 788   occurred.
 789
 790   \sa call(), QJSEngine::newObject()
 791 */
 792 QJSValue QJSValue::callAsConstructor(const QJSValueList &args)
 793 {
 794     Q_D(QJSValue);
 795     QScriptIsolate api(d->engine());
 796     return QJSValuePrivate::get(d->callAsConstructor(args));
 797 }
 798
 799 #ifdef QT_DEPRECATED
 800
 801 /*!
 802   \obsolete
 803
 804   Use callWithInstance() instead.
 805 */
 806 QJSValue QJSValue::call(const QJSValue& thisObject, const QJSValueList& args)
 807 {
 808     Q_D(QJSValue);
 809     QScriptIsolate api(d->engine());
 810     return d->call(QJSValuePrivate::get(thisObject), args);
 811 }
 812
 813 /*!
 814   \obsolete
 815
 816   Use callAsConstructor() instead.
 817 */
 818 QJSValue QJSValue::construct(const QJSValueList &args)
 819 {
 820     Q_D(QJSValue);
 821     QScriptIsolate api(d->engine());
 822     return QJSValuePrivate::get(d->callAsConstructor(args));
 823 }
 824
 825 /*!
 826   \obsolete
 827
 828   Returns the QJSEngine that created this QJSValue,
 829   or 0 if this QJSValue is invalid or the value is not
 830   associated with a particular engine.
 831 */
 832 QJSEngine* QJSValue::engine() const
 833 {
 834     Q_D(const QJSValue);
 835     QScriptIsolate api(d->engine());
 836     QV8Engine* engine = d->engine();
 837     if (engine)
 838         return QV8Engine::get(engine);
 839     return 0;
 840 }
 841
 842 #endif // QT_DEPRECATED
 843
 844 /*!
 845   If this QJSValue is an object, returns the internal prototype
 846   (\c{__proto__} property) of this object; otherwise returns an
 847   invalid QJSValue.
 848
 849   \sa setPrototype(), isObject()
 850 */
 851 QJSValue QJSValue::prototype() const
 852 {
 853     Q_D(const QJSValue);
 854     QScriptIsolate api(d->engine());
 855     return QJSValuePrivate::get(d->prototype());
 856 }
 857
 858 /*!
 859   If this QJSValue is an object, sets the internal prototype
 860   (\c{__proto__} property) of this object to be \a prototype;
 861   otherwise does nothing.
 862
 863   The internal prototype should not be confused with the public
 864   property with name "prototype"; the public prototype is usually
 865   only set on functions that act as constructors.
 866
 867   \sa prototype(), isObject()
 868 */
 869 void QJSValue::setPrototype(const QJSValue& prototype)
 870 {
 871     Q_D(QJSValue);
 872     QScriptIsolate api(d->engine());
 873     d->setPrototype(QJSValuePrivate::get(prototype));
 874 }
 875
 876 /*!
 877   Assigns the \a other value to this QJSValue.
 878
 879   Note that if \a other is an object (isObject() returns true),
 880   only a reference to the underlying object will be assigned;
 881   the object itself will not be copied.
 882 */
 883 QJSValue& QJSValue::operator=(const QJSValue& other)
 884 {
 885     d_ptr = other.d_ptr;
 886     return *this;
 887 }
 888
 889 /*!
 890   Returns true if this QJSValue is equal to \a other, otherwise
 891   returns false. The comparison follows the behavior described in
 892   \l{ECMA-262} section 11.9.3, "The Abstract Equality Comparison
 893   Algorithm".
 894
 895   This function can return true even if the type of this QJSValue
 896   is different from the type of the \a other value; i.e. the
 897   comparison is not strict.  For example, comparing the number 9 to
 898   the string "9" returns true; comparing an undefined value to a null
 899   value returns true; comparing a \c{Number} object whose primitive
 900   value is 6 to a \c{String} object whose primitive value is "6"
 901   returns true; and comparing the number 1 to the boolean value
 902   \c{true} returns true. If you want to perform a comparison
 903   without such implicit value conversion, use strictlyEquals().
 904
 905   Note that if this QJSValue or the \a other value are objects,
 906   calling this function has side effects on the script engine, since
 907   the engine will call the object's valueOf() function (and possibly
 908   toString()) in an attempt to convert the object to a primitive value
 909   (possibly resulting in an uncaught script exception).
 910
 911   \sa strictlyEquals()
 912 */
 913 bool QJSValue::equals(const QJSValue& other) const
 914 {
 915     Q_D(const QJSValue);
 916     QJSValuePrivate* otherValue = QJSValuePrivate::get(other);
 917     QScriptIsolate api(d->engine() ? d->engine() : otherValue->engine());
 918     return d_ptr->equals(otherValue);
 919 }
 920
 921 /*!
 922   Returns true if this QJSValue is equal to \a other using strict
 923   comparison (no conversion), otherwise returns false. The comparison
 924   follows the behavior described in \l{ECMA-262} section 11.9.6, "The
 925   Strict Equality Comparison Algorithm".
 926
 927   If the type of this QJSValue is different from the type of the
 928   \a other value, this function returns false. If the types are equal,
 929   the result depends on the type, as shown in the following table:
 930
 931     \table
 932     \header \o Type \o Result
 933     \row    \o Undefined  \o true
 934     \row    \o Null       \o true
 935     \row    \o Boolean    \o true if both values are true, false otherwise
 936     \row    \o Number     \o false if either value is NaN (Not-a-Number); true if values are equal, false otherwise
 937     \row    \o String     \o true if both values are exactly the same sequence of characters, false otherwise
 938     \row    \o Object     \o true if both values refer to the same object, false otherwise
 939     \endtable
 940
 941   \sa equals()
 942 */
 943 bool QJSValue::strictlyEquals(const QJSValue& other) const
 944 {
 945     Q_D(const QJSValue);
 946     QJSValuePrivate* o = QJSValuePrivate::get(other);
 947     QScriptIsolate api(d->engine() ? d->engine() : o->engine());
 948     return d_ptr->strictlyEquals(o);
 949 }
 950
 951 #ifdef QT_DEPRECATED
 952
 953 /*!
 954     \obsolete
 955
 956     Returns true if this QJSValue is an instance of
 957     \a other; otherwise returns false.
 958
 959     This QJSValue is considered to be an instance of \a other if
 960     \a other is a function and the value of the \c{prototype}
 961     property of \a other is in the prototype chain of this
 962     QJSValue.
 963 */
 964 bool QJSValue::instanceOf(const QJSValue &other) const
 965 {
 966     Q_D(const QJSValue);
 967     QScriptIsolate api(d->engine());
 968     return d->instanceOf(QJSValuePrivate::get(other));
 969 }
 970
 971 #endif // QT_DEPRECATED
 972
 973 /*!
 974   Returns the value of this QJSValue's property with the given \a name.
 975   If no such property exists, an invalid QJSValue is returned.
 976
 977   If the property is implemented using a getter function (i.e. has the
 978   PropertyGetter flag set), calling property() has side-effects on the
 979   script engine, since the getter function will be called (possibly
 980   resulting in an uncaught script exception). If an exception
 981   occurred, property() returns the value that was thrown (typically
 982   an \c{Error} object).
 983
 984   \sa setProperty(), hasProperty(), QJSValueIterator
 985 */
 986 QJSValue QJSValue::property(const QString& name) const
 987 {
 988     Q_D(const QJSValue);
 989     QScriptIsolate api(d->engine());
 990     return QJSValuePrivate::get(d->property(name));
 991 }
 992
 993 /*!
 994   \overload
 995
 996   Returns the property at the given \a arrayIndex.
 997
 998   This function is provided for convenience and performance when
 999   working with array objects.
1000
1001   If this QJSValue is not an Array object, this function behaves
1002   as if property() was called with the string representation of \a
1003   arrayIndex.
1004 */
1005 QJSValue QJSValue::property(quint32 arrayIndex) const
1006 {
1007     Q_D(const QJSValue);
1008     QScriptIsolate api(d->engine());
1009     return QJSValuePrivate::get(d->property(arrayIndex));
1010 }
1011
1012 /*!
1013   Sets the value of this QJSValue's property with the given \a name to
1014   the given \a value.
1015
1016   If this QJSValue is not an object, this function does nothing.
1017
1018   If this QJSValue does not already have a property with name \a name,
1019   a new property is created.
1020
1021   If \a value is invalid, the property is removed.
1022
1023   If the property is implemented using a setter function (i.e. has the
1024   PropertySetter flag set), calling setProperty() has side-effects on
1025   the script engine, since the setter function will be called with the
1026   given \a value as argument (possibly resulting in an uncaught script
1027   exception).
1028
1029   Note that you cannot specify custom getter or setter functions for
1030   built-in properties, such as the \c{length} property of Array objects
1031   or meta properties of QObject objects.
1032
1033   \sa property(), deleteProperty()
1034 */
1035 void QJSValue::setProperty(const QString& name, const QJSValue& value)
1036 {
1037     Q_D(QJSValue);
1038     QScriptIsolate api(d->engine());
1039     d->setProperty(name, QJSValuePrivate::get(value));
1040 }
1041
1042 /*!
1043   \overload
1044
1045   Sets the property at the given \a arrayIndex to the given \a value.
1046
1047   This function is provided for convenience and performance when
1048   working with array objects.
1049
1050   If this QJSValue is not an Array object, this function behaves
1051   as if setProperty() was called with the string representation of \a
1052   arrayIndex.
1053 */
1054 void QJSValue::setProperty(quint32 arrayIndex, const QJSValue& value)
1055 {
1056     Q_D(QJSValue);
1057     QScriptIsolate api(d->engine());
1058     d->setProperty(arrayIndex, QJSValuePrivate::get(value));
1059 }
1060
1061 /*!
1062   Attempts to delete this object's property of the given \a name.
1063   Returns true if the property was deleted, otherwise returns false.
1064
1065   The behavior of this function is consistent with the JavaScript
1066   delete operator. In particular:
1067
1068   \list
1069   \o Non-configurable properties cannot be deleted.
1070   \o This function will return true even if this object doesn't
1071      have a property of the given \a name (i.e., non-existent
1072      properties are "trivially deletable").
1073   \o If this object doesn't have an own property of the given
1074      \a name, but an object in the prototype() chain does, the
1075      prototype object's property is not deleted, and this function
1076      returns true.
1077   \endlist
1078
1079   \sa setProperty(), hasOwnProperty()
1080 */
1081 bool QJSValue::deleteProperty(const QString &name)
1082 {
1083     Q_D(QJSValue);
1084     QScriptIsolate api(d->engine());
1085     return d->deleteProperty(name);
1086 }
1087
1088 /*!
1089   Returns true if this object has a property of the given \a name,
1090   otherwise returns false.
1091
1092   \sa property(), hasOwnProperty()
1093 */
1094 bool QJSValue::hasProperty(const QString &name) const
1095 {
1096     Q_D(const QJSValue);
1097     QScriptIsolate api(d->engine());
1098     return d->hasProperty(name);
1099 }
1100
1101 /*!
1102   Returns true if this object has an own (not prototype-inherited)
1103   property of the given \a name, otherwise returns false.
1104
1105   \sa property(), hasProperty()
1106 */
1107 bool QJSValue::hasOwnProperty(const QString &name) const
1108 {
1109     Q_D(const QJSValue);
1110     QScriptIsolate api(d->engine());
1111     return d->hasOwnProperty(name);
1112 }
1113
1114 #ifdef QT_DEPRECATED
1115
1116 /*!
1117   \obsolete
1118
1119   Returns the flags of the property with the given \a name.
1120
1121   \sa property()
1122 */
1123 QJSValue::PropertyFlags QJSValue::propertyFlags(const QString& name) const
1124 {
1125     Q_D(const QJSValue);
1126     QScriptIsolate api(d->engine());
1127     return d->propertyFlags(name);
1128 }
1129
1130 #endif // QT_DEPRECATED
1131
1132 /*!
1133  * If this QJSValue is a QObject, returns the QObject pointer
1134  * that the QJSValue represents; otherwise, returns 0.
1135  *
1136  * If the QObject that this QJSValue wraps has been deleted,
1137  * this function returns 0 (i.e. it is possible for toQObject()
1138  * to return 0 even when isQObject() returns true).
1139  *
1140  * \sa isQObject()
1141  */
1142 QObject *QJSValue::toQObject() const
1143 {
1144     Q_D(const QJSValue);
1145     QScriptIsolate api(d->engine());
1146     return d->toQObject();
1147 }
1148
1149 /*!
1150   Returns a QDateTime representation of this value, in local time.
1151   If this QJSValue is not a date, or the value of the date is NaN
1152   (Not-a-Number), an invalid QDateTime is returned.
1153
1154   \sa isDate()
1155 */
1156 QDateTime QJSValue::toDateTime() const
1157 {
1158     Q_D(const QJSValue);
1159     QScriptIsolate api(d->engine());
1160     return d->toDataTime();
1161 }
1162
1163 #ifdef QT_DEPRECATED
1164
1165 /*!
1166   \obsolete
1167
1168   Returns the QRegExp representation of this value.
1169   If this QJSValue is not a regular expression, an empty
1170   QRegExp is returned.
1171
1172   \sa isRegExp()
1173 */
1174 QRegExp QJSValue::toRegExp() const
1175 {
1176     Q_D(const QJSValue);
1177     QScriptIsolate api(d->engine());
1178     return d->toRegExp();
1179 }
1180
1181 #endif // QT_DEPRECATED
1182
1183 /*!
1184   Returns true if this QJSValue is an object of the Date class;
1185   otherwise returns false.
1186
1187   \sa QJSEngine::newDate()
1188 */
1189 bool QJSValue::isDate() const
1190 {
1191     Q_D(const QJSValue);
1192     QScriptIsolate api(d->engine());
1193     return d->isDate();
1194 }
1195
1196 /*!
1197   Returns true if this QJSValue is an object of the RegExp class;
1198   otherwise returns false.
1199
1200   \sa QJSEngine::newRegExp()
1201 */
1202 bool QJSValue::isRegExp() const
1203 {
1204     Q_D(const QJSValue);
1205     QScriptIsolate api(d->engine());
1206     return d->isRegExp();
1207 }
1208
1209 /*!
1210   Returns true if this QJSValue is a QObject; otherwise returns
1211   false.
1212
1213   Note: This function returns true even if the QObject that this
1214   QJSValue wraps has been deleted.
1215
1216   \sa toQObject(), QJSEngine::newQObject()
1217 */
1218 bool QJSValue::isQObject() const
1219 {
1220     Q_D(const QJSValue);
1221     QScriptIsolate api(d->engine());
1222     return d->isQObject();
1223 }
1224
1225 QT_END_NAMESPACE