summaryrefslogtreecommitdiffstats
path: root/doc/qvaluelist.doc
blob: 9e573c813204e32d785d1b600e7421b2f5115667 (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
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
/****************************************************************************
**
** QValueList and QValueListIterator class documentation
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/


/*****************************************************************************
  QValueList documentation
 *****************************************************************************/

/*!
    \class QValueList ntqvaluelist.h
    \brief The QValueList class is a value-based template class that
    provides lists.

    \ingroup qtl
    \ingroup tools
    \ingroup shared
    \mainclass
    \reentrant

    QValueList is a Qt implementation of an STL-like list container.
    It can be used in your application if the standard \c list is not
    available for your target platform(s). QValueList is part of the
    \link ntqtl.html Qt Template Library\endlink.

    QValueList\<T\> defines a template instance to create a list of
    values that all have the class T. Note that QValueList does not
    store pointers to the members of the list; it holds a copy of
    every member. This is why these kinds of classes are called "value
    based"; QPtrList and QDict are "pointer based".

    QValueList contains and manages a collection of objects of type T
    and provides iterators that allow the contained objects to be
    addressed. QValueList owns the contained items. For more relaxed
    ownership semantics, see QPtrCollection and friends which are
    pointer-based containers.

    Some classes cannot be used within a QValueList, for example, all
    classes derived from QObject and thus all classes that implement
    widgets. Only values can be used in a QValueList. To qualify as a
    value the class must provide:
    \list
    \i a copy constructor;
    \i an assignment operator;
    \i a default constructor, i.e. a constructor that does not take any arguments.
    \endlist

    Note that C++ defaults to field-by-field assignment operators and
    copy constructors if no explicit version is supplied. In many
    cases this is sufficient.

    In addition, some compilers (e.g. Sun CC) might require that the
    class provides an equality operator (operator==()).

    QValueList's function naming is consistent with the other Qt
    classes (e.g. count(), isEmpty()). QValueList also provides extra
    functions for compatibility with STL algorithms, such as size()
    and empty(). Programmers already familiar with the STL \c list may
    prefer to use the STL-compatible functions.

    Example:
    \code
    class Employee
    {
    public:
	Employee(): sn(0) {}
	Employee( const QString& forename, const QString& surname, int salary )
	    : fn(forename), sn(surname), sal(salary)
	{}

	QString forename() const { return fn; }
	QString surname() const { return sn; }
	int salary() const { return sal; }
	void setSalary( int salary ) { sal = salary; }

    private:
	QString fn;
	QString sn;
	int sal;
    };

    typedef QValueList<Employee> EmployeeList;
    EmployeeList list;

    list.append( Employee("John", "Doe", 50000) );
    list.append( Employee("Jane", "Williams", 80000) );
    list.append( Employee("Tom", "Jones", 60000) );

    Employee mary( "Mary", "Hawthorne", 90000 );
    list.append( mary );
    mary.setSalary( 100000 );

    EmployeeList::iterator it;
    for ( it = list.begin(); it != list.end(); ++it )
	cout << (*it).surname().latin1() << ", " <<
		(*it).forename().latin1() << " earns " <<
		(*it).salary() << endl;

    // Output:
    // Doe, John earns 50000
    // Williams, Jane earns 80000
    // Hawthorne, Mary earns 90000
    // Jones, Tom earns 60000
    \endcode


    Notice that the latest changes to Mary's salary did not affect the
    value in the list because the list created a copy of Mary's entry.

    There are several ways to find items in the list. The begin() and
    end() functions return iterators to the beginning and end of the
    list. The advantage of getting an iterator is that you can move
    forward or backward from this position by
    incrementing/decrementing the iterator. The iterator returned by
    end() points to the item which is one \e past the last item in the
    container. The past-the-end iterator is still associated with the
    list it belongs to, however it is \e not dereferenceable;
    operator*() will not return a well-defined value. If the list is
    empty(), the iterator returned by begin() will equal the iterator
    returned by end().

    Another way to find an item in the list is by using the \link
    ntqtl.html#qFind tqFind()\endlink algorithm. For example:

    \code
    QValueList<int> list;
    ...
    QValueList<int>::iterator it = tqFind( list.begin(), list.end(), 3 );
    if ( it != list.end() )
	// it points to the found item
    \endcode

    It is safe to have multiple iterators a the list at the same
    time. If some member of the list is removed, only iterators
    pointing to the removed member become invalid. Inserting into the
    list does not invalidate any iterator. For convenience, the
    function last() returns a reference to the last item in the list,
    and first() returns a reference to the the first item. If the
    list is empty(), both last() and first() have undefined behavior
    (your application will crash or do unpredictable things). Use
    last() and first() with caution, for example:

    \code
    QValueList<int> list;
    list.append( 1 );
    list.append( 2 );
    list.append( 3 );
    ...
    if ( !list.empty() ) {
	// OK, modify the first item
	int& i = list.first();
	i = 18;
    }
    ...
    QValueList<double> dlist;
    double d = dlist.last(); // undefined
    \endcode

    Because QValueList is value-based there is no need to be careful
    about deleting items in the list. The list holds its own copies
    and will free them if the corresponding member or the list itself
    is deleted. You can force the list to free all of its items with
    clear().

    QValueList is shared implicitly, which means it can be copied in
    constant time, i.e. O(1). If multiple QValueList instances share
    the same data and one needs to modify its contents, this modifying
    instance makes a copy and modifies its private copy; therefore it
    does not affect the other instances; this takes O(n) time. This is
    often called "copy on write". If a QValueList is being used in a
    multi-threaded program, you must protect all access to the list.
    See \l QMutex.

    There are several ways to insert items into the list. The
    prepend() and append() functions insert items at the beginning and
    the end of the list respectively. The insert() function comes in
    several flavors and can be used to add one or more items at
    specific positions within the list.

    Items can also be removed from the list in several ways. There
    are several variants of the remove() function, which removes a
    specific item from the list. The remove() function will find and
    remove items according to a specific item value.

    Lists can also be sorted using the \link ntqtl.html Qt Template
    Library\endlink. For example with qHeapSort():

    Example:
    \code
    QValueList<int> list;
    list.append( 5 );
    list.append( 8 );
    list.append( 3 );
    list.append( 4 );
    qHeapSort( list );
    \endcode

    \sa QValueListIterator
*/

/*! \enum QValueList::iterator
	The list's iterator type, QValueListIterator. */
/*! \enum QValueList::const_iterator
	The list's const iterator type, QValueListConstIterator. */
/*! \enum QValueList::value_type
	The type of the object stored in the list, T. */
/*! \enum QValueList::pointer
	The pointer to T type. */
/*! \enum QValueList::const_pointer
	The const pointer to T type. */
/*! \enum QValueList::reference
	The reference to T type. */
/*! \enum QValueList::const_reference
	The const reference to T type. */
/*! \enum QValueList::size_type
	An unsigned integral type, used to represent various sizes. */
/*! \enum QValueList::difference_type
    \internal
*/
/*! \enum QValueList::ValueType
    \internal
*/
/*!
    \fn QValueList::QValueList()

    Constructs an empty list.
*/

/*!
    \fn QValueList::QValueList( const QValueList<T>& l )

    Constructs a copy of \a l.

    This operation takes O(1) time because QValueList is implicitly
    shared.

    The first modification to a list will take O(n) time.
*/

/*!
    \fn QValueList::QValueList( const std::list<T>& l )

    Contructs a copy of \a l.

    This constructor is provided for compatibility with STL
    containers.
*/

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

    Destroys the list. References to the values in the list and all
    iterators of this list become invalidated. Note that it is
    impossible for an iterator to check whether or not it is valid:
    QValueList is highly tuned for performance, not for error
    checking.
*/

/*! \enum  QValueListIterator::NodePtr
	\internal */
/*! \enum  QValueListIterator::iterator_category
	\internal */
/*! \enum  QValueListIterator::size_type
	\internal */
/*! \enum  QValueListIterator::difference_type
	\internal */
/*!
    \fn QValueListIterator::QValueListIterator( NodePtr p )
    \internal
*/

/*!
    \fn bool QValueList::operator== ( const QValueList<T>& l ) const

    Compares both lists.

    Returns TRUE if this list and \a l are equal; otherwise returns
    FALSE.
*/

/*!
    \fn bool QValueList::operator== ( const std::list<T>& l ) const

    \overload

    Returns TRUE if this list and \a l are equal; otherwise returns
    FALSE.

    This operator is provided for compatibility with STL containers.
*/

/*!
    \fn QValueList<T>& QValueList::operator= ( const QValueList<T>& l )

    Assigns \a l to this list and returns a reference to this list.

    All iterators of the current list become invalidated by this
    operation. The cost of such an assignment is O(1) since QValueList
    is implicitly shared.
*/

/*!
    \fn QValueList<T>& QValueList::operator= ( const std::list<T>& l )

    \overload

    Assigns the contents of \a l to the list.

    All iterators of the current list become invalidated by this
    operation.
*/

/*!
    \fn bool QValueList::operator!= ( const QValueList<T>& l ) const

    Compares both lists.

    Returns TRUE if this list and \a l are unequal; otherwise returns
    FALSE.
*/

/*!
    \fn iterator QValueList::insert( iterator it, const T& x )

    Inserts the value \a x in front of the item pointed to by the
    iterator, \a it.

    Returns an iterator pointing at the inserted item.

    \sa append(), prepend()
*/

/*!
    \fn uint QValueList::remove( const T& x )

    \overload

    Removes all items that have value \a x and returns the number of
    removed items.
*/

/*!
    \fn void QValueList::clear()

    Removes all items from the list.

    \sa remove()
*/

/*!
    \fn iterator QValueList::begin()

    \overload

    Returns an iterator pointing to the first item in the list. This
    iterator equals end() if the list is empty.

    \sa first(), end()
*/

/*!
    \fn const_iterator QValueList::begin() const

    Returns an iterator pointing to the first item in the list. This
    iterator equals end() if the list is empty.

    \sa first(), end(), constBegin()
*/

/*!
    \fn const_iterator QValueList::constBegin() const

    Returns an iterator pointing to the first item in the list. This
    iterator equals constEnd() if the list is empty.

    \sa begin()
*/

/*!
    \fn iterator QValueList::end()

    Returns an iterator pointing \e past the last item in the list.
    This iterator equals begin() if the list is empty.

    \sa last(), begin(), constEnd()
*/

/*!
    \fn const_iterator QValueList::end() const

    \overload

    Returns an iterator pointing \e past the last item in the list.
    This iterator equals begin() if the list is empty.

    \sa last(), begin()
*/

/*!
    \fn const_iterator QValueList::constEnd() const

    Returns an iterator pointing \e past the last item in the list.
    This iterator equals constBegin() if the list is empty.

    \sa end()
*/

/*!
    \fn QDataStream& operator>>( QDataStream& s, QValueList<T>& l )

    \relates QValueList

    Reads a list, \a l, from the stream \a s. The type T stored in the
    list must implement the streaming operator.
*/

/*!
    \fn QDataStream& operator<<( QDataStream& s, const QValueList<T>& l )

    \overload
    \relates QValueList

    Writes a list, \a l, to the stream \a s. The type T stored in the
    list must implement the streaming operator.
*/

/*!
    \fn size_type QValueList::size() const

    Returns the number of items in the list.

    This function is provided for STL compatibility. It is equivalent
    to count().

    \sa empty()
*/

/*!
    \fn bool QValueList::empty() const

    Returns TRUE if the list contains no items; otherwise returns
    FALSE.

    \sa size()
*/

/*!
    \fn void QValueList::push_front( const T& x )

    Inserts \a x at the beginning of the list.

    This function is provided for STL compatibility. It is equivalent
    to prepend().
*/

/*!
    \fn void QValueList::push_back( const T& x )

    Inserts \a x at the end of the list.

    This function is provided for STL compatibility. It is equivalent
    to append().
*/

/*!
    \fn iterator QValueList::erase( iterator it )

    Removes the item pointed to by \a it from the list. No iterators
    other than \a it or other iterators pointing at the same item as
    \a it are invalidated. Returns an iterator to the next item after
    \a it, or end() if there is no such item.

    This function is provided for STL compatibility. It is equivalent
    to remove().
*/

/*!
    \fn iterator QValueList::erase( iterator first, iterator last )

    \overload

    Deletes all items from \a first to \a last (not including \a
    last). No iterators are invalidated, except those pointing to the
    removed items themselves. Returns \a last.
*/

/*!
    \fn reference QValueList::front()

    Returns a reference to the first item. If the list contains no
    first item (i.e. empty() returns TRUE), the return value is
    undefined.

    This function is provided for STL compatibility. It is equivalent
    to first().

    \sa back()
*/

/*!
    \fn const_reference QValueList::front() const

    \overload
*/

/*!
    \fn reference QValueList::back()

    Returns a reference to the last item. If the list contains no last
    item (i.e. empty() returns TRUE), the return value is undefined.

    This function is provided for STL compatibility. It is equivalent
    to last().

    \sa front()
*/

/*!
    \fn const_reference QValueList::back() const

    \overload
*/

/*!
    \fn void QValueList::pop_front()

    Removes the first item. If there is no first item, this operation
    is undefined.

    This function is provided for STL compatibility.
*/

/*!
    \fn void QValueList::pop_back()

    Removes the last item. If there is no last item, this operation is
    undefined.

    This function is provided for STL compatibility.
*/

/*!
    \fn void QValueList::insert( iterator pos, size_type n, const T& x )

    \overload

    Inserts \a n copies of \a x before position \a pos.
*/

/*!
  \fn void QValueList::detach()
  \internal
*/

/*!
    \fn QValueList<T>& QValueList::operator<< ( const T& x )

    Adds the value \a x to the end of the list.

    Returns a reference to the list.
*/

/*!
    \fn const T& QValueList::operator[] ( size_type i ) const

    Returns a const reference to the item with index \a i in the list.
    It is up to you to check whether this item really exists. You can
    do that easily with the count() function. However this operator
    does not check whether \a i is in range and will deliver undefined
    results if it does not exist.

    \warning This function uses a linear search and can be extremely
    slow for large lists. QValueList is not optimized for random item
    access. If you need random access use a different container, such
    as QValueVector.
*/

/*!
    \fn T& QValueList::operator[] ( size_type i )

    \overload

    Returns a non-const reference to the item with index \a i.
*/

/*!
    \fn const_iterator QValueList::at( size_type i ) const

    Returns an iterator pointing to the item at position \a i in the
    list, or an undefined value if the index is out of range.

    \warning This function uses a linear search and can be extremely
    slow for large lists. QValueList is not optimized for random item
    access. If you need random access use a different container, such
    as QValueVector.
*/

/*!
    \fn iterator QValueList::at( size_type i )

    \overload

    Returns an iterator pointing to the item at position \a i in the
    list, or an undefined value if the index is out of range.

*/

/*!
    \fn iterator QValueList::fromLast()

    \overload

    Returns an iterator to the last item in the list, or end() if
    there is no last item.

    Use the end() function instead. For example:

    \code
    QValueList<int> l;
    ...
    QValueList<int>::iterator it = l.end();
    --it;
    if ( it != end() )
	// ...
    \endcode

*/

/*!
    \fn const_iterator QValueList::fromLast() const

    Returns an iterator to the last item in the list, or end() if
    there is no last item.

    Use the end() function instead. For example:

    \code
    QValueList<int> l;
    ...
    QValueList<int>::iterator it = l.end();
    --it;
    if ( it != end() )
	// ...
    \endcode

*/

/*!
    \fn QValueList<T> QValueList::operator+( const QValueList<T>& l ) const

    Creates a new list and fills it with the items of this list. Then
    the items of \a l are appended. Returns the new list.
*/

/*!
    \fn QValueList<T>& QValueList::operator+= ( const QValueList<T>& l )

    Appends the items of \a l to this list. Returns a reference to
    this list.
*/

/*!
    \fn QValueList<T>& QValueList::operator+= ( const T& x )

    \overload

    Appends the value \a x to the list. Returns a reference to the
    list.
*/

/*!
    \fn uint QValueList::count() const

    Returns the number of items in the list.

    \sa isEmpty()
*/

/*!
    \fn bool QValueList::isEmpty() const

    Returns TRUE if the list contains no items; otherwise returns
    FALSE.

    \sa count()
*/

/*!
    \fn iterator QValueList::append( const T& x )

    Inserts \a x at the end of the list.

    \sa insert(), prepend()
*/

/*!
    \fn iterator QValueList::prepend( const T& x )

    Inserts \a x at the beginning of the list.

    \sa insert(), append()
*/

/*!
    \fn iterator QValueList::remove( iterator it )

    Removes the item pointed to by \a it from the list. No iterators
    other than \a it or other iterators pointing at the same item as
    \a it are invalidated. Returns an iterator to the next item after
    \a it, or end() if there is no such item.

    \sa clear()
*/

/*!
    \fn iterator QValueList::find( const T& x )

    Returns an iterator pointing to the first occurrence of \a x in
    the list.

    Returns end() is no item matched.
*/

/*!
    \fn const_iterator QValueList::find( const T& x ) const

    \overload

    Returns an iterator pointing to the first occurrence of \a x in
    the list.

    Returns end() if no item matched.
*/

/*!
    \fn iterator QValueList::find( iterator it, const T& x )

    \overload

    Finds the first occurrence of \a x in the list starting at the
    position given by \a it.

    Returns end() if no item matched.
*/

/*!
    \fn const_iterator QValueList::find( const_iterator it, const T& x ) const

    \overload

    Finds the first occurrence of \a x in the list starting at the
    position given by \a it.

    Returns end() if no item matched.
*/

/*!
    \fn uint QValueList::contains( const T& x ) const

    Returns the number of occurrences of the value \a x in the list.
*/

/*!
    \fn int QValueList::findIndex( const T& x ) const

    Returns the index of the first occurrence of the value \a x.
    Returns -1 if no item matched.
*/

/*!
    \fn T& QValueList::first()

    Returns a reference to the first item. If the list contains no
    first item (i.e. isEmpty() returns TRUE), the return value is
    undefined.

    \sa last()
*/

/*!
    \fn const T& QValueList::first() const

    \overload
*/

/*!
    \fn T& QValueList::last()

    Returns a reference to the last item. If the list contains no last
    item (i.e. empty() returns TRUE), the return value is undefined.
*/

/*!
    \fn const T& QValueList::last() const

    \overload
*/

/*****************************************************************************
  QValueListIterator documentation
 *****************************************************************************/

/*!
    \class QValueListIterator ntqvaluelist.h
    \brief The QValueListIterator class provides an iterator for QValueList.

    \ingroup qtl
    \ingroup tools
    \reentrant

    An iterator is a class for accessing the items of a container
    class: a generalization of the index in an array. A pointer
    into a "const char *" and an index into an "int[]" are both
    iterators, and the general idea is to provide that functionality
    for any data structure.

    The QValueListIterator class is an iterator for QValueList
    instantiations. You can create the appropriate iterator type by
    using the \c iterator typedef provided by QValueList.

    The only way to access the items in a QValueList is to use an
    iterator.

    Example (see QValueList for the complete code):
    \code
    EmployeeList::iterator it;
    for ( it = list.begin(); it != list.end(); ++it )
	cout << (*it).surname().latin1() << ", " <<
		(*it).forename().latin1() << " earns " <<
		(*it).salary() << endl;

    // Output:
    // Doe, John earns 50000
    // Williams, Jane earns 80000
    // Hawthorne, Mary earns 90000
    // Jones, Tom earns 60000
    \endcode

    QValueList is highly optimized for performance and memory usage.
    This means that you must be careful: QValueList does not know
    about all its iterators and the iterators don't know to which list
    they belong. This makes things very fast, but if you're not
    careful, you can get spectacular bugs. Always make sure iterators
    are valid before dereferencing them or using them as parameters to
    generic algorithms in the STL or the \link ntqtl.html QTL\endlink.

    Using an invalid iterator is undefined (your application will
    probably crash). Many Qt functions return const value lists; to
    iterate over these you should make a copy and iterate over the
    copy.

    For every Iterator there is a ConstIterator. When accessing a
    QValueList in a const environment or if the reference or pointer
    to the list is itself const, then you must use the ConstIterator.
    Its semantics are the same as the Iterator, but it only returns
    const references.

    \sa QValueList, QValueListConstIterator
*/

/*! \enum  QValueListIterator::value_type
	The type of value, T. */
/*! \enum  QValueListIterator::pointer
	Pointer to value_type. */
/*! \enum  QValueListIterator::reference
	Reference to value_type. */

/*!
    \fn QValueListIterator::QValueListIterator()

    Creates un uninitialized iterator.
*/

/*
    \fn QValueListIterator::QValueListIterator( NodePtr p )

    \overload

    \internal
*/

/*!
    \fn QValueListIterator::QValueListIterator( const QValueListIterator<T>& it )

    \overload

    Constructs a copy of the iterator \a it.
*/

/* Unfortunately not with MSVC
  \fn T *QValueListIterator::operator->()
  Pointer operator. Returns a pointer to the current iterator item.
  The great advantage of this operator is that you can treat the
  iterator like a pointer.

  Example:
  \code
    QValueList<int>::Iterator it = list.begin();
    for( ; it != end(); ++it )
	it->show();
  \endcode
*/

/*!
    \fn T& QValueListIterator::operator*()

    Asterisk operator. Returns a reference to the current iterator item.
*/

/*!
    \fn const T& QValueListIterator::operator*() const

    \overload

    Asterisk operator. Returns a reference to the current iterator item.
*/

/*!
    \fn QValueListIterator<T>& QValueListIterator::operator++()

    Prefix ++ makes the succeeding item current and returns an
    iterator pointing to the new current item. The iterator cannot
    check whether it reached the end of the list. Incrementing the
    iterator returned by end() causes undefined results.
*/

/*!
    \fn QValueListIterator<T> QValueListIterator::operator++(int)

    \overload

    Postfix ++ makes the succeeding item current and returns an
    iterator pointing to the new current item. The iterator cannot
    check whether it reached the end of the list. Incrementing the
    iterator returned by end() causes undefined results.
*/

/*!
    \fn QValueListIterator<T>& QValueListIterator::operator--()

    Prefix -- makes the previous item current and returns an iterator
    pointing to the new current item. The iterator cannot check
    whether it reached the beginning of the list. Decrementing the
    iterator returned by begin() causes undefined results.
*/

/*!
    \fn QValueListIterator<T> QValueListIterator::operator--(int)

    \overload

    Postfix -- makes the previous item current and returns an iterator
    pointing to the new current item. The iterator cannot check
    whether it reached the beginning of the list. Decrementing the
    iterator returned by begin() causes undefined results.
*/


/*!
    \fn QValueListIterator<T>& QValueListIterator::operator+=(int j)

    Postfix -- jumps \a j steps forward in the list. The iterator
    cannot check whether it reached the end of the list. Jumping past
    the end() causes undefined results.
*/

/*!
    \fn QValueListIterator<T>& QValueListIterator::operator-=(int j)

    Postfix -- jumps \a j steps backward in the list. The iterator
    cannot check whether it reached the beginning of the list. Jumping
    past begin() causes undefined results.
*/

/*!
    \fn bool QValueListIterator::operator==( const QValueListIterator<T>& it ) const

    Compares this iterator and \a it and returns TRUE if they point to
    the same item; otherwise returns FALSE.
*/

/*!
    \fn bool QValueListIterator::operator!=( const QValueListIterator<T>& it ) const

    Compares this iterator and \a it and returns TRUE if they point to
    different items; otherwise returns FALSE.
*/

/*****************************************************************************
  QValueListConstIterator documentation
 *****************************************************************************/

/*!
    \class QValueListConstIterator ntqvaluelist.h
    \brief The QValueListConstIterator class provides a const iterator
    for QValueList.

    \ingroup qtl
    \ingroup tools
    \reentrant

    In contrast to QValueListIterator, this class is used to iterate
    over a const list. It does not allow modification of the values of
    the list since that would break const semantics.

    You can create the appropriate const iterator type by using the \c
    const_iterator typedef provided by QValueList.

    For more information on QValueList iterators, see
    QValueListIterator.

    \sa QValueListIterator, QValueList
*/

/*! \enum  QValueListConstIterator::value_type
	The type of value. */
/*! \enum  QValueListConstIterator::pointer
	Pointer to value_type. */
/*! \enum  QValueListConstIterator::reference
	Reference to value_type. */
/*! \enum  QValueListConstIterator::NodePtr
	\internal */
/*! \enum  QValueListConstIterator::iterator_category
	\internal */
/*! \enum  QValueListConstIterator::size_type
	\internal */
/*! \enum  QValueListConstIterator::difference_type
	\internal */

/*!
    \fn QValueListConstIterator::QValueListConstIterator()

    Creates un uninitialized iterator.
*/

/*!
    \fn QValueListConstIterator::QValueListConstIterator( NodePtr p )

    \overload

    \internal
*/

/*!
    \fn QValueListConstIterator::QValueListConstIterator( const QValueListConstIterator<T>& it )

    \overload

    Constructs a copy of the iterator \a it.
*/

/*!
    \fn QValueListConstIterator::QValueListConstIterator( const QValueListIterator<T>& it )

    Constructs a copy of the iterator \a it.
*/

/* Unfortunately not with MSVC
  \fn const T *QValueListConstIterator::operator->()
  Pointer operator. Returns a pointer to the current iterator item.
  The great advantage of this operator is that you can treat the
  iterator like a pointer.

  Example:
  \code
    QValueList<int>::Iterator it = list.begin();
    for( ; it != end(); ++it )
	it->show();
  \endcode
*/

/*!
    \fn const T& QValueListConstIterator::operator*() const

    Asterisk operator. Returns a reference to the current iterator item.
*/

/*!
    \fn QValueListConstIterator<T>& QValueListConstIterator::operator++()

    Prefix ++ makes the succeeding item current and returns an
    iterator pointing to the new current item. The iterator cannot
    check whether it reached the end of the list. Incrementing the
    iterator returned by end() causes undefined results.
*/

/*!
    \fn QValueListConstIterator<T> QValueListConstIterator::operator++(int)

    \overload

    Postfix ++ makes the succeeding item current and returns an
    iterator pointing to the new current item. The iterator cannot
    check whether it reached the end of the list. Incrementing the
    iterator returned by end() causes undefined results.
*/

/*!
    \fn QValueListConstIterator<T>& QValueListConstIterator::operator--()

    Prefix -- makes the previous item current and returns an iterator
    pointing to the new current item. The iterator cannot check
    whether it reached the beginning of the list. Decrementing the
    iterator returned by begin() causes undefined results.
*/

/*!
    \fn QValueListConstIterator<T> QValueListConstIterator::operator--(int)

    \overload

    Postfix -- makes the previous item current and returns an iterator
    pointing to the new current item. The iterator cannot check
    whether it reached the beginning of the list. Decrementing the
    iterator returned by begin() causes undefined results.
*/

/*!
    \fn bool QValueListConstIterator::operator==( const QValueListConstIterator<T>& it ) const

    Compares this iterator with \a it and returns TRUE if they point
    to the same item; otherwise returns FALSE.
*/

/*!
    \fn bool QValueListConstIterator::operator!=( const QValueListConstIterator<T>& it ) const

    Compares this iterator with \a it and returns TRUE if they point
    to different items; otherwise returns FALSE.
*/


/*!
    \enum QValueList::Iterator

    This iterator is an instantiation of QValueListIterator for the
    same type as this QValueList. In other words, if you instantiate
    QValueList<int>, Iterator is a QValueListIterator<int>. Several
    member function use it, such as QValueList::begin(), which returns
    an iterator pointing to the first item in the list.

    Functionally, this is almost the same as ConstIterator. The only
    difference is that you cannot use ConstIterator for non-const
    operations, and that the compiler can often generate better code
    if you use ConstIterator.

    \sa QValueListIterator ConstIterator
*/

/*!
    \enum QValueList::ConstIterator

    This iterator is an instantiation of QValueListConstIterator for
    the same type as this QValueList. In other words, if you
    instantiate QValueList<int>, ConstIterator is a
    QValueListConstIterator<int>. Several member function use it, such
    as QValueList::begin(), which returns an iterator pointing to the
    first item in the list.

    Functionally, this is almost the same as Iterator. The only
    difference is you cannot use ConstIterator for non-const
    operations, and that the compiler can often generate better code
    if you use ConstIterator.

    \sa QValueListIterator Iterator
*/