qt/api/qscriptvalue.cpp

   1 /*
   2     Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies)
   3
   4     This library is free software; you can redistribute it and/or
   5     modify it under the terms of the GNU Library General Public
   6     License as published by the Free Software Foundation; either
   7     version 2 of the License, or (at your option) any later version.
   8
   9     This library is distributed in the hope that it will be useful,
  10     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12     Library General Public License for more details.
  13
  14     You should have received a copy of the GNU Library General Public License
  15     along with this library; see the file COPYING.LIB.  If not, write to
  16     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17     Boston, MA 02110-1301, USA.
  18 */
  19
  20 #include "config.h"
  21
  22 #include "qscriptvalue.h"
  23
  24 #include "qscriptengine.h"
  25 #include "qscriptengine_p.h"
  26 #include "qscriptvalue_p.h"
  27 #include <QtCore/qdebug.h>
  28
  29 /*!
  30     Constructs an invalid value.
  31 */
  32 QScriptValue::QScriptValue()
  33     : d_ptr(new QScriptValuePrivate())
  34 {
  35 }
  36
  37 /*!
  38   Constructs a new QScriptValue with a boolean \a value.
  39 */
  40 QScriptValue::QScriptValue(bool value)
  41     : d_ptr(new QScriptValuePrivate(value))
  42 {
  43 }
  44
  45 /*!
  46   Constructs a new QScriptValue with a number \a value.
  47 */
  48 QScriptValue::QScriptValue(int value)
  49     : d_ptr(new QScriptValuePrivate(value))
  50 {
  51 }
  52
  53 /*!
  54   Constructs a new QScriptValue with a number \a value.
  55 */
  56 QScriptValue::QScriptValue(uint value)
  57     : d_ptr(new QScriptValuePrivate(value))
  58 {
  59 }
  60
  61 /*!
  62   Constructs a new QScriptValue with a number \a value.
  63 */
  64 QScriptValue::QScriptValue(qsreal value)
  65     : d_ptr(new QScriptValuePrivate(value))
  66 {
  67 }
  68
  69 /*!
  70   Constructs a new QScriptValue with a string \a value.
  71 */
  72 QScriptValue::QScriptValue(const QString& value)
  73     : d_ptr(new QScriptValuePrivate(value))
  74 {
  75 }
  76
  77 /*!
  78   Constructs a new QScriptValue with a special \a value.
  79 */
  80 QScriptValue::QScriptValue(SpecialValue value)
  81     : d_ptr(new QScriptValuePrivate(value))
  82 {
  83 }
  84
  85 /*!
  86   Constructs a new QScriptValue with a string \a value.
  87 */
  88 QScriptValue::QScriptValue(const char* value)
  89     : d_ptr(new QScriptValuePrivate(QString::fromUtf8(value)))
  90 {
  91 }
  92
  93 /*!
  94     Block automatic convertion to bool
  95     \internal
  96 */
  97 QScriptValue::QScriptValue(void* d)
  98 {
  99     Q_ASSERT(false);
 100 }
 101
 102 /*!
 103     Constructs a new QScriptValue from private
 104     \internal
 105 */
 106 QScriptValue::QScriptValue(QScriptValuePrivate* d)
 107     : d_ptr(d)
 108 {
 109 }
 110
 111 /*!
 112   \obsolete
 113
 114   Constructs a new QScriptValue with the boolean \a value and
 115   registers it with the script \a engine.
 116 */
 117 QScriptValue::QScriptValue(QScriptEngine* engine, bool value)
 118 {
 119     if (engine)
 120         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 121     else
 122         d_ptr = new QScriptValuePrivate(value);
 123 }
 124
 125 /*!
 126   \obsolete
 127
 128   Constructs a new QScriptValue with the integer \a value and
 129   registers it with the script \a engine.
 130 */
 131 QScriptValue::QScriptValue(QScriptEngine* engine, int value)
 132 {
 133     if (engine)
 134         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 135     else
 136         d_ptr = new QScriptValuePrivate(value);
 137 }
 138
 139 /*!
 140   \obsolete
 141
 142   Constructs a new QScriptValue with the unsigned integer \a value and
 143   registers it with the script \a engine.
 144  */
 145 QScriptValue::QScriptValue(QScriptEngine* engine, uint value)
 146 {
 147     if (engine)
 148         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 149     else
 150         d_ptr = new QScriptValuePrivate(value);
 151 }
 152
 153 /*!
 154   \obsolete
 155
 156   Constructs a new QScriptValue with the qsreal \a value and
 157   registers it with the script \a engine.
 158 */
 159 QScriptValue::QScriptValue(QScriptEngine* engine, qsreal value)
 160 {
 161     if (engine)
 162         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 163     else
 164         d_ptr = new QScriptValuePrivate(value);
 165 }
 166
 167 /*!
 168   \obsolete
 169
 170   Constructs a new QScriptValue with the string \a value and
 171   registers it with the script \a engine.
 172 */
 173 QScriptValue::QScriptValue(QScriptEngine* engine, const QString& value)
 174 {
 175     if (engine)
 176         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 177     else
 178         d_ptr = new QScriptValuePrivate(value);
 179 }
 180
 181 /*!
 182   \obsolete
 183
 184   Constructs a new QScriptValue with the string \a value and
 185   registers it with the script \a engine.
 186 */
 187 QScriptValue::QScriptValue(QScriptEngine* engine, const char* value)
 188 {
 189     if (engine)
 190         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), QString::fromUtf8(value));
 191     else
 192         d_ptr = new QScriptValuePrivate(QString::fromUtf8(value));
 193 }
 194
 195 /*!
 196   \obsolete
 197
 198   Constructs a new QScriptValue with the special \a value and
 199   registers it with the script \a engine.
 200 */
 201 QScriptValue::QScriptValue(QScriptEngine* engine, SpecialValue value)
 202 {
 203     if (engine)
 204         d_ptr = new QScriptValuePrivate(QScriptEnginePrivate::get(engine), value);
 205     else
 206         d_ptr = new QScriptValuePrivate(value);
 207 }
 208
 209 /*!
 210   Constructs a new QScriptValue that is a copy of \a other.
 211
 212   Note that if \a other is an object (i.e., isObject() would return
 213   true), then only a reference to the underlying object is copied into
 214   the new script value (i.e., the object itself is not copied).
 215 */
 216 QScriptValue::QScriptValue(const QScriptValue& other)
 217     : d_ptr(other.d_ptr)
 218 {
 219 }
 220
 221 /*!
 222     Destroys this QScriptValue.
 223 */
 224 QScriptValue::~QScriptValue()
 225 {
 226 }
 227
 228 /*!
 229   Returns true if this QScriptValue is valid; otherwise returns
 230   false.
 231 */
 232 bool QScriptValue::isValid() const
 233 {
 234     return d_ptr->isValid();
 235 }
 236
 237 /*!
 238   Returns true if this QScriptValue is of the primitive type Boolean;
 239   otherwise returns false.
 240
 241   \sa toBool()
 242 */
 243 bool QScriptValue::isBool() const
 244 {
 245     return d_ptr->isBool();
 246 }
 247
 248 /*!
 249   \obsolete
 250
 251   Use isBool() instead.
 252   Returns true if this QScriptValue is of the primitive type Boolean;
 253   otherwise returns false.
 254 */
 255 bool QScriptValue::isBoolean() const
 256 {
 257     return d_ptr->isBool();
 258 }
 259
 260 /*!
 261   Returns true if this QScriptValue is of the primitive type Number;
 262   otherwise returns false.
 263
 264   \sa toNumber()
 265 */
 266 bool QScriptValue::isNumber() const
 267 {
 268     return d_ptr->isNumber();
 269 }
 270
 271 /*!
 272   Returns true if this QScriptValue is of the primitive type Null;
 273   otherwise returns false.
 274
 275   \sa QScriptEngine::nullValue()
 276 */
 277 bool QScriptValue::isNull() const
 278 {
 279     return d_ptr->isNull();
 280 }
 281
 282 /*!
 283   Returns true if this QScriptValue is of the primitive type String;
 284   otherwise returns false.
 285
 286   \sa toString()
 287 */
 288 bool QScriptValue::isString() const
 289 {
 290     return d_ptr->isString();
 291 }
 292
 293 /*!
 294   Returns true if this QScriptValue is of the primitive type Undefined;
 295   otherwise returns false.
 296
 297   \sa QScriptEngine::undefinedValue()
 298 */
 299 bool QScriptValue::isUndefined() const
 300 {
 301     return d_ptr->isUndefined();
 302 }
 303
 304 /*!
 305   Returns true if this QScriptValue is an object of the Error class;
 306   otherwise returns false.
 307
 308   \sa QScriptContext::throwError()
 309 */
 310 bool QScriptValue::isError() const
 311 {
 312     return d_ptr->isError();
 313 }
 314
 315 /*!
 316   Returns true if this QScriptValue is of the Object type; otherwise
 317   returns false.
 318
 319   Note that function values, variant values, and QObject values are
 320   objects, so this function returns true for such values.
 321
 322   \sa toObject(), QScriptEngine::newObject()
 323 */
 324 bool QScriptValue::isObject() const
 325 {
 326     return d_ptr->isObject();
 327 }
 328
 329 /*!
 330   Returns true if this QScriptValue is a function; otherwise returns
 331   false.
 332
 333   \sa call()
 334 */
 335 bool QScriptValue::isFunction() const
 336 {
 337     return d_ptr->isFunction();
 338 }
 339
 340 /*!
 341   Returns the string value of this QScriptValue, as defined in
 342   \l{ECMA-262} section 9.8, "ToString".
 343
 344   Note that if this QScriptValue is an object, calling this function
 345   has side effects on the script engine, since the engine will call
 346   the object's toString() function (and possibly valueOf()) in an
 347   attempt to convert the object to a primitive value (possibly
 348   resulting in an uncaught script exception).
 349
 350   \sa isString()
 351 */
 352 QString QScriptValue::toString() const
 353 {
 354     return d_ptr->toString();
 355 }
 356
 357 /*!
 358   Returns the number value of this QScriptValue, as defined in
 359   \l{ECMA-262} section 9.3, "ToNumber".
 360
 361   Note that if this QScriptValue is an object, calling this function
 362   has side effects on the script engine, since the engine will call
 363   the object's valueOf() function (and possibly toString()) in an
 364   attempt to convert the object to a primitive value (possibly
 365   resulting in an uncaught script exception).
 366
 367   \sa isNumber(), toInteger(), toInt32(), toUInt32(), toUInt16()
 368 */
 369 qsreal QScriptValue::toNumber() const
 370 {
 371     return d_ptr->toNumber();
 372 }
 373
 374 /*!
 375   Returns the boolean value of this QScriptValue, using the conversion
 376   rules described in \l{ECMA-262} section 9.2, "ToBoolean".
 377
 378   Note that if this QScriptValue is an object, calling this function
 379   has side effects on the script engine, since the engine will call
 380   the object's valueOf() function (and possibly toString()) in an
 381   attempt to convert the object to a primitive value (possibly
 382   resulting in an uncaught script exception).
 383
 384   \sa isBool()
 385 */
 386 bool QScriptValue::toBool() const
 387 {
 388     return d_ptr->toBool();
 389 }
 390
 391 /*!
 392   \obsolete
 393
 394   Use toBool() instead.
 395 */
 396 bool QScriptValue::toBoolean() const
 397 {
 398     return d_ptr->toBool();
 399 }
 400
 401 /*!
 402   Returns the integer value of this QScriptValue, using the conversion
 403   rules described in \l{ECMA-262} section 9.4, "ToInteger".
 404
 405   Note that if this QScriptValue is an object, calling this function
 406   has side effects on the script engine, since the engine will call
 407   the object's valueOf() function (and possibly toString()) in an
 408   attempt to convert the object to a primitive value (possibly
 409   resulting in an uncaught script exception).
 410
 411   \sa toNumber()
 412 */
 413 qsreal QScriptValue::toInteger() const
 414 {
 415     return d_ptr->toInteger();
 416 }
 417
 418 /*!
 419   Returns the signed 32-bit integer value of this QScriptValue, using
 420   the conversion rules described in \l{ECMA-262} section 9.5, "ToInt32".
 421
 422   Note that if this QScriptValue is an object, calling this function
 423   has side effects on the script engine, since the engine will call
 424   the object's valueOf() function (and possibly toString()) in an
 425   attempt to convert the object to a primitive value (possibly
 426   resulting in an uncaught script exception).
 427
 428   \sa toNumber(), toUInt32()
 429 */
 430 qint32 QScriptValue::toInt32() const
 431 {
 432     return d_ptr->toInt32();
 433 }
 434
 435 /*!
 436   Returns the unsigned 32-bit integer value of this QScriptValue, using
 437   the conversion rules described in \l{ECMA-262} section 9.6, "ToUint32".
 438
 439   Note that if this QScriptValue is an object, calling this function
 440   has side effects on the script engine, since the engine will call
 441   the object's valueOf() function (and possibly toString()) in an
 442   attempt to convert the object to a primitive value (possibly
 443   resulting in an uncaught script exception).
 444
 445   \sa toNumber(), toInt32()
 446 */
 447 quint32 QScriptValue::toUInt32() const
 448 {
 449     return d_ptr->toUInt32();
 450 }
 451
 452 /*!
 453   Returns the unsigned 16-bit integer value of this QScriptValue, using
 454   the conversion rules described in \l{ECMA-262} section 9.7, "ToUint16".
 455
 456   Note that if this QScriptValue is an object, calling this function
 457   has side effects on the script engine, since the engine will call
 458   the object's valueOf() function (and possibly toString()) in an
 459   attempt to convert the object to a primitive value (possibly
 460   resulting in an uncaught script exception).
 461
 462   \sa toNumber()
 463 */
 464 quint16 QScriptValue::toUInt16() const
 465 {
 466     return d_ptr->toUInt16();
 467 }
 468
 469 /*!
 470   Calls this QScriptValue as a function, using \a thisObject as
 471   the `this' object in the function call, and passing \a args
 472   as arguments to the function. Returns the value returned from
 473   the function.
 474
 475   If this QScriptValue is not a function, call() does nothing
 476   and returns an invalid QScriptValue.
 477
 478   Note that if \a thisObject is not an object, the global object
 479   (see \l{QScriptEngine::globalObject()}) will be used as the
 480   `this' object.
 481
 482   Calling call() can cause an exception to occur in the script engine;
 483   in that case, call() returns the value that was thrown (typically an
 484   \c{Error} object). You can call
 485   QScriptEngine::hasUncaughtException() to determine if an exception
 486   occurred.
 487
 488   \snippet doc/src/snippets/code/src_script_qscriptvalue.cpp 2
 489
 490   \sa construct()
 491 */
 492 QScriptValue QScriptValue::call(const QScriptValue& thisObject, const QScriptValueList& args)
 493 {
 494     return d_ptr->call(thisObject.d_ptr.data(), args);
 495 }
 496
 497 /*!
 498   Returns the QScriptEngine that created this QScriptValue,
 499   or 0 if this QScriptValue is invalid or the value is not
 500   associated with a particular engine.
 501 */
 502 QScriptEngine* QScriptValue::engine() const
 503 {
 504     QScriptEnginePrivate* engine = d_ptr->engine();
 505     if (engine)
 506         return QScriptEnginePrivate::get(engine);
 507     return 0;
 508 }
 509
 510 /*!
 511   Assigns the \a other value to this QScriptValue.
 512
 513   Note that if \a other is an object (isObject() returns true),
 514   only a reference to the underlying object will be assigned;
 515   the object itself will not be copied.
 516 */
 517 QScriptValue& QScriptValue::operator=(const QScriptValue& other)
 518 {
 519     d_ptr = other.d_ptr;
 520     return *this;
 521 }
 522
 523 /*!
 524   Returns true if this QScriptValue is equal to \a other, otherwise
 525   returns false. The comparison follows the behavior described in
 526   \l{ECMA-262} section 11.9.3, "The Abstract Equality Comparison
 527   Algorithm".
 528
 529   This function can return true even if the type of this QScriptValue
 530   is different from the type of the \a other value; i.e. the
 531   comparison is not strict.  For example, comparing the number 9 to
 532   the string "9" returns true; comparing an undefined value to a null
 533   value returns true; comparing a \c{Number} object whose primitive
 534   value is 6 to a \c{String} object whose primitive value is "6"
 535   returns true; and comparing the number 1 to the boolean value
 536   \c{true} returns true. If you want to perform a comparison
 537   without such implicit value conversion, use strictlyEquals().
 538
 539   Note that if this QScriptValue or the \a other value are objects,
 540   calling this function has side effects on the script engine, since
 541   the engine will call the object's valueOf() function (and possibly
 542   toString()) in an attempt to convert the object to a primitive value
 543   (possibly resulting in an uncaught script exception).
 544
 545   \sa strictlyEquals(), lessThan()
 546 */
 547 bool QScriptValue::equals(const QScriptValue& other) const
 548 {
 549     return d_ptr == other.d_ptr || d_ptr->equals(QScriptValuePrivate::get(other));
 550 }
 551
 552 /*!
 553   Returns true if this QScriptValue is equal to \a other using strict
 554   comparison (no conversion), otherwise returns false. The comparison
 555   follows the behavior described in \l{ECMA-262} section 11.9.6, "The
 556   Strict Equality Comparison Algorithm".
 557
 558   If the type of this QScriptValue is different from the type of the
 559   \a other value, this function returns false. If the types are equal,
 560   the result depends on the type, as shown in the following table:
 561
 562     \table
 563     \header \o Type \o Result
 564     \row    \o Undefined  \o true
 565     \row    \o Null       \o true
 566     \row    \o Boolean    \o true if both values are true, false otherwise
 567     \row    \o Number     \o false if either value is NaN (Not-a-Number); true if values are equal, false otherwise
 568     \row    \o String     \o true if both values are exactly the same sequence of characters, false otherwise
 569     \row    \o Object     \o true if both values refer to the same object, false otherwise
 570     \endtable
 571
 572   \sa equals()
 573 */
 574 bool QScriptValue::strictlyEquals(const QScriptValue& other) const
 575 {
 576     return d_ptr == other.d_ptr || d_ptr->strictlyEquals(QScriptValuePrivate::get(other));
 577 }