qt/api/qscriptvalueiterator.cpp

   1 /*
   2     Copyright (C) 2010 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 "qscriptvalueiterator.h"
  23
  24 #include "qscriptvalue_p.h"
  25 #include "qscriptvalueiterator_p.h"
  26
  27 /*!
  28     \class QScriptValueIterator
  29
  30     \brief The QScriptValueIterator class provides a Java-style iterator for QScriptValue.
  31
  32     \ingroup script
  33
  34
  35     The QScriptValueIterator constructor takes a QScriptValue as
  36     argument.  After construction, the iterator is located at the very
  37     beginning of the sequence of properties. Here's how to iterate over
  38     all the properties of a QScriptValue:
  39
  40     \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 0
  41
  42     The next() advances the iterator. The name(), value() and flags()
  43     functions return the name, value and flags of the last item that was
  44     jumped over.
  45
  46     If you want to remove properties as you iterate over the
  47     QScriptValue, use remove(). If you want to modify the value of a
  48     property, use setValue().
  49
  50     Note that QScriptValueIterator only iterates over the QScriptValue's
  51     own properties; i.e. it does not follow the prototype chain. You can
  52     use a loop like this to follow the prototype chain:
  53
  54     \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 1
  55
  56     Note that QScriptValueIterator will not automatically skip over
  57     properties that have the QScriptValue::SkipInEnumeration flag set;
  58     that flag only affects iteration in script code.  If you want, you
  59     can skip over such properties with code like the following:
  60
  61     \snippet doc/src/snippets/code/src_script_qscriptvalueiterator.cpp 2
  62
  63     \sa QScriptValue::property()
  64 */
  65
  66 /*!
  67     Constructs an iterator for traversing \a object. The iterator is
  68     set to be at the front of the sequence of properties (before the
  69     first property).
  70 */
  71 QScriptValueIterator::QScriptValueIterator(const QScriptValue& object)
  72     : d_ptr(new QScriptValueIteratorPrivate(QScriptValuePrivate::get(object)))
  73 {}
  74
  75 /*!
  76     Destroys the iterator.
  77 */
  78 QScriptValueIterator::~QScriptValueIterator()
  79 {}
  80
  81 /*!
  82     Returns true if there is at least one item ahead of the iterator
  83     (i.e. the iterator is \e not at the back of the property sequence);
  84     otherwise returns false.
  85
  86     \sa next(), hasPrevious()
  87 */
  88 bool QScriptValueIterator::hasNext() const
  89 {
  90     return d_ptr->hasNext();
  91 }
  92
  93 /*!
  94     Advances the iterator by one position.
  95
  96     Calling this function on an iterator located at the back of the
  97     container leads to undefined results.
  98
  99     \sa hasNext(), previous(), name()
 100 */
 101 void QScriptValueIterator::next()
 102 {
 103     d_ptr->next();
 104 }
 105
 106 /*!
 107     Returns true if there is at least one item behind the iterator
 108     (i.e. the iterator is \e not at the front of the property sequence);
 109     otherwise returns false.
 110
 111     \sa previous(), hasNext()
 112 */
 113 bool QScriptValueIterator::hasPrevious() const
 114 {
 115     return d_ptr->hasPrevious();
 116 }
 117
 118 /*!
 119     Moves the iterator back by one position.
 120
 121     Calling this function on an iterator located at the front of the
 122     container leads to undefined results.
 123
 124     \sa hasPrevious(), next(), name()
 125 */
 126 void QScriptValueIterator::previous()
 127 {
 128     d_ptr->previous();
 129 }
 130
 131 /*!
 132     Moves the iterator to the front of the QScriptValue (before the
 133     first property).
 134
 135     \sa toBack(), next()
 136 */
 137 void QScriptValueIterator::toFront()
 138 {
 139     d_ptr->toFront();
 140 }
 141
 142 /*!
 143     Moves the iterator to the back of the QScriptValue (after the
 144     last property).
 145
 146     \sa toFront(), previous()
 147 */
 148 void QScriptValueIterator::toBack()
 149 {
 150     d_ptr->toBack();
 151 }
 152
 153 /*!
 154     Returns the name of the last property that was jumped over using
 155     next() or previous().
 156
 157     \sa value(), flags()
 158 */
 159 QString QScriptValueIterator::name() const
 160 {
 161     return d_ptr->name();
 162 }
 163
 164 /*!
 165     Returns the name of the last property that was jumped over using
 166     next() or previous().
 167 */
 168 QScriptString QScriptValueIterator::scriptName() const
 169 {
 170     return QScriptStringPrivate::get(d_ptr->scriptName());
 171 }
 172
 173 /*!
 174     Returns the value of the last property that was jumped over using
 175     next() or previous().
 176
 177     \sa setValue(), name()
 178 */
 179 QScriptValue QScriptValueIterator::value() const
 180 {
 181     return QScriptValuePrivate::get(d_ptr->value());
 182 }
 183
 184 /*!
 185     Sets the \a value of the last property that was jumped over using
 186     next() or previous().
 187
 188     \sa value(), name()
 189 */
 190 void QScriptValueIterator::setValue(const QScriptValue& value)
 191 {
 192     d_ptr->setValue(QScriptValuePrivate::get(value));
 193 }
 194
 195 /*!
 196     Removes the last property that was jumped over using next()
 197     or previous().
 198
 199     \sa setValue()
 200 */
 201 void QScriptValueIterator::remove()
 202 {
 203     d_ptr->remove();
 204 }
 205
 206 /*!
 207     Returns the flags of the last property that was jumped over using
 208     next() or previous().
 209
 210     \sa value()
 211 */
 212 QScriptValue::PropertyFlags QScriptValueIterator::flags() const
 213 {
 214     return d_ptr->flags();
 215 }
 216
 217 /*!
 218     Makes the iterator operate on \a object. The iterator is set to be
 219     at the front of the sequence of properties (before the first
 220     property).
 221 */
 222 QScriptValueIterator& QScriptValueIterator::operator=(QScriptValue& object)
 223 {
 224     d_ptr = new QScriptValueIteratorPrivate(QScriptValuePrivate::get(object));
 225     return *this;
 226 }