src/declarative/qml/v8/qjsvalueiterator.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   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 ** us via http://www.qt-project.org/.
  20 ** $QT_END_LICENSE$
  21 **
  22 ****************************************************************************/
  23
  24 #include "qjsvalueiterator.h"
  25 #include "qjsvalueiterator_p.h"
  26
  27 #include "qscriptisolate_p.h"
  28 #include "qjsvalue_p.h"
  29 #include "qv8engine_p.h"
  30 #include "qscript_impl_p.h"
  31
  32 QT_BEGIN_NAMESPACE
  33
  34 /*!
  35     \class QJSValueIterator
  36
  37     \brief The QJSValueIterator class provides a Java-style iterator for QJSValue.
  38
  39     \ingroup qtjavascript
  40
  41
  42     The QJSValueIterator constructor takes a QJSValue as
  43     argument.  After construction, the iterator is located at the very
  44     beginning of the sequence of properties. Here's how to iterate over
  45     all the properties of a QJSValue:
  46
  47     \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 0
  48
  49     The next() advances the iterator. The name() and value()
  50     functions return the name and value of the last item that was
  51     jumped over.
  52
  53     Note that QJSValueIterator only iterates over the QJSValue's
  54     own properties; i.e. it does not follow the prototype chain. You can
  55     use a loop like this to follow the prototype chain:
  56
  57     \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 1
  58
  59     Note that QJSValueIterator will not automatically skip over
  60     properties that have the QJSValue::SkipInEnumeration flag set;
  61     that flag only affects iteration in script code.  If you want, you
  62     can skip over such properties with code like the following:
  63
  64     \snippet doc/src/snippets/code/src_script_qjsvalueiterator.cpp 2
  65
  66     \sa QJSValue::property()
  67 */
  68
  69 /*!
  70     Constructs an iterator for traversing \a object. The iterator is
  71     set to be at the front of the sequence of properties (before the
  72     first property).
  73 */
  74 QJSValueIterator::QJSValueIterator(const QJSValue& object)
  75     : d_ptr(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)))
  76 {}
  77
  78 /*!
  79     Destroys the iterator.
  80 */
  81 QJSValueIterator::~QJSValueIterator()
  82 {}
  83
  84 /*!
  85     Returns true if there is at least one item ahead of the iterator
  86     (i.e. the iterator is \e not at the back of the property sequence);
  87     otherwise returns false.
  88
  89     \sa next()
  90 */
  91 bool QJSValueIterator::hasNext() const
  92 {
  93     Q_D(const QJSValueIterator);
  94     QScriptIsolate api(d->engine());
  95     return d->hasNext();
  96 }
  97
  98 /*!
  99     Advances the iterator by one position.
 100     Returns true if there is at least one item ahead of the iterator
 101     (i.e. the iterator is \e not at the back of the property sequence);
 102     otherwise returns false.
 103
 104     Calling this function on an iterator located at the back of the
 105     container leads to undefined results.
 106
 107     \sa hasNext(), name()
 108 */
 109 bool QJSValueIterator::next()
 110 {
 111     Q_D(QJSValueIterator);
 112     QScriptIsolate api(d->engine());
 113     return d->next();
 114 }
 115
 116 /*!
 117     Returns the name of the last property that was jumped over using
 118     next().
 119
 120     \sa value()
 121 */
 122 QString QJSValueIterator::name() const
 123 {
 124     Q_D(const QJSValueIterator);
 125     QScriptIsolate api(d->engine());
 126     return d_ptr->name();
 127 }
 128
 129
 130 /*!
 131     Returns the value of the last property that was jumped over using
 132     next().
 133
 134     \sa name()
 135 */
 136 QJSValue QJSValueIterator::value() const
 137 {
 138     Q_D(const QJSValueIterator);
 139     QScriptIsolate api(d->engine());
 140     return QJSValuePrivate::get(d->value());
 141 }
 142
 143
 144 /*!
 145     Makes the iterator operate on \a object. The iterator is set to be
 146     at the front of the sequence of properties (before the first
 147     property).
 148 */
 149 QJSValueIterator& QJSValueIterator::operator=(QJSValue& object)
 150 {
 151     Q_D(QJSValueIterator);
 152     QScriptIsolate api(d->engine());
 153     d_ptr.reset(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)));
 154     return *this;
 155 }
 156
 157 QT_END_NAMESPACE