TQStringList Class

Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions |

# TQStringList Class Reference

The TQStringList class provides a list of strings. More...

All the functions in this class are reentrant when TQt is built with thread support.

`#include <tqstringlist.h>`

Inherits TQValueList<TQString>.

List of all member functions.

## Public Members

- TQStringList ()
- TQStringList ( const TQStringList & l )
- TQStringList ( const TQValueList<TQString> & l )
- TQStringList ( const TQString & i )
- TQStringList ( const char * i )
- void sort ()
- TQString join ( const TQString & sep ) const
- TQStringList grep ( const TQString & str, bool cs = true ) const
- TQStringList grep ( const TQRegExp & rx ) const
- TQStringList & gres ( const TQString & before, const TQString & after, bool cs = true )
- TQStringList & gres ( const TQRegExp & rx, const TQString & after )

## Static Public Members

- TQStringList fromStrList ( const TQStrList & ascii )
- TQStringList split ( const TQString & sep, const TQString & str, bool allowEmptyEntries = false )
- TQStringList split ( const TQChar & sep, const TQString & str, bool allowEmptyEntries = false )
- TQStringList split ( const TQRegExp & sep, const TQString & str, bool allowEmptyEntries = false )

## Detailed Description

The TQStringList class provides a list of strings.

It is used to store and manipulate strings that logically belong together. Essentially TQStringList is a TQValueList of TQString objects. Unlike TQStrList, which stores pointers to characters, TQStringList holds real TQString objects. It is the class of choice whenever you work with Unicode strings. TQStringList is part of the TQt Template Library.

Like TQString itself, TQStringList 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.

        TQStringList fonts;
        fonts.append( "Times" );
        fonts += "Courier";
        fonts += "Courier New";
        fonts << "Helvetica [Cronyx]" << "Helvetica [Adobe]";

String lists have an iterator, TQStringList::Iterator(), e.g.

        for ( TQStringList::Iterator it = fonts.begin(); it != fonts.end(); ++it ) {
            cout << *it << ":";
        }
        cout << endl;
        // Output:
        //  Times:Courier:Courier New:Helvetica [Cronyx]:Helvetica [Adobe]:

Many TQt 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.

        TQString 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

        TQStringList 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.

        TQString s = "Red\tGreen\tBlue";
        TQStringList colors = TQStringList::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

### TQStringList::TQStringList ()

Creates an empty string list.

### TQStringList::TQStringList ( const TQStringList & l )

Creates a copy of the list l. This function is very fast because TQStringList 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 .

### TQStringList::TQStringList ( const TQValueList<TQString> & l )

Constructs a new string list that is a copy of l.

### TQStringList::TQStringList ( const TQString & i )

Constructs a string list consisting of the single string i. Longer lists are easily created as follows:

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

### TQStringList::TQStringList ( const char * i )

Constructs a string list consisting of the single Latin-1 string i.

### TQStringList TQStringList::fromStrList ( const TQStrList & ascii )`[static]`

Converts from an ASCII-TQStrList ascii to a TQStringList (Unicode).

### TQStringList TQStringList::grep ( const TQString & 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.

        TQStringList list;
        list << "Bill Gates" << "John Doe" << "Bill Clinton";
        list = list.grep( "Bill" );
        // list == ["Bill Gates", "Bill Clinton"]

See also TQString::find().

### TQStringList TQStringList::grep ( const TQRegExp & 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 TQString::find().

### TQStringList & TQStringList::gres ( const TQString & before, const TQString & 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:

        TQStringList list;
        list << "alpha" << "beta" << "gamma" << "epsilon";
        list.gres( "a", "o" );
        // list == ["olpho", "beto", "gommo", "epsilon"]

See also TQString::replace().

### TQStringList & TQStringList::gres ( const TQRegExp & rx, const TQString & 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:

        TQStringList list;
        list << "alpha" << "beta" << "gamma" << "epsilon";
        list.gres( TQRegExp("^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:

        TQStringList list;
        list << "Bill Clinton" << "Gates, Bill";
        list.gres( TQRegExp("^(.*), (.*)$"), "\\2 \\1" );
        // list == ["Bill Clinton", "Bill Gates"]

See also TQString::replace().

### TQString TQStringList::join ( const TQString & 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/tqfileiconview.cpp and toplevel/options.ui.h.

### void TQStringList::sort ()

Sorts the list of strings in ascending case-sensitive order.

Sorting is very fast. It uses the TQt 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 TQMap. For example you could use a TQMap<TQString,TQString> to create a case-insensitive ordering (e.g. mapping the lowercase text to the text), or a TQMap<int,TQString> to sort the strings by some integer index, etc.

Example: themes/themes.cpp.

### TQStringList TQStringList::split ( const TQRegExp & sep, const TQString & 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 TQString::section().

Examples: chart/element.cpp, dirview/dirview.cpp, and network/httpd/httpd.cpp.

### TQStringList TQStringList::split ( const TQString & sep, const TQString & 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 TQString as separator, rather than a regular expression.

If sep is an empty string, the return value is a list of one-character strings: split( TQString( "" ), "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 TQString::section().

### TQStringList TQStringList::split ( const TQChar & sep, const TQString & 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 TQChar as separator, rather than a regular expression.

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

This file is part of the TQt toolkit. Copyright © 1995-2007 Trolltech. All Rights Reserved.