1QValueList(3qt)                                                QValueList(3qt)
2
3
4

NAME

6       QValueList - Value-based template class that provides lists
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qvaluelist.h>
13
14       Inherited by QCanvasItemList, QStringList, and QValueStack.
15
16   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

DESCRIPTION

89       The QValueList class is a value-based template class that provides
90       lists.
91
92       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
96       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
102       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
108       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
113       a copy constructor;
114
115       an assignment operator;
116
117       a default constructor, i.e. a constructor that does not take any
118       arguments.
119
120       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
124       In addition, some compilers (e.g. Sun CC) might require that the class
125       provides an equality operator (operator==()).
126
127       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
133       Example:
134
135           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
170       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
173       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
184       Another way to find an item in the list is by using the qFind()
185       algorithm. For example:
186
187           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
193       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
203           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
217       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
222       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
230       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
236       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
241       Lists can also be sorted using the Qt Template Library. For example
242       with qHeapSort():
243
244       Example:
245
246           QValueList<int> list;
247           list.append( 5 );
248           list.append( 8 );
249           list.append( 3 );
250           list.append( 4 );
251           qHeapSort( list );
252
253       See also QValueListIterator, Qt Template Library Classes, Implicitly
254       and Explicitly Shared Classes, and Non-GUI Classes.
255
256   Member Type Documentation

QValueList::ConstIterator

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
264       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
268       See also QValueListIterator and Iterator.
269

QValueList::Iterator

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
277       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
282       See also QValueListIterator and ConstIterator.
283

QValueList::const_iterator

285       The list's const iterator type, QValueListConstIterator.
286

QValueList::const_pointer

288       The const pointer to T type.
289

QValueList::const_reference

291       The const reference to T type.
292

QValueList::iterator

294       The list's iterator type, QValueListIterator.
295

QValueList::pointer

297       The pointer to T type.
298

QValueList::reference

300       The reference to T type.
301

QValueList::size_type

303       An unsigned integral type, used to represent various sizes.
304

QValueList::value_type

306       The type of the object stored in the list, T.
307

MEMBER FUNCTION DOCUMENTATION

QValueList::QValueList ()

310       Constructs an empty list.
311

QValueList::QValueList ( const QValueList<T> & l )

313       Constructs a copy of l.
314
315       This operation takes O(1) time because QValueList is implicitly shared.
316
317       The first modification to a list will take O(n) time.
318

QValueList::QValueList ( const std::list<T> & l )

320       Contructs a copy of l.
321
322       This constructor is provided for compatibility with STL containers.
323

QValueList::~QValueList ()

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

iterator QValueList::append ( const T & x )

331       Inserts x at the end of the list.
332
333       See also insert() and prepend().
334
335       Examples:
336

const_iterator QValueList::at ( size_type i ) const

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
341       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

iterator QValueList::at ( size_type i )

346       This is an overloaded member function, provided for convenience. It
347       behaves essentially like the above function.
348
349       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

reference QValueList::back ()

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
356       This function is provided for STL compatibility. It is equivalent to
357       last().
358
359       See also front().
360

const_reference QValueList::back () const

362       This is an overloaded member function, provided for convenience. It
363       behaves essentially like the above function.
364

const_iterator QValueList::begin () const

366       Returns an iterator pointing to the first item in the list. This
367       iterator equals end() if the list is empty.
368
369       See also first(), end(), and constBegin().
370
371       Examples:
372

iterator QValueList::begin ()

374       This is an overloaded member function, provided for convenience. It
375       behaves essentially like the above function.
376
377       Returns an iterator pointing to the first item in the list. This
378       iterator equals end() if the list is empty.
379
380       See also first() and end().
381

void QValueList::clear ()

383       Removes all items from the list.
384
385       See also remove().
386

const_iterator QValueList::constBegin () const

388       Returns an iterator pointing to the first item in the list. This
389       iterator equals constEnd() if the list is empty.
390
391       See also begin().
392

const_iterator QValueList::constEnd () const

394       Returns an iterator pointing past the last item in the list. This
395       iterator equals constBegin() if the list is empty.
396
397       See also end().
398

