QStringList

NAME

SYNOPSIS

#include <qstringlist.h>

Inherits QValueList<QString>.

Public Members

Static Public Members

DESCRIPTION

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 ()

QStringList::QStringList ( const QStringList & l )

QStringList::QStringList ( const QValueList<QString> & l )

QStringList::QStringList ( const QString & i )

    QStringList items;


    items << "Buy" << "Sell" << "Update" << "Value";

QStringList::QStringList ( const char * i )

QStringList QStringList::fromStrList ( const QStrList & ascii ) [static]

QStringList QStringList::grep ( const QString & str, bool cs = TRUE ) const

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

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 )

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 )

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 &#92;1, &#92;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

See also split().

Examples:  

void QStringList::sort ()

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]

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:  

QStringList QStringList::split ( const QString & sep, const QString & str, bool allowEmptyEntries = FALSE ) [static]

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 version of the function uses a QChar as separator, rather than a regular expression.

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

SEE ALSO

COPYRIGHT

AUTHOR

BUGS