QStringList(3qt)

NAME
QStringList - List of strings

SYNOPSIS
#include <qstringlist.h>

Inherits QValueList<QString>.

  Public Members
QStringList ()
QStringList ( const QStringList & l )
QStringList ( const QValueList<QString> & l )
QStringList ( const QString & i )
QStringList ( const char * i )
void sort ()
QString join ( const QString & sep ) const
QStringList grep ( const QString & str, bool cs = TRUE ) const
QStringList grep ( const QRegExp & expr ) const

  Static Public Members
QStringList fromStrList ( const QStrList & ascii )
QStringList split ( const QString & sep, const QString & str, bool allowEmptyEntries = FALSE )
QStringList split ( const QChar & sep, const QString & str, bool allowEmptyEntries = FALSE )
QStringList split ( const QRegExp & sep, const QString & str, bool allowEmptyEntries = FALSE )

DESCRIPTION
The QStringList class provides a list of strings.

It is used to store and manipulate strings that logically belong together. Basically QStringList is a QValueList of QString objects. As opposed to QStrList, which stores pointers to characters, QStringList deals with 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. 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 const string lists; 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. However, for the programmer this is the same as a deep copy. 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.

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 strings containing the substring str.

If cs is TRUE, the grep is done case-sensitively; otherwise case is ignored.

QStringList QStringList::grep ( const QRegExp & expr ) 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 contain a substring that matches the regular expression expr.

QString QStringList::join ( const QString & sep ) const
Joins the string list into a single string with each element separated by the string sep.

See also split().

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, an empty 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 list consisting of the single string str.

See also join() and QString::section().

Examples:

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( "" ), "mfc" ) returns the three-item list, "m", "f", "c".

If allowEmptyEntries is TRUE, an empty 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().

SEE ALSO
http://doc.trolltech.com/qstringlist.html http://www.trolltech.com/faq/tech.html

COPYRIGHT
Copyright 1992-2001 Trolltech AS, http://www.trolltech.com. See the license file included in the distribution for a complete license statement.

AUTHOR
Generated automatically from the source code.

BUGS
If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you.

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt 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.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qstringlist.3qt) and the Qt version (3.0.3).