1QValueList(3qt) QValueList(3qt)
2
6 QValueList - Value-based template class that provides lists
7
9 All the functions in this class are reentrant when Qt is built with
10 thread support.</p>
11 #include <qvaluelist.h>
13 Inherited by QCanvasItemList, QStringList, and QValueStack.
15 Public Members
17 typedef QValueListIterator<T> iterator
18 typedef QValueListConstIterator<T> const_iterator
19 typedef T value_type
20 typedef value_type * pointer
21 typedef const value_type * const_pointer
22 typedef value_type & reference
23 typedef const value_type & const_reference
24 typedef size_t size_type
25 QValueList ()
26 QValueList ( const QValueList<T> & l )
27 QValueList ( const std::list<T> & l )
28 ~QValueList ()
29 QValueList<T> & operator= ( const QValueList<T> & l )
30 QValueList<T> & operator= ( const std::list<T> & l )
31 bool operator== ( const std::list<T> & l ) const
32 bool operator== ( const QValueList<T> & l ) const
33 bool operator!= ( const QValueList<T> & l ) const
34 iterator begin ()
35 const_iterator begin () const
36 const_iterator constBegin () const
37 iterator end ()
38 const_iterator end () const
39 const_iterator constEnd () const
40 iterator insert ( iterator it, const T & x )
41 uint remove ( const T & x )
42 void clear ()
43 QValueList<T> & operator<< ( const T & x )
44 size_type size () const
45 bool empty () const
46 void push_front ( const T & x )
47 void push_back ( const T & x )
48 iterator erase ( iterator it )
49 iterator erase ( iterator first, iterator last )
50 reference front ()
51 const_reference front () const
52 reference back ()
53 const_reference back () const
54 void pop_front ()
55 void pop_back ()
56 void insert ( iterator pos, size_type n, const T & x )
57 QValueList<T> operator+ ( const QValueList<T> & l ) const
58 QValueList<T> & operator+= ( const QValueList<T> & l )
59 iterator fromLast ()
60 const_iterator fromLast () const
61 bool isEmpty () const
62 iterator append ( const T & x )
63 iterator prepend ( const T & x )
64 iterator remove ( iterator it )
65 T & first ()
66 const T & first () const
67 T & last ()
68 const T & last () const
69 T & operator[] ( size_type i )
70 const T & operator[] ( size_type i ) const
71 iterator at ( size_type i )
72 const_iterator at ( size_type i ) const
73 iterator find ( const T & x )
74 const_iterator find ( const T & x ) const
75 iterator find ( iterator it, const T & x )
76 const_iterator find ( const_iterator it, const T & x ) const
77 int findIndex ( const T & x ) const
78 size_type contains ( const T & x ) const
79 size_type count () const
80 QValueList<T> & operator+= ( const T & x )
81 typedef QValueListIterator<T> Iterator
82 typedef QValueListConstIterator<T> ConstIterator
83
85 QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )
86 QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )
87
89 The QValueList class is a value-based template class that provides
90 lists.
91 QValueList is a Qt implementation of an STL-like list container. It can
93 be used in your application if the standard list is not available for
94 your target platform(s). QValueList is part of the Qt Template Library.
95 QValueList<T> defines a template instance to create a list of values
97 that all have the class T. Note that QValueList does not store pointers
98 to the members of the list; it holds a copy of every member. This is
99 why these kinds of classes are called "value based"; QPtrList and QDict
100 are "pointer based".
101 QValueList contains and manages a collection of objects of type T and
103 provides iterators that allow the contained objects to be addressed.
104 QValueList owns the contained items. For more relaxed ownership
105 semantics, see QPtrCollection and friends which are pointer-based
106 containers.
107 Some classes cannot be used within a QValueList, for example, all
109 classes derived from QObject and thus all classes that implement
110 widgets. Only values can be used in a QValueList. To qualify as a value
111 the class must provide:
112 a copy constructor;
114 an assignment operator;
116 a default constructor, i.e. a constructor that does not take any
118 arguments.
119 Note that C++ defaults to field-by-field assignment operators and copy
121 constructors if no explicit version is supplied. In many cases this is
122 sufficient.
123 In addition, some compilers (e.g. Sun CC) might require that the class
125 provides an equality operator (operator==()).
126 QValueList's function naming is consistent with the other Qt classes
128 (e.g. count(), isEmpty()). QValueList also provides extra functions for
129 compatibility with STL algorithms, such as size() and empty().
130 Programmers already familiar with the STL list may prefer to use the
131 STL-compatible functions.
132 Example:
134 class Employee
136 {
137 public:
138 Employee(): sn(0) {}
139 Employee( const QString& forename, const QString& surname, int salary )
140 : fn(forename), sn(surname), sal(salary)
141 {}
142 QString forename() const { return fn; }
143 QString surname() const { return sn; }
144 int salary() const { return sal; }
145 void setSalary( int salary ) { sal = salary; }
146 private:
147 QString fn;
148 QString sn;
149 int sal;
150 };
151 typedef QValueList<Employee> EmployeeList;
152 EmployeeList list;
153 list.append( Employee("John", "Doe", 50000) );
154 list.append( Employee("Jane", "Williams", 80000) );
155 list.append( Employee("Tom", "Jones", 60000) );
156 Employee mary( "Mary", "Hawthorne", 90000 );
157 list.append( mary );
158 mary.setSalary( 100000 );
159 EmployeeList::iterator it;
160 for ( it = list.begin(); it != list.end(); ++it )
161 cout << (*it).surname().latin1() << ", " <<
162 (*it).forename().latin1() << " earns " <<
163 (*it).salary() << endl;
164 // Output:
165 // Doe, John earns 50000
166 // Williams, Jane earns 80000
167 // Hawthorne, Mary earns 90000
168 // Jones, Tom earns 60000
169 Notice that the latest changes to Mary's salary did not affect the
171 value in the list because the list created a copy of Mary's entry.
172 There are several ways to find items in the list. The begin() and end()
174 functions return iterators to the beginning and end of the list. The
175 advantage of getting an iterator is that you can move forward or
176 backward from this position by incrementing/decrementing the iterator.
177 The iterator returned by end() points to the item which is one past the
178 last item in the container. The past-the-end iterator is still
179 associated with the list it belongs to, however it is not
180 dereferenceable; operator*() will not return a well-defined value. If
181 the list is empty(), the iterator returned by begin() will equal the
182 iterator returned by end().
183 Another way to find an item in the list is by using the qFind()
185 algorithm. For example:
186 QValueList<int> list;
188 ...
189 QValueList<int>::iterator it = qFind( list.begin(), list.end(), 3 );
190 if ( it != list.end() )
191 // it points to the found item
192 It is safe to have multiple iterators a the list at the same time. If
194 some member of the list is removed, only iterators pointing to the
195 removed member become invalid. Inserting into the list does not
196 invalidate any iterator. For convenience, the function last() returns a
197 reference to the last item in the list, and first() returns a reference
198 to the the first item. If the list is empty(), both last() and first()
199 have undefined behavior (your application will crash or do
200 unpredictable things). Use last() and first() with caution, for
201 example:
202 QValueList<int> list;
204 list.append( 1 );
205 list.append( 2 );
206 list.append( 3 );
207 ...
208 if ( !list.empty() ) {
209 // OK, modify the first item
210 int& i = list.first();
211 i = 18;
212 }
213 ...
214 QValueList<double> dlist;
215 double d = dlist.last(); // undefined
216 Because QValueList is value-based there is no need to be careful about
218 deleting items in the list. The list holds its own copies and will free
219 them if the corresponding member or the list itself is deleted. You can
220 force the list to free all of its items with clear().
221 QValueList is shared implicitly, which means it can be copied in
223 constant time, i.e. O(1). If multiple QValueList instances share the
224 same data and one needs to modify its contents, this modifying instance
225 makes a copy and modifies its private copy; therefore it does not
226 affect the other instances; this takes O(n) time. This is often called
227 "copy on write". If a QValueList is being used in a multi-threaded
228 program, you must protect all access to the list. See QMutex.
229 There are several ways to insert items into the list. The prepend() and
231 append() functions insert items at the beginning and the end of the
232 list respectively. The insert() function comes in several flavors and
233 can be used to add one or more items at specific positions within the
234 list.
235 Items can also be removed from the list in several ways. There are
237 several variants of the remove() function, which removes a specific
238 item from the list. The remove() function will find and remove items
239 according to a specific item value.
240 Lists can also be sorted using the Qt Template Library. For example
242 with qHeapSort():
243 Example:
245 QValueList<int> list;
247 list.append( 5 );
248 list.append( 8 );
249 list.append( 3 );
250 list.append( 4 );
251 qHeapSort( list );
252 See also QValueListIterator, Qt Template Library Classes, Implicitly
254 and Explicitly Shared Classes, and Non-GUI Classes.
255 Member Type Documentation
258 This iterator is an instantiation of QValueListConstIterator for the
259 same type as this QValueList. In other words, if you instantiate
260 QValueList<int>, ConstIterator is a QValueListConstIterator<int>.
261 Several member function use it, such as QValueList::begin(), which
262 returns an iterator pointing to the first item in the list.
263 Functionally, this is almost the same as Iterator. The only difference
265 is you cannot use ConstIterator for non-const operations, and that the
266 compiler can often generate better code if you use ConstIterator.
267 See also QValueListIterator and Iterator.
269
271 This iterator is an instantiation of QValueListIterator for the same
272 type as this QValueList. In other words, if you instantiate
273 QValueList<int>, Iterator is a QValueListIterator<int>. Several member
274 function use it, such as QValueList::begin(), which returns an iterator
275 pointing to the first item in the list.
276 Functionally, this is almost the same as ConstIterator. The only
278 difference is that you cannot use ConstIterator for non-const
279 operations, and that the compiler can often generate better code if you
280 use ConstIterator.
281 See also QValueListIterator and ConstIterator.
283
285 The list's const iterator type, QValueListConstIterator.
286
288 The const pointer to T type.
289
291 The const reference to T type.
292
294 The list's iterator type, QValueListIterator.
295
297 The pointer to T type.
298
300 The reference to T type.
301
303 An unsigned integral type, used to represent various sizes.
304
306 The type of the object stored in the list, T.
307
310 Constructs an empty list.
311
313 Constructs a copy of l.
314 This operation takes O(1) time because QValueList is implicitly shared.
316 The first modification to a list will take O(n) time.
318
320 Contructs a copy of l.
321 This constructor is provided for compatibility with STL containers.
323
325 Destroys the list. References to the values in the list and all
326 iterators of this list become invalidated. Note that it is impossible
327 for an iterator to check whether or not it is valid: QValueList is
328 highly tuned for performance, not for error checking.
329
331 Inserts x at the end of the list.
332 See also insert() and prepend().
334 Examples:
336
338 Returns an iterator pointing to the item at position i in the list, or
339 an undefined value if the index is out of range.
340 Warning: This function uses a linear search and can be extremely slow
342 for large lists. QValueList is not optimized for random item access. If
343 you need random access use a different container, such as QValueVector.
344
346 This is an overloaded member function, provided for convenience. It
347 behaves essentially like the above function.
348 Returns an iterator pointing to the item at position i in the list, or
350 an undefined value if the index is out of range.
351
353 Returns a reference to the last item. If the list contains no last item
354 (i.e. empty() returns TRUE), the return value is undefined.
355 This function is provided for STL compatibility. It is equivalent to
357 last().
358 See also front().
360
362 This is an overloaded member function, provided for convenience. It
363 behaves essentially like the above function.
364
366 Returns an iterator pointing to the first item in the list. This
367 iterator equals end() if the list is empty.
368 See also first(), end(), and constBegin().
370 Examples:
372
374 This is an overloaded member function, provided for convenience. It
375 behaves essentially like the above function.
376 Returns an iterator pointing to the first item in the list. This
378 iterator equals end() if the list is empty.
379 See also first() and end().
381
383 Removes all items from the list.
384 See also remove().
386
388 Returns an iterator pointing to the first item in the list. This
389 iterator equals constEnd() if the list is empty.
390 See also begin().
392
394 Returns an iterator pointing past the last item in the list. This
395 iterator equals constBegin() if the list is empty.
396 See also end().
398
400 Returns the number of occurrences of the value x in the list.
401
403 Returns the number of items in the list.
404 See also isEmpty().
406 Examples:
408
410 Returns TRUE if the list contains no items; otherwise returns FALSE.
411 See also size().
413
415 Returns an iterator pointing past the last item in the list. This
416 iterator equals begin() if the list is empty.
417 See also last(), begin(), and constEnd().
419 Examples:
421
423 This is an overloaded member function, provided for convenience. It
424 behaves essentially like the above function.
425 Returns an iterator pointing past the last item in the list. This
427 iterator equals begin() if the list is empty.
428 See also last() and begin().
430
432 Removes the item pointed to by it from the list. No iterators other
433 than it or other iterators pointing at the same item as it are
434 invalidated. Returns an iterator to the next item after it, or end() if
435 there is no such item.
436 This function is provided for STL compatibility. It is equivalent to
438 remove().
439
441 This is an overloaded member function, provided for convenience. It
442 behaves essentially like the above function.
443 Deletes all items from first to last (not including last). No iterators
445 are invalidated, except those pointing to the removed items themselves.
446 Returns last.
447
449 Returns an iterator pointing to the first occurrence of x in the list.
450 Returns end() is no item matched.
452
454 This is an overloaded member function, provided for convenience. It
455 behaves essentially like the above function.
456 Returns an iterator pointing to the first occurrence of x in the list.
458 Returns end() if no item matched.
460
462 This is an overloaded member function, provided for convenience. It
463 behaves essentially like the above function.
464 Finds the first occurrence of x in the list starting at the position
466 given by it.
467 Returns end() if no item matched.
469
471 This is an overloaded member function, provided for convenience. It
472 behaves essentially like the above function.
473 Finds the first occurrence of x in the list starting at the position
475 given by it.
476 Returns end() if no item matched.
478
480 Returns the index of the first occurrence of the value x. Returns -1 if
481 no item matched.
482
484 Returns a reference to the first item. If the list contains no first
485 item (i.e. isEmpty() returns TRUE), the return value is undefined.
486 See also last().
488 Example: network/mail/smtp.cpp.
490
492 This is an overloaded member function, provided for convenience. It
493 behaves essentially like the above function.
494
496 Returns an iterator to the last item in the list, or end() if there is
497 no last item.
498 Use the end() function instead. For example:
500 QValueList<int> l;
502 ...
503 QValueList<int>::iterator it = l.end();
504 --it;
505 if ( it != end() )
506 // ...
507
509 This is an overloaded member function, provided for convenience. It
510 behaves essentially like the above function.
511 Returns an iterator to the last item in the list, or end() if there is
513 no last item.
514 Use the end() function instead. For example:
516 QValueList<int> l;
518 ...
519 QValueList<int>::iterator it = l.end();
520 --it;
521 if ( it != end() )
522 // ...
523
525 Returns a reference to the first item. If the list contains no first
526 item (i.e. empty() returns TRUE), the return value is undefined.
527 This function is provided for STL compatibility. It is equivalent to
529 first().
530 See also back().
532
534 This is an overloaded member function, provided for convenience. It
535 behaves essentially like the above function.
536
538 Inserts the value x in front of the item pointed to by the iterator,
539 it.
540 Returns an iterator pointing at the inserted item.
542 See also append() and prepend().
544 Example: themes/themes.cpp.
546
548 This is an overloaded member function, provided for convenience. It
549 behaves essentially like the above function.
550 Inserts n copies of x before position pos.
552
554 Returns TRUE if the list contains no items; otherwise returns FALSE.
555 See also count().
557 Examples:
559
561 Returns a reference to the last item. If the list contains no last item
562 (i.e. empty() returns TRUE), the return value is undefined.
563
565 This is an overloaded member function, provided for convenience. It
566 behaves essentially like the above function.
567
569 Compares both lists.
570 Returns TRUE if this list and l are unequal; otherwise returns FALSE.
572
574 Creates a new list and fills it with the items of this list. Then the
575 items of l are appended. Returns the new list.
576
578 Appends the items of l to this list. Returns a reference to this list.
579
581 This is an overloaded member function, provided for convenience. It
582 behaves essentially like the above function.
583 Appends the value x to the list. Returns a reference to the list.
585
587 Adds the value x to the end of the list.
588 Returns a reference to the list.
590
592 Assigns l to this list and returns a reference to this list.
593 All iterators of the current list become invalidated by this operation.
595 The cost of such an assignment is O(1) since QValueList is implicitly
596 shared.
597
599 This is an overloaded member function, provided for convenience. It
600 behaves essentially like the above function.
601 Assigns the contents of l to the list.
603 All iterators of the current list become invalidated by this operation.
605
607 Compares both lists.
608 Returns TRUE if this list and l are equal; otherwise returns FALSE.
610
612 This is an overloaded member function, provided for convenience. It
613 behaves essentially like the above function.
614 Returns TRUE if this list and l are equal; otherwise returns FALSE.
616 This operator is provided for compatibility with STL containers.
618
620 Returns a const reference to the item with index i in the list. It is
621 up to you to check whether this item really exists. You can do that
622 easily with the count() function. However this operator does not check
623 whether i is in range and will deliver undefined results if it does not
624 exist.
625 Warning: This function uses a linear search and can be extremely slow
627 for large lists. QValueList is not optimized for random item access. If
628 you need random access use a different container, such as QValueVector.
629
631 This is an overloaded member function, provided for convenience. It
632 behaves essentially like the above function.
633 Returns a non-const reference to the item with index i.
635
637 Removes the last item. If there is no last item, this operation is
638 undefined.
639 This function is provided for STL compatibility.
641
643 Removes the first item. If there is no first item, this operation is
644 undefined.
645 This function is provided for STL compatibility.
647
649 Inserts x at the beginning of the list.
650 See also insert() and append().
652
654 Inserts x at the end of the list.
655 This function is provided for STL compatibility. It is equivalent to
657 append().
658
660 Inserts x at the beginning of the list.
661 This function is provided for STL compatibility. It is equivalent to
663 prepend().
664 Example: toplevel/options.ui.h.
666
668 Removes the item pointed to by it from the list. No iterators other
669 than it or other iterators pointing at the same item as it are
670 invalidated. Returns an iterator to the next item after it, or end() if
671 there is no such item.
672 See also clear().
674
676 This is an overloaded member function, provided for convenience. It
677 behaves essentially like the above function.
678 Removes all items that have value x and returns the number of removed
680 items.
681
683 Returns the number of items in the list.
684 This function is provided for STL compatibility. It is equivalent to
686 count().
687 See also empty().
689
692 This is an overloaded member function, provided for convenience. It
693 behaves essentially like the above function.
694 Writes a list, l, to the stream s. The type T stored in the list must
696 implement the streaming operator.
697
699 Reads a list, l, from the stream s. The type T stored in the list must
700 implement the streaming operator.
701
704 http://doc.trolltech.com/qvaluelist.html
705 http://www.trolltech.com/faq/tech.html
706
708 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
709 license file included in the distribution for a complete license
710 statement.
711
713 Generated automatically from the source code.
714
716 If you find a bug in Qt, please report it as described in
717 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
718 help you. Thank you.
719 The definitive Qt documentation is provided in HTML format; it is
721 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
722 web browser. This man page is provided as a convenience for those users
723 who prefer man pages, although this format is not officially supported
724 by Trolltech.
725 If you find errors in this manual page, please report them to qt-
727 bugs@trolltech.com. Please include the name of the manual page
728 (qvaluelist.3qt) and the Qt version (3.3.8).
729Trolltech AS 2 February 2007 QValueList(3qt)