size_type QValueList::contains ( const T & x ) const

400       Returns the number of occurrences of the value x in the list.
401

size_type QValueList::count () const

403       Returns the number of items in the list.
404
405       See also isEmpty().
406
407       Examples:
408

bool QValueList::empty () const

410       Returns TRUE if the list contains no items; otherwise returns FALSE.
411
412       See also size().
413

iterator QValueList::end ()

415       Returns an iterator pointing past the last item in the list. This
416       iterator equals begin() if the list is empty.
417
418       See also last(), begin(), and constEnd().
419
420       Examples:
421

const_iterator QValueList::end () const

423       This is an overloaded member function, provided for convenience. It
424       behaves essentially like the above function.
425
426       Returns an iterator pointing past the last item in the list. This
427       iterator equals begin() if the list is empty.
428
429       See also last() and begin().
430

iterator QValueList::erase ( iterator it )

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
437       This function is provided for STL compatibility. It is equivalent to
438       remove().
439

iterator QValueList::erase ( iterator first, iterator last )

441       This is an overloaded member function, provided for convenience. It
442       behaves essentially like the above function.
443
444       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

iterator QValueList::find ( const T & x )

449       Returns an iterator pointing to the first occurrence of x in the list.
450
451       Returns end() is no item matched.
452

const_iterator QValueList::find ( const T & x ) const

454       This is an overloaded member function, provided for convenience. It
455       behaves essentially like the above function.
456
457       Returns an iterator pointing to the first occurrence of x in the list.
458
459       Returns end() if no item matched.
460

iterator QValueList::find ( iterator it, const T & x )

462       This is an overloaded member function, provided for convenience. It
463       behaves essentially like the above function.
464
465       Finds the first occurrence of x in the list starting at the position
466       given by it.
467
468       Returns end() if no item matched.
469

const_iterator QValueList::find ( const_iterator it, const T & x ) const

471       This is an overloaded member function, provided for convenience. It
472       behaves essentially like the above function.
473
474       Finds the first occurrence of x in the list starting at the position
475       given by it.
476
477       Returns end() if no item matched.
478

int QValueList::findIndex ( const T & x ) const

480       Returns the index of the first occurrence of the value x. Returns -1 if
481       no item matched.
482

T & QValueList::first ()

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
487       See also last().
488
489       Example: network/mail/smtp.cpp.
490

const T & QValueList::first () const

492       This is an overloaded member function, provided for convenience. It
493       behaves essentially like the above function.
494

const_iterator QValueList::fromLast () const

496       Returns an iterator to the last item in the list, or end() if there is
497       no last item.
498
499       Use the end() function instead. For example:
500
501           QValueList<int> l;
502           ...
503           QValueList<int>::iterator it = l.end();
504           --it;
505           if ( it != end() )
506               // ...
507

iterator QValueList::fromLast ()

509       This is an overloaded member function, provided for convenience. It
510       behaves essentially like the above function.
511
512       Returns an iterator to the last item in the list, or end() if there is
513       no last item.
514
515       Use the end() function instead. For example:
516
517           QValueList<int> l;
518           ...
519           QValueList<int>::iterator it = l.end();
520           --it;
521           if ( it != end() )
522               // ...
523

reference QValueList::front ()

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
528       This function is provided for STL compatibility. It is equivalent to
529       first().
530
531       See also back().
532

const_reference QValueList::front () const

534       This is an overloaded member function, provided for convenience. It
535       behaves essentially like the above function.
536

iterator QValueList::insert ( iterator it, const T & x )

538       Inserts the value x in front of the item pointed to by the iterator,
539       it.
540
541       Returns an iterator pointing at the inserted item.
542
543       See also append() and prepend().
544
545       Example: themes/themes.cpp.
546

void QValueList::insert ( iterator pos, size_type n, const T & x )

548       This is an overloaded member function, provided for convenience. It
549       behaves essentially like the above function.
550
551       Inserts n copies of x before position pos.
552

bool QValueList::isEmpty () const

554       Returns TRUE if the list contains no items; otherwise returns FALSE.
555
556       See also count().
557
558       Examples:
559

