src/declarative/qml/v8/qjsvalueiterator.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 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 "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 script
  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(), value() and flags()
  50     functions return the name, value and flags of the last item that was
  51     jumped over.
  52
  53     If you want to remove properties as you iterate over the
  54     QJSValue, use remove(). If you want to modify the value of a
  55     property, use setValue().
  56
  57     Note that QJSValueIterator only iterates over the QJSValue's
  58     own properties; i.e. it does not follow the prototype chain. You can
  59     use a loop like this to follow the prototype chain:
  60
  61     \snippet doc/src/snippets/code/src_script_QJSValueIterator.cpp 1
  62
  63     Note that QJSValueIterator will not automatically skip over
  64     properties that have the QJSValue::SkipInEnumeration flag set;
  65     that flag only affects iteration in script code.  If you want, you
  66     can skip over such properties with code like the following:
  67
  68     \snippet doc/src/snippets/code/src_script_QJSValueIterator.cpp 2
  69
  70     \sa QJSValue::property()
  71 */
  72
  73 /*!
  74     Constructs an iterator for traversing \a object. The iterator is
  75     set to be at the front of the sequence of properties (before the
  76     first property).
  77 */
  78 QJSValueIterator::QJSValueIterator(const QJSValue& object)
  79     : d_ptr(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)))
  80 {}
  81
  82 /*!
  83     Destroys the iterator.
  84 */
  85 QJSValueIterator::~QJSValueIterator()
  86 {}
  87
  88 /*!
  89     Returns true if there is at least one item ahead of the iterator
  90     (i.e. the iterator is \e not at the back of the property sequence);
  91     otherwise returns false.
  92
  93     \sa next(), hasPrevious()
  94 */
  95 bool QJSValueIterator::hasNext() const
  96 {
  97     Q_D(const QJSValueIterator);
  98     QScriptIsolate api(d->engine());
  99     return d->hasNext();
 100 }
 101
 102 /*!
 103     Advances the iterator by one position.
 104
 105     Calling this function on an iterator located at the back of the
 106     container leads to undefined results.
 107
 108     \sa hasNext(), previous(), name()
 109 */
 110 bool QJSValueIterator::next()
 111 {
 112     Q_D(QJSValueIterator);
 113     QScriptIsolate api(d->engine());
 114     return d->next();
 115 }
 116
 117 /*!
 118     Returns the name of the last property that was jumped over using
 119     next() or previous().
 120
 121     \sa value(), flags()
 122 */
 123 QString QJSValueIterator::name() const
 124 {
 125     Q_D(const QJSValueIterator);
 126     QScriptIsolate api(d->engine());
 127     return d_ptr->name();
 128 }
 129
 130
 131 /*!
 132     Returns the value of the last property that was jumped over using
 133     next() or previous().
 134
 135     \sa setValue(), name()
 136 */
 137 QJSValue QJSValueIterator::value() const
 138 {
 139     Q_D(const QJSValueIterator);
 140     QScriptIsolate api(d->engine());
 141     return QJSValuePrivate::get(d->value());
 142 }
 143
 144
 145 /*!
 146     Makes the iterator operate on \a object. The iterator is set to be
 147     at the front of the sequence of properties (before the first
 148     property).
 149 */
 150 QJSValueIterator& QJSValueIterator::operator=(QJSValue& object)
 151 {
 152     Q_D(QJSValueIterator);
 153     QScriptIsolate api(d->engine());
 154     d_ptr.reset(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)));
 155     return *this;
 156 }
 157
 158 QT_END_NAMESPACE