1 /****************************************************************************

     2 ** 

     3 **

     4 ** Implementation of QStringList

     5 **

     6 ** Created : 990406

     7 **

     8 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.

     9 **

    10 ** This file is part of the tools module of the Qt GUI Toolkit.

    11 **

    12 ** This file may be distributed under the terms of the Q Public License

    13 ** as defined by Trolltech AS of Norway and appearing in the file

    14 ** LICENSE.QPL included in the packaging of this file.

    15 **

    16 ** This file may be distributed and/or modified under the terms of the

    17 ** GNU General Public License version 2 as published by the Free Software

    18 ** Foundation and appearing in the file LICENSE.GPL included in the

    19 ** packaging of this file.

    20 **

    21 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition

    22 ** licenses may use this file in accordance with the Qt Commercial License

    23 ** Agreement provided with the Software.

    24 **

    25 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE

    26 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

    27 **

    28 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for

    29 **   information about Qt Commercial License Agreements.

    30 ** See http://www.trolltech.com/qpl/ for QPL licensing information.

    31 ** See http://www.trolltech.com/gpl/ for GPL licensing information.

    32 **

    33 ** Contact info@trolltech.com if any conditions of this licensing are

    34 ** not clear to you.

    35 **

    36 **********************************************************************/

    37 

    38 #include "qstringlist.h"

    39 

    40 #ifndef QT_NO_STRINGLIST

    41 #include "qstrlist.h"

    42 #include "qdatastream.h"

    43 #include "qtl.h"

    44 

    45 // NOT REVISED

    46 /*!

    47   \class QStringList qstringlist.h

    48   \brief A list of strings.

    49 

    50   \ingroup qtl

    51   \ingroup tools

    52   \ingroup shared

    53 

    54   QStringList is basically a QValueList of QString objects. As opposed

    55   to QStrList, that stores pointers to characters, QStringList deals

    56   with real QString objects.  It is the class of choice whenever you

    57   work with unicode strings.

    58 

    59   Like QString itself, QStringList objects are implicit shared.

    60   Passing them around as value-parameters is both fast and safe.

    61 

    62   Example:

    63   \code

    64 	QStringList list;

    65 

    66 	// three different ways of appending values:

    67 	list.append( "Torben");

    68 	list += "Warwick";

    69 	list << "Matthias" << "Arnt" << "Paul";

    70 

    71 	// sort the list, Arnt's now first

    72 	list.sort();

    73 

    74 	// print it out

    75 	for ( QStringList::Iterator it = list.begin(); it != list.end(); ++it ) {

    76 	    printf( "%s \n", (*it).latin1() );

    77 	}

    78   \endcode

    79 

    80   Convenience methods such as sort(), split(), join() and grep() make

    81   working with QStringList easy.

    82 */

    83 

    84 /*!

    85  \fn QStringList::QStringList()

    86   Creates an empty list.

    87 */

    88 

    89 /*! \fn QStringList::QStringList( const QStringList& l )

    90   Creates a copy of the list. This function is very fast since

    91   QStringList is implicit shared. However, for the programmer this

    92   is the same as a deep copy. If this list or the original one or some

    93   other list referencing the same shared data is modified, then the

    94   modifying list makes a copy first.

    95 */

    96 

    97 /*!

    98   \fn QStringList::QStringList (const QString & i)

    99   Constructs a string list consisting of the single string \a i.

   100   To make longer lists easily, use:

   101   \code

   102     QString s1,s2,s3;

   103     ...

   104     QStringList mylist = QStringList() << s1 << s2 << s3;

   105   \endcode

   106 */

   107 

   108 /*!

   109   \fn QStringList::QStringList (const char* i)

   110   Constructs a string list consisting of the single latin-1 string \a i.

   111 */

   112 

   113 /*! \fn QStringList::QStringList( const QValueList<QString>& l )

   114 

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

   116 */

   117 

   118 /*!

   119   Sorts the list of strings in ascending order.

   120 

   121   Sorting is very fast. It uses the Qt Template Library's

   122   efficient HeapSort implementation that operates in O(n*log n).

   123 */

   124 void QStringList::sort()

   125 {

   126     qHeapSort(*this);

   127 }

   128 

   129 /*!

   130   Splits the string \a str using \a sep as separator. Returns the

   131   list of strings. If \a allowEmptyEntries is TRUE, also empty

   132   entries are inserted into the list, else not. So if you have

   133   a string 'abc..d.e.', a list which contains 'abc', 'd', and 'e'

   134   would be returned if \a allowEmptyEntries is FALSE, but

   135   a list containing 'abc', '', 'd', 'e' and '' would be returned if

   136   \a allowEmptyEntries is TRUE.

   137   If \a str doesn't contain \a sep, a stringlist

   138   with one item, which is the same as \a str, is returned.

   139 

   140   \sa join()

   141 */

   142 

   143 QStringList QStringList::split( const QChar &sep, const QString &str, bool allowEmptyEntries )

   144 {

   145     return split( QString( sep ), str, allowEmptyEntries );

   146 }

   147 

   148 /*!

   149   Splits the string \a str using \a sep as separator. Returns the

   150   list of strings. If \a allowEmptyEntries is TRUE, also empty

   151   entries are inserted into the list, else not. So if you have

   152   a string 'abc..d.e.', a list which contains 'abc', 'd', and 'e'

   153   would be returned if \a allowEmptyEntries is FALSE, but

   154   a list containing 'abc', '', 'd', 'e' and '' would be returned if

   155   \a allowEmptyEntries is TRUE.

   156   If \a str doesn't contain \a sep, a stringlist

   157   with one item, which is the same as \a str, is returned.

   158 

   159   \sa join()

   160 */

   161 

   162 QStringList QStringList::split( const QString &sep, const QString &str, bool allowEmptyEntries )

   163 {

   164     QStringList lst;

   165 

   166     int j = 0;

   167     int i = str.find( sep, j );

   168 

   169     while ( i != -1 ) {

   170 	if ( str.mid( j, i - j ).length() > 0 )

   171 	    lst << str.mid( j, i - j );

   172 	else if ( allowEmptyEntries )

   173 	    lst << QString::null;

   174 	j = i + sep.length();

   175 	i = str.find( sep, j );

   176     }

   177 

   178     int l = str.length() - 1;

   179     if ( str.mid( j, l - j + 1 ).length() > 0 )

   180 	lst << str.mid( j, l - j + 1 );

   181     else if ( allowEmptyEntries )

   182 	lst << QString::null;

   183 

   184     return lst;

   185 }

   186 

   187 /*!

   188   Splits the string \a str using the regular expression \a sep as separator. Returns the

   189   list of strings. If \a allowEmptyEntries is TRUE, also empty

   190   entries are inserted into the list, else not. So if you have

   191   a string 'abc..d.e.', a list which contains 'abc', 'd', and 'e'

   192   would be returned if \a allowEmptyEntries is FALSE, but

   193   a list containing 'abc', '', 'd', 'e' and '' would be returned if

   194   \a allowEmptyEntries is TRUE.

   195   If \a str doesn't contain \a sep, a stringlist

   196   with one item, which is the same as \a str, is returned.

   197 

   198   \sa join()

   199 */

   200 

   201 QStringList QStringList::split( const QRegExp &sep, const QString &str, bool allowEmptyEntries )

   202 {

   203     QStringList lst;

   204 

   205     int j = 0;

   206     int len = 0;

   207     int i = sep.match( str, j, &len );

   208 

   209     while ( i != -1 ) {

   210 	if ( str.mid( j, i - j ).length() > 0 )

   211 	    lst << str.mid( j, i - j );

   212 	else if ( allowEmptyEntries )

   213 	    lst << QString::null;

   214 	j = i + len;

   215 	i = sep.match( str, j, &len );

   216     }

   217 

   218     int l = str.length() - 1;

   219     if ( str.mid( j, l - j + 1 ).length() > 0 )

   220 	lst << str.mid( j, l - j + 1 );

   221     else if ( allowEmptyEntries )

   222 	lst << QString::null;

   223 

   224     return lst;

   225 }

   226 

   227 /*!

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

   229 

   230   If \a cs is TRUE, the grep is done case sensitively, else not.

   231 */

   232 

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

   234 {

   235     QStringList res;

   236     for ( QStringList::ConstIterator it = begin(); it != end(); ++it )

   237 	if ( (*it).contains( str, cs ) )

   238 	    res << *it;

   239 

   240     return res;

   241 }

   242 

   243 /*!

   244   Returns a list of all strings containing a substring that matches

   245   the regular expression \a expr.

   246 */

   247 

   248 QStringList QStringList::grep( const QRegExp &expr ) const

   249 {

   250     QStringList res;

   251     for ( QStringList::ConstIterator it = begin(); it != end(); ++it )

   252 	if ( (*it).contains( expr ) )

   253 	    res << *it;

   254 

   255     return res;

   256 }

   257 

   258 /*!

   259   Joins the stringlist into a single string with each element

   260   separated by \a sep.

   261 

   262   \sa split()

   263 */

   264 QString QStringList::join( const QString &sep ) const

   265 {

   266     QString res;

   267     bool alredy = FALSE;

   268     for ( QStringList::ConstIterator it = begin(); it != end(); ++it ) {

   269 	if ( alredy )

   270 	    res += sep;

   271 	alredy = TRUE;

   272 	res += *it;

   273     }

   274 

   275     return res;

   276 }

   277 

   278 #ifndef QT_NO_DATASTREAM

   279 Q_EXPORT QDataStream &operator>>( QDataStream & s, QStringList& l )

   280 {

   281     return s >> (QValueList<QString>&)l;

   282 }

   283 

   284 Q_EXPORT QDataStream &operator<<( QDataStream & s, const QStringList& l )

   285 {

   286     return s << (const QValueList<QString>&)l;

   287 }

   288 #endif

   289 

   290 /*!

   291   Converts from a QStrList (ASCII) to a QStringList (Unicode).

   292 */

   293 QStringList QStringList::fromStrList(const QStrList& ascii)

   294 {

   295     QStringList res;

   296     const char * s;

   297     for ( QStrListIterator it(ascii); (s=it.current()); ++it )

   298 	res << s;

   299     return res;

   300 }

   301 

   302 #endif //QT_NO_STRINGLIST