T & QValueList::last ()

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

const T & QValueList::last () const

565       This is an overloaded member function, provided for convenience. It
566       behaves essentially like the above function.
567

bool QValueList::operator!= ( const QValueList<T> & l ) const

569       Compares both lists.
570
571       Returns TRUE if this list and l are unequal; otherwise returns FALSE.
572

QValueList<T> QValueList::operator+ ( const QValueList<T> & l ) const

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

QValueList<T> & QValueList::operator+= ( const QValueList<T> & l )

578       Appends the items of l to this list. Returns a reference to this list.
579

QValueList<T> & QValueList::operator+= ( const T & x )

581       This is an overloaded member function, provided for convenience. It
582       behaves essentially like the above function.
583
584       Appends the value x to the list. Returns a reference to the list.
585

QValueList<T> & QValueList::operator<< ( const T & x )

587       Adds the value x to the end of the list.
588
589       Returns a reference to the list.
590

QValueList<T> & QValueList::operator= ( const QValueList<T> & l )

592       Assigns l to this list and returns a reference to this list.
593
594       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

QValueList<T> & QValueList::operator= ( const std::list<T> & l )

599       This is an overloaded member function, provided for convenience. It
600       behaves essentially like the above function.
601
602       Assigns the contents of l to the list.
603
604       All iterators of the current list become invalidated by this operation.
605

bool QValueList::operator== ( const QValueList<T> & l ) const

607       Compares both lists.
608
609       Returns TRUE if this list and l are equal; otherwise returns FALSE.
610

bool QValueList::operator== ( const std::list<T> & l ) const

612       This is an overloaded member function, provided for convenience. It
613       behaves essentially like the above function.
614
615       Returns TRUE if this list and l are equal; otherwise returns FALSE.
616
617       This operator is provided for compatibility with STL containers.
618

const T & QValueList::operator[] ( size_type i ) const

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
626       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

T & QValueList::operator[] ( size_type i )

631       This is an overloaded member function, provided for convenience. It
632       behaves essentially like the above function.
633
634       Returns a non-const reference to the item with index i.
635

void QValueList::pop_back ()

637       Removes the last item. If there is no last item, this operation is
638       undefined.
639
640       This function is provided for STL compatibility.
641

void QValueList::pop_front ()

643       Removes the first item. If there is no first item, this operation is
644       undefined.
645
646       This function is provided for STL compatibility.
647

iterator QValueList::prepend ( const T & x )

649       Inserts x at the beginning of the list.
650
651       See also insert() and append().
652

void QValueList::push_back ( const T & x )

654       Inserts x at the end of the list.
655
656       This function is provided for STL compatibility. It is equivalent to
657       append().
658

void QValueList::push_front ( const T & x )

660       Inserts x at the beginning of the list.
661
662       This function is provided for STL compatibility. It is equivalent to
663       prepend().
664
665       Example: toplevel/options.ui.h.
666

iterator QValueList::remove ( iterator it )

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
673       See also clear().
674

uint QValueList::remove ( const T & x )

676       This is an overloaded member function, provided for convenience. It
677       behaves essentially like the above function.
678
679       Removes all items that have value x and returns the number of removed
680       items.
681

size_type QValueList::size () const

683       Returns the number of items in the list.
684
685       This function is provided for STL compatibility. It is equivalent to
686       count().
687
688       See also empty().
689

QDataStream & operator<< ( QDataStream & s, const QValueList<T> & l )

692       This is an overloaded member function, provided for convenience. It
693       behaves essentially like the above function.
694
695       Writes a list, l, to the stream s. The type T stored in the list must
696       implement the streaming operator.
697

QDataStream & operator>> ( QDataStream & s, QValueList<T> & l )

699       Reads a list, l, from the stream s. The type T stored in the list must
700       implement the streaming operator.
701
702

SEE ALSO

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

AUTHOR

713       Generated automatically from the source code.
714

BUGS

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
720       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
726       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).
729
730
731
732Trolltech AS                    2 February 2007                QValueList(3qt)
Impressum