1/****************************************************************************
2**
3** Copyright (C) 2020 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QtCore/qiterable.h>
41
42QT_BEGIN_NAMESPACE
43
44/*!
45 \class QBaseIterator
46
47 QBaseIterator forms the common base class for all iterators operating on
48 subclasses of QIterable.
49*/
50
51/*!
52 \fn template<class Container> QBaseIterator<Container>::QBaseIterator(const QIterable<Container> *iterable, void *iterator)
53
54 \internal
55 Creates a const QBaseIterator from an \a iterable and an \a iterator.
56 */
57
58/*!
59 \fn template<class Container> QBaseIterator<Container>::QBaseIterator(QIterable<Container> *iterable, void *iterator)
60
61 \internal
62 Creates a non-const QBaseIterator from an \a iterable and an \a iterator.
63 */
64
65/*!
66 \fn template<class Container> QBaseIterator<Container>::QBaseIterator(QBaseIterator<Container> &&other)
67
68 \internal
69 Move-constructs a QBaseIterator from \a other, preserving its const-ness.
70 */
71
72/*!
73 \fn template<class Container> QBaseIterator<Container>::QBaseIterator(const QBaseIterator<Container> &other)
74
75 \internal
76 Copy-constructs a QBaseIterator from \a other, preserving its const-ness.
77 */
78
79/*!
80 \fn template<class Container> QBaseIterator<Container>::~QBaseIterator()
81
82 \internal
83 Destroys a QBaseIterator.
84 */
85
86/*!
87 \fn template<class Container> QBaseIterator<Container> &QBaseIterator<Container>::operator=(const QBaseIterator<Container> &other)
88
89 \internal
90 Copy-assigns a QBaseIterator from \a other, preserving its const-ness.
91 */
92
93/*!
94 \fn template<class Container> void QBaseIterator<Container>::initIterator(const void *copy)
95
96 \internal
97 Initializes the internal native iterator by duplicating \a copy, if given.
98 */
99
100/*!
101 \fn template<class Container> void QBaseIterator<Container>::clearIterator()
102
103 \internal
104 Destroys the internal native iterator.
105 */
106
107
108/*!
109 \fn QMetaContainer QBaseIterator<Container>::metaContainer() const
110
111 \internal
112 Returns the meta sequence.
113 */
114
115/*!
116 \fn template<class Container> QIterable *QBaseIterator<Container>::mutableIterable() const
117
118 \internal
119 Returns a non-const pointer to the iterable, if the original iterable was
120 non-const. Otherwise returns nullptr.
121 */
122
123/*!
124 \fn template<class Container> const QIterable *QBaseIterator<Container>::constIterable() const
125
126 \internal
127 Returns a const pointer to the iterable.
128 */
129
130/*!
131 \fn template<class Container> void *QBaseIterator<Container>::mutableIterator()
132
133 Returns a non-const pointer to the internal native iterator.
134 */
135
136/*!
137 \fn template<class Container> const void *QBaseIterator<Container>::constIterator() const
138
139 Returns a const pointer to the internal native iterator.
140 */
141
142/*!
143 \fn template<class Container> QBaseIterator &QBaseIterator<Container>::operator=(QBaseIterator<Container> &&other)
144
145 \internal
146 Move-assigns a QBaseIterator from \a other, preserving its const-ness.
147 */
148
149/*!
150 \class QIterator
151 \since 6.0
152 \inmodule QtCore
153 \brief The QIterator is a template class that allows iteration over a container in a QVariant.
154
155 A QIterator can only be created by a QIterable instance, and can be used
156 in a way similar to other stl-style iterators. Generally, QIterator should
157 not be used directly, but through its derived classes provided by
158 QSequentialIterable and QAssociativeIterable.
159
160 \sa QIterable
161*/
162
163/*!
164 \fn template<class Container> QIterator<Container>::QIterator(QIterable<Container> *iterable, void *iterator)
165
166 Creates an iterator from an \a iterable and a pointer to a native \a iterator.
167 */
168
169/*!
170 \fn template<class Container> bool QIterator<Container>::operator==(const QIterator<Container> &other) const
171
172 Returns \c true if \a other points to the same item as this
173 iterator; otherwise returns \c false.
174
175 \sa operator!=()
176*/
177
178/*!
179 \fn template<class Container> bool QIterator<Container>::operator!=(const QIterator<Container> &other) const
180
181 Returns \c true if \a other points to a different item than this
182 iterator; otherwise returns \c false.
183
184 \sa operator==()
185*/
186
187/*!
188 \fn template<class Container> QIterator<Container> &QIterator<Container>::operator++()
189
190 The prefix ++ operator (\c{++it}) advances the iterator to the
191 next item in the container and returns an iterator to the new current
192 item.
193
194 Calling this function on QSequentialIterable::end() leads to undefined results.
195
196 \sa operator--()
197*/
198
199/*!
200 \fn template<class Container> QIterator<Container> QIterator<Container>::operator++(int)
201 \overload
202
203 The postfix ++ operator (\c{it++}) advances the iterator to the
204 next item in the container and returns an iterator to the previously
205 current item.
206*/
207
208
209/*!
210 \fn template<class Container> QIterator<Container> &QIterator<Container>::operator--()
211
212 The prefix -- operator (\c{--it}) makes the preceding item
213 current and returns an iterator to the new current item.
214
215 Calling this function on QSequentialIterable::begin() leads to undefined results.
216
217 If the container in the QVariant does not support bi-directional iteration, calling this function
218 leads to undefined results.
219
220 \sa operator++(), QIterable::canReverseIterate()
221*/
222
223/*!
224 \fn template<class Container> QIterator<Container> QIterator<Container>::operator--(int)
225
226 \overload
227
228 The postfix -- operator (\c{it--}) makes the preceding item
229 current and returns an iterator to the previously current item.
230
231 If the container in the QVariant does not support bi-directional iteration, calling this function
232 leads to undefined results.
233
234 \sa QIterable::canReverseIterate()
235*/
236
237/*!
238 \fn template<class Container> QIterator<Container> &QIterator<Container>::operator+=(qsizetype j)
239
240 Advances the iterator by \a j items.
241
242 \sa operator-=(), operator+()
243*/
244
245/*!
246 \fn template<class Container> QIterator<Container> &QIterator<Container>::operator-=(qsizetype j)
247
248 Makes the iterator go back by \a j items.
249
250 If the container in the QVariant does not support bi-directional iteration, calling this function
251 leads to undefined results.
252
253 \sa operator+=(), operator-(), QIterable::canReverseIterate()
254*/
255
256/*!
257 \fn template<class Container> QIterator<Container> QIterator<Container>::operator+(qsizetype j) const
258
259 Returns an iterator to the item at \a j positions forward from
260 this iterator.
261
262 \sa operator-(), operator+=()
263*/
264
265/*!
266 \fn template<class Container> QIterator<Container> QIterator<Container>::operator-(qsizetype j) const
267
268 Returns an iterator to the item at \a j positions backward from
269 this iterator.
270
271 If the container in the QVariant does not support bi-directional iteration, calling this function
272 leads to undefined results.
273
274 \sa operator+(), operator-=(), QIterable::canReverseIterate()
275*/
276
277/*!
278 \fn template<class Container> qsizetype QIterator<Container>::operator-(const QIterator<Container> &j) const
279
280 Returns the distance between the two iterators.
281
282 \sa operator+(), operator-=(), QIterable::canReverseIterate()
283 */
284
285/*!
286 \fn template<class Container> QConstIterator<Container>::QConstIterator(const QIterable<Container> *iterable, void *iterator)
287
288 Creates a QConstIterator to wrap \a iterator, operating on \a iterable.
289 */
290
291/*!
292 \fn template<class Container> bool QConstIterator<Container>::operator==(const QConstIterator<Container> &other) const
293
294 Returns \c true if \a other points to the same item as this
295 iterator; otherwise returns \c false.
296
297 \sa operator!=()
298*/
299
300/*!
301 \fn template<class Container> bool QConstIterator<Container>::operator!=(const QConstIterator<Container> &other) const
302
303 Returns \c true if \a other points to a different item than this
304 iterator; otherwise returns \c false.
305
306 \sa operator==()
307*/
308
309/*!
310 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator++()
311
312 The prefix ++ operator (\c{++it}) advances the iterator to the
313 next item in the container and returns an iterator to the new current
314 item.
315
316 Calling this function on QIterable<Container>::end() leads to undefined results.
317
318 \sa operator--()
319*/
320
321/*!
322 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator++(int)
323
324 \overload
325
326 The postfix ++ operator (\c{it++}) advances the iterator to the
327 next item in the container and returns an iterator to the previously
328 current item.
329*/
330
331/*!
332 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator--()
333
334 The prefix -- operator (\c{--it}) makes the preceding item
335 current and returns an iterator to the new current item.
336
337 Calling this function on QIterable<Container>::begin() leads to undefined results.
338
339 If the container in the QVariant does not support bi-directional iteration, calling this function
340 leads to undefined results.
341
342 \sa operator++(), canReverseIterate()
343*/
344
345/*!
346 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator--(int)
347
348 \overload
349
350 The postfix -- operator (\c{it--}) makes the preceding item
351 current and returns an iterator to the previously current item.
352
353 If the container in the QVariant does not support bi-directional iteration, calling this function
354 leads to undefined results.
355
356 \sa canReverseIterate()
357*/
358
359/*!
360 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator+=(qsizetype j)
361
362 Advances the iterator by \a j items.
363
364 \sa operator-=(), operator+()
365*/
366
367/*!
368 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator-=(qsizetype j)
369
370 Makes the iterator go back by \a j items.
371
372 If the container in the QVariant does not support bi-directional iteration, calling this function
373 leads to undefined results.
374
375 \sa operator+=(), operator-(), canReverseIterate()
376*/
377
378/*!
379 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator+(qsizetype j) const
380
381 Returns an iterator to the item at \a j positions forward from
382 this iterator.
383
384 \sa operator-(), operator+=()
385*/
386
387/*!
388 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator-(qsizetype j) const
389
390 Returns an iterator to the item at \a j positions backward from
391 this iterator.
392
393 If the container in the QVariant does not support bi-directional iteration, calling this function
394 leads to undefined results.
395
396 \sa operator+(), operator-=(), canReverseIterate()
397*/
398
399/*!
400 \fn template<class Container> qsizetype QConstIterator<Container>::operator-(const QConstIterator<Container> &j) const
401
402 Returns the distance between the two iterators.
403
404 \sa operator+(), operator-=(), canReverseIterator()
405 */
406
407/*!
408 \class QIterable
409 \since 6.0
410 \brief QIterable is a template class that is the base class for QSequentialIterable and QAssociativeIterable.
411*/
412
413/*!
414 \fn template<class Container> bool QIterable<Container>::canInputIterate() const
415
416 Returns whether the container has an input iterator. This corresponds to
417 the std::input_iterator_tag iterator trait of the iterator and
418 const_iterator of the container.
419*/
420
421/*!
422 \fn template<class Container> bool QIterable<Container>::canForwardIterate() const
423
424 Returns whether it is possible to iterate over the container in forward
425 direction. This corresponds to the std::forward_iterator_tag iterator trait
426 of the iterator and const_iterator of the container.
427*/
428
429/*!
430 \fn template<class Container> bool QIterable<Container>::canReverseIterate() const
431
432 Returns whether it is possible to iterate over the container in reverse. This
433 corresponds to the std::bidirectional_iterator_tag iterator trait of the
434 const_iterator of the container.
435*/
436
437/*!
438 \fn template<class Container> bool QIterable<Container>::canRandomAccessIterate() const
439
440 Returns whether it is possible to efficiently skip over multiple values
441 using and iterator. This corresponds to the std::random_access_iterator_tag
442 iterator trait of the iterator and const_iterator of the container.
443*/
444
445/*!
446 \fn template<class Container> QConstIterator<Container> QIterable<Container>::constBegin() const
447
448 Returns a QConstIterator for the beginning of the container. This
449 can be used in stl-style iteration.
450
451 \sa constEnd(), mutableBegin()
452*/
453
454/*!
455 \fn template<class Container> QConstIterator<Container> QIterable<Container>::constEnd() const
456
457 Returns a Qterable::QConstIterator for the end of the container. This
458 can be used in stl-style iteration.
459
460 \sa constBegin(), mutableEnd()
461*/
462
463/*!
464 \fn template<class Container> QIterator<Container> QIterable<Container>::mutableBegin()
465
466 Returns a QIterator for the beginning of the container. This
467 can be used in stl-style iteration.
468
469 \sa mutableEnd(), constBegin()
470*/
471
472/*!
473 \fn template<class Container> QIterator<Container> QIterable<Container>::mutableEnd()
474
475 Returns a QSequentialIterable::iterator for the end of the container. This
476 can be used in stl-style iteration.
477
478 \sa mutableBegin(), constEnd()
479*/
480
481/*!
482 \fn template<class Container> qsizetype QIterable<Container>::size() const
483
484 Returns the number of values in the container.
485*/
486
487/*!
488 \class QTaggedIterator
489 \since 6.0
490 \inmodule QtCore
491 \brief QTaggedIterator is a template class that wraps an iterator and exposes standard iterator traits.
492
493 In order to use an iterator any of the standard algorithms, it iterator
494 traits need to be known. As QSequentialIterable can work with many different
495 kinds of containers, we cannot declare the traits in the iterator classes
496 themselves. StdIterator gives you a way to explicitly declare a trait for
497 a concrete instance of an iterator or QConstIterator.
498*/
499
500/*!
501 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::QTaggedIterator(Iterator &&it)
502
503 Constructs a QTaggedIterator from an iterator or QConstIterator \a it. Checks
504 whether the IteratorCategory passed as template argument matches the run
505 time capabilities of \a it and refuses \a it if not.
506*/
507
508/*!
509 \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator==(const QTaggedIterator<Iterator, IteratorCategory> &other) const
510
511 Returns \c true if \a other points to the same item as this
512 iterator; otherwise returns \c false.
513
514 \sa operator!=()
515*/
516
517/*!
518 \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator!=(const QTaggedIterator<Iterator, IteratorCategory> &other) const
519
520 Returns \c true if \a other points to a different item than this
521 iterator; otherwise returns \c false.
522
523 \sa operator==()
524*/
525
526/*!
527 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator++()
528
529 The prefix ++ operator (\c{++it}) advances the iterator to the
530 next item in the container and returns an iterator to the new current
531 item.
532
533 Calling this function on QSequentialIterable::end() leads to undefined results.
534
535 \sa operator--()
536*/
537
538/*!
539 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator++(int)
540 \overload
541
542 The postfix ++ operator (\c{it++}) advances the iterator to the
543 next item in the container and returns an iterator to the previously
544 current item.
545*/
546
547
548/*!
549 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator--()
550
551 The prefix -- operator (\c{--it}) makes the preceding item
552 current and returns an iterator to the new current item.
553
554 Calling this function on QSequentialIterable::begin() leads to undefined results.
555
556 If the container in the QVariant does not support bi-directional iteration, calling this function
557 leads to undefined results.
558
559 \sa operator++(), QIterable::canReverseIterate()
560*/
561
562/*!
563 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator--(int)
564 \overload
565
566 The postfix -- operator (\c{it--}) makes the preceding item
567 current and returns an iterator to the previously current item.
568
569 If the container in the QVariant does not support bi-directional iteration, calling this function
570 leads to undefined results.
571
572 \sa QIterable::canReverseIterate()
573*/
574
575
576/*!
577 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator+=(qsizetype j)
578
579 Advances the iterator by \a j items.
580
581 \sa operator-=(), operator+()
582*/
583
584/*!
585 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator-=(qsizetype j)
586
587 Makes the iterator go back by \a j items.
588
589 If the container in the QVariant does not support bi-directional iteration, calling this function
590 leads to undefined results.
591
592 \sa operator+=(), operator-(), QIterable::canReverseIterate()
593*/
594
595/*!
596 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j) const
597
598 Returns an iterator to the item at \a j positions forward from
599 this iterator.
600
601 \sa operator-(), operator+=()
602*/
603
604/*!
605 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator-(qsizetype j) const
606
607 Returns an iterator to the item at \a j positions backward from
608 this iterator.
609
610 If the container in the QVariant does not support bi-directional iteration, calling this function
611 leads to undefined results.
612
613 \sa operator+(), operator-=(), QIterable::canReverseIterate()
614*/
615
616/*!
617 \fn template<class Iterator, typename IteratorCategory> qsizetype QTaggedIterator<Iterator, IteratorCategory>::operator-(const QTaggedIterator &j) const
618
619 Returns the distance between the two iterators.
620
621 \sa operator+(), operator-=(), QIterable::canReverseIterate()
622*/
623
624QT_END_NAMESPACE
625