Merge branch 'master' of scm.dev.nokia.troll.no:qt/qt-air-staging into master-integration
[qt:qt.git] / src / script / api / qscriptvalueiterator.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 "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
88     ~QScriptValueIteratorPrivate()
89     {
90         if (!initialized)
91             return;
92         QScriptEnginePrivate *eng_p = engine();
93         if (!eng_p)
94             return;
95         QScript::APIShim shim(eng_p);
96         propertyNames.clear(); //destroying the identifiers need to be done under the APIShim guard
97     }
98
99     QScriptValuePrivate *object() const
100     {
101         return QScriptValuePrivate::get(objectValue);
102     }
103
104     QScriptEnginePrivate *engine() const
105     {
106         return QScriptEnginePrivate::get(objectValue.engine());
107     }
108
109     void ensureInitialized()
110     {
111         if (initialized)
112             return;
113         QScriptEnginePrivate *eng_p = engine();
114         QScript::APIShim shim(eng_p);
115         JSC::ExecState *exec = eng_p->globalExec();
116         JSC::PropertyNameArray propertyNamesArray(exec);
117         JSC::asObject(object()->jscValue)->getOwnPropertyNames(exec, propertyNamesArray, JSC::IncludeDontEnumProperties);
118
119         JSC::PropertyNameArray::const_iterator propertyNamesIt = propertyNamesArray.begin();
120         for(; propertyNamesIt != propertyNamesArray.end(); ++propertyNamesIt) {
121             propertyNames.append(*propertyNamesIt);
122         }
123         it = propertyNames.begin();
124         initialized = true;
125     }
126
127     QScriptValue objectValue;
128     QLinkedList<JSC::Identifier> propertyNames;
129     QLinkedList<JSC::Identifier>::iterator it;
130     QLinkedList<JSC::Identifier>::iterator current;
131     bool initialized;
132 };
133
134 /*!
135   Constructs an iterator for traversing \a object. The iterator is
136   set to be at the front of the sequence of properties (before the
137   first property).
138 */
139 QScriptValueIterator::QScriptValueIterator(const QScriptValue &object)
140     : d_ptr(0)
141 {
142     if (object.isObject()) {
143         d_ptr.reset(new QScriptValueIteratorPrivate());
144         d_ptr->objectValue = object;
145     }
146 }
147
148 /*!
149   Destroys the iterator.
150 */
151 QScriptValueIterator::~QScriptValueIterator()
152 {
153 }
154
155 /*!
156   Returns true if there is at least one item ahead of the iterator
157   (i.e. the iterator is \e not at the back of the property sequence);
158   otherwise returns false.
159
160   \sa next(), hasPrevious()
161 */
162 bool QScriptValueIterator::hasNext() const
163 {
164     Q_D(const QScriptValueIterator);
165     if (!d || !d->engine())
166         return false;
167
168     const_cast<QScriptValueIteratorPrivate*>(d)->ensureInitialized();
169     return d->it != d->propertyNames.end();
170 }
171
172 /*!
173   Advances the iterator by one position.
174
175   Calling this function on an iterator located at the back of the
176   container leads to undefined results.
177
178   \sa hasNext(), previous(), name()
179 */
180 void QScriptValueIterator::next()
181 {
182     Q_D(QScriptValueIterator);
183     if (!d)
184         return;
185     d->ensureInitialized();
186
187     d->current = d->it;
188     ++(d->it);
189 }
190
191 /*!
192   Returns true if there is at least one item behind the iterator
193   (i.e. the iterator is \e not at the front of the property sequence);
194   otherwise returns false.
195
196   \sa previous(), hasNext()
197 */
198 bool QScriptValueIterator::hasPrevious() const
199 {
200     Q_D(const QScriptValueIterator);
201     if (!d || !d->engine())
202         return false;
203
204     const_cast<QScriptValueIteratorPrivate*>(d)->ensureInitialized();
205     return d->it != d->propertyNames.begin();
206 }
207
208 /*!
209   Moves the iterator back by one position.
210
211   Calling this function on an iterator located at the front of the
212   container leads to undefined results.
213
214   \sa hasPrevious(), next(), name()
215 */
216 void QScriptValueIterator::previous()
217 {
218     Q_D(QScriptValueIterator);
219     if (!d)
220         return;
221     d->ensureInitialized();
222     --(d->it);
223     d->current = d->it;
224 }
225
226 /*!
227   Moves the iterator to the front of the QScriptValue (before the
228   first property).
229
230   \sa toBack(), next()
231 */
232 void QScriptValueIterator::toFront()
233 {
234     Q_D(QScriptValueIterator);
235     if (!d)
236         return;
237     d->ensureInitialized();
238     d->it = d->propertyNames.begin();
239 }
240
241 /*!
242   Moves the iterator to the back of the QScriptValue (after the
243   last property).
244
245   \sa toFront(), previous()
246 */
247 void QScriptValueIterator::toBack()
248 {
249     Q_D(QScriptValueIterator);
250     if (!d)
251         return;
252     d->ensureInitialized();
253     d->it = d->propertyNames.end();
254 }
255
256 /*!
257   Returns the name of the last property that was jumped over using
258   next() or previous().
259
260   \sa value(), flags()
261 */
262 QString QScriptValueIterator::name() const
263 {
264     Q_D(const QScriptValueIterator);
265     if (!d || !d->initialized || !d->engine())
266         return QString();
267     return d->current->ustring();
268 }
269
270 /*!
271   \since 4.4
272
273   Returns the name of the last property that was jumped over using
274   next() or previous().
275 */
276 QScriptString QScriptValueIterator::scriptName() const
277 {
278     Q_D(const QScriptValueIterator);
279     if (!d || !d->initialized || !d->engine())
280         return QScriptString();
281     return d->engine()->toStringHandle(*d->current);
282 }
283
284 /*!
285   Returns the value of the last property that was jumped over using
286   next() or previous().
287
288   \sa setValue(), name()
289 */
290 QScriptValue QScriptValueIterator::value() const
291 {
292     Q_D(const QScriptValueIterator);
293     if (!d || !d->initialized || !d->engine())
294         return QScriptValue();
295     QScript::APIShim shim(d->engine());
296     JSC::JSValue jsValue = d->object()->property(*d->current);
297     return d->engine()->scriptValueFromJSCValue(jsValue);
298 }
299
300 /*!
301   Sets the \a value of the last property that was jumped over using
302   next() or previous().
303
304   \sa value(), name()
305 */
306 void QScriptValueIterator::setValue(const QScriptValue &value)
307 {
308     Q_D(QScriptValueIterator);
309     if (!d || !d->initialized || !d->engine())
310         return;
311     QScript::APIShim shim(d->engine());
312     JSC::JSValue jsValue = d->engine()->scriptValueToJSCValue(value);
313     d->object()->setProperty(*d->current, jsValue);
314 }
315
316 /*!
317   Returns the flags of the last property that was jumped over using
318   next() or previous().
319
320   \sa value()
321 */
322 QScriptValue::PropertyFlags QScriptValueIterator::flags() const
323 {
324     Q_D(const QScriptValueIterator);
325     if (!d || !d->initialized || !d->engine())
326         return 0;
327     QScript::APIShim shim(d->engine());
328     return d->object()->propertyFlags(*d->current);
329 }
330
331 /*!
332   Removes the last property that was jumped over using next()
333   or previous().
334
335   \sa setValue()
336 */
337 void QScriptValueIterator::remove()
338 {
339     Q_D(QScriptValueIterator);
340     if (!d || !d->initialized || !d->engine())
341         return;
342     QScript::APIShim shim(d->engine());
343     d->object()->setProperty(*d->current, JSC::JSValue());
344     d->propertyNames.erase(d->current);
345 }
346
347 /*!
348   Makes the iterator operate on \a object. The iterator is set to be
349   at the front of the sequence of properties (before the first
350   property).
351 */
352 QScriptValueIterator& QScriptValueIterator::operator=(QScriptValue &object)
353 {
354     d_ptr.reset();
355     if (object.isObject()) {
356         d_ptr.reset(new QScriptValueIteratorPrivate());
357         d_ptr->objectValue = object;
358     }
359     return *this;
360 }
361
362 QT_END_NAMESPACE