1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
43 \class QAbstractXmlForwardIterator
44 \brief The QAbstractXmlForwardIterator class is a base class for forward iterators.
48 \inmodule QtXmlPatterns
51 This abstract base class is for creating iterators for
52 traversing custom data structures modeled to look like XML.
53 An item can be instantiated in QAbstractXmlForwardIterator if:
56 \li It has a default constructor, a copy constructor, and an
57 assignment operator, and
59 \li It has an appropriate qIsForwardIteratorEnd() function.
62 @ingroup Patternist_iterators
63 @author Frans Englich <frans.englich@nokia.com>
67 \typedef QAbstractXmlForwardIterator::Ptr
69 A smart pointer wrapping an instance of a QAbstractXmlForwardIterator subclass.
73 \typedef QAbstractXmlForwardIterator::List
74 A QList containing QAbstractXmlForwardIterator::Ptr instances.
78 \typedef QAbstractXmlForwardIterator::Vector
79 A QVector containing QAbstractXmlForwardIterator::Ptr instances.
83 \fn QAbstractXmlForwardIterator::QAbstractXmlForwardIterator()
89 \fn QAbstractXmlForwardIterator::~QAbstractXmlForwardIterator()
95 \fn T QAbstractXmlForwardIterator::next() = 0;
97 Returns the next item in the sequence, or
98 a null object if the end has been reached.
102 \fn T QAbstractXmlForwardIterator::current() const = 0;
104 Returns the current item in the sequence. If this function is called
105 before the first call to next(), a null object is returned. If the
106 end of the sequence has been reached, a null object is returned.
110 \fn qint64 QAbstractXmlForwardIterator::position() const = 0;
112 Returns the current position in the sequence represented
115 The first position is 1, not 0. If next() hasn't been called, 0 is
116 returned. If \e this has reached the end, -1 is returned.
120 \fn bool qIsForwardIteratorEnd(const T &unit)
122 \relates QAbstractXmlForwardIterator
124 The Callback QAbstractXmlForwardIterator uses for determining
125 whether \a unit is the end of a sequence.
127 If \a unit is a value that would signal the end of a sequence
128 (typically a default constructed value), this function returns \c
129 true, otherwise \c false.
131 This implementation works for any type that has a boolean operator.
132 For example, this function should work satisfactory for pointers.
136 \fn qint64 QAbstractXmlForwardIterator::count()
139 Determines the number of items this QAbstractXmlForwardIterator
142 Note that this function is not \c const. It modifies the
143 QAbstractXmlForwardIterator. The reason for this is efficiency. If
144 this QAbstractXmlForwardIterator must not be changed, get a copy()
145 before performing the count.
147 The default implementation simply calls next() until the end is
148 reached. Hence, it may be of interest to override this function if
149 the sub-class knows a better way of computing its count.
151 The number of items in the sequence is returned.
155 \fn QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::toReversed();
158 Returns a reverse iterator for the sequence.
160 This function may modify the iterator, it can be considered a
161 function that evaluates this QAbstractXmlForwardIterator. It is not
162 a \e getter, but potentially alters the iterator in the same way the
163 next() function does. If this QAbstractXmlForwardIterator must not
164 be modified, such that it can be used for evaluation with next(),
169 \fn QList<T> QAbstractXmlForwardIterator<T>::toList();
172 Performs a copy of this QAbstractXmlForwardIterator(with copy()),
173 and returns its items in a QList. Thus, this function acts as a
174 conversion function, converting the sequence to a QList.
176 This function may modify the iterator. It is not a \e getter, but
177 potentially alters the iterator in the same way the next() function
178 does. If this QAbstractXmlForwardIterator must not be modified,
179 such that it can be used for evaluation with next(), use a copy().
183 \fn T QAbstractXmlForwardIterator::last();
186 Returns the item at the end of this QAbstractXmlForwardIterator.
187 The default implementation calls next() until the end is reached.
191 \fn T QAbstractXmlForwardIterator::isEmpty();
193 Returns true if the sequence is empty.
197 \fn qint64 QAbstractXmlForwardIterator::sizeHint() const;
200 Gives a hint to the size of the contained sequence. The hint is
201 assumed to be as close as possible to the actual size.
203 If no sensible estimate can be computed, -1 should be returned.
207 \fn typename QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::copy() const;
210 Copies this QAbstractXmlForwardIterator and returns the copy.
212 A copy and the original instance are completely independent of each
213 other. Because evaluating an QAbstractXmlForwardIterator modifies
214 it, one should always use a copy when an
215 QAbstractXmlForwardIterator needs to be used several times.
219 \class QPatternist::ListIteratorPlatform
220 \brief Helper class for ListIterator, and should only be instantiated through sub-classing.
226 ListIteratorPlatform iterates an InputList with instances
227 of InputType. For every item in it, it returns an item from it,
228 that is converted to OutputType by calling a function on Derived
229 that has the following signature:
231 \snippet code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp 0
233 TODO Document why this class doesn't duplicate ItemMappingIterator.
237 \fn QPatternist::ListIteratorPlatform::ListIteratorPlatform(const ListType &list);
239 Constructs a ListIteratorPlatform that walks the given \a list.
243 \class QPatternist::ListIterator
244 \brief Bridges values in Qt's QList container class into an QAbstractXmlForwardIterator.
250 ListIterator takes a reference to a QList<T> instance and allows
251 access to that list via its QAbstractXmlForwardIterator interface.
252 ListIterator is parameterized with the type to iterate over, e.g.,
253 Item or Expression::Ptr.
255 ListIterator is used by the ExpressionSequence to create an
256 iterator over its operands. The iterator will be passed to a
261 \fn QPatternist::makeListIterator(const QList<T> &qList)
262 \relates QPatternist::ListIterator
264 An object generator for ListIterator.
266 makeListIterator() is a convenience function to avoid specifying
267 the full template instantiation for ListIterator. Conceptually, it
268 is identical to Qt's qMakePair().