summaryrefslogtreecommitdiff
path: root/src/xmlpatterns/api/qabstractxmlforwarditerator.cpp
blob: 8abde9e4bb2f4d98ff328da350062de9cca2e04b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtXmlPatterns module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
  \class QAbstractXmlForwardIterator
  \brief The QAbstractXmlForwardIterator class is a base class for forward iterators.
  \reentrant
  \since 4.4
  \ingroup xml-tools
  \internal

  This abstract base class is for creating iterators for
  traversing custom data structures modeled to look like XML.
  An item can be instantiated in QAbstractXmlForwardIterator if:
  \list

  \o It has a default constructor, a copy constructor, and an
  assignment operator, and

  \o It has an appropriate qIsForwardIteratorEnd() function.
  \endlist

   @ingroup Patternist_iterators
   @author Frans Englich <fenglich@trolltech.com>
 */

/*!
 \typedef QAbstractXmlForwardIterator::Ptr

 A smart pointer wrapping an instance of a QAbstractXmlForwardIterator subclass.
 */

/*!
 \typedef QAbstractXmlForwardIterator::List
 A QList containing QAbstractXmlForwardIterator::Ptr instances.
 */

/*!
 \typedef QAbstractXmlForwardIterator::Vector
 A QVector containing QAbstractXmlForwardIterator::Ptr instances.
 */

/*!
  \fn QAbstractXmlForwardIterator::QAbstractXmlForwardIterator()

  Default constructor.
 */

/*!
  \fn QAbstractXmlForwardIterator::~QAbstractXmlForwardIterator()

  Destructor.
 */

/*!
  \fn T QAbstractXmlForwardIterator::next() = 0;

 Returns the next item in the sequence, or
 a null object if the end has been reached.
 */

/*!
  \fn T QAbstractXmlForwardIterator::current() const = 0;

  Returns the current item in the sequence. If this function is called
  before the first call to next(), a null object is returned. If the
  end of the sequence has been reached, a null object is returned.
 */

/*!
  \fn qint64 QAbstractXmlForwardIterator::position() const = 0;

   Returns the current position in the sequence represented
   by \e this.

   The first position is 1, not 0. If next() hasn't been called, 0 is
   returned. If \e this has reached the end, -1 is returned.
 */

/*!
  \fn bool qIsForwardIteratorEnd(const T &unit)
  \since 4.4
  \relates QAbstractXmlForwardIterator

  The Callback QAbstractXmlForwardIterator uses for determining
  whether \a unit is the end of a sequence.

  If \a unit is a value that would signal the end of a sequence
  (typically a default constructed value), this function returns \c
  true, otherwise \c false.

  This implementation works for any type that has a boolean operator.
  For example, this function should work satisfactory for pointers.
 */

/*!
  \fn qint64 QAbstractXmlForwardIterator::count()
  \internal

   Determines the number of items this QAbstractXmlForwardIterator
   represents.

   Note that this function is not \c const. It modifies the
   QAbstractXmlForwardIterator. The reason for this is efficiency. If
   this QAbstractXmlForwardIterator must not be changed, get a copy()
   before performing the count.

   The default implementation simply calls next() until the end is
   reached. Hence, it may be of interest to override this function if
   the sub-class knows a better way of computing its count.

   The number of items in the sequence is returned.
 */

/*!
  \fn QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::toReversed();
  \internal

  Returns a reverse iterator for the sequence.

  This function may modify the iterator, it can be considered a
  function that evaluates this QAbstractXmlForwardIterator. It is not
  a \e getter, but potentially alters the iterator in the same way the
  next() function does. If this QAbstractXmlForwardIterator must not
  be modified, such that it can be used for evaluation with next(),
  use a copy().
 */

/*!
  \fn QList<T> QAbstractXmlForwardIterator<T>::toList();
  \internal

   Performs a copy of this QAbstractXmlForwardIterator(with copy()),
   and returns its items in a QList. Thus, this function acts as a
   conversion function, converting the sequence to a QList.

   This function may modify the iterator. It is not a \e getter, but
   potentially alters the iterator in the same way the next() function
   does. If this QAbstractXmlForwardIterator must not be modified,
   such that it can be used for evaluation with next(), use a copy().
 */

/*!
  \fn T QAbstractXmlForwardIterator::last();
  \internal

   Returns the item at the end of this QAbstractXmlForwardIterator.
   The default implementation calls next() until the end is reached.
 */

/*!
  \fn T QAbstractXmlForwardIterator::isEmpty();
  \internal
  Returns true if the sequence is empty.
 */

/*!
  \fn qint64 QAbstractXmlForwardIterator::sizeHint() const;
  \internal

  Gives a hint to the size of the contained sequence. The hint is
  assumed to be as close as possible to the actual size.

  If no sensible estimate can be computed, -1 should be returned.
 */

/*!
  \fn typename QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::copy() const;
  \internal

   Copies this QAbstractXmlForwardIterator and returns the copy.

   A copy and the original instance are completely independent of each
   other. Because evaluating an QAbstractXmlForwardIterator modifies
   it, one should always use a copy when an
   QAbstractXmlForwardIterator needs to be used several times.
 */

/*!
  \class QPatternist::ListIteratorPlatform
  \brief Helper class for ListIterator, and should only be instantiated through sub-classing.
  \reentrant
  \since 4.4
  \internal
  \ingroup xml-tools

   ListIteratorPlatform iterates an InputList with instances
   of InputType. For every item in it, it returns an item from it,
   that is converted to OutputType by calling a function on Derived
   that has the following signature:

   \snippet doc/src/snippets/code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp 0

   TODO Document why this class doesn't duplicate ItemMappingIterator.
 */

/*!
  \fn QPatternist::ListIteratorPlatform::ListIteratorPlatform(const ListType &list);

  Constructs a ListIteratorPlatform that walks the given \a list.
 */

/*!
  \class QPatternist::ListIterator
  \brief Bridges values in Qt's QList container class into an QAbstractXmlForwardIterator.
  \reentrant
  \since 4.4
  \internal
  \ingroup xml-tools

   ListIterator takes a reference to a QList<T> instance and allows
   access to that list via its QAbstractXmlForwardIterator interface.
   ListIterator is parameterized with the type to iterate over, e.g.,
   Item or Expression::Ptr.

   ListIterator is used by the ExpressionSequence to create an
   iterator over its operands. The iterator will be passed to a
   MappingIterator.
 */

/*!
   \fn QPatternist::makeListIterator(const QList<T> &qList)
   \relates QPatternist::ListIterator

   An object generator for ListIterator.

   makeListIterator() is a convenience function to avoid specifying
   the full template instantiation for ListIterator.  Conceptually, it
   is identical to Qt's qMakePair().

 */