summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/tqstringlist.3qt
blob: 02bef4bf8afb5c7084d415a943ed01f6900e4fa5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
'\" t
.TH QStringList 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2007 Trolltech ASA.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QStringList \- List of strings
.SH SYNOPSIS
All the functions in this class are reentrant when TQt is built with thread support.</p>
.PP
\fC#include <ntqstringlist.h>\fR
.PP
Inherits QValueList<QString>.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQStringList\fR ()"
.br
.ti -1c
.BI "\fBQStringList\fR ( const QStringList & l )"
.br
.ti -1c
.BI "\fBQStringList\fR ( const QValueList<QString> & l )"
.br
.ti -1c
.BI "\fBQStringList\fR ( const QString & i )"
.br
.ti -1c
.BI "\fBQStringList\fR ( const char * i )"
.br
.ti -1c
.BI "void \fBsort\fR ()"
.br
.ti -1c
.BI "QString \fBjoin\fR ( const QString & sep ) const"
.br
.ti -1c
.BI "QStringList \fBgrep\fR ( const QString & str, bool cs = TRUE ) const"
.br
.ti -1c
.BI "QStringList \fBgrep\fR ( const QRegExp & rx ) const"
.br
.ti -1c
.BI "QStringList & \fBgres\fR ( const QString & before, const QString & after, bool cs = TRUE )"
.br
.ti -1c
.BI "QStringList & \fBgres\fR ( const QRegExp & rx, const QString & after )"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "QStringList \fBfromStrList\fR ( const QStrList & ascii )"
.br
.ti -1c
.BI "QStringList \fBsplit\fR ( const QString & sep, const QString & str, bool allowEmptyEntries = FALSE )"
.br
.ti -1c
.BI "QStringList \fBsplit\fR ( const QChar & sep, const QString & str, bool allowEmptyEntries = FALSE )"
.br
.ti -1c
.BI "QStringList \fBsplit\fR ( const QRegExp & sep, const QString & str, bool allowEmptyEntries = FALSE )"
.br
.in -1c
.SH DESCRIPTION
The QStringList class provides a list of strings.
.PP
It is used to store and manipulate strings that logically belong together. Essentially QStringList is a QValueList of QString objects. Unlike QStrList, which stores pointers to characters, QStringList holds real QString objects. It is the class of choice whenever you work with Unicode strings. QStringList is part of the TQt Template Library.
.PP
Like QString itself, QStringList objects are implicitly shared, so passing them around as value-parameters is both fast and safe.
.PP
Strings can be added to a list using append(), operator+=() or operator<<(), e.g.
.PP
.nf
.br
    QStringList fonts;
.br
    fonts.append( "Times" );
.br
    fonts += "Courier";
.br
    fonts += "Courier New";
.br
    fonts << "Helvetica [Cronyx]" << "Helvetica [Adobe]";
.br
.fi
.PP
String lists have an iterator, QStringList::Iterator(), e.g.
.PP
.nf
.br
    for ( QStringList::Iterator it = fonts.begin(); it != fonts.end(); ++it ) {
.br
        cout << *it << ":";
.br
    }
.br
    cout << endl;
.br
    // Output:
.br
    //  Times:Courier:Courier New:Helvetica [Cronyx]:Helvetica [Adobe]:
.br
.fi
.PP
Many TQt functions return string lists by value; to iterate over these you should make a copy and iterate over the copy.
.PP
You can concatenate all the strings in a string list into a single string (with an optional separator) using join(), e.g.
.PP
.nf
.br
    QString allFonts = fonts.join( ", " );
.br
    cout << allFonts << endl;
.br
    // Output:
.br
    //  Times, Courier, Courier New, Helvetica [Cronyx], Helvetica [Adobe]
.br
.fi
.PP
You can sort the list with sort(), and extract a new list which contains only those strings which contain a particular substring (or match a particular regular expression) using the grep() functions, e.g.
.PP
.nf
.br
    fonts.sort();
.br
    cout << fonts.join( ", " ) << endl;
.br
    // Output:
.br
    //  Courier, Courier New, Helvetica [Adobe], Helvetica [Cronyx], Times
.br
.br
    QStringList helveticas = fonts.grep( "Helvetica" );
.br
    cout << helveticas.join( ", " ) << endl;
.br
    // Output:
.br
    //  Helvetica [Adobe], Helvetica [Cronyx]
.br
.fi
.PP
Existing strings can be split into string lists with character, string or regular expression separators, e.g.
.PP
.nf
.br
    QString s = "Red\\tGreen\\tBlue";
.br
    QStringList colors = QStringList::split( "\\t", s );
.br
    cout << colors.join( ", " ) << endl;
.br
    // Output:
.br
    //  Red, Green, Blue
.br
.fi
.PP
See also Implicitly and Explicitly Shared Classes, Text Related Classes, and Non-GUI Classes.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QStringList::QStringList ()"
Creates an empty string list.
.SH "QStringList::QStringList ( const QStringList & l )"
Creates a copy of the list \fIl\fR. This function is very fast because QStringList is implicitly shared. In most situations this acts like a deep copy, for example, if this list or the original one or some other list referencing the same shared data is modified, the modifying list first makes a copy, i.e. copy-on-write. In a threaded environment you may require a real deep copy
.
.SH "QStringList::QStringList ( const QValueList<QString> & l )"
Constructs a new string list that is a copy of \fIl\fR.
.SH "QStringList::QStringList ( const QString & i )"
Constructs a string list consisting of the single string \fIi\fR. Longer lists are easily created as follows:
.PP
.nf
.br
    QStringList items;
.br
    items << "Buy" << "Sell" << "Update" << "Value";
