QStringList Class | Qt Core | Qt 6.11.1
Description: The QStringList class provides a list of strings.

- Qt 6.11
- Qt Core
- C++ Classes
- QStringList
- Qt 6.11.1 Reference Documentation

# QStringList Class

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

Header: | `#include <QStringList>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Core)` `target_link_libraries(mytarget PRIVATE Qt6::Core)`
qmake: | `QT += core`
Inherits: | QList

- List of all members, including inherited members
- QStringList is part of Implicitly Shared Classes and Classes for string data.

Note: All functions in this class are reentrant.

## Public Functions

| QStringList(const QList<QString> &other)
| QStringList(const QString &str)
| QStringList(QList<QString> &&other)
bool | contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
bool | contains(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
bool | contains(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
`(since 6.9)` QStringList | filter(const QLatin1StringMatcher &matcher) const
QStringList | filter(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
QStringList | filter(const QRegularExpression &re) const
`(since 6.7)` QStringList | filter(const QStringMatcher &matcher) const
`(since 6.7)` QStringList | filter(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
QStringList | filter(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | indexOf(QLatin1StringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | indexOf(QStringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | indexOf(const QString &str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | indexOf(const QRegularExpression &re, qsizetype from = 0) const
QString | join(const QString &separator) const
QString | join(QChar separator) const
QString | join(QLatin1StringView separator) const
QString | join(QStringView separator) const
qsizetype | lastIndexOf(QLatin1StringView str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | lastIndexOf(QStringView str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | lastIndexOf(const QString &str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
qsizetype | lastIndexOf(const QRegularExpression &re, qsizetype from = -1) const
qsizetype | removeDuplicates()
QStringList & | replaceInStrings(const QString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive)
QStringList & | replaceInStrings(const QRegularExpression &re, const QString &after)
QStringList & | replaceInStrings(QStringView before, QStringView after, Qt::CaseSensitivity cs = Qt::CaseSensitive)
QStringList & | replaceInStrings(QStringView before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive)
QStringList & | replaceInStrings(const QString &before, QStringView after, Qt::CaseSensitivity cs = Qt::CaseSensitive)
void | sort(Qt::CaseSensitivity cs = Qt::CaseSensitive)
QStringList | operator+(const QStringList &other) const
QStringList & | operator<<(const QString &str)
QStringList & | operator<<(const QList<QString> &other)
QStringList & | operator<<(const QStringList &other)
QStringList & | operator=(const QList<QString> &other)
QStringList & | operator=(QList<QString> &&other)

## Related Non-Members

| QMutableStringListIterator
| QStringListIterator

## Detailed Description

QStringList is actually just a QList<QString>. Like QList, QStringList is implicitly shared. It provides fast index-based access as well as fast insertions and removals. Passing string lists as value parameters is both fast and safe.

All of QList's functionality also applies to QStringList. For example, you can use isEmpty() to test whether the list is empty, and you can call functions like append(), prepend(), insert(), replace(), removeAll(), removeAt(), removeFirst(), removeLast(), and removeOne() to modify a QStringList. In addition, QStringList provides a few convenience functions that make handling lists of strings easier.

### Initializing

The default constructor creates an empty list. You can use the initializer-list constructor to create a list with elements:

         QStringList fonts = { "Arial", "Helvetica", "Times" };

### Adding Strings

Strings can be added to a list using the insert(), append(), operator+=() and operator<<() functions.

operator<<() can be used to conveniently add multiple elements to a list:

         fonts << "Courier" << "Verdana";

### Iterating Over the Strings

See Iterating over Containers.

### Manipulating the Strings

QStringList provides several functions allowing you to manipulate the contents of a list. You can concatenate all the strings in a string list into a single string (with an optional separator) using the join() function. For example:

         QString str = fonts.join(", ");
          // str == "Arial, Helvetica, Times, Courier"

The argument to join can be a single character or a string.

To break up a string into a string list, use the QString::split() function:

         QStringList list;
         list = str.split(',');
          // list: ["Arial", "Helvetica", "Times", "Courier"]

The argument to split can be a single character, a string or a QRegularExpression.

In addition, the operator+() function allows you to concatenate two string lists into one. To sort a string list, use the sort() function.

QString list also provides the filter() function which lets you to extract a new list which contains only those strings which contain a particular substring (or match a particular regular expression):

         QStringList monospacedFonts = fonts.filter(QRegularExpression("Courier|Fixed"));

The contains() function tells you whether the list contains a given string, while the indexOf() function returns the index of the first occurrence of the given string. The lastIndexOf() function on the other hand, returns the index of the last occurrence of the string.

Finally, the replaceInStrings() function calls QString::replace() on each string in the string list in turn. For example:

         QStringList files;
         files << "$QTDIR/src/moc/moc.y"
               << "$QTDIR/src/moc/moc.l"
               << "$QTDIR/include/qconfig.h";

         files.replaceInStrings("$QTDIR", "/usr/lib/qt");
         // files: [ "/usr/lib/qt/src/moc/moc.y", ...]

See also QString.

## Member Function Documentation

### QStringList::QStringList(const QList<QString> &other)

Constructs a copy of other.

This operation takes constant time, because QStringList is implicitly shared. This makes returning a QStringList from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takes linear time.

See also operator=().

### QStringList::QStringList(const QString &str)

Constructs a string list that contains the given string, str. Longer lists are easily created like this:

         QStringList longerList = (QStringList() << str1 << str2 << str3);

See also append().

### QStringList::QStringList(QList<QString> &&other)

Move-constructs from QList<QString>.

After a successful construction, other will be empty.

This is an overloaded function.

### `[noexcept]` bool QStringList::contains(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns `true` if the list contains the string str; otherwise returns `false`.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

See also indexOf(), lastIndexOf(), and QString::contains().

### `[noexcept]` bool QStringList::contains(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns `true` if the list contains the Latin-1 string viewed by str; otherwise returns `false`.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

This is an overloaded function.

See also indexOf(), lastIndexOf(), and QString::contains().

### `[noexcept]` bool QStringList::contains(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns `true` if the list contains the string str; otherwise returns `false`.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

This is an overloaded function.

### `[since 6.9]` QStringList QStringList::filter(const QLatin1StringMatcher &matcher) const

Returns a list of all the strings matched by matcher (i.e. for which `matcher.indexIn()` returns an index >= 0).

Using QLatin1StringMatcher may be faster when searching in large lists and/or in lists with long strings (the best way to find out is benchmarking).

For example:

         QStringList veryLargeList;
         QLatin1StringMatcher matcher("Street"_L1, Qt::CaseInsensitive);
         QStringList filtered = veryLargeList.filter(matcher);

This function was introduced in Qt 6.9.

See also contains() and filter(const QStringMatcher &).

### QStringList QStringList::filter(const QString &str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns a list of all the strings containing the substring str.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

         QStringList list;
         list << "Bill Murray" << "John Doe" << "Bill Clinton";

         QStringList result;
         result = list.filter("Bill");
         // result: ["Bill Murray", "Bill Clinton"]

This is equivalent to

         QStringList result;
         for (const auto &str : std::as_const(list)) {
             if (str.contains("Bill"))
                 result += str;
         }

See also contains().

### QStringList QStringList::filter(const QRegularExpression &re) const

Returns a list of all the strings that match the regular expression re.

This is an overloaded function.

### `[since 6.7]` QStringList QStringList::filter(const QStringMatcher &matcher) const

Returns a list of all the strings matched by matcher (i.e. for which `matcher.indexIn()` returns an index >= 0).

Using a QStringMatcher may be faster when searching in large lists and/or in lists with long strings (the best way to find out is benchmarking).

For example:

         QStringList veryLongList;
         QStringMatcher matcher(u"Straße", Qt::CaseInsensitive);
         QStringList filtered = veryLongList.filter(matcher);

This is an overloaded function.

This function was introduced in Qt 6.7.

See also contains() and filter(const QLatin1StringMatcher &).

### `[since 6.7]` QStringList QStringList::filter(QLatin1StringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

This function was introduced in Qt 6.7.

### QStringList QStringList::filter(QStringView str, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

This is an overloaded function.

### `[noexcept]` qsizetype QStringList::indexOf(const QString &str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

### `[noexcept]` qsizetype QStringList::indexOf(QStringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

### `[noexcept]` qsizetype QStringList::indexOf(QLatin1StringView str, qsizetype from = 0, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the first match of str in the list, searching forward from index position from. Returns -1 if no item matched.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

Note: The cs parameter was added in Qt 6.7, i.e. these methods now overload the methods inherited from the base class. Prior to that these methods only had two parameters. This change is source compatible and existing code should continue to work.

See also lastIndexOf().

### qsizetype QStringList::indexOf(const QRegularExpression &re, qsizetype from = 0) const

Returns the index position of the first exact match of re in the list, searching forward from index position from. Returns -1 if no item matched.

This is an overloaded function.

See also lastIndexOf().

### QString QStringList::join(const QString &separator) const

Joins all the string list's strings into a single string with each element separated by the given separator (which can be an empty string).

See also QString::split().

### QString QStringList::join(QChar separator) const

This function overloads QStringList::join().

### QString QStringList::join(QLatin1StringView separator) const

This function overloads QStringList::join().

### QString QStringList::join(QStringView separator) const

This is an overloaded function.

### `[noexcept]` qsizetype QStringList::lastIndexOf(const QString &str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

### `[noexcept]` qsizetype QStringList::lastIndexOf(QStringView str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

### `[noexcept]` qsizetype QStringList::lastIndexOf(QLatin1StringView str, qsizetype from = -1, Qt::CaseSensitivity cs = Qt::CaseSensitive) const

Returns the index position of the last match of str in the list, searching backward from index position from. If from is -1 (the default), the search starts at the last item. Returns -1 if no item matched.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

Note: The cs parameter was added in Qt 6.7, i.e. these methods now overload the methods inherited from the base class. Prior to that these methods only had two parameters. This change is source compatible and existing code should continue to work.

See also indexOf().

### qsizetype QStringList::lastIndexOf(const QRegularExpression &re, qsizetype from = -1) const

Returns the index position of the last exact match of re in the list, searching backward from index position from. If from is -1 (the default), the search starts at the last item. Returns -1 if no item matched.

This is an overloaded function.

See also indexOf().

### qsizetype QStringList::removeDuplicates()

This function removes duplicate entries from a list. The entries do not have to be sorted. They will retain their original order.

Returns the number of removed entries.

### QStringList &QStringList::replaceInStrings(const QString &before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive)

Returns a string list where every string has had the before text replaced with the after text wherever the before text is found.

Note: If you use an empty before argument, the after argument will be inserted before and after each character of the string.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

For example:

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

See also QString::replace().

### QStringList &QStringList::replaceInStrings(const QRegularExpression &re, const QString &after)

Replaces every occurrence of the regular expression re, in each of the string lists's strings, with after. Returns a reference to the string list.

For example:

         QStringList list;
         list << "alpha" << "beta" << "gamma" << "epsilon";
         list.replaceInStrings(QRegularExpression("^a"), "o");
         // list == ["olpha", "beta", "gamma", "epsilon"]

For regular expressions that contain capturing groups, occurrences of \1, \2, ..., in after are replaced with the string captured by the corresponding capturing group.

For example:

         QStringList list;
         list << "Bill Clinton" << "Murray, Bill";
         list.replaceInStrings(QRegularExpression("^(.*), (.*)$"), "\\2 \\1");
         // list == ["Bill Clinton", "Bill Murray"]

This is an overloaded function.

### QStringList &QStringList::replaceInStrings(QStringView before, QStringView after, Qt::CaseSensitivity cs = Qt::CaseSensitive)

This is an overloaded function.

### QStringList &QStringList::replaceInStrings(QStringView before, const QString &after, Qt::CaseSensitivity cs = Qt::CaseSensitive)

This is an overloaded function.

### QStringList &QStringList::replaceInStrings(const QString &before, QStringView after, Qt::CaseSensitivity cs = Qt::CaseSensitive)

This is an overloaded function.

### void QStringList::sort(Qt::CaseSensitivity cs = Qt::CaseSensitive)

Sorts the list of strings in ascending order.

If cs is Qt::CaseSensitive (the default), the string comparison is case sensitive; otherwise the comparison is case insensitive.

Sorting is performed using the STL's std::sort() algorithm, which averages linear-logarithmic time, i.e. O(n log n).

If you want to sort your strings in an arbitrary order, consider using the QMap class. For example, you could use a QMap<QString, QString> to create a case-insensitive ordering (e.g. with the keys being lower-case versions of the strings, and the values being the strings), or a QMap<int, QString> to sort the strings by some integer index.

### QStringList QStringList::operator+(const QStringList &other) const

Returns a string list that is the concatenation of this string list with the other string list.

See also append().

### QStringList &QStringList::operator<<(const QString &str)

Appends the given string, str, to this string list and returns a reference to the string list.

See also append().

### QStringList &QStringList::operator<<(const QList<QString> &other)

Appends the other string list to the string list and returns a reference to the latter string list.

This is an overloaded function.

### QStringList &QStringList::operator<<(const QStringList &other)

Appends the other string list to the string list and returns a reference to the latter string list.

This is an overloaded function.

### QStringList &QStringList::operator=(const QList<QString> &other)

Copy assignment operator from QList<QString>. Assigns the other list of strings to this string list.

After the operation, other and `*this` will be equal.

### QStringList &QStringList::operator=(QList<QString> &&other)

Move assignment operator from QList<QString>. Moves the other list of strings to this string list.

After the operation, other will be empty.

This is an overloaded function.

## Related Non-Members

### `[alias]` QMutableStringListIterator

The QStringListIterator type definition provides a Java-style non-const iterator for QStringList.

QStringList provides both Java-style iterators and STL-style iterators. The Java-style non-const iterator is simply a type definition for QMutableListIterator<QString>.

See also QStringListIterator and QStringList::iterator.

### `[alias]` QStringListIterator

The QStringListIterator type definition provides a Java-style const iterator for QStringList.

QStringList provides both Java-style iterators and STL-style iterators. The Java-style const iterator is simply a type definition for QListIterator<QString>.

See also QMutableStringListIterator and QStringList::const_iterator.