qscriptvalueiterator.cpp revision cad810f21b803229eb11403f9209855525a25d57 
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*/
71QScriptValueIterator::QScriptValueIterator(const QScriptValue& object)
72    : d_ptr(new QScriptValueIteratorPrivate(QScriptValuePrivate::get(object)))
73{}
74
75/*!
76    Destroys the iterator.
77*/
78QScriptValueIterator::~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*/
88bool 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*/
101void 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*/
113bool 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*/
126void 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*/
137void 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*/
148void 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*/
159QString 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*/
168QScriptString 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*/
179QScriptValue 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*/
190void 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*/
201void 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*/
212QScriptValue::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*/
222QScriptValueIterator& QScriptValueIterator::operator=(QScriptValue& object)
223{
224    d_ptr = new QScriptValueIteratorPrivate(QScriptValuePrivate::get(object));
225    return *this;
226}
227