Context Navigation

qvaluelist.html

Last change on this file was 190, checked in by rudi, 14 years ago
reference documentation added
File size: 41.4 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2	<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qvaluelist.doc:41 -->
3	<html>
4	<head>
5	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6	<title>QValueList Class</title>
7	<style type="text/css"><!--
8	fn { margin-left: 1cm; text-indent: -1cm; }
9	a:link { color: #004faf; text-decoration: none }
10	a:visited { color: #672967; text-decoration: none }
11	body { background: #ffffff; color: black; }
12	--></style>
13	</head>
14	<body>
15
16	<table border="0" cellpadding="0" cellspacing="0" width="100%">
17	<tr bgcolor="#E5E5E5">
18	<td valign=center>
19	<a href="index.html">
20	<font color="#004faf">Home</font></a>
21	\| <a href="classes.html">
22	<font color="#004faf">All Classes</font></a>
23	\| <a href="mainclasses.html">
24	<font color="#004faf">Main Classes</font></a>
25	\| <a href="annotated.html">
26	<font color="#004faf">Annotated</font></a>
27	\| <a href="groups.html">
28	<font color="#004faf">Grouped Classes</font></a>
29	\| <a href="functions.html">
30	<font color="#004faf">Functions</font></a>
31	</td>
32	<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QValueList Class Reference</h1>
33
34	<p>The QValueList class is a value-based template class that
35	provides lists.
36	<a href="#details">More...</a>
37	<p>All the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support.</p>
38	<p><tt>#include <<a href="qvaluelist-h.html">qvaluelist.h</a>></tt>
39	<p>Inherited by <a href="qcanvasitemlist.html">QCanvasItemList</a>, <a href="qstringlist.html">QStringList</a>, and <a href="qvaluestack.html">QValueStack</a>.
40	<p><a href="qvaluelist-members.html">List of all member functions.</a>
41	<h2>Public Members</h2>
42	<ul>
43	<li class=fn>typedef QValueListIterator<T> <a href="#iterator"><b>iterator</b></a></li>
44	<li class=fn>typedef QValueListConstIterator<T> <a href="#const_iterator"><b>const_iterator</b></a></li>
45	<li class=fn>typedef T <a href="#value_type"><b>value_type</b></a></li>
46	<li class=fn>typedef value_type * <a href="#pointer"><b>pointer</b></a></li>
47	<li class=fn>typedef const value_type * <a href="#const_pointer"><b>const_pointer</b></a></li>
48	<li class=fn>typedef value_type & <a href="#reference"><b>reference</b></a></li>
49	<li class=fn>typedef const value_type & <a href="#const_reference"><b>const_reference</b></a></li>
50	<li class=fn>typedef size_t <a href="#size_type"><b>size_type</b></a></li>
51	<li class=fn><a href="#QValueList"><b>QValueList</b></a> ()</li>
52	<li class=fn><a href="#QValueList-2"><b>QValueList</b></a> ( const QValueList<T> & l )</li>
53	<li class=fn><a href="#QValueList-3"><b>QValueList</b></a> ( const std::list<T> & l )</li>
54	<li class=fn><a href="#~QValueList"><b>~QValueList</b></a> ()</li>
55	<li class=fn>QValueList<T> & <a href="#operator-eq"><b>operator=</b></a> ( const QValueList<T> & l )</li>
56	<li class=fn>QValueList<T> & <a href="#operator-eq-2"><b>operator=</b></a> ( const std::list<T> & l )</li>
57	<li class=fn>bool <a href="#operator-eq-eq-2"><b>operator==</b></a> ( const std::list<T> & l ) const</li>
58	<li class=fn>bool <a href="#operator-eq-eq"><b>operator==</b></a> ( const QValueList<T> & l ) const</li>
59	<li class=fn>bool <a href="#operator!-eq"><b>operator!=</b></a> ( const QValueList<T> & l ) const</li>
60	<li class=fn>iterator <a href="#begin-2"><b>begin</b></a> ()</li>
61	<li class=fn>const_iterator <a href="#begin"><b>begin</b></a> () const</li>
62	<li class=fn>const_iterator <a href="#constBegin"><b>constBegin</b></a> () const</li>
63	<li class=fn>iterator <a href="#end"><b>end</b></a> ()</li>
64	<li class=fn>const_iterator <a href="#end-2"><b>end</b></a> () const</li>
65	<li class=fn>const_iterator <a href="#constEnd"><b>constEnd</b></a> () const</li>
66	<li class=fn>iterator <a href="#insert"><b>insert</b></a> ( iterator it, const T & x )</li>
67	<li class=fn>uint <a href="#remove-2"><b>remove</b></a> ( const T & x )</li>
68	<li class=fn>void <a href="#clear"><b>clear</b></a> ()</li>
69	<li class=fn>QValueList<T> & <a href="#operator-lt-lt"><b>operator<<</b></a> ( const T & x )</li>
70	<li class=fn>size_type <a href="#size"><b>size</b></a> () const</li>
71	<li class=fn>bool <a href="#empty"><b>empty</b></a> () const</li>
72	<li class=fn>void <a href="#push_front"><b>push_front</b></a> ( const T & x )</li>
73	<li class=fn>void <a href="#push_back"><b>push_back</b></a> ( const T & x )</li>
74	<li class=fn>iterator <a href="#erase"><b>erase</b></a> ( iterator it )</li>
75	<li class=fn>iterator <a href="#erase-2"><b>erase</b></a> ( iterator first, iterator last )</li>
76	<li class=fn>reference <a href="#front"><b>front</b></a> ()</li>
77	<li class=fn>const_reference <a href="#front-2"><b>front</b></a> () const</li>
78	<li class=fn>reference <a href="#back"><b>back</b></a> ()</li>
79	<li class=fn>const_reference <a href="#back-2"><b>back</b></a> () const</li>
80	<li class=fn>void <a href="#pop_front"><b>pop_front</b></a> ()</li>
81	<li class=fn>void <a href="#pop_back"><b>pop_back</b></a> ()</li>
82	<li class=fn>void <a href="#insert-2"><b>insert</b></a> ( iterator pos, size_type n, const T & x )</li>
83	<li class=fn>QValueList<T> <a href="#operator+"><b>operator+</b></a> ( const QValueList<T> & l ) const</li>
84	<li class=fn>QValueList<T> & <a href="#operator+-eq"><b>operator+=</b></a> ( const QValueList<T> & l )</li>
85	<li class=fn>iterator <a href="#fromLast-2"><b>fromLast</b></a> ()</li>
86	<li class=fn>const_iterator <a href="#fromLast"><b>fromLast</b></a> () const</li>
87	<li class=fn>bool <a href="#isEmpty"><b>isEmpty</b></a> () const</li>
88	<li class=fn>iterator <a href="#append"><b>append</b></a> ( const T & x )</li>
89	<li class=fn>iterator <a href="#prepend"><b>prepend</b></a> ( const T & x )</li>
90	<li class=fn>iterator <a href="#remove"><b>remove</b></a> ( iterator it )</li>
91	<li class=fn>T & <a href="#first"><b>first</b></a> ()</li>
92	<li class=fn>const T & <a href="#first-2"><b>first</b></a> () const</li>
93	<li class=fn>T & <a href="#last"><b>last</b></a> ()</li>
94	<li class=fn>const T & <a href="#last-2"><b>last</b></a> () const</li>
95	<li class=fn>T & <a href="#operator[]-2"><b>operator[]</b></a> ( size_type i )</li>
96	<li class=fn>const T & <a href="#operator[]"><b>operator[]</b></a> ( size_type i ) const</li>
97	<li class=fn>iterator <a href="#at-2"><b>at</b></a> ( size_type i )</li>
98	<li class=fn>const_iterator <a href="#at"><b>at</b></a> ( size_type i ) const</li>
99	<li class=fn>iterator <a href="#find"><b>find</b></a> ( const T & x )</li>
100	<li class=fn>const_iterator <a href="#find-2"><b>find</b></a> ( const T & x ) const</li>
101	<li class=fn>iterator <a href="#find-3"><b>find</b></a> ( iterator it, const T & x )</li>
102	<li class=fn>const_iterator <a href="#find-4"><b>find</b></a> ( const_iterator it, const T & x ) const</li>
103	<li class=fn>int <a href="#findIndex"><b>findIndex</b></a> ( const T & x ) const</li>
104	<li class=fn>size_type <a href="#contains"><b>contains</b></a> ( const T & x ) const</li>
105	<li class=fn>size_type <a href="#count"><b>count</b></a> () const</li>
106	<li class=fn>QValueList<T> & <a href="#operator+-eq-2"><b>operator+=</b></a> ( const T & x )</li>
107	<li class=fn>typedef QValueListIterator<T> <a href="#Iterator"><b>Iterator</b></a></li>
108	<li class=fn>typedef QValueListConstIterator<T> <a href="#ConstIterator"><b>ConstIterator</b></a></li>
109	</ul>
110	<h2>Related Functions</h2>
111	<ul>
112	<li class=fn>QDataStream & <a href="#operator-gt-gt"><b>operator>></b></a> ( QDataStream & s, QValueList<T> & l )</li>
113	<li class=fn>QDataStream & <a href="#operator-lt-lt-2"><b>operator<<</b></a> ( QDataStream & s, const QValueList<T> & l )</li>
114	</ul>
115	<hr><a name="details"></a><h2>Detailed Description</h2>
116
117
118	The QValueList class is a value-based template class that
119	provides lists.
120	<p>
121
122
123
124
125	<p> QValueList is a Qt implementation of an STL-like list container.
126	It can be used in your application if the standard <tt>list</tt> is not
127	available for your target platform(s). QValueList is part of the
128	<a href="qtl.html">Qt Template Library</a>.
129	<p> QValueList<T> defines a template instance to create a list of
130	values that all have the class T. Note that QValueList does not
131	store pointers to the members of the list; it holds a copy of
132	every member. This is why these kinds of classes are called "value
133	based"; <a href="qptrlist.html">QPtrList</a> and <a href="qdict.html">QDict</a> are "pointer based".
134	<p> QValueList contains and manages a collection of objects of type T
135	and provides iterators that allow the contained objects to be
136	addressed. QValueList owns the contained items. For more relaxed
137	ownership semantics, see <a href="qptrcollection.html">QPtrCollection</a> and friends which are
138	pointer-based containers.
139	<p> Some classes cannot be used within a QValueList, for example, all
140	classes derived from <a href="qobject.html">QObject</a> and thus all classes that implement
141	widgets. Only values can be used in a QValueList. To qualify as a
142	value the class must provide:
143	<ul>
144	<li> a copy constructor;
145	<li> an assignment operator;
146	<li> a default constructor, i.e. a constructor that does not take any arguments.
147	</ul>
148	<p> Note that C++ defaults to field-by-field assignment operators and
149	copy constructors if no explicit version is supplied. In many
150	cases this is sufficient.
151	<p> In addition, some compilers (e.g. Sun CC) might require that the
152	class provides an equality operator (<a href="#operator-eq-eq">operator==</a>()).
153	<p> QValueList's function naming is consistent with the other Qt
154	classes (e.g. <a href="#count">count</a>(), <a href="#isEmpty">isEmpty</a>()). QValueList also provides extra
155	functions for compatibility with STL algorithms, such as <a href="#size">size</a>()
156	and <a href="#empty">empty</a>(). Programmers already familiar with the STL <tt>list</tt> may
157	prefer to use the STL-compatible functions.
158	<p> Example:
159	<pre>
160	class Employee
161	{
162	public:
163	Employee(): sn(0) {}
164	Employee( const <a href="qstring.html">QString</a>& forename, const <a href="qstring.html">QString</a>& surname, int salary )
165	: fn(forename), sn(surname), sal(salary)
166	{}
167
168	<a href="qstring.html">QString</a> forename() const { return fn; }
169	<a href="qstring.html">QString</a> surname() const { return sn; }
170	int salary() const { return sal; }
171	void setSalary( int salary ) { sal = salary; }
172
173	private:
174	<a href="qstring.html">QString</a> fn;
175	<a href="qstring.html">QString</a> sn;
176	int sal;
177	};
178
179	typedef QValueList<Employee> EmployeeList;
180	EmployeeList list;
181
182	list.append( Employee("John", "Doe", 50000) );
183	list.append( Employee("Jane", "Williams", 80000) );
184	list.append( Employee("Tom", "Jones", 60000) );
185
186	Employee mary( "Mary", "Hawthorne", 90000 );
187	list.append( mary );
188	mary.setSalary( 100000 );
189
190	EmployeeList::<a href="#iterator">iterator</a> it;
191	for ( it = list.begin(); it != list.end(); ++it )
192	cout << (*it).surname().latin1() << ", " <<
193	(*it).forename().latin1() << " earns " <<
194	(*it).salary() << endl;
195
196	// Output:
197	// Doe, John earns 50000
198	// Williams, Jane earns 80000
199	// Hawthorne, Mary earns 90000
200	// Jones, Tom earns 60000
201	</pre>
202
203	<p> Notice that the latest changes to Mary's salary did not affect the
204	value in the list because the list created a copy of Mary's entry.
205	<p> There are several ways to find items in the list. The <a href="#begin">begin</a>() and
206	<a href="#end">end</a>() functions return iterators to the beginning and end of the
207	list. The advantage of getting an iterator is that you can move
208	forward or backward from this position by
209	incrementing/decrementing the iterator. The iterator returned by
210	end() points to the item which is one <em>past</em> the last item in the
211	container. The past-the-end iterator is still associated with the
212	list it belongs to, however it is <em>not</em> dereferenceable;
213	<a href="qsize.html#operator-4">operator</a>() will not return a well-defined value. If the list is
214	<a href="#empty">empty</a>(), the iterator returned by begin() will equal the iterator
215	returned by end().
216	<p> Another way to find an item in the list is by using the <a href="qtl.html#qFind">qFind()</a> algorithm. For example:
217	<p> <pre>
218	QValueList<int> list;
219	...
220	QValueList<int>::<a href="#iterator">iterator</a> it = qFind( list.<a href="#begin">begin</a>(), list.<a href="#end">end</a>(), 3 );
221	if ( it != list.<a href="#end">end</a>() )
222	// it points to the found item
223	</pre>
224
225	<p> It is safe to have multiple iterators a the list at the same
226	time. If some member of the list is removed, only iterators
227	pointing to the removed member become invalid. Inserting into the
228	list does not invalidate any iterator. For convenience, the
229	function <a href="#last">last</a>() returns a reference to the last item in the list,
230	and <a href="#first">first</a>() returns a reference to the the first item. If the
231	list is empty(), both last() and first() have undefined behavior
232	(your application will crash or do unpredictable things). Use
233	last() and first() with caution, for example:
234	<p> <pre>
235	QValueList<int> list;
236	list.<a href="#append">append</a>( 1 );
237	list.<a href="#append">append</a>( 2 );
238	list.<a href="#append">append</a>( 3 );
239	...
240	if ( !list.<a href="#empty">empty</a>() ) {
241	// OK, modify the first item
242	int& i = list.<a href="#first">first</a>();
243	i = 18;
244	}
245	...
246	QValueList<double> dlist;
247	double d = dlist.<a href="#last">last</a>(); // undefined
248	</pre>
249
250	<p> Because QValueList is value-based there is no need to be careful
251	about deleting items in the list. The list holds its own copies
252	and will free them if the corresponding member or the list itself
253	is deleted. You can force the list to free all of its items with
254	<a href="#clear">clear</a>().
255	<p> QValueList is <a href="shclass.html#shared-implicitly">shared implicitly</a>, which means it can be copied in
256	constant time, i.e. O(1). If multiple QValueList instances share
257	the same data and one needs to modify its contents, this modifying
258	instance makes a copy and modifies its private copy; therefore it
259	does not affect the other instances; this takes O(n) time. This is
260	often called "copy on write". If a QValueList is being used in a
261	multi-threaded program, you must protect all access to the list.
262	See <a href="qmutex.html">QMutex</a>.
263	<p> There are several ways to insert items into the list. The
264	<a href="#prepend">prepend</a>() and <a href="#append">append</a>() functions insert items at the beginning and
265	the end of the list respectively. The <a href="#insert">insert</a>() function comes in
266	several flavors and can be used to add one or more items at
267	specific positions within the list.
268	<p> Items can also be removed from the list in several ways. There
269	are several variants of the <a href="#remove">remove</a>() function, which removes a
270	specific item from the list. The remove() function will find and
271	remove items according to a specific item value.
272	<p> Lists can also be sorted using the <a href="qtl.html">Qt Template
273	Library</a>. For example with qHeapSort():
274	<p> Example:
275	<pre>
276	QValueList<int> list;
277	list.<a href="#append">append</a>( 5 );
278	list.<a href="#append">append</a>( 8 );
279	list.<a href="#append">append</a>( 3 );
280	list.<a href="#append">append</a>( 4 );
281	qHeapSort( list );
282	</pre>
283
284	<p> <p>See also <a href="qvaluelistiterator.html">QValueListIterator</a>, <a href="qtl.html">Qt Template Library Classes</a>, <a href="shared.html">Implicitly and Explicitly Shared Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
285
286	<hr><h2>Member Type Documentation</h2>
287	<h3 class=fn><a name="ConstIterator"></a>QValueList::ConstIterator</h3>
288
289	<p> This iterator is an instantiation of <a href="qvaluelistconstiterator.html">QValueListConstIterator</a> for
290	the same type as this QValueList. In other words, if you
291	instantiate QValueList<int>, ConstIterator is a
292	QValueListConstIterator<int>. Several member function use it, such
293	as <a href="#begin">QValueList::begin</a>(), which returns an iterator pointing to the
294	first item in the list.
295	<p> Functionally, this is almost the same as Iterator. The only
296	difference is you cannot use ConstIterator for non-const
297	operations, and that the compiler can often generate better code
298	if you use ConstIterator.
299	<p> <p>See also <a href="qvaluelistiterator.html">QValueListIterator</a> and <a href="#Iterator">Iterator</a>.
300
301	<h3 class=fn><a name="Iterator"></a>QValueList::Iterator</h3>
302
303	<p> This iterator is an instantiation of <a href="qvaluelistiterator.html">QValueListIterator</a> for the
304	same type as this QValueList. In other words, if you instantiate
305	QValueList<int>, Iterator is a QValueListIterator<int>. Several
306	member function use it, such as <a href="#begin">QValueList::begin</a>(), which returns
307	an iterator pointing to the first item in the list.
308	<p> Functionally, this is almost the same as ConstIterator. The only
309	difference is that you cannot use ConstIterator for non-const
310	operations, and that the compiler can often generate better code
311	if you use ConstIterator.
312	<p> <p>See also <a href="qvaluelistiterator.html">QValueListIterator</a> and <a href="#ConstIterator">ConstIterator</a>.
313
314	<h3 class=fn><a name="const_iterator"></a>QValueList::const_iterator</h3>
315	The list's const iterator type, <a href="qvaluelistconstiterator.html">QValueListConstIterator</a>.
316	<h3 class=fn><a name="const_pointer"></a>QValueList::const_pointer</h3>
317	The const pointer to T type.
318	<h3 class=fn><a name="const_reference"></a>QValueList::const_reference</h3>
319	The const reference to T type.
320	<h3 class=fn><a name="iterator"></a>QValueList::iterator</h3>
321	The list's iterator type, <a href="qvaluelistiterator.html">QValueListIterator</a>.
322	<h3 class=fn><a name="pointer"></a>QValueList::pointer</h3>
323	The pointer to T type.
324	<h3 class=fn><a name="reference"></a>QValueList::reference</h3>
325	The reference to T type.
326	<h3 class=fn><a name="size_type"></a>QValueList::size_type</h3>
327	An unsigned integral type, used to represent various sizes.
328	<h3 class=fn><a name="value_type"></a>QValueList::value_type</h3>
329	The type of the object stored in the list, T.
330	<hr><h2>Member Function Documentation</h2>
331	<h3 class=fn><a name="QValueList"></a>QValueList::QValueList ()
332	</h3>
333
334	<p> Constructs an empty list.
335
336	<h3 class=fn><a name="QValueList-2"></a>QValueList::QValueList ( const <a href="qvaluelist.html">QValueList</a><T> & l )
337	</h3>
338
339	<p> Constructs a copy of <em>l</em>.
340	<p> This operation takes O(1) time because QValueList is <a href="shclass.html#implicitly-shared">implicitly shared</a>.
341	<p> The first modification to a list will take O(n) time.
342
343	<h3 class=fn><a name="QValueList-3"></a>QValueList::QValueList ( const std::list<T> & l )
344	</h3>
345
346	<p> Contructs a copy of <em>l</em>.
347	<p> This constructor is provided for compatibility with STL
348	containers.
349
350	<h3 class=fn><a name="~QValueList"></a>QValueList::~QValueList ()
351	</h3>
352
353	<p> Destroys the list. References to the values in the list and all
354	iterators of this list become invalidated. Note that it is
355	impossible for an iterator to check whether or not it is valid:
356	QValueList is highly tuned for performance, not for error
357	checking.
358
359	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="append"></a>QValueList::append ( const T & x )
360	</h3>
361
362	<p> Inserts <em>x</em> at the end of the list.
363	<p> <p>See also <a href="#insert">insert</a>() and <a href="#prepend">prepend</a>().
364
365	<p>Examples: <a href="checklists-example.html#x434">checklists/checklists.cpp</a> and <a href="simple-font-demo-example.html#x2853">fonts/simple-qfont-demo/viewer.cpp</a>.
366	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="at"></a>QValueList::at ( <a href="qvaluelist.html#size_type">size_type</a> i ) const
367	</h3>
368
369	<p> Returns an iterator pointing to the item at position <em>i</em> in the
370	list, or an undefined value if the index is out of range.
371	<p> <b>Warning:</b> This function uses a linear search and can be extremely
372	slow for large lists. QValueList is not optimized for random item
373	access. If you need random access use a different container, such
374	as <a href="qvaluevector.html">QValueVector</a>.
375
376	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="at-2"></a>QValueList::at ( <a href="qvaluelist.html#size_type">size_type</a> i )
377	</h3>
378
379	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
380	<p> Returns an iterator pointing to the item at position <em>i</em> in the
381	list, or an undefined value if the index is out of range.
382	<p>
383	<h3 class=fn><a href="qvaluelist.html#reference">reference</a> <a name="back"></a>QValueList::back ()
384	</h3>
385
386	<p> Returns a reference to the last item. If the list contains no last
387	item (i.e. <a href="#empty">empty</a>() returns TRUE), the return value is undefined.
388	<p> This function is provided for STL compatibility. It is equivalent
389	to <a href="#last">last</a>().
390	<p> <p>See also <a href="#front">front</a>().
391
392	<h3 class=fn><a href="qvaluelist.html#const_reference">const_reference</a> <a name="back-2"></a>QValueList::back () const
393	</h3>
394
395	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
396	<p>
397	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="begin"></a>QValueList::begin () const
398	</h3>
399
400	<p> Returns an iterator pointing to the first item in the list. This
401	iterator equals <a href="#end">end</a>() if the list is empty.
402	<p> <p>See also <a href="#first">first</a>(), <a href="#end">end</a>(), and <a href="#constBegin">constBegin</a>().
403
404	<p>Examples: <a href="canvas-example.html#x2952">canvas/canvas.cpp</a>, <a href="tutorial2-06.html#x2588">chart/canvasview.cpp</a>, <a href="tutorial2-03.html#x2554">chart/element.cpp</a>, <a href="checklists-example.html#x435">checklists/checklists.cpp</a>, <a href="sql.html#x2197">sql/overview/insert/main.cpp</a>, <a href="statistics-example.html#x2789">table/statistics/statistics.cpp</a>, and <a href="themes-example.html#x344">themes/themes.cpp</a>.
405	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="begin-2"></a>QValueList::begin ()
406	</h3>
407
408	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
409	<p> Returns an iterator pointing to the first item in the list. This
410	iterator equals <a href="#end">end</a>() if the list is empty.
411	<p> <p>See also <a href="#first">first</a>() and <a href="#end">end</a>().
412
413	<h3 class=fn>void <a name="clear"></a>QValueList::clear ()
414	</h3>
415
416	<p> Removes all items from the list.
417	<p> <p>See also <a href="#remove">remove</a>().
418
419	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="constBegin"></a>QValueList::constBegin () const
420	</h3>
421
422	<p> Returns an iterator pointing to the first item in the list. This
423	iterator equals <a href="#constEnd">constEnd</a>() if the list is empty.
424	<p> <p>See also <a href="#begin">begin</a>().
425
426	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="constEnd"></a>QValueList::constEnd () const
427	</h3>
428
429	<p> Returns an iterator pointing <em>past</em> the last item in the list.
430	This iterator equals <a href="#constBegin">constBegin</a>() if the list is empty.
431	<p> <p>See also <a href="#end">end</a>().
432
433	<h3 class=fn><a href="qvaluelist.html#size_type">size_type</a> <a name="contains"></a>QValueList::contains ( const T & x ) const
434	</h3>
435
436	<p> Returns the number of occurrences of the value <em>x</em> in the list.
437
438	<h3 class=fn><a href="qvaluelist.html#size_type">size_type</a> <a name="count"></a>QValueList::count () const
439	</h3>
440
441	<p> Returns the number of items in the list.
442	<p> <p>See also <a href="#isEmpty">isEmpty</a>().
443
444	<p>Examples: <a href="tutorial2-03.html#x2555">chart/element.cpp</a>, <a href="fileiconview-example.html#x874">fileiconview/qfileiconview.cpp</a>, and <a href="statistics-example.html#x2790">table/statistics/statistics.cpp</a>.
445	<h3 class=fn>bool <a name="empty"></a>QValueList::empty () const
446	</h3>
447
448	<p> Returns TRUE if the list contains no items; otherwise returns
449	FALSE.
450	<p> <p>See also <a href="#size">size</a>().
451
452	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="end"></a>QValueList::end ()
453	</h3>
454
455	<p> Returns an iterator pointing <em>past</em> the last item in the list.
456	This iterator equals <a href="#begin">begin</a>() if the list is empty.
457	<p> <p>See also <a href="#last">last</a>(), <a href="#begin">begin</a>(), and <a href="#constEnd">constEnd</a>().
458
459	<p>Examples: <a href="canvas-example.html#x2953">canvas/canvas.cpp</a>, <a href="tutorial2-06.html#x2589">chart/canvasview.cpp</a>, <a href="tutorial2-03.html#x2556">chart/element.cpp</a>, <a href="checklists-example.html#x436">checklists/checklists.cpp</a>, <a href="sql.html#x2198">sql/overview/insert/main.cpp</a>, <a href="statistics-example.html#x2791">table/statistics/statistics.cpp</a>, and <a href="themes-example.html#x345">themes/themes.cpp</a>.
460	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="end-2"></a>QValueList::end () const
461	</h3>
462
463	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
464	<p> Returns an iterator pointing <em>past</em> the last item in the list.
465	This iterator equals <a href="#begin">begin</a>() if the list is empty.
466	<p> <p>See also <a href="#last">last</a>() and <a href="#begin">begin</a>().
467
468	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="erase"></a>QValueList::erase ( <a href="qvaluelist.html#iterator">iterator</a> it )
469	</h3>
470
471	<p> Removes the item pointed to by <em>it</em> from the list. No iterators
472	other than <em>it</em> or other iterators pointing at the same item as
473	<em>it</em> are invalidated. Returns an iterator to the next item after
474	<em>it</em>, or <a href="#end">end</a>() if there is no such item.
475	<p> This function is provided for STL compatibility. It is equivalent
476	to <a href="#remove">remove</a>().
477
478	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="erase-2"></a>QValueList::erase ( <a href="qvaluelist.html#iterator">iterator</a> first, <a href="qvaluelist.html#iterator">iterator</a> last )
479	</h3>
480
481	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
482	<p> Deletes all items from <em>first</em> to <em>last</em> (not including <em>last</em>). No iterators are invalidated, except those pointing to the
483	removed items themselves. Returns <em>last</em>.
484
485	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="find"></a>QValueList::find ( const T & x )
486	</h3>
487
488	<p> Returns an iterator pointing to the first occurrence of <em>x</em> in
489	the list.
490	<p> Returns <a href="#end">end</a>() is no item matched.
491
492	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="find-2"></a>QValueList::find ( const T & x ) const
493	</h3>
494
495	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
496	<p> Returns an iterator pointing to the first occurrence of <em>x</em> in
497	the list.
498	<p> Returns <a href="#end">end</a>() if no item matched.
499
500	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="find-3"></a>QValueList::find ( <a href="qvaluelist.html#iterator">iterator</a> it, const T & x )
501	</h3>
502
503	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
504	<p> Finds the first occurrence of <em>x</em> in the list starting at the
505	position given by <em>it</em>.
506	<p> Returns <a href="#end">end</a>() if no item matched.
507
508	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="find-4"></a>QValueList::find ( <a href="qvaluelist.html#const_iterator">const_iterator</a> it, const T & x ) const
509	</h3>
510
511	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
512	<p> Finds the first occurrence of <em>x</em> in the list starting at the
513	position given by <em>it</em>.
514	<p> Returns <a href="#end">end</a>() if no item matched.
515
516	<h3 class=fn>int <a name="findIndex"></a>QValueList::findIndex ( const T & x ) const
517	</h3>
518
519	<p> Returns the index of the first occurrence of the value <em>x</em>.
520	Returns -1 if no item matched.
521
522	<h3 class=fn>T & <a name="first"></a>QValueList::first ()
523	</h3>
524
525	<p> Returns a reference to the first item. If the list contains no
526	first item (i.e. <a href="#isEmpty">isEmpty</a>() returns TRUE), the return value is
527	undefined.
528	<p> <p>See also <a href="#last">last</a>().
529
530	<p>Example: <a href="mail-example.html#x719">network/mail/smtp.cpp</a>.
531	<h3 class=fn>const T & <a name="first-2"></a>QValueList::first () const
532	</h3>
533
534	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
535	<p>
536	<h3 class=fn><a href="qvaluelist.html#const_iterator">const_iterator</a> <a name="fromLast"></a>QValueList::fromLast () const
537	</h3>
538
539	<p> Returns an iterator to the last item in the list, or <a href="#end">end</a>() if
540	there is no last item.
541	<p> Use the end() function instead. For example:
542	<p> <pre>
543	QValueList<int> l;
544	...
545	QValueList<int>::<a href="#iterator">iterator</a> it = l.<a href="#end">end</a>();
546	--it;
547	if ( it != <a href="#end">end</a>() )
548	// ...
549	</pre>
550
551	<p>
552	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="fromLast-2"></a>QValueList::fromLast ()
553	</h3>
554
555	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
556	<p> Returns an iterator to the last item in the list, or <a href="#end">end</a>() if
557	there is no last item.
558	<p> Use the end() function instead. For example:
559	<p> <pre>
560	QValueList<int> l;
561	...
562	QValueList<int>::<a href="#iterator">iterator</a> it = l.<a href="#end">end</a>();
563	--it;
564	if ( it != <a href="#end">end</a>() )
565	// ...
566	</pre>
567
568	<p>
569	<h3 class=fn><a href="qvaluelist.html#reference">reference</a> <a name="front"></a>QValueList::front ()
570	</h3>
571
572	<p> Returns a reference to the first item. If the list contains no
573	first item (i.e. <a href="#empty">empty</a>() returns TRUE), the return value is
574	undefined.
575	<p> This function is provided for STL compatibility. It is equivalent
576	to <a href="#first">first</a>().
577	<p> <p>See also <a href="#back">back</a>().
578
579	<h3 class=fn><a href="qvaluelist.html#const_reference">const_reference</a> <a name="front-2"></a>QValueList::front () const
580	</h3>
581
582	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
583	<p>
584	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="insert"></a>QValueList::insert ( <a href="qvaluelist.html#iterator">iterator</a> it, const T & x )
585	</h3>
586
587	<p> Inserts the value <em>x</em> in front of the item pointed to by the
588	iterator, <em>it</em>.
589	<p> Returns an iterator pointing at the inserted item.
590	<p> <p>See also <a href="#append">append</a>() and <a href="#prepend">prepend</a>().
591
592	<p>Example: <a href="themes-example.html#x346">themes/themes.cpp</a>.
593	<h3 class=fn>void <a name="insert-2"></a>QValueList::insert ( <a href="qvaluelist.html#iterator">iterator</a> pos, <a href="qvaluelist.html#size_type">size_type</a> n, const T & x )
594	</h3>
595
596	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
597	<p> Inserts <em>n</em> copies of <em>x</em> before position <em>pos</em>.
598
599	<h3 class=fn>bool <a name="isEmpty"></a>QValueList::isEmpty () const
600	</h3>
601
602	<p> Returns TRUE if the list contains no items; otherwise returns
603	FALSE.
604	<p> <p>See also <a href="#count">count</a>().
605
606	<p>Examples: <a href="simple-font-demo-example.html#x2856">fonts/simple-qfont-demo/viewer.cpp</a> and <a href="mail-example.html#x720">network/mail/smtp.cpp</a>.
607	<h3 class=fn>T & <a name="last"></a>QValueList::last ()
608	</h3>
609
610	<p> Returns a reference to the last item. If the list contains no last
611	item (i.e. <a href="#empty">empty</a>() returns TRUE), the return value is undefined.
612
613	<h3 class=fn>const T & <a name="last-2"></a>QValueList::last () const
614	</h3>
615
616	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
617	<p>
618	<h3 class=fn>bool <a name="operator!-eq"></a>QValueList::operator!= ( const <a href="qvaluelist.html">QValueList</a><T> & l ) const
619	</h3>
620
621	<p> Compares both lists.
622	<p> Returns TRUE if this list and <em>l</em> are unequal; otherwise returns
623	FALSE.
624
625	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> <a name="operator+"></a>QValueList::operator+ ( const <a href="qvaluelist.html">QValueList</a><T> & l ) const
626	</h3>
627
628	<p> Creates a new list and fills it with the items of this list. Then
629	the items of <em>l</em> are appended. Returns the new list.
630
631	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> & <a name="operator+-eq"></a>QValueList::operator+= ( const <a href="qvaluelist.html">QValueList</a><T> & l )
632	</h3>
633
634	<p> Appends the items of <em>l</em> to this list. Returns a reference to
635	this list.
636
637	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> & <a name="operator+-eq-2"></a>QValueList::operator+= ( const T & x )
638	</h3>
639
640	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
641	<p> Appends the value <em>x</em> to the list. Returns a reference to the
642	list.
643
644	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> & <a name="operator-lt-lt"></a>QValueList::operator<< ( const T & x )
645	</h3>
646
647	<p> Adds the value <em>x</em> to the end of the list.
648	<p> Returns a reference to the list.
649
650	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> & <a name="operator-eq"></a>QValueList::operator= ( const <a href="qvaluelist.html">QValueList</a><T> & l )
651	</h3>
652
653	<p> Assigns <em>l</em> to this list and returns a reference to this list.
654	<p> All iterators of the current list become invalidated by this
655	operation. The cost of such an assignment is O(1) since QValueList
656	is <a href="shclass.html#implicitly-shared">implicitly shared</a>.
657
658	<h3 class=fn><a href="qvaluelist.html">QValueList</a><T> & <a name="operator-eq-2"></a>QValueList::operator= ( const std::list<T> & l )
659	</h3>
660
661	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
662	<p> Assigns the contents of <em>l</em> to the list.
663	<p> All iterators of the current list become invalidated by this
664	operation.
665
666	<h3 class=fn>bool <a name="operator-eq-eq"></a>QValueList::operator== ( const <a href="qvaluelist.html">QValueList</a><T> & l ) const
667	</h3>
668
669	<p> Compares both lists.
670	<p> Returns TRUE if this list and <em>l</em> are equal; otherwise returns
671	FALSE.
672
673	<h3 class=fn>bool <a name="operator-eq-eq-2"></a>QValueList::operator== ( const std::list<T> & l ) const
674	</h3>
675
676	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
677	<p> Returns TRUE if this list and <em>l</em> are equal; otherwise returns
678	FALSE.
679	<p> This operator is provided for compatibility with STL containers.
680
681	<h3 class=fn>const T & <a name="operator[]"></a>QValueList::operator[] ( <a href="qvaluelist.html#size_type">size_type</a> i ) const
682	</h3>
683
684	<p> Returns a const reference to the item with index <em>i</em> in the list.
685	It is up to you to check whether this item really exists. You can
686	do that easily with the <a href="#count">count</a>() function. However this operator
687	does not check whether <em>i</em> is in range and will deliver undefined
688	results if it does not exist.
689	<p> <b>Warning:</b> This function uses a linear search and can be extremely
690	slow for large lists. QValueList is not optimized for random item
691	access. If you need random access use a different container, such
692	as <a href="qvaluevector.html">QValueVector</a>.
693
694	<h3 class=fn>T & <a name="operator[]-2"></a>QValueList::operator[] ( <a href="qvaluelist.html#size_type">size_type</a> i )
695	</h3>
696
697	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
698	<p> Returns a non-const reference to the item with index <em>i</em>.
699
700	<h3 class=fn>void <a name="pop_back"></a>QValueList::pop_back ()
701	</h3>
702
703	<p> Removes the last item. If there is no last item, this operation is
704	undefined.
705	<p> This function is provided for STL compatibility.
706
707	<h3 class=fn>void <a name="pop_front"></a>QValueList::pop_front ()
708	</h3>
709
710	<p> Removes the first item. If there is no first item, this operation
711	is undefined.
712	<p> This function is provided for STL compatibility.
713
714	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="prepend"></a>QValueList::prepend ( const T & x )
715	</h3>
716
717	<p> Inserts <em>x</em> at the beginning of the list.
718	<p> <p>See also <a href="#insert">insert</a>() and <a href="#append">append</a>().
719
720	<h3 class=fn>void <a name="push_back"></a>QValueList::push_back ( const T & x )
721	</h3>
722
723	<p> Inserts <em>x</em> at the end of the list.
724	<p> This function is provided for STL compatibility. It is equivalent
725	to <a href="#append">append</a>().
726
727	<h3 class=fn>void <a name="push_front"></a>QValueList::push_front ( const T & x )
728	</h3>
729
730	<p> Inserts <em>x</em> at the beginning of the list.
731	<p> This function is provided for STL compatibility. It is equivalent
732	to <a href="#prepend">prepend</a>().
733
734	<p>Example: <a href="toplevel-example.html#x2534">toplevel/options.ui.h</a>.
735	<h3 class=fn><a href="qvaluelist.html#iterator">iterator</a> <a name="remove"></a>QValueList::remove ( <a href="qvaluelist.html#iterator">iterator</a> it )
736	</h3>
737
738	<p> Removes the item pointed to by <em>it</em> from the list. No iterators
739	other than <em>it</em> or other iterators pointing at the same item as
740	<em>it</em> are invalidated. Returns an iterator to the next item after
741	<em>it</em>, or <a href="#end">end</a>() if there is no such item.
742	<p> <p>See also <a href="#clear">clear</a>().
743
744	<h3 class=fn>uint <a name="remove-2"></a>QValueList::remove ( const T & x )
745	</h3>
746
747	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
748	<p> Removes all items that have value <em>x</em> and returns the number of
749	removed items.
750
751	<h3 class=fn><a href="qvaluelist.html#size_type">size_type</a> <a name="size"></a>QValueList::size () const
752	</h3>
753
754	<p> Returns the number of items in the list.
755	<p> This function is provided for STL compatibility. It is equivalent
756	to <a href="#count">count</a>().
757	<p> <p>See also <a href="#empty">empty</a>().
758
759	<hr><h2>Related Functions</h2>
760	<h3 class=fn><a href="qdatastream.html">QDataStream</a> & <a name="operator-lt-lt-2"></a>operator<< ( <a href="qdatastream.html">QDataStream</a> & s, const <a href="qvaluelist.html">QValueList</a><T> & l )
761	</h3>
762
763	<p> This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
764	<p>
765	<p> Writes a list, <em>l</em>, to the stream <em>s</em>. The type T stored in the
766	list must implement the streaming operator.
767
768	<h3 class=fn><a href="qdatastream.html">QDataStream</a> & <a name="operator-gt-gt"></a>operator>> ( <a href="qdatastream.html">QDataStream</a> & s, <a href="qvaluelist.html">QValueList</a><T> & l )
769	</h3>
770
771	<p>
772	<p> Reads a list, <em>l</em>, from the stream <em>s</em>. The type T stored in the
773	list must implement the streaming operator.
774
775	<!-- eof -->
776	<hr><p>
777	This file is part of the <a href="index.html">Qt toolkit</a>.
778	Copyright © 1995-2007
779	<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
780	<table width=100% cellspacing=0 border=0><tr>
781	<td>Copyright © 2007
782	<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
783	<td align=right><div align=right>Qt 3.3.8</div>
784	</table></div></address></body>
785	</html>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/doc/html/qvaluelist.html

Download in other formats: