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::end() 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::begin() 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
244 Returns the distance between the two iterators.
245
246 \sa operator+(), operator-=(), QIterable::canReverseIterate()
247 */
248
249/*!
250 \fn template <class Container> QIterator<Container> QIterator<Container>::operator+(qsizetype j, const QIterator<Container> &k)
251
252 Returns an iterator to the item at \a j positions forward from iterator \a k.
253*/
254
255/*!
256 \struct QConstIterator
257 \since 6.0
258 \inmodule QtCore
259 \brief The QConstIterator allows iteration over a container in a QVariant.
260 \sa QIterator, QIterable
261*/
262
263/*!
264 \fn template <class Container> QConstIterator<Container>::QConstIterator(const QIterable<Container> *iterable, void *iterator)
265
266 Creates a QConstIterator to wrap \a iterator, operating on \a iterable.
267 */
268
269/*!
270 \fn template<class Container> bool QConstIterator<Container>::operator==(const QConstIterator<Container> &other) const
271
272 Returns \c true if \a other points to the same item as this
273 iterator; otherwise returns \c false.
274
275 \sa operator!=()
276*/
277
278/*!
279 \fn template<class Container> bool QConstIterator<Container>::operator!=(const QConstIterator<Container> &other) const
280
281 Returns \c true if \a other points to a different item than this
282 iterator; otherwise returns \c false.
283
284 \sa operator==()
285*/
286
287/*!
288 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator++()
289
290 The prefix \c{++} operator (\c{++it}) advances the iterator to the
291 next item in the container and returns an iterator to the new current
292 item.
293
294 Calling this function on QIterable<Container>::end() leads to undefined results.
295
296 \sa operator--()
297*/
298
299/*!
300 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator++(int)
301
302 \overload
303
304 The postfix \c{++} operator (\c{it++}) advances the iterator to the
305 next item in the container and returns an iterator to the previously
306 current item.
307*/
308
309/*!
310 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator--()
311
312 The prefix \c{--} operator (\c{--it}) makes the preceding item
313 current and returns an iterator to the new current item.
314
315 Calling this function on QIterable<Container>::begin() leads to undefined results.
316
317 If the container in the QVariant does not support bi-directional iteration, calling this function
318 leads to undefined results.
319
320 \sa operator++(), QIterable::canReverseIterate()
321*/
322
323/*!
324 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator--(int)
325
326 \overload
327
328 The postfix \c{--} operator (\c{it--}) makes the preceding item
329 current and returns an iterator to the previously current item.
330
331 If the container in the QVariant does not support bi-directional iteration, calling this function
332 leads to undefined results.
333
334 \sa QIterable::canReverseIterate()
335*/
336
337/*!
338 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator+=(qsizetype j)
339
340 Advances the iterator by \a j items.
341
342 \sa operator-=(), operator+()
343*/
344
345/*!
346 \fn template<class Container> QConstIterator<Container> &QConstIterator<Container>::operator-=(qsizetype j)
347
348 Makes the iterator go back by \a j items.
349
350 If the container in the QVariant does not support bi-directional iteration, calling this function
351 leads to undefined results.
352
353 \sa operator+=(), operator-(), QIterable::canReverseIterate()
354*/
355
356/*!
357 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator+(qsizetype j) const
358
359 Returns an iterator to the item at \a j positions forward from
360 this iterator.
361
362 \sa operator-(), operator+=()
363*/
364
365/*!
366 \fn template<class Container> QConstIterator<Container> QConstIterator<Container>::operator-(qsizetype j) const
367
368 Returns an iterator to the item at \a j positions backward from
369 this iterator.
370
371 If the container in the QVariant does not support bi-directional iteration, calling this function
372 leads to undefined results.
373
374 \sa operator+(), operator-=(), QIterable::canReverseIterate()
375*/
376
377/*!
378 \fn template <class Container> qsizetype QConstIterator<Container>::operator-(const QConstIterator<Container> &j) const
379
380 Returns the distance between the two iterators.
381
382 \sa operator+(), operator-=(), QIterable::canReverseIterate()
383 */
384
385/*!
386 \class QIterable
387 \inmodule QtCore
388 \since 6.0
389 \brief QIterable is a template class that is the base class for QSequentialIterable and QAssociativeIterable.
390*/
391
392/*!
393 \fn template <class Container> bool QIterable<Container>::canInputIterate() const
394
395 Returns whether the container has an input iterator. This corresponds to
396 the std::input_iterator_tag iterator trait of the iterator and
397 const_iterator of the container.
398*/
399
400/*!
401 \fn template<class Container> bool QIterable<Container>::canForwardIterate() const
402
403 Returns whether it is possible to iterate over the container in forward
404 direction. This corresponds to the std::forward_iterator_tag iterator trait
405 of the iterator and const_iterator of the container.
406*/
407
408/*!
409 \fn template<class Container> bool QIterable<Container>::canReverseIterate() const
410
411 Returns whether it is possible to iterate over the container in reverse. This
412 corresponds to the std::bidirectional_iterator_tag iterator trait of the
413 const_iterator of the container.
414*/
415
416/*!
417 \fn template<class Container> bool QIterable<Container>::canRandomAccessIterate() const
418
419 Returns whether it is possible to efficiently skip over multiple values
420 using and iterator. This corresponds to the std::random_access_iterator_tag
421 iterator trait of the iterator and const_iterator of the container.
422*/
423
424/*!
425 \fn template<class Container> QConstIterator<Container> QIterable<Container>::constBegin() const
426
427 Returns a QConstIterator for the beginning of the container. This
428 can be used in stl-style iteration.
429
430 \sa constEnd(), mutableBegin()
431*/
432
433/*!
434 \fn template<class Container> QConstIterator<Container> QIterable<Container>::constEnd() const
435
436 Returns a Qterable::QConstIterator for the end of the container. This
437 can be used in stl-style iteration.
438
439 \sa constBegin(), mutableEnd()
440*/
441
442/*!
443 \fn template<class Container> QIterator<Container> QIterable<Container>::mutableBegin()
444
445 Returns a QIterator for the beginning of the container. This
446 can be used in stl-style iteration.
447
448 \sa mutableEnd(), constBegin()
449*/
450
451/*!
452 \fn template<class Container> QIterator<Container> QIterable<Container>::mutableEnd()
453
454 Returns a QSequentialIterable::iterator for the end of the container. This
455 can be used in stl-style iteration.
456
457 \sa mutableBegin(), constEnd()
458*/
459
460/*!
461 \fn template<class Container> qsizetype QIterable<Container>::size() const
462
463 Returns the number of values in the container.
464*/
465
466/*!
467 \class QTaggedIterator
468 \since 6.0
469 \inmodule QtCore
470 \brief QTaggedIterator is a template class that wraps an iterator and exposes standard iterator traits.
471
472 In order to use an iterator any of the standard algorithms, its iterator
473 traits need to be known. As QSequentialIterable can work with many different
474 kinds of containers, we cannot declare the traits in the iterator classes
475 themselves. A QTaggedIterator gives you a way to explicitly declare a trait for
476 a concrete instance of an iterator or QConstIterator.
477*/
478
479/*!
480 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::QTaggedIterator(Iterator &&it)
481
482 Constructs a QTaggedIterator from an iterator or QConstIterator \a it. Checks
483 whether the IteratorCategory passed as template argument matches the run
484 time capabilities of \a it; if there's no match, \a it is refused.
485*/
486
487/*!
488 \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator==(const QTaggedIterator<Iterator, IteratorCategory> &other) const
489
490 Returns \c true if \a other points to the same item as this
491 iterator; otherwise returns \c false.
492
493 \sa operator!=()
494*/
495
496/*!
497 \fn template<class Iterator, typename IteratorCategory> bool QTaggedIterator<Iterator, IteratorCategory>::operator!=(const QTaggedIterator<Iterator, IteratorCategory> &other) const
498
499 Returns \c true if \a other points to a different item than this
500 iterator; otherwise returns \c false.
501
502 \sa operator==()
503*/
504
505/*!
506 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator++()
507
508 The prefix \c{++} operator (\c{++it}) advances the iterator to the
509 next item in the container and returns an iterator to the new current
510 item.
511
512 Calling this function on QSequentialIterable::end() leads to undefined results.
513
514 \sa operator--()
515*/
516
517/*!
518 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator++(int)
519 \overload
520
521 The postfix \c{++} operator (\c{it++}) advances the iterator to the
522 next item in the container and returns an iterator to the previously
523 current item.
524*/
525
526
527/*!
528 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator--()
529
530 The prefix \c{--} operator (\c{--it}) makes the preceding item
531 current and returns an iterator to the new current item.
532
533 Calling this function on QSequentialIterable::begin() leads to undefined results.
534
535 If the container in the QVariant does not support bi-directional iteration, calling this function
536 leads to undefined results.
537
538 \sa operator++(), QIterable::canReverseIterate()
539*/
540
541/*!
542 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator--(int)
543 \overload
544
545 The postfix \c{--} operator (\c{it--}) makes the preceding item
546 current and returns an iterator to the previously current item.
547
548 If the container in the QVariant does not support bi-directional iteration, calling this function
549 leads to undefined results.
550
551 \sa QIterable::canReverseIterate()
552*/
553
554
555/*!
556 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator+=(qsizetype j)
557
558 Advances the iterator by \a j items.
559
560 \sa operator-=(), operator+()
561*/
562
563/*!
564 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> &QTaggedIterator<Iterator, IteratorCategory>::operator-=(qsizetype j)
565
566 Makes the iterator go back by \a j items.
567
568 If the container in the QVariant does not support bi-directional iteration, calling this function
569 leads to undefined results.
570
571 \sa operator+=(), operator-(), QIterable::canReverseIterate()
572*/
573
574/*!
575 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j) const
576
577 Returns an iterator to the item at \a j positions forward from
578 this iterator.
579
580 \sa operator-(), operator+=()
581*/
582
583/*!
584 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j, const QTaggedIterator &k)
585
586 Returns an iterator to the item at \a j positions forward from iterator \a k.
587*/
588
589/*!
590 \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator-(qsizetype j) const
591
592 Returns an iterator to the item at \a j positions backward from
593 this iterator.
594
595 If the container in the QVariant does not support bi-directional iteration, calling this function
596 leads to undefined results.
597
598 \sa operator+(), operator-=(), QIterable::canReverseIterate()
599*/
600
601/*!
602 \fn template <class Iterator, typename IteratorCategory> qsizetype QTaggedIterator<Iterator, IteratorCategory>::operator-(const QTaggedIterator<Iterator, IteratorCategory> &j) const
603
604 Returns the distance between this iterator and \a j.
605
606 \sa operator+(), operator-=(), QIterable::canReverseIterate()
607*/
608
609QT_END_NAMESPACE
610

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