/**************************************************************************** | |
** | |
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). | |
** All rights reserved. | |
** Contact: Nokia Corporation (qt-info@nokia.com) | |
** | |
** This file is part of the QtCore module of the Qt Toolkit. | |
** | |
** $QT_BEGIN_LICENSE:LGPL$ | |
** GNU Lesser General Public License Usage | |
** This file may be used under the terms of the GNU Lesser General Public | |
** License version 2.1 as published by the Free Software Foundation and | |
** appearing in the file LICENSE.LGPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU Lesser | |
** General Public License version 2.1 requirements will be met: | |
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. | |
** | |
** In addition, as a special exception, Nokia gives you certain additional | |
** rights. These rights are described in the Nokia Qt LGPL Exception | |
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. | |
** | |
** GNU General Public License Usage | |
** Alternatively, this file may be used under the terms of the GNU General | |
** Public License version 3.0 as published by the Free Software Foundation | |
** and appearing in the file LICENSE.GPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU General | |
** Public License version 3.0 requirements will be met: | |
** http://www.gnu.org/copyleft/gpl.html. | |
** | |
** Other Usage | |
** Alternatively, this file may be used in accordance with the terms and | |
** conditions contained in a signed written agreement between you and Nokia. | |
** | |
** | |
** | |
** | |
** | |
** $QT_END_LICENSE$ | |
** | |
****************************************************************************/ | |
#include <qstringlist.h> | |
#include <qset.h> | |
QT_BEGIN_NAMESPACE | |
/*! \typedef QStringListIterator | |
\relates QStringList | |
The QStringListIterator type definition provides a Java-style const | |
iterator for QStringList. | |
QStringList provides both \l{Java-style iterators} and | |
\l{STL-style iterators}. The Java-style const iterator is simply | |
a type definition for QListIterator<QString>. | |
\sa QMutableStringListIterator, QStringList::const_iterator | |
*/ | |
/*! \typedef QMutableStringListIterator | |
\relates QStringList | |
The QStringListIterator type definition provides a Java-style | |
non-const iterator for QStringList. | |
QStringList provides both \l{Java-style iterators} and | |
\l{STL-style iterators}. The Java-style non-const iterator is | |
simply a type definition for QMutableListIterator<QString>. | |
\sa QStringListIterator, QStringList::iterator | |
*/ | |
/*! | |
\class QStringList | |
\brief The QStringList class provides a list of strings. | |
\ingroup tools | |
\ingroup shared | |
\ingroup string-processing | |
\reentrant | |
QStringList inherits from QList<QString>. Like QList, QStringList is | |
\l{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: | |
\tableofcontents | |
\section1 Adding strings | |
Strings can be added to a list using the \l | |
{QList::append()}{append()}, \l | |
{QList::operator+=()}{operator+=()} and \l | |
{QStringList::operator<<()}{operator<<()} functions. For example: | |
\snippet doc/src/snippets/qstringlist/main.cpp 0 | |
\section1 Iterating over the strings | |
To iterate over a list, you can either use index positions or | |
QList's Java-style and STL-style iterator types: | |
Indexing: | |
\snippet doc/src/snippets/qstringlist/main.cpp 1 | |
Java-style iterator: | |
\snippet doc/src/snippets/qstringlist/main.cpp 2 | |
STL-style iterator: | |
\snippet doc/src/snippets/qstringlist/main.cpp 3 | |
The QStringListIterator class is simply a type definition for | |
QListIterator<QString>. QStringList also provide the | |
QMutableStringListIterator class which is a type definition for | |
QMutableListIterator<QString>. | |
\section1 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: | |
\snippet doc/src/snippets/qstringlist/main.cpp 4 | |
To break up a string into a string list, use the QString::split() | |
function: | |
\snippet doc/src/snippets/qstringlist/main.cpp 6 | |
The argument to split can be a single character, a string, or a | |
QRegExp. | |
In addition, the \l {QStringList::operator+()}{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): | |
\snippet doc/src/snippets/qstringlist/main.cpp 7 | |
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: | |
\snippet doc/src/snippets/qstringlist/main.cpp 8 | |
\sa QString | |
*/ | |
/*! | |
\fn QStringList::QStringList() | |
Constructs an empty string list. | |
*/ | |
/*! | |
\fn QStringList::QStringList(const QString &str) | |
Constructs a string list that contains the given string, \a | |
str. Longer lists are easily created like this: | |
\snippet doc/src/snippets/qstringlist/main.cpp 9 | |
\sa append() | |
*/ | |
/*! | |
\fn QStringList::QStringList(const QStringList &other) | |
Constructs a copy of the \a other string list. | |
This operation takes \l{constant time} because QStringList is | |
\l{implicitly shared}, making the process of returning a | |
QStringList from a function very fast. If a shared instance is | |
modified, it will be copied (copy-on-write), and that takes | |
\l{linear time}. | |
\sa operator=() | |
*/ | |
/*! | |
\fn QStringList::QStringList(const QList<QString> &other) | |
Constructs a copy of \a other. | |
This operation takes \l{constant time}, because QStringList is | |
\l{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 \l{linear time}. | |
\sa operator=() | |
*/ | |
/*! | |
\fn void QStringList::sort() | |
Sorts the list of strings in ascending order (case sensitively). | |
Sorting is performed using Qt's qSort() algorithm, | |
which operates in \l{linear-logarithmic time}, i.e. O(\e{n} log \e{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. | |
\sa qSort() | |
*/ | |
void QtPrivate::QStringList_sort(QStringList *that) | |
{ | |
qSort(*that); | |
} | |
#ifdef QT3_SUPPORT | |
/*! | |
\fn QStringList QStringList::split(const QChar &sep, const QString &str, bool allowEmptyEntries) | |
\overload | |
This version of the function uses a QChar as separator. | |
\sa join() QString::section() | |
*/ | |
/*! | |
\fn QStringList QStringList::split(const QString &sep, const QString &str, bool allowEmptyEntries) | |
\overload | |
This version of the function uses a QString as separator. | |
\sa join() QString::section() | |
*/ | |
#ifndef QT_NO_REGEXP | |
/*! | |
\fn QStringList QStringList::split(const QRegExp &sep, const QString &str, bool allowEmptyEntries) | |
Use QString::split(\a sep, QString::SkipEmptyParts) or | |
QString::split(\a sep, QString::KeepEmptyParts) instead. | |
Be aware that the QString::split()'s return value is a | |
QStringList that always contains at least one element, even if \a | |
str is empty. | |
\sa join() QString::section() | |
*/ | |
#endif | |
#endif // QT3_SUPPORT | |
/*! | |
\fn QStringList QStringList::filter(const QString &str, Qt::CaseSensitivity cs) const | |
Returns a list of all the strings containing the substring \a str. | |
If \a cs is \l Qt::CaseSensitive (the default), the string | |
comparison is case sensitive; otherwise the comparison is case | |
insensitive. | |
\snippet doc/src/snippets/qstringlist/main.cpp 5 | |
\snippet doc/src/snippets/qstringlist/main.cpp 10 | |
This is equivalent to | |
\snippet doc/src/snippets/qstringlist/main.cpp 11 | |
\snippet doc/src/snippets/qstringlist/main.cpp 12 | |
\sa contains() | |
*/ | |
QStringList QtPrivate::QStringList_filter(const QStringList *that, const QString &str, | |
Qt::CaseSensitivity cs) | |
{ | |
QStringMatcher matcher(str, cs); | |
QStringList res; | |
for (int i = 0; i < that->size(); ++i) | |
if (matcher.indexIn(that->at(i)) != -1) | |
res << that->at(i); | |
return res; | |
} | |
/*! | |
\fn QBool QStringList::contains(const QString &str, Qt::CaseSensitivity cs) const | |
Returns true if the list contains the string \a str; otherwise | |
returns false. The search is case insensitive if \a cs is | |
Qt::CaseInsensitive; the search is case sensitive by default. | |
\sa indexOf(), lastIndexOf(), QString::contains() | |
*/ | |
QBool QtPrivate::QStringList_contains(const QStringList *that, const QString &str, | |
Qt::CaseSensitivity cs) | |
{ | |
for (int i = 0; i < that->size(); ++i) { | |
const QString & string = that->at(i); | |
if (string.length() == str.length() && str.compare(string, cs) == 0) | |
return QBool(true); | |
} | |
return QBool(false); | |
} | |
#ifndef QT_NO_REGEXP | |
/*! | |
\fn QStringList QStringList::filter(const QRegExp &rx) const | |
\overload | |
Returns a list of all the strings that match the regular | |
expression \a rx. | |
*/ | |
QStringList QtPrivate::QStringList_filter(const QStringList *that, const QRegExp &rx) | |
{ | |
QStringList res; | |
for (int i = 0; i < that->size(); ++i) | |
if (that->at(i).contains(rx)) | |
res << that->at(i); | |
return res; | |
} | |
#endif | |
/*! | |
\fn QStringList &QStringList::replaceInStrings(const QString &before, const QString &after, Qt::CaseSensitivity cs) | |
Returns a string list where every string has had the \a before | |
text replaced with the \a after text wherever the \a before text | |
is found. The \a before text is matched case-sensitively or not | |
depending on the \a cs flag. | |
For example: | |
\snippet doc/src/snippets/qstringlist/main.cpp 5 | |
\snippet doc/src/snippets/qstringlist/main.cpp 13 | |
\sa QString::replace() | |
*/ | |
void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QString &before, | |
const QString &after, Qt::CaseSensitivity cs) | |
{ | |
for (int i = 0; i < that->size(); ++i) | |
(*that)[i].replace(before, after, cs); | |
} | |
#ifndef QT_NO_REGEXP | |
/*! | |
\fn QStringList &QStringList::replaceInStrings(const QRegExp &rx, const QString &after) | |
\overload | |
Replaces every occurrence of the regexp \a rx, in each of the | |
string lists's strings, with \a after. Returns a reference to the | |
string list. | |
For example: | |
\snippet doc/src/snippets/qstringlist/main.cpp 5 | |
\snippet doc/src/snippets/qstringlist/main.cpp 14 | |
For regular expressions that contain \l{capturing parentheses}, | |
occurrences of \bold{\\1}, \bold{\\2}, ..., in \a after are | |
replaced with \a{rx}.cap(1), \a{rx}.cap(2), ... | |
For example: | |
\snippet doc/src/snippets/qstringlist/main.cpp 5 | |
\snippet doc/src/snippets/qstringlist/main.cpp 15 | |
*/ | |
void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegExp &rx, const QString &after) | |
{ | |
for (int i = 0; i < that->size(); ++i) | |
(*that)[i].replace(rx, after); | |
} | |
#endif | |
/*! | |
\fn 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 \a separator (which can be an | |
empty string). | |
\sa QString::split() | |
*/ | |
QString QtPrivate::QStringList_join(const QStringList *that, const QString &sep) | |
{ | |
int totalLength = 0; | |
const int size = that->size(); | |
for (int i = 0; i < size; ++i) | |
totalLength += that->at(i).size(); | |
if(size > 0) | |
totalLength += sep.size() * (size - 1); | |
QString res; | |
if (totalLength == 0) | |
return res; | |
res.reserve(totalLength); | |
for (int i = 0; i < that->size(); ++i) { | |
if (i) | |
res += sep; | |
res += that->at(i); | |
} | |
return res; | |
} | |
/*! | |
\fn QStringList QStringList::operator+(const QStringList &other) const | |
Returns a string list that is the concatenation of this string | |
list with the \a other string list. | |
\sa append() | |
*/ | |
/*! | |
\fn QStringList &QStringList::operator<<(const QString &str) | |
Appends the given string, \a str, to this string list and returns | |
a reference to the string list. | |
\sa append() | |
*/ | |
/*! | |
\fn QStringList &QStringList::operator<<(const QStringList &other) | |
\overload | |
Appends the \a other string list to the string list and returns a reference to | |
the latter string list. | |
*/ | |
#ifndef QT_NO_DATASTREAM | |
/*! | |
\fn QDataStream &operator>>(QDataStream &in, QStringList &list) | |
\relates QStringList | |
Reads a string list from the given \a in stream into the specified | |
\a list. | |
\sa {Serializing Qt Data Types} | |
*/ | |
/*! | |
\fn QDataStream &operator<<(QDataStream &out, const QStringList &list) | |
\relates QStringList | |
Writes the given string \a list to the specified \a out stream. | |
\sa {Serializing Qt Data Types} | |
*/ | |
#endif // QT_NO_DATASTREAM | |
/*! | |
\fn QStringList QStringList::grep(const QString &str, bool cs = true) const | |
Use filter() instead. | |
*/ | |
/*! | |
\fn QStringList QStringList::grep(const QRegExp &rx) const | |
Use filter() instead. | |
*/ | |
/*! | |
\fn QStringList &QStringList::gres(const QString &before, const QString &after, bool cs = true) | |
Use replaceInStrings() instead. | |
*/ | |
/*! | |
\fn QStringList &QStringList::gres(const QRegExp &rx, const QString &after) | |
Use replaceInStrings() instead. | |
*/ | |
/*! | |
\fn Iterator QStringList::fromLast() | |
Use end() instead. | |
\oldcode | |
QStringList::Iterator i = list.fromLast(); | |
\newcode | |
QStringList::Iterator i = list.isEmpty() ? list.end() : --list.end(); | |
\endcode | |
*/ | |
/*! | |
\fn ConstIterator QStringList::fromLast() const | |
Use end() instead. | |
\oldcode | |
QStringList::ConstIterator i = list.fromLast(); | |
\newcode | |
QStringList::ConstIterator i = list.isEmpty() ? list.end() : --list.end(); | |
\endcode | |
*/ | |
#ifndef QT_NO_REGEXP | |
static int indexOfMutating(const QStringList *that, QRegExp &rx, int from) | |
{ | |
if (from < 0) | |
from = qMax(from + that->size(), 0); | |
for (int i = from; i < that->size(); ++i) { | |
if (rx.exactMatch(that->at(i))) | |
return i; | |
} | |
return -1; | |
} | |
static int lastIndexOfMutating(const QStringList *that, QRegExp &rx, int from) | |
{ | |
if (from < 0) | |
from += that->size(); | |
else if (from >= that->size()) | |
from = that->size() - 1; | |
for (int i = from; i >= 0; --i) { | |
if (rx.exactMatch(that->at(i))) | |
return i; | |
} | |
return -1; | |
} | |
/*! | |
\fn int QStringList::indexOf(const QRegExp &rx, int from) const | |
Returns the index position of the first exact match of \a rx in | |
the list, searching forward from index position \a from. Returns | |
-1 if no item matched. | |
By default, this function is case sensitive. | |
\sa lastIndexOf(), contains(), QRegExp::exactMatch() | |
*/ | |
int QtPrivate::QStringList_indexOf(const QStringList *that, const QRegExp &rx, int from) | |
{ | |
QRegExp rx2(rx); | |
return indexOfMutating(that, rx2, from); | |
} | |
/*! | |
\fn int QStringList::indexOf(QRegExp &rx, int from) const | |
\overload indexOf() | |
\since 4.5 | |
Returns the index position of the first exact match of \a rx in | |
the list, searching forward from index position \a from. Returns | |
-1 if no item matched. | |
By default, this function is case sensitive. | |
If an item matched, the \a rx regular expression will contain the | |
matched objects (see QRegExp::matchedLength, QRegExp::cap). | |
\sa lastIndexOf(), contains(), QRegExp::exactMatch() | |
*/ | |
int QtPrivate::QStringList_indexOf(const QStringList *that, QRegExp &rx, int from) | |
{ | |
return indexOfMutating(that, rx, from); | |
} | |
/*! | |
\fn int QStringList::lastIndexOf(const QRegExp &rx, int from) const | |
Returns the index position of the last exact match of \a rx in | |
the list, searching backward from index position \a from. If \a | |
from is -1 (the default), the search starts at the last item. | |
Returns -1 if no item matched. | |
By default, this function is case sensitive. | |
\sa indexOf(), contains(), QRegExp::exactMatch() | |
*/ | |
int QtPrivate::QStringList_lastIndexOf(const QStringList *that, const QRegExp &rx, int from) | |
{ | |
QRegExp rx2(rx); | |
return lastIndexOfMutating(that, rx2, from); | |
} | |
/*! | |
\fn int QStringList::lastIndexOf(QRegExp &rx, int from) const | |
\overload lastIndexOf() | |
\since 4.5 | |
Returns the index position of the last exact match of \a rx in | |
the list, searching backward from index position \a from. If \a | |
from is -1 (the default), the search starts at the last item. | |
Returns -1 if no item matched. | |
By default, this function is case sensitive. | |
If an item matched, the \a rx regular expression will contain the | |
matched objects (see QRegExp::matchedLength, QRegExp::cap). | |
\sa indexOf(), contains(), QRegExp::exactMatch() | |
*/ | |
int QtPrivate::QStringList_lastIndexOf(const QStringList *that, QRegExp &rx, int from) | |
{ | |
return lastIndexOfMutating(that, rx, from); | |
} | |
#endif | |
/*! | |
\fn int QStringList::indexOf(const QString &value, int from = 0) const | |
Returns the index position of the first occurrence of \a value in | |
the list, searching forward from index position \a from. Returns | |
-1 if no item matched. | |
\sa lastIndexOf(), contains(), QList::indexOf() | |
*/ | |
/*! | |
\fn int QStringList::lastIndexOf(const QString &value, int from = -1) const | |
Returns the index position of the last occurrence of \a value in | |
the list, searching backward from index position \a from. If \a | |
from is -1 (the default), the search starts at the last item. | |
Returns -1 if no item matched. | |
By default, this function is case sensitive. | |
\sa indexOf(), QList::lastIndexOf() | |
*/ | |
/*! | |
\fn int QStringList::removeDuplicates() | |
\since 4.5 | |
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. | |
*/ | |
int QtPrivate::QStringList_removeDuplicates(QStringList *that) | |
{ | |
int n = that->size(); | |
int j = 0; | |
QSet<QString> seen; | |
seen.reserve(n); | |
for (int i = 0; i < n; ++i) { | |
const QString &s = that->at(i); | |
if (seen.contains(s)) | |
continue; | |
seen.insert(s); | |
if (j != i) | |
(*that)[j] = s; | |
++j; | |
} | |
if (n != j) | |
that->erase(that->begin() + j, that->end()); | |
return n - j; | |
} | |
QT_END_NAMESPACE |