Detailed Description
The QStringList class provides a list of strings.
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
Qt Template Library.
Like QString itself, QStringList objects are implicitly shared, so
passing them around as value-parameters is both fast and safe.
Strings can be added to a list using append(), operator+=() or
operator<<(), e.g.
QStringList fonts;
fonts.append( "Times" );
fonts += "Courier";
fonts += "Courier New";
fonts << "Helvetica [Cronyx]" << "Helvetica [Adobe]";
String lists have an iterator, QStringList::Iterator(), e.g.
for ( QStringList::Iterator it = fonts.begin(); it != fonts.end(); ++it ) {
cout << *it << ":";
}
cout << endl;
// Output:
// Times:Courier:Courier New:Helvetica [Cronyx]:Helvetica [Adobe]:
Many Qt functions return string lists by value; to iterate over
these you should make a copy and iterate over the copy.
You can concatenate all the strings in a string list into a single
string (with an optional separator) using join(), e.g.
QString allFonts = fonts.join( ", " );
cout << allFonts << endl;
// Output:
// Times, Courier, Courier New, Helvetica [Cronyx], Helvetica [Adobe]
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.
fonts.sort();
cout << fonts.join( ", " ) << endl;
// Output:
// Courier, Courier New, Helvetica [Adobe], Helvetica [Cronyx], Times
QStringList helveticas = fonts.grep( "Helvetica" );
cout << helveticas.join( ", " ) << endl;
// Output:
// Helvetica [Adobe], Helvetica [Cronyx]
Existing strings can be split into string lists with character,
string or regular expression separators, e.g.
QString s = "Red\tGreen\tBlue";
QStringList colors = QStringList::split( "\t", s );
cout << colors.join( ", " ) << endl;
// Output:
// Red, Green, Blue
See also Implicitly and Explicitly Shared Classes, Text Related Classes, and Non-GUI Classes.
Member Function Documentation
QStringList::QStringList ()
Creates an empty string list.
QStringList::QStringList ( const QStringList & l )
Creates a copy of the list l. 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
.
QStringList::QStringList ( const QValueList<QString> & l )
Constructs a new string list that is a copy of l.
QStringList::QStringList ( const QString & i )
Constructs a string list consisting of the single string i.
Longer lists are easily created as follows:
QStringList items;
items << "Buy" << "Sell" << "Update" << "Value";
QStringList::QStringList ( const char * i )
Constructs a string list consisting of the single Latin-1 string i.
QStringList QStringList::fromStrList ( const QStrList & ascii ) [static]
Converts from an ASCII-QStrList ascii to a QStringList (Unicode).
QStringList QStringList::grep ( const QString & str, bool cs = TRUE ) const
Returns a list of all the strings containing the substring str.
If cs is TRUE, the grep is done case-sensitively; otherwise
case is ignored.
QStringList list;
list << "Bill Gates" << "John Doe" << "Bill Clinton";
list = list.grep( "Bill" );
// list == ["Bill Gates", "Bill Clinton"]
See also QString::find().
QStringList QStringList::grep ( const QRegExp & rx ) const
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
Returns a list of all the strings that match the regular expression rx.
See also QString::find().
QStringList & QStringList::gres ( const QString & before, const QString & after, bool cs = TRUE )
Replaces every occurrence of the string before in the strings
that constitute the string list with the string after. Returns
a reference to the string list.
If cs is TRUE, the search is case sensitive; otherwise the
search is case insensitive.
Example:
QStringList list;
list << "alpha" << "beta" << "gamma" << "epsilon";
list.gres( "a", "o" );
// list == ["olpho", "beto", "gommo", "epsilon"]
See also QString::replace().
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.
Replaces every occurrence of the regexp rx in the string
with after. Returns a reference to the string list.
Example:
QStringList list;
list << "alpha" << "beta" << "gamma" << "epsilon";
list.gres( QRegExp("^a"), "o" );
// list == ["olpha", "beta", "gamma", "epsilon"]
For regexps containing capturing parentheses, occurrences of \1,
\2, ..., in after are replaced with rx.cap(1),
cap(2), ...
Example:
QStringList list;
list << "Bill Clinton" << "Gates, Bill";
list.gres( QRegExp("^(.*), (.*)$"), "\\2 \\1" );
// list == ["Bill Clinton", "Bill Gates"]
See also QString::replace().
QString QStringList::join ( const QString & sep ) const
Joins the string list into a single string with each element
separated by the string sep (which can be empty).
See also split().
Examples: fileiconview/qfileiconview.cpp and toplevel/options.ui.h.
void QStringList::sort ()
Sorts the list of strings in ascending case-sensitive order.
Sorting is very fast. It uses the Qt Template
Library's efficient HeapSort implementation that has a
time complexity of O(n*log n).
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.
Example: themes/themes.cpp.
QStringList QStringList::split ( const QRegExp & sep, const QString & str, bool allowEmptyEntries = FALSE ) [static]
Splits the string str into strings wherever the regular expression sep occurs, and returns the list of those strings.
If allowEmptyEntries is TRUE, a null string is inserted in
the list wherever the separator matches twice without intervening
text.
For example, if you split the string "a,,b,c" on commas, split()
returns the three-item list "a", "b", "c" if allowEmptyEntries
is FALSE (the default), and the four-item list "a", "", "b", "c"
if allowEmptyEntries is TRUE.
If sep does not match anywhere in str, split() returns a
single element list with the element containing the single string
str.
See also join() and QString::section().
Examples: chart/element.cpp, dirview/dirview.cpp, and network/httpd/httpd.cpp.
QStringList QStringList::split ( const QString & sep, const QString & str, bool allowEmptyEntries = FALSE ) [static]
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
This version of the function uses a QString as separator, rather
than a regular expression.
If sep 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".
If allowEmptyEntries is TRUE, a null string is inserted in
the list wherever the separator matches twice without intervening
text.
See also join() and QString::section().
QStringList QStringList::split ( const QChar & sep, const QString & str, bool allowEmptyEntries = FALSE ) [static]
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
This version of the function uses a QChar as separator, rather
than a regular expression.
See also join() and QString::section().
This file is part of the Qt toolkit.
Copyright © 1995-2005
Trolltech. All Rights Reserved.
