src/qml/qml/v8/qjsvalueiterator.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtQml module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qjsvalueiterator.h"
  43 #include "qjsvalueiterator_p.h"
  44
  45 #include "qscriptisolate_p.h"
  46 #include "qjsvalue_p.h"
  47 #include "qv8engine_p.h"
  48 #include "qscript_impl_p.h"
  49
  50 QT_BEGIN_NAMESPACE
  51
  52 /*!
  53     \class QJSValueIterator
  54
  55     \brief The QJSValueIterator class provides a Java-style iterator for QJSValue.
  56
  57     \ingroup qtjavascript
  58
  59
  60     The QJSValueIterator constructor takes a QJSValue as
  61     argument.  After construction, the iterator is located at the very
  62     beginning of the sequence of properties. Here's how to iterate over
  63     all the properties of a QJSValue:
  64
  65     \snippet code/src_script_qjsvalueiterator.cpp 0
  66
  67     The next() advances the iterator. The name() and value()
  68     functions return the name and value of the last item that was
  69     jumped over.
  70
  71     Note that QJSValueIterator only iterates over the QJSValue's
  72     own properties; i.e. it does not follow the prototype chain. You can
  73     use a loop like this to follow the prototype chain:
  74
  75     \snippet code/src_script_qjsvalueiterator.cpp 1
  76
  77     \sa QJSValue::property()
  78 */
  79
  80 /*!
  81     Constructs an iterator for traversing \a object. The iterator is
  82     set to be at the front of the sequence of properties (before the
  83     first property).
  84 */
  85 QJSValueIterator::QJSValueIterator(const QJSValue& object)
  86     : d_ptr(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)))
  87 {}
  88
  89 /*!
  90     Destroys the iterator.
  91 */
  92 QJSValueIterator::~QJSValueIterator()
  93 {}
  94
  95 /*!
  96     Returns true if there is at least one item ahead of the iterator
  97     (i.e. the iterator is \e not at the back of the property sequence);
  98     otherwise returns false.
  99
 100     \sa next()
 101 */
 102 bool QJSValueIterator::hasNext() const
 103 {
 104     Q_D(const QJSValueIterator);
 105     QScriptIsolate api(d->engine());
 106     return d->hasNext();
 107 }
 108
 109 /*!
 110     Advances the iterator by one position.
 111     Returns true if there is at least one item ahead of the iterator
 112     (i.e. the iterator is \e not at the back of the property sequence);
 113     otherwise returns false.
 114
 115     Calling this function on an iterator located at the back of the
 116     container leads to undefined results.
 117
 118     \sa hasNext(), name()
 119 */
 120 bool QJSValueIterator::next()
 121 {
 122     Q_D(QJSValueIterator);
 123     QScriptIsolate api(d->engine());
 124     return d->next();
 125 }
 126
 127 /*!
 128     Returns the name of the last property that was jumped over using
 129     next().
 130
 131     \sa value()
 132 */
 133 QString QJSValueIterator::name() const
 134 {
 135     Q_D(const QJSValueIterator);
 136     QScriptIsolate api(d->engine());
 137     return d_ptr->name();
 138 }
 139
 140
 141 /*!
 142     Returns the value of the last property that was jumped over using
 143     next().
 144
 145     \sa name()
 146 */
 147 QJSValue QJSValueIterator::value() const
 148 {
 149     Q_D(const QJSValueIterator);
 150     QScriptIsolate api(d->engine());
 151     return QJSValuePrivate::get(d->value());
 152 }
 153
 154
 155 /*!
 156     Makes the iterator operate on \a object. The iterator is set to be
 157     at the front of the sequence of properties (before the first
 158     property).
 159 */
 160 QJSValueIterator& QJSValueIterator::operator=(QJSValue& object)
 161 {
 162     Q_D(QJSValueIterator);
 163     QScriptIsolate api(d->engine());
 164     d_ptr.reset(new QJSValueIteratorPrivate(QJSValuePrivate::get(object)));
 165     return *this;
 166 }
 167
 168 QT_END_NAMESPACE