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

source code of qtbase/src/corelib/kernel/qiterable.cpp