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

     2 **

     3 ** Copyright (C) 2010 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 QtScript module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL-ONLY$

    10 ** GNU Lesser General Public License Usage

    11 ** This file may be used under the terms of the GNU Lesser

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

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

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

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

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

    17 **

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

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

    20 ** $QT_END_LICENSE$

    21 **

    22 ****************************************************************************/

    23 

    24 #include "config.h"

    25 #include "qscriptvalueiterator.h"

    26 

    27 #include "qscriptstring.h"

    28 #include "qscriptengine.h"

    29 #include "qscriptengine_p.h"

    30 #include "qscriptvalue_p.h"

    31 #include "qlinkedlist.h"

    32 

    33 

    34 #include "JSObject.h"

    35 #include "PropertyNameArray.h"

    36 #include "JSArray.h"

    37 #include "JSFunction.h"

    38 

    39 QT_BEGIN_NAMESPACE

    40 

    41 /*!

    42   \since 4.3

    43   \class QScriptValueIterator

    44 

    45   \brief The QScriptValueIterator class provides a Java-style iterator for QScriptValue.

    46 

    47   \ingroup script

    48 

    49 

    50   The QScriptValueIterator constructor takes a QScriptValue as

    51   argument.  After construction, the iterator is located at the very

    52   beginning of the sequence of properties. Here's how to iterate over

    53   all the properties of a QScriptValue:

    54 

    55   \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 0

    56 

    57   The next() advances the iterator. The name(), value() and flags()

    58   functions return the name, value and flags of the last item that was

    59   jumped over.

    60 

    61   If you want to remove properties as you iterate over the

    62   QScriptValue, use remove(). If you want to modify the value of a

    63   property, use setValue().

    64 

    65   Note that QScriptValueIterator only iterates over the QScriptValue's

    66   own properties; i.e. it does not follow the prototype chain. You can

    67   use a loop like this to follow the prototype chain:

    68 

    69   \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 1

    70 

    71   Note that QScriptValueIterator will not automatically skip over

    72   properties that have the QScriptValue::SkipInEnumeration flag set;

    73   that flag only affects iteration in script code.  If you want, you

    74   can skip over such properties with code like the following:

    75 

    76   \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 2

    77 

    78   \sa QScriptValue::property()

    79 */

    80 

    81 class QScriptValueIteratorPrivate

    82 {

    83 public:

    84     QScriptValueIteratorPrivate()

    85         : initialized(false)

    86     {}

    87     void ensureInitialized()

    88     {

    89         if (initialized)

    90             return;

    91         QScriptEnginePrivate *eng_p = QScriptEnginePrivate::get(object.engine());

    92         JSC::ExecState *exec = eng_p->globalExec();

    93         JSC::PropertyNameArray propertyNamesArray(exec);

    94         propertyNamesArray.setShouldCache(false);

    95         JSC::asObject(QScriptValuePrivate::get(object)->jscValue)->getOwnPropertyNames(exec, propertyNamesArray, /*includeNonEnumerable=*/true);

    96 

    97         JSC::PropertyNameArray::const_iterator propertyNamesIt = propertyNamesArray.begin();

    98         for(; propertyNamesIt != propertyNamesArray.end(); ++propertyNamesIt) {

    99             propertyNames.append(propertyNamesIt->ustring());

   100         }

   101         it = propertyNames.begin();

   102         initialized = true;

   103     }

   104 

   105     QScriptValue object;

   106     QLinkedList<JSC::UString> propertyNames;

   107     QLinkedList<JSC::UString>::iterator it;

   108     QLinkedList<JSC::UString>::iterator current;

   109     bool initialized;

   110 };

   111 

   112 /*!

   113   Constructs an iterator for traversing \a object. The iterator is

   114   set to be at the front of the sequence of properties (before the

   115   first property).

   116 */

   117 QScriptValueIterator::QScriptValueIterator(const QScriptValue &object)

   118     : d_ptr(0)

   119 {

   120     if (object.isObject()) {

   121         d_ptr.reset(new QScriptValueIteratorPrivate());

   122         d_ptr->object = object;

   123     }

   124 }

   125 

   126 /*!

   127   Destroys the iterator.

   128 */

   129 QScriptValueIterator::~QScriptValueIterator()

   130 {

   131 }

   132 

   133 /*!

   134   Returns true if there is at least one item ahead of the iterator

   135   (i.e. the iterator is \e not at the back of the property sequence);

   136   otherwise returns false.

   137 

   138   \sa next(), hasPrevious()

   139 */

   140 bool QScriptValueIterator::hasNext() const

   141 {

   142     Q_D(const QScriptValueIterator);

   143     if (!d)

   144         return false;

   145 

   146     const_cast<QScriptValueIteratorPrivate*>(d)->ensureInitialized();

   147     return d->it != d->propertyNames.end();

   148 }

   149 

   150 /*!

   151   Advances the iterator by one position.

   152 

   153   Calling this function on an iterator located at the back of the

   154   container leads to undefined results.

   155 

   156   \sa hasNext(), previous(), name()

   157 */

   158 void QScriptValueIterator::next()

   159 {

   160     Q_D(QScriptValueIterator);

   161     if (!d)

   162         return;

   163     d->ensureInitialized();

   164 

   165     d->current = d->it;

   166     ++(d->it);

   167 }

   168 

   169 /*!

   170   Returns true if there is at least one item behind the iterator

   171   (i.e. the iterator is \e not at the front of the property sequence);

   172   otherwise returns false.

   173 

   174   \sa previous(), hasNext()

   175 */

   176 bool QScriptValueIterator::hasPrevious() const

   177 {

   178     Q_D(const QScriptValueIterator);

   179     if (!d)

   180         return false;

   181 

   182     const_cast<QScriptValueIteratorPrivate*>(d)->ensureInitialized();

   183     return d->it != d->propertyNames.begin();

   184 }

   185 

   186 /*!

   187   Moves the iterator back by one position.

   188 

   189   Calling this function on an iterator located at the front of the

   190   container leads to undefined results.

   191 

   192   \sa hasPrevious(), next(), name()

   193 */

   194 void QScriptValueIterator::previous()

   195 {

   196     Q_D(QScriptValueIterator);

   197     if (!d)

   198         return;

   199     d->ensureInitialized();

   200     --(d->it);

   201     d->current = d->it;

   202 }

   203 

   204 /*!

   205   Moves the iterator to the front of the QScriptValue (before the

   206   first property).

   207 

   208   \sa toBack(), next()

   209 */

   210 void QScriptValueIterator::toFront()

   211 {

   212     Q_D(QScriptValueIterator);

   213     if (!d)

   214         return;

   215     d->ensureInitialized();

   216     d->it = d->propertyNames.begin();

   217 }

   218 

   219 /*!

   220   Moves the iterator to the back of the QScriptValue (after the

   221   last property).

   222 

   223   \sa toFront(), previous()

   224 */

   225 void QScriptValueIterator::toBack()

   226 {

   227     Q_D(QScriptValueIterator);

   228     if (!d)

   229         return;

   230     d->ensureInitialized();

   231     d->it = d->propertyNames.end();

   232 }

   233 

   234 /*!

   235   Returns the name of the last property that was jumped over using

   236   next() or previous().

   237 

   238   \sa value(), flags()

   239 */

   240 QString QScriptValueIterator::name() const

   241 {

   242     Q_D(const QScriptValueIterator);

   243     if (!d || !d->initialized)

   244         return QString();

   245     return *d->current;

   246 }

   247 

   248 /*!

   249   \since 4.4

   250 

   251   Returns the name of the last property that was jumped over using

   252   next() or previous().

   253 */

   254 QScriptString QScriptValueIterator::scriptName() const

   255 {

   256     Q_D(const QScriptValueIterator);

   257     if (!d || !d->initialized)

   258         return QScriptString();

   259     return d->object.engine()->toStringHandle(name());

   260 }

   261 

   262 /*!

   263   Returns the value of the last property that was jumped over using

   264   next() or previous().

   265 

   266   \sa setValue(), name()

   267 */

   268 QScriptValue QScriptValueIterator::value() const

   269 {

   270     Q_D(const QScriptValueIterator);

   271     if (!d || !d->initialized)

   272         return QScriptValue();

   273     return d->object.property(name());

   274 }

   275 

   276 /*!

   277   Sets the \a value of the last property that was jumped over using

   278   next() or previous().

   279 

   280   \sa value(), name()

   281 */

   282 void QScriptValueIterator::setValue(const QScriptValue &value)

   283 {

   284     Q_D(QScriptValueIterator);

   285     if (!d || !d->initialized)

   286         return;

   287     d->object.setProperty(name(), value);

   288 }

   289 

   290 /*!

   291   Returns the flags of the last property that was jumped over using

   292   next() or previous().

   293 

   294   \sa value()

   295 */

   296 QScriptValue::PropertyFlags QScriptValueIterator::flags() const

   297 {

   298     Q_D(const QScriptValueIterator);

   299     if (!d || !d->initialized)

   300         return 0;

   301     return d->object.propertyFlags(name());

   302 }

   303 

   304 /*!

   305   Removes the last property that was jumped over using next()

   306   or previous().

   307 

   308   \sa setValue()

   309 */

   310 void QScriptValueIterator::remove()

   311 {

   312     Q_D(QScriptValueIterator);

   313     if (!d || !d->initialized)

   314         return;

   315     d->object.setProperty(name(), QScriptValue());

   316     d->propertyNames.erase(d->current);

   317 }

   318 

   319 /*!

   320   Makes the iterator operate on \a object. The iterator is set to be

   321   at the front of the sequence of properties (before the first

   322   property).

   323 */

   324 QScriptValueIterator& QScriptValueIterator::operator=(QScriptValue &object)

   325 {

   326     d_ptr.reset();

   327     if (object.isObject()) {

   328         d_ptr.reset(new QScriptValueIteratorPrivate());

   329         d_ptr->object = object;

   330     }

   331     return *this;

   332 }

   333 

   334 QT_END_NAMESPACE