source: trunk/doc/html/qstringlist.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 16.6 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/src/tools/qstringlist.cpp:46 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QStringList Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { 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&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;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&nbsp;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>QStringList Class Reference</h1>
33
34<p>The QStringList class provides a list of strings.
35<a href="#details">More...</a>
36<p>All the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support.</p>
37<p><tt>#include &lt;<a href="qstringlist-h.html">qstringlist.h</a>&gt;</tt>
38<p>Inherits <a href="qvaluelist.html">QValueList</a>&lt;QString&gt;.
39<p><a href="qstringlist-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn><a href="#QStringList"><b>QStringList</b></a> ()</li>
43<li class=fn><a href="#QStringList-2"><b>QStringList</b></a> ( const&nbsp;QStringList&nbsp;&amp;&nbsp;l )</li>
44<li class=fn><a href="#QStringList-3"><b>QStringList</b></a> ( const&nbsp;QValueList&lt;QString&gt;&nbsp;&amp;&nbsp;l )</li>
45<li class=fn><a href="#QStringList-4"><b>QStringList</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;i )</li>
46<li class=fn><a href="#QStringList-5"><b>QStringList</b></a> ( const&nbsp;char&nbsp;*&nbsp;i )</li>
47<li class=fn>void <a href="#sort"><b>sort</b></a> ()</li>
48<li class=fn>QString <a href="#join"><b>join</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;sep ) const</li>
49<li class=fn>QStringList <a href="#grep"><b>grep</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;str, bool&nbsp;cs = TRUE ) const</li>
50<li class=fn>QStringList <a href="#grep-2"><b>grep</b></a> ( const&nbsp;QRegExp&nbsp;&amp;&nbsp;rx ) const</li>
51<li class=fn>QStringList &amp; <a href="#gres"><b>gres</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;before, const&nbsp;QString&nbsp;&amp;&nbsp;after, bool&nbsp;cs = TRUE )</li>
52<li class=fn>QStringList &amp; <a href="#gres-2"><b>gres</b></a> ( const&nbsp;QRegExp&nbsp;&amp;&nbsp;rx, const&nbsp;QString&nbsp;&amp;&nbsp;after )</li>
53</ul>
54<h2>Static Public Members</h2>
55<ul>
56<li class=fn>QStringList <a href="#fromStrList"><b>fromStrList</b></a> ( const&nbsp;QStrList&nbsp;&amp;&nbsp;ascii )</li>
57<li class=fn>QStringList <a href="#split-2"><b>split</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;sep, const&nbsp;QString&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )</li>
58<li class=fn>QStringList <a href="#split-3"><b>split</b></a> ( const&nbsp;QChar&nbsp;&amp;&nbsp;sep, const&nbsp;QString&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )</li>
59<li class=fn>QStringList <a href="#split"><b>split</b></a> ( const&nbsp;QRegExp&nbsp;&amp;&nbsp;sep, const&nbsp;QString&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )</li>
60</ul>
61<hr><a name="details"></a><h2>Detailed Description</h2>
62
63
64
65The QStringList class provides a list of strings.
66<p>
67
68
69
70<p> It is used to store and manipulate strings that logically belong
71together. Essentially QStringList is a <a href="qvaluelist.html">QValueList</a> of <a href="qstring.html">QString</a>
72objects. Unlike <a href="qstrlist.html">QStrList</a>, which stores pointers to characters,
73QStringList holds real QString objects. It is the class of choice
74whenever you work with Unicode strings. QStringList is part of the
75<a href="qtl.html">Qt Template Library</a>.
76<p> Like QString itself, QStringList objects are <a href="shclass.html#implicitly-shared">implicitly shared</a>, so
77passing them around as value-parameters is both fast and safe.
78<p> Strings can be added to a list using <a href="qvaluelist.html#append">append</a>(), <a href="qvaluelist.html#operator+-eq">operator+=</a>() or
79<a href="qvaluelist.html#operator-lt-lt">operator&lt;&lt;</a>(), e.g.
80<pre>
81 QStringList fonts;
82 fonts.<a href="qvaluelist.html#append">append</a>( "Times" );
83 fonts += "Courier";
84 fonts += "Courier New";
85 fonts &lt;&lt; "Helvetica [Cronyx]" &lt;&lt; "Helvetica [Adobe]";
86 </pre>
87
88<p> String lists have an iterator, QStringList::Iterator(), e.g.
89<pre>
90 for ( QStringList::<a href="qvaluelist.html#Iterator">Iterator</a> it = fonts.begin(); it != fonts.end(); ++it ) {
91 cout &lt;&lt; *it &lt;&lt; ":";
92 }
93 cout &lt;&lt; endl;
94 // Output:
95 // Times:Courier:Courier New:Helvetica [Cronyx]:Helvetica [Adobe]:
96 </pre>
97
98<p> Many Qt functions return string lists by value; to iterate over
99these you should make a copy and iterate over the copy.
100<p> You can concatenate all the strings in a string list into a single
101string (with an optional separator) using <a href="#join">join</a>(), e.g.
102<pre>
103 <a href="qstring.html">QString</a> allFonts = fonts.join( ", " );
104 cout &lt;&lt; allFonts &lt;&lt; endl;
105 // Output:
106 // Times, Courier, Courier New, Helvetica [Cronyx], Helvetica [Adobe]
107 </pre>
108
109<p> You can sort the list with <a href="#sort">sort</a>(), and extract a new list which
110contains only those strings which contain a particular substring
111(or match a particular <a href="qregexp.html#regular-expression">regular expression</a>) using the <a href="#grep">grep</a>()
112functions, e.g.
113<pre>
114 fonts.sort();
115 cout &lt;&lt; fonts.join( ", " ) &lt;&lt; endl;
116 // Output:
117 // Courier, Courier New, Helvetica [Adobe], Helvetica [Cronyx], Times
118
119 QStringList helveticas = fonts.grep( "Helvetica" );
120 cout &lt;&lt; helveticas.<a href="#join">join</a>( ", " ) &lt;&lt; endl;
121 // Output:
122 // Helvetica [Adobe], Helvetica [Cronyx]
123 </pre>
124
125<p> Existing strings can be split into string lists with character,
126string or regular expression separators, e.g.
127<pre>
128 <a href="qstring.html">QString</a> s = "Red\tGreen\tBlue";
129 QStringList colors = QStringList::<a href="#split">split</a>( "\t", s );
130 cout &lt;&lt; colors.<a href="#join">join</a>( ", " ) &lt;&lt; endl;
131 // Output:
132 // Red, Green, Blue
133 </pre>
134
135<p>See also <a href="shared.html">Implicitly and Explicitly Shared Classes</a>, <a href="text.html">Text Related Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
136
137<hr><h2>Member Function Documentation</h2>
138<h3 class=fn><a name="QStringList"></a>QStringList::QStringList ()
139</h3>
140
141<p> Creates an empty string list.
142
143<h3 class=fn><a name="QStringList-2"></a>QStringList::QStringList ( const&nbsp;<a href="qstringlist.html">QStringList</a>&nbsp;&amp;&nbsp;l )
144</h3>
145
146<p> Creates a copy of the list <em>l</em>. This function is very fast
147because QStringList is <a href="shclass.html#implicitly-shared">implicitly shared</a>. In most situations this
148acts like a <a href="shclass.html#deep-copy">deep copy</a>, for example, if this list or the original
149one or some other list referencing the same shared data is
150modified, the modifying list first makes a copy, i.e.
151copy-on-write.
152In a threaded environment you may require a real deep copy
153.
154
155<h3 class=fn><a name="QStringList-3"></a>QStringList::QStringList ( const&nbsp;<a href="qvaluelist.html">QValueList</a>&lt;QString&gt;&nbsp;&amp;&nbsp;l )
156</h3>
157
158<p> Constructs a new string list that is a copy of <em>l</em>.
159
160<h3 class=fn><a name="QStringList-4"></a>QStringList::QStringList ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;i )
161</h3>
162
163<p> Constructs a string list consisting of the single string <em>i</em>.
164Longer lists are easily created as follows:
165<p> <pre>
166 QStringList items;
167 items &lt;&lt; "Buy" &lt;&lt; "Sell" &lt;&lt; "Update" &lt;&lt; "Value";
168 </pre>
169
170
171<h3 class=fn><a name="QStringList-5"></a>QStringList::QStringList ( const&nbsp;char&nbsp;*&nbsp;i )
172</h3>
173
174<p> Constructs a string list consisting of the single Latin-1 string <em>i</em>.
175
176<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="fromStrList"></a>QStringList::fromStrList ( const&nbsp;<a href="qstrlist.html">QStrList</a>&nbsp;&amp;&nbsp;ascii )<tt> [static]</tt>
177</h3>
178Converts from an ASCII-QStrList <em>ascii</em> to a QStringList (Unicode).
179
180<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="grep"></a>QStringList::grep ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;str, bool&nbsp;cs = TRUE ) const
181</h3>
182Returns a list of all the strings containing the substring <em>str</em>.
183<p> If <em>cs</em> is TRUE, the grep is done case-sensitively; otherwise
184case is ignored.
185<p> <pre>
186 QStringList list;
187 list &lt;&lt; "Bill Gates" &lt;&lt; "John Doe" &lt;&lt; "Bill Clinton";
188 list = list.<a href="#grep">grep</a>( "Bill" );
189 // list == ["Bill Gates", "Bill Clinton"]
190 </pre>
191
192<p> <p>See also <a href="qstring.html#find">QString::find</a>().
193
194<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="grep-2"></a>QStringList::grep ( const&nbsp;<a href="qregexp.html">QRegExp</a>&nbsp;&amp;&nbsp;rx ) const
195</h3>
196This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
197<p> Returns a list of all the strings that match the <a href="qregexp.html#regular-expression">regular expression</a> <em>rx</em>.
198<p> <p>See also <a href="qstring.html#find">QString::find</a>().
199
200<h3 class=fn><a href="qstringlist.html">QStringList</a>&nbsp;&amp; <a name="gres"></a>QStringList::gres ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;before, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;after, bool&nbsp;cs = TRUE )
201</h3>
202Replaces every occurrence of the string <em>before</em> in the strings
203that constitute the string list with the string <em>after</em>. Returns
204a reference to the string list.
205<p> If <em>cs</em> is TRUE, the search is case sensitive; otherwise the
206search is case insensitive.
207<p> Example:
208<pre>
209 QStringList list;
210 list &lt;&lt; "alpha" &lt;&lt; "beta" &lt;&lt; "gamma" &lt;&lt; "epsilon";
211 list.<a href="#gres">gres</a>( "a", "o" );
212 // list == ["olpho", "beto", "gommo", "epsilon"]
213 </pre>
214
215<p> <p>See also <a href="qstring.html#replace">QString::replace</a>().
216
217<h3 class=fn><a href="qstringlist.html">QStringList</a>&nbsp;&amp; <a name="gres-2"></a>QStringList::gres ( const&nbsp;<a href="qregexp.html">QRegExp</a>&nbsp;&amp;&nbsp;rx, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;after )
218</h3>
219This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
220<p> Replaces every occurrence of the regexp <em>rx</em> in the string
221with <em>after</em>. Returns a reference to the string list.
222<p> Example:
223<pre>
224 QStringList list;
225 list &lt;&lt; "alpha" &lt;&lt; "beta" &lt;&lt; "gamma" &lt;&lt; "epsilon";
226 list.<a href="#gres">gres</a>( QRegExp("^a"), "o" );
227 // list == ["olpha", "beta", "gamma", "epsilon"]
228 </pre>
229
230<p> For regexps containing <a href="qregexp.html#capturing-text">capturing parentheses</a>, occurrences of <b>&#92;1</b>,
231<b>&#92;2</b>, ..., in <em>after</em> are replaced with <em>rx</em>.cap(1),
232cap(2), ...
233<p> Example:
234<pre>
235 QStringList list;
236 list &lt;&lt; "Bill Clinton" &lt;&lt; "Gates, Bill";
237 list.<a href="#gres">gres</a>( QRegExp("^(.*), (.*)$"), "\\2 \\1" );
238 // list == ["Bill Clinton", "Bill Gates"]
239 </pre>
240
241<p> <p>See also <a href="qstring.html#replace">QString::replace</a>().
242
243<h3 class=fn><a href="qstring.html">QString</a> <a name="join"></a>QStringList::join ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;sep ) const
244</h3>
245Joins the string list into a single string with each element
246separated by the string <em>sep</em> (which can be empty).
247<p> <p>See also <a href="#split">split</a>().
248
249<p>Examples: <a href="fileiconview-example.html#x872">fileiconview/qfileiconview.cpp</a> and <a href="toplevel-example.html#x2533">toplevel/options.ui.h</a>.
250<h3 class=fn>void <a name="sort"></a>QStringList::sort ()
251</h3>
252Sorts the list of strings in ascending case-sensitive order.
253<p> Sorting is very fast. It uses the <a href="qtl.html">Qt Template
254 Library's</a> efficient HeapSort implementation that has a
255time complexity of O(n*log n).
256<p> If you want to sort your strings in an arbitrary order consider
257using a <a href="qmap.html">QMap</a>. For example you could use a QMap&lt;QString,QString&gt;
258to create a case-insensitive ordering (e.g. mapping the lowercase
259text to the text), or a QMap&lt;int,QString&gt; to sort the strings by
260some integer index, etc.
261
262<p>Example: <a href="themes-example.html#x341">themes/themes.cpp</a>.
263<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="split"></a>QStringList::split ( const&nbsp;<a href="qregexp.html">QRegExp</a>&nbsp;&amp;&nbsp;sep, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )<tt> [static]</tt>
264</h3>
265Splits the string <em>str</em> into strings wherever the <a href="qregexp.html#regular-expression">regular expression</a> <em>sep</em> occurs, and returns the list of those strings.
266<p> If <em>allowEmptyEntries</em> is TRUE, a null string is inserted in
267the list wherever the separator matches twice without intervening
268text.
269<p> For example, if you split the string "a,,b,c" on commas, <a href="#split">split</a>()
270returns the three-item list "a", "b", "c" if <em>allowEmptyEntries</em>
271is FALSE (the default), and the four-item list "a", "", "b", "c"
272if <em>allowEmptyEntries</em> is TRUE.
273<p> If <em>sep</em> does not match anywhere in <em>str</em>, split() returns a
274single element list with the element containing the single string
275<em>str</em>.
276<p> <p>See also <a href="#join">join</a>() and <a href="qstring.html#section">QString::section</a>().
277
278<p>Examples: <a href="tutorial2-03.html#x2552">chart/element.cpp</a>, <a href="dirview-example.html#x1703">dirview/dirview.cpp</a>, and <a href="httpd-example.html#x733">network/httpd/httpd.cpp</a>.
279<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="split-2"></a>QStringList::split ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;sep, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )<tt> [static]</tt>
280</h3>
281This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
282<p> This version of the function uses a <a href="qstring.html">QString</a> as separator, rather
283than a <a href="qregexp.html#regular-expression">regular expression</a>.
284<p> If <em>sep</em> is an empty string, the return value is a list of
285one-character strings: <a href="#split">split</a>( QString( "" ), "four" ) returns the
286four-item list, "f", "o", "u", "r".
287<p> If <em>allowEmptyEntries</em> is TRUE, a null string is inserted in
288the list wherever the separator matches twice without intervening
289text.
290<p> <p>See also <a href="#join">join</a>() and <a href="qstring.html#section">QString::section</a>().
291
292<h3 class=fn><a href="qstringlist.html">QStringList</a> <a name="split-3"></a>QStringList::split ( const&nbsp;<a href="qchar.html">QChar</a>&nbsp;&amp;&nbsp;sep, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;str, bool&nbsp;allowEmptyEntries = FALSE )<tt> [static]</tt>
293</h3>
294This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
295<p> This version of the function uses a <a href="qchar.html">QChar</a> as separator, rather
296than a <a href="qregexp.html#regular-expression">regular expression</a>.
297<p> <p>See also <a href="#join">join</a>() and <a href="qstring.html#section">QString::section</a>().
298
299<!-- eof -->
300<hr><p>
301This file is part of the <a href="index.html">Qt toolkit</a>.
302Copyright &copy; 1995-2007
303<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
304<table width=100% cellspacing=0 border=0><tr>
305<td>Copyright &copy; 2007
306<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
307<td align=right><div align=right>Qt 3.3.8</div>
308</table></div></address></body>
309</html>
Note: See TracBrowser for help on using the repository browser.