.br
.fi
.SH "QStringList::QStringList ( const char * i )"
Constructs a string list consisting of the single Latin-1 string \fIi\fR.
.SH "QStringList QStringList::fromStrList ( const QStrList & ascii )\fC [static]\fR"
Converts from an ASCII-QStrList \fIascii\fR to a QStringList (Unicode).
.SH "QStringList QStringList::grep ( const QString & str, bool cs = TRUE ) const"
Returns a list of all the strings containing the substring \fIstr\fR.
.PP
If \fIcs\fR is TRUE, the grep is done case-sensitively; otherwise case is ignored.
.PP
.nf
.br
    QStringList list;
.br
    list << "Bill Gates" << "John Doe" << "Bill Clinton";
.br
    list = list.grep( "Bill" );
.br
    // list == ["Bill Gates", "Bill Clinton"]
.br
.fi
.PP
See also QString::find().
.SH "QStringList QStringList::grep ( const QRegExp & rx ) const"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Returns a list of all the strings that match the regular expression \fIrx\fR.
.PP
See also QString::find().
.SH "QStringList & QStringList::gres ( const QString & before, const QString & after, bool cs = TRUE )"
Replaces every occurrence of the string \fIbefore\fR in the strings that constitute the string list with the string \fIafter\fR. Returns a reference to the string list.
.PP
If \fIcs\fR is TRUE, the search is case sensitive; otherwise the search is case insensitive.
.PP
Example:
.PP
.nf
.br
    QStringList list;
.br
    list << "alpha" << "beta" << "gamma" << "epsilon";
.br
    list.gres( "a", "o" );
.br
    // list == ["olpho", "beto", "gommo", "epsilon"]
.br
.fi
.PP
See also QString::replace().
.SH "QStringList & QStringList::gres ( const QRegExp & rx, const QString & after )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Replaces every occurrence of the regexp \fIrx\fR in the string with \fIafter\fR. Returns a reference to the string list.
.PP
Example:
.PP
.nf
.br
    QStringList list;
.br
    list << "alpha" << "beta" << "gamma" << "epsilon";
.br
    list.gres( QRegExp("^a"), "o" );
.br
    // list == ["olpha", "beta", "gamma", "epsilon"]
.br
.fi
.PP
For regexps containing capturing parentheses, occurrences of \fB&#92;1\fR, \fB&#92;2\fR, ..., in \fIafter\fR are replaced with \fIrx\fR.cap(1), cap(2), ...
.PP
Example:
.PP
.nf
.br
    QStringList list;
.br
    list << "Bill Clinton" << "Gates, Bill";
.br
    list.gres( QRegExp("^(.*), (.*)$"), "\\\\2 \\\\1" );
.br
    // list == ["Bill Clinton", "Bill Gates"]
.br
.fi
.PP
See also QString::replace().
.SH "QString QStringList::join ( const QString & sep ) const"
Joins the string list into a single string with each element separated by the string \fIsep\fR (which can be empty).
.PP
See also split().
.PP
Examples:
.)l fileiconview/qfileiconview.cpp and toplevel/options.ui.h.
.SH "void QStringList::sort ()"
Sorts the list of strings in ascending case-sensitive order.
.PP
Sorting is very fast. It uses the TQt Template Library's efficient HeapSort implementation that has a time complexity of O(n*log n).
.PP
If you want to sort your strings in an arbitrary order consider using a QMap. For example you could use a QMap<QString,QString> to create a case-insensitive ordering (e.g. mapping the lowercase text to the text), or a QMap<int,QString> to sort the strings by some integer index, etc.
.PP
Example: themes/themes.cpp.
.SH "QStringList QStringList::split ( const QRegExp & sep, const QString & str, bool allowEmptyEntries = FALSE )\fC [static]\fR"
Splits the string \fIstr\fR into strings wherever the regular expression \fIsep\fR occurs, and returns the list of those strings.
.PP
If \fIallowEmptyEntries\fR is TRUE, a null string is inserted in the list wherever the separator matches twice without intervening text.
.PP
For example, if you split the string "a,,b,c" on commas, split() returns the three-item list "a", "b", "c" if \fIallowEmptyEntries\fR is FALSE (the default), and the four-item list "a", "", "b", "c" if \fIallowEmptyEntries\fR is TRUE.
.PP
If \fIsep\fR does not match anywhere in \fIstr\fR, split() returns a single element list with the element containing the single string \fIstr\fR.
.PP
See also join() and QString::section().
.PP
Examples:
.)l chart/element.cpp, dirview/dirview.cpp, and network/httpd/httpd.cpp.
.SH "QStringList QStringList::split ( const QString & sep, const QString & str, bool allowEmptyEntries = FALSE )\fC [static]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
This version of the function uses a QString as separator, rather than a regular expression.
.PP
If \fIsep\fR is an empty string, the return value is a list of one-character strings: split( QString( "" ), "four" ) returns the four-item list, "f", "o", "u", "r".
.PP
If \fIallowEmptyEntries\fR is TRUE, a null string is inserted in the list wherever the separator matches twice without intervening text.
.PP
See also join() and QString::section().
.SH "QStringList QStringList::split ( const QChar & sep, const QString & str, bool allowEmptyEntries = FALSE )\fC [static]\fR"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
This version of the function uses a QChar as separator, rather than a regular expression.
.PP
See also join() and QString::section().

.SH "SEE ALSO"
.BR http://doc.trolltech.com/ntqstringlist.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive TQt documentation is provided in HTML format; it is
located at $TQTDIR/doc/html and can be read using TQt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech. 
.P
If you find errors in this manual page, please report them to
.BR qt-bugs@trolltech.com .
Please include the name of the manual page (tqstringlist.3qt) and the Qt
version (3.3.8).