pstring.h

Go to the documentation of this file.
00001 /*
00002  * pstring.h
00003  *
00004  * Character string class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
00025  * All Rights Reserved.
00026  *
00027  * Contributor(s): ______________________________________.
00028  *
00029  * $Log: pstring.h,v $
00030  * Revision 1.91  2006/08/11 08:18:57  csoutheren
00031  * Add PCaselessString constructor for std::string
00032  *
00033  * Revision 1.90  2006/08/11 04:44:48  csoutheren
00034  * Add operator to convert PString to std::string
00035  *
00036  * Revision 1.89  2006/07/10 09:15:28  shorne
00037  * Corrected PString::Tokenize() documentation Thx. David Corrie
00038  *
00039  * Revision 1.88  2006/06/30 00:56:31  csoutheren
00040  * Applied 1494931 - various pwlib bug fixes and enhancement
00041  * Thanks to Frederich Heem
00042  *
00043  * Revision 1.87  2006/06/21 03:28:41  csoutheren
00044  * Various cleanups thanks for Frederic Heem
00045  *
00046  * Revision 1.86  2006/04/09 07:05:40  rjongbloed
00047  * Moved output stream operator for PString from sockets code to string code and fixed
00048  *   its implemetation to continue to use PrintOn. Why it was added is unknown, probably
00049  *   a compiler issue, but it should not be in a random source file!
00050  *
00051  * Revision 1.85  2005/12/15 21:14:34  dsandras
00052  * Fixed from Alexander Larsson <alexl _AT__ redhat.com> for gcc 4.1 compilation. Thanks!
00053  *
00054  * Revision 1.84  2005/11/30 12:47:38  csoutheren
00055  * Removed tabs, reformatted some code, and changed tags for Doxygen
00056  *
00057  * Revision 1.83  2005/11/25 03:43:47  csoutheren
00058  * Fixed function argument comments to be compatible with Doxygen
00059  *
00060  * Revision 1.82  2005/09/18 11:05:36  dominance
00061  * include/ptlib/channel.h, include/ptlib/pstring.h, src/ptlib/common/contain.cxx,
00062  * src/ptlib/common/pchannel.cxx:
00063  *   correct the STL defined checking to use proper syntax.
00064  *
00065  * include/ptlib/object.h:
00066  *   re-add typedef to compile on mingw
00067  *
00068  * make/ptlib-config.in:
00069  *   import a long-standing fix from the Debian packs which allows usage of
00070  *   ptlib-config without manually adding -lpt for each of the subsequent
00071  *   projects
00072  *
00073  * Revision 1.81  2004/12/22 04:04:36  dereksmithies
00074  * Modify description of parameters for PString::Replace()
00075  *
00076  * Revision 1.80  2004/11/23 11:33:08  csoutheren
00077  * Fixed problem with RemoveAt returning invalid pointer in some cases,
00078  * and added extra documentation on this case.
00079  * Thanks to Diego Tartara for pointing out this potential problem
00080  *
00081  * Revision 1.79  2004/10/21 13:04:20  rjongbloed
00082  * Fixed possibility of const operator[] on PStringArray returning a NULL reference. This
00083  *   function should return a non-lvalue PString anyway as it is const!
00084  *
00085  * Revision 1.78  2004/08/16 08:49:59  csoutheren
00086  * Removed error when compiling with gcc
00087  *
00088  * Revision 1.77  2004/08/16 06:40:59  csoutheren
00089  * Added adapters template to make device plugins available via the abstract factory interface
00090  *
00091  * Revision 1.76  2004/06/01 05:54:18  csoutheren
00092  * Added <vector> and <string>
00093  *
00094  * Revision 1.75  2004/06/01 05:21:38  csoutheren
00095  * Added conversions between std::string and PString, and vector<PString> and PStringArray
00096  *
00097  * Revision 1.74  2004/05/04 11:10:36  rjongbloed
00098  * Fixed usage of MakeEmpty() with PStringStream.
00099  *
00100  * Revision 1.73  2004/04/18 04:33:36  rjongbloed
00101  * Changed all operators that return BOOL to return standard type bool. This is primarily
00102  *   for improved compatibility with std STL usage removing many warnings.
00103  *
00104  * Revision 1.72  2004/04/11 13:26:25  csoutheren
00105  * Removed namespace problems and removed warnings for Windows <string>
00106  *
00107  * Revision 1.71  2004/04/09 06:38:10  rjongbloed
00108  * Fixed compatibility with STL based streams, eg as used by VC++2003
00109  *
00110  * Revision 1.70  2004/04/09 03:42:34  csoutheren
00111  * Removed all usages of "virtual inline" and "inline virtual"
00112  *
00113  * Revision 1.69  2004/04/03 06:54:22  rjongbloed
00114  * Many and various changes to support new Visual C++ 2003
00115  *
00116  * Revision 1.68  2004/02/23 00:44:38  csoutheren
00117  * A completely different, other regex include hack to avoid requiring
00118  * the sources when using a header-file only environment
00119  *
00120  * Revision 1.67  2004/02/23 00:26:05  csoutheren
00121  * Finally, a generic and elegant fix for the regex include hacks.  Thanks to Roger Hardiman
00122  *
00123  * Revision 1.66  2004/02/11 05:09:14  csoutheren
00124  * Fixed problems with regex libraries on Solaris, and with host OS numbering
00125  * being a quoted string rather than a number. Thanks to Chad Attermann
00126  * Fixed problems SSL detection problems thanks to Michal Zygmuntowicz
00127  *
00128  * Revision 1.65  2004/02/08 11:13:11  rjongbloed
00129  * Fixed crash in heavily loaded multi-threaded systems using simultaneous sorted
00130  *   lists, Thanks Federico Pinna, Fabrizio Ammollo and the gang at Reitek S.p.A.
00131  *
00132  * Revision 1.64  2004/01/18 13:43:48  rjongbloed
00133  * Fixed broken PString::MakeEmpty() function and moved implementations to .inl file.
00134  *
00135  * Revision 1.63  2004/01/17 18:15:24  csoutheren
00136  * Fixed multi-threading problem with PString::Empty
00137  * Created PString::MakeEmpty for efficient emptying of existing strings
00138  *
00139  * Revision 1.62  2004/01/16 13:24:37  csoutheren
00140  * Changed PString::Empty to be thread-safe
00141  * Fixed PContainer::SetMinSize and PAbstractArray::SetSize, thanks to 123@call2ua.com
00142  * Fixed PString::FindLast, thanks to Andreas Sikkema
00143  *
00144  * Revision 1.61  2003/12/13 23:08:46  csoutheren
00145  * Changed PRegularExpression to allow a copy constructor and operator =
00146  *
00147  * Revision 1.60  2003/12/10 03:28:50  csoutheren
00148  * Removed compile time warning under Linux
00149  *
00150  * Revision 1.59  2003/12/07 05:50:49  csoutheren
00151  * Blocked operator = for PRegularExpression
00152  *
00153  * Revision 1.58  2003/12/04 13:10:38  csoutheren
00154  * Made PRegularExpression copy constructor private to avoid accidental usage (and subsequent crash)
00155  *
00156  * Revision 1.57  2003/05/14 00:46:47  rjongbloed
00157  * Added constructor to string lists/arrays etc that takes a single PString.
00158  *
00159  * Revision 1.56  2003/03/31 01:23:56  robertj
00160  * Added ReadFrom functions for standard container classes such as
00161  *   PIntArray and PStringList etc
00162  *
00163  * Revision 1.55  2003/03/05 08:48:32  robertj
00164  * Added PStringArray::ToCharAray() function at suggestion of Ravelli Rossano
00165  *
00166  * Revision 1.54  2002/11/12 09:17:44  robertj
00167  * Added PString::NumCompare() as functional equivalent of strncmp().
00168  * Added PSortedStringList::GetNextStringsIndex() to do searches of binary
00169  *   tree on partal strings.
00170  *
00171  * Revision 1.53  2002/10/31 05:53:44  robertj
00172  * Now comprehensively stated that a PString is ALWAYS an 8 bit string as
00173  *   there are far too many inheerent assumptions every to make it 16 bit.
00174  * Added UTF-8/UCS-2 conversion functions to PString.
00175  *
00176  * Revision 1.52  2002/09/16 01:08:59  robertj
00177  * Added #define so can select if #pragma interface/implementation is used on
00178  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00179  *
00180  * Revision 1.51  2002/08/14 00:43:39  robertj
00181  * Added ability to have fixed maximum length PStringStream's so does not do
00182  *   unwanted malloc()'s while outputing data.
00183  *
00184  * Revision 1.50  2002/04/09 02:30:18  robertj
00185  * Removed GCC3 variable as __GNUC__ can be used instead, thanks jason Spence
00186  *
00187  * Revision 1.49  2002/02/15 04:29:31  robertj
00188  * Added PString::Empty() to return the primordial empty string. Saves on a
00189  *   couple of memory allocations for every empty string ever used.
00190  *
00191  * Revision 1.48  2002/01/26 23:55:55  craigs
00192  * Changed for GCC 3.0 compatibility, thanks to manty@manty.net
00193  *
00194  * Revision 1.47  2002/01/22 01:03:57  craigs
00195  * Added operator += and operator + functions to PStringArray and PStringList
00196  * Added AppendString operator to PStringArray
00197  *
00198  * Revision 1.46  2001/10/17 05:09:22  robertj
00199  * Added contructors and assigmnent operators so integer types can be
00200  *   automatically converted to strings.
00201  *
00202  * Revision 1.45  2001/08/11 07:57:30  rogerh
00203  * Add Mac OS Carbon changes from John Woods <jfw@jfwhome.funhouse.com>
00204  *
00205  * Revision 1.44  2001/04/18 04:10:15  robertj
00206  * Removed hash function for caseless strings as confuses mixed dictionaries.
00207  *
00208  * Revision 1.43  2001/04/18 01:20:58  robertj
00209  * Fixed problem with hash function for short strings, thanks Patrick Koorevaar.
00210  * Also fixed hash function for caseless strings.
00211  *
00212  * Revision 1.42  2001/02/21 03:38:37  robertj
00213  * Added ability to copy between various string lists/arrays etc during construction.
00214  *
00215  * Revision 1.41  2001/02/13 04:39:08  robertj
00216  * Fixed problem with operator= in container classes. Some containers will
00217  *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
00218  *   needed to add a new AssignContents() function to all containers.
00219  *
00220  * Revision 1.40  1999/08/22 12:13:43  robertj
00221  * Fixed warning when using inlines on older GNU compiler
00222  *
00223  * Revision 1.39  1999/05/28 14:01:22  robertj
00224  * Added initialisers to string containers (list, sorted list and set).
00225  *
00226  * Revision 1.38  1999/03/09 09:34:05  robertj
00227  * Fixed typo's.
00228  *
00229  * Revision 1.37  1999/03/09 02:59:50  robertj
00230  * Changed comments to doc++ compatible documentation.
00231  *
00232  * Revision 1.36  1999/02/16 08:11:09  robertj
00233  * MSVC 6.0 compatibility changes.
00234  *
00235  * Revision 1.35  1998/09/23 06:21:12  robertj
00236  * Added open source copyright license.
00237  *
00238  * Revision 1.34  1998/01/26 00:33:46  robertj
00239  * Added FindRegEx function to PString that returns position and length.
00240  * Added Execute() functions to PRegularExpression that take PINDEX references instead of PIntArrays.
00241  * Added static function to PRegularExpression to escape all special operator characters in a string.
00242  *
00243  * Revision 1.33  1998/01/05 10:39:35  robertj
00244  * Fixed "typesafe" templates/macros for dictionaries, especially on GNU.
00245  *
00246  * Revision 1.32  1997/12/11 13:32:47  robertj
00247  * Added AsUnsigned() function to convert string to DWORD.
00248  *
00249  * Revision 1.31  1997/12/11 10:29:49  robertj
00250  * Added type correct Contains() function to dictionaries.
00251  *
00252  * Revision 1.30  1997/07/08 13:13:47  robertj
00253  * DLL support.
00254  *
00255  * Revision 1.29  1997/06/10 11:36:32  craigs
00256  * Added inline statements to allow compilation uder Unix
00257  *
00258  * Revision 1.28  1997/06/08 04:48:58  robertj
00259  * Added regular expressions.
00260  * Fixed non-template class descendent order.
00261  *
00262  * Revision 1.27  1997/05/16 12:10:12  robertj
00263  * Fixed G++ compatibility bug.
00264  *
00265  * Revision 1.26  1996/10/08 13:13:38  robertj
00266  * Added operator += and &= for char so no implicit PString construction.
00267  *
00268  * Revision 1.25  1996/09/14 12:52:39  robertj
00269  * Added operator! for !IsEmpty().
00270  *
00271  * Revision 1.24  1996/08/17 10:00:25  robertj
00272  * Changes for Windows DLL support.
00273  *
00274  * Revision 1.23  1996/05/26 03:27:02  robertj
00275  * Compatibility to GNU 2.7.x
00276  *
00277  * Revision 1.22  1996/03/31 08:51:22  robertj
00278  * Added RemoveAt() function to remove entries from dictionaries.
00279  *
00280  * Revision 1.21  1996/03/10 13:15:50  robertj
00281  * Added operator() to template version.
00282  *
00283  * Revision 1.20  1996/02/19 13:17:33  robertj
00284  * Removed PCaselessString hash function to fix dictionary match failure.
00285  * Added operator() to do string dictionary lookup with default value.
00286  *
00287  * Revision 1.19  1996/02/08 12:19:16  robertj
00288  * Added new operators to PString for case insensitive compare and spaced concatenate.
00289  *
00290  * Revision 1.18  1996/01/24 14:43:15  robertj
00291  * Added initialisers to string dictionaries.
00292  *
00293  * Revision 1.17  1996/01/23 13:15:17  robertj
00294  * Added Replace() function to strings.
00295  * Mac Metrowerks compiler support.
00296  * String searching algorithm rewrite.
00297  *
00298  * Revision 1.16  1996/01/02 12:04:31  robertj
00299  * Mac OS compatibility changes.
00300  * Removed requirement that PArray elements have parameterless constructor..
00301  *
00302  * Revision 1.15  1995/12/23 03:46:23  robertj
00303  * Added operators for include and exclude from string set.
00304  *
00305  * Revision 1.14  1995/10/14 15:02:56  robertj
00306  * Changed arrays to not break references, but strings still need to.
00307  *
00308  * Revision 1.13  1995/06/17 11:13:08  robertj
00309  * Documentation update.
00310  *
00311  * Revision 1.12  1995/06/17 00:43:40  robertj
00312  * Added flag for PStringArray constructor to create caseless strings.
00313  *
00314  * Revision 1.11  1995/06/04 12:34:57  robertj
00315  * Better C++ compatibility (with BC++)
00316  *
00317  * Revision 1.10  1995/04/02 09:27:23  robertj
00318  * Added "balloon" help.
00319  *
00320  * Revision 1.9  1995/03/14 12:42:16  robertj
00321  * Updated documentation to use HTML codes.
00322  *
00323  * Revision 1.8  1995/03/12  04:44:39  robertj
00324  * Fixed use of PCaselessString as dictionary key.
00325  *
00326  * Revision 1.7  1995/02/05  00:48:09  robertj
00327  * Fixed template version.
00328  *
00329  * Revision 1.6  1995/01/15  04:50:20  robertj
00330  * Added inlines on friend functions, required by GNU compiler.
00331  *
00332  * Revision 1.5  1995/01/10  11:43:41  robertj
00333  * Removed PString parameter in stdarg function for GNU C++ compatibility.
00334  *
00335  * Revision 1.4  1995/01/09  12:33:44  robertj
00336  * Removed unnecesary return value from I/O functions.
00337  * Changed function names due to Mac port.
00338  *
00339  * Revision 1.3  1994/12/21  11:53:21  robertj
00340  * Documentation and variable normalisation.
00341  *
00342  * Revision 1.2  1994/12/12  13:13:13  robertj
00343  * Fixed bugs in PString mods just made.
00344  *
00345  * Revision 1.1  1994/12/12  09:59:37  robertj
00346  * Initial revision
00347  *
00348  */
00349 #ifndef __PSTRING__
00350 #define __PSTRING__
00351 
00352 #ifdef P_USE_PRAGMA
00353 #pragma interface
00354 #endif
00355 
00356 #include <string>
00357 #include <vector>
00358 #include <ptlib/array.h>
00359 
00361 // PString class
00362 
00363 class PStringArray;
00364 class PRegularExpression;
00365 
00400 class PString : public PCharArray {
00401   PCLASSINFO(PString, PCharArray);
00402 
00403 //  using namespace std;
00404 
00405   public:
00411     PINLINE PString();
00412 
00416     PINLINE PString(
00417       const PString & str  
00418     );
00419 
00422     PINLINE PString(
00423       const std::string & str
00424     );
00425 
00434     PString(
00435       const char * cstr 
00436     );
00437 
00442     PString(
00443       const WORD * ustr 
00444     );
00445 
00459     PString(
00460       const char * cstr,  
00461       PINDEX len          
00462     );
00463 
00474     PString(
00475       const WORD * ustr,  
00476       PINDEX len          
00477     );
00478 
00489     PString(
00490       const PWORDArray & ustr 
00491     );
00492 
00501     PString(
00502       char ch    
00503     );
00504 
00509     PString(
00510       short n   
00511     );
00512 
00517     PString(
00518       unsigned short n   
00519     );
00520 
00525     PString(
00526       int n   
00527     );
00528 
00533     PString(
00534       unsigned int n   
00535     );
00536 
00541     PString(
00542       long n   
00543     );
00544 
00549     PString(
00550       unsigned long n   
00551     );
00552 
00557     PString(
00558       PInt64 n   
00559     );
00560 
00565     PString(
00566       PUInt64 n   
00567     );
00568 
00569  
00570     enum ConversionType {
00571       Pascal,   // Data is a length byte followed by characters.
00572       Basic,    // Data is two length bytes followed by characters.
00573       Literal,  // Data is C language style string with \ escape codes.
00574       Signed,   // Convert a signed integer to a string.
00575       Unsigned, // Convert an unsigned integer to a string.
00576       Decimal,  // Convert a real number to a string in decimal format.
00577       Exponent, // Convert a real number to a string in exponent format.
00578       Printf,   // Formatted output, sprintf() style function.
00579       NumConversionTypes
00580     };
00581     /* Type of conversion to make in the conversion constructors.
00582      */
00583 
00584     /* Contruct a new string converting from the spcified data source into
00585        a string array.
00586      */
00587     PString(
00588       ConversionType type,  
00589       const char * str,    
00590       ...                 
00591     );
00592     PString(
00593       ConversionType type,  
00594       long value,           
00595       unsigned base = 10    
00596     );
00597     PString(
00598       ConversionType type,  
00599       double value,         
00600       unsigned places       
00601     );
00602 
00610     PString & operator=(
00611       const PString & str  
00612     );
00613 
00623     PString & operator=(
00624       const char * cstr  
00625     );
00626 
00635     PString & operator=(
00636       char ch            
00637     );
00638 
00643     PString & operator=(
00644       short n   
00645     );
00646 
00651     PString & operator=(
00652       unsigned short n   
00653     );
00654 
00659     PString & operator=(
00660       int n   
00661     );
00662 
00667     PString & operator=(
00668       unsigned int n   
00669     );
00670 
00675     PString & operator=(
00676       long n   
00677     );
00678 
00683     PString & operator=(
00684       unsigned long n   
00685     );
00686 
00691     PString & operator=(
00692       PInt64 n   
00693     );
00694 
00699     PString & operator=(
00700       PUInt64 n   
00701     );
00702 
00705     virtual PString & MakeEmpty();
00706 
00709     static PString Empty();
00711 
00718     virtual PObject * Clone() const;
00719 
00729     virtual Comparison Compare(
00730       const PObject & obj   
00731     ) const;
00732 
00735     virtual void PrintOn(
00736       ostream & strm  
00737     ) const;
00738 
00744     virtual void ReadFrom(
00745       istream & strm  
00746     );
00747 
00761     virtual PINDEX HashFunction() const;
00763 
00778     virtual BOOL SetSize(
00779       PINDEX newSize  
00780     );
00781 
00790     virtual BOOL IsEmpty() const;
00791 
00800     virtual BOOL MakeUnique();
00802 
00803 
00816     BOOL MakeMinimumSize();
00817 
00826     PINLINE PINDEX GetLength() const;
00827 
00834     bool operator!() const;
00836 
00845     PString operator+(
00846       const PString & str   
00847     ) const;
00848 
00860     PString operator+(
00861       const char * cstr  
00862     ) const;
00863 
00875     PString operator+(
00876       char ch   
00877     ) const;
00878 
00890     friend PString operator+(
00891       const char * cstr,    
00892       const PString & str   
00893     );
00894 
00906     friend PString operator+(
00907       char  c,              
00908       const PString & str   
00909     );
00910 
00916     PString & operator+=(
00917       const PString & str   
00918     );
00919 
00929     PString & operator+=(
00930       const char * cstr  
00931     );
00932 
00942     PString & operator+=(
00943       char ch   
00944     );
00945 
00946 
00953     PString operator&(
00954       const PString & str   
00955     ) const;
00956 
00973     PString operator&(
00974       const char * cstr  
00975     ) const;
00976 
00993     PString operator&(
00994       char ch   
00995     ) const;
00996 
01013     friend PString operator&(
01014       const char * cstr,    
01015       const PString & str   
01016     );
01017 
01034     friend PString operator&(
01035       char  ch,              
01036       const PString & str   
01037     );
01038 
01044     PString & operator&=(
01045       const PString & str   
01046     );
01047 
01062     PString & operator&=(
01063       const char * cstr  
01064     );
01065 
01066 
01081     PString & operator&=(
01082       char ch  
01083     );
01085 
01086 
01094     bool operator*=(
01095       const PString & str  
01096     ) const;
01097 
01105     bool operator==(
01106       const PObject & str  
01107     ) const;
01108 
01116     bool operator!=(
01117       const PObject & str  
01118     ) const;
01119 
01127     bool operator<(
01128       const PObject & str  
01129     ) const;
01130 
01138     bool operator>(
01139       const PObject & str  
01140     ) const;
01141 
01149     bool operator<=(
01150       const PObject & str  
01151     ) const;
01152 
01160     bool operator>=(
01161       const PObject & str  
01162     ) const;
01163 
01164 
01175     bool operator*=(
01176       const char * cstr  
01177     ) const;
01178 
01189     bool operator==(
01190       const char * cstr  
01191     ) const;
01192 
01203     bool operator!=(
01204       const char * cstr  
01205     ) const;
01206 
01217     bool operator<(
01218       const char * cstr  
01219     ) const;
01220 
01231     bool operator>(
01232       const char * cstr  
01233     ) const;
01234 
01245     bool operator<=(
01246       const char * cstr  
01247     ) const;
01248 
01259     bool operator>=(
01260       const char * cstr  
01261     ) const;
01262 
01274     Comparison NumCompare(
01275       const PString & str,        
01276       PINDEX count = P_MAX_INDEX, 
01277       PINDEX offset = 0           
01278     ) const;
01279 
01291     Comparison NumCompare(
01292       const char * cstr,          
01293       PINDEX count = P_MAX_INDEX, 
01294       PINDEX offset = 0           
01295     ) const;
01297 
01298 
01302     PINDEX Find(
01303       char ch,              
01304       PINDEX offset = 0     
01305     ) const;
01306 
01308     PINDEX Find(
01309       const PString & str,  
01310       PINDEX offset = 0     
01311     ) const;
01312 
01313     /* Locate the position within the string of the character or substring. The
01314        search will begin at the character offset provided.
01315        
01316        If #offset# is beyond the length of the string, then the
01317        function will always return #P_MAX_INDEX#.
01318        
01319        The matching will be for identical character or string. If a search
01320        ignoring case is required then the string should be converted to a
01321        #PCaselessString# before the search is made.
01322 
01323        @return
01324        position of character or substring in the string, or P_MAX_INDEX if the
01325        character or substring is not in the string.
01326      */
01327     PINDEX Find(
01328       const char * cstr,    
01329       PINDEX offset = 0     
01330     ) const;
01331 
01333     PINDEX FindLast(
01334       char ch,                     
01335       PINDEX offset = P_MAX_INDEX  
01336     ) const;
01337 
01339     PINDEX FindLast(
01340       const PString & str,         
01341       PINDEX offset = P_MAX_INDEX  
01342     ) const;
01343 
01361     PINDEX FindLast(
01362       const char * cstr,           
01363       PINDEX offset = P_MAX_INDEX  
01364     ) const;
01365 
01367     PINDEX FindOneOf(
01368       const PString & set,  
01369       PINDEX offset = 0     
01370     ) const;
01371 
01386     PINDEX FindOneOf(
01387       const char * cset,    
01388       PINDEX offset = 0     
01389     ) const;
01390 
01401     PINDEX FindRegEx(
01402       const PRegularExpression & regex, 
01403       PINDEX offset = 0                 
01404     ) const;
01405 
01416     BOOL FindRegEx(
01417       const PRegularExpression & regex, 
01418       PINDEX & pos,                     
01419       PINDEX & len,                     
01420       PINDEX offset = 0,                
01421       PINDEX maxPos = P_MAX_INDEX       
01422     ) const;
01423 
01424 
01435     void Replace(
01436       const PString & target,   
01437       const PString & subs,     
01438       BOOL all = FALSE,         
01439       PINDEX offset = 0         
01440     );
01441 
01449     void Splice(
01450       const PString & str,  
01451       PINDEX pos,           
01452       PINDEX len = 0        
01453     );
01454 
01462     void Splice(
01463       const char * cstr,    
01464       PINDEX pos,           
01465       PINDEX len = 0        
01466     );
01467 
01474     void Delete(
01475       PINDEX start,   
01476       PINDEX len      
01477     );
01479 
01480 
01500     PString operator()(
01501       PINDEX start,  
01502       PINDEX end     
01503     ) const;
01504 
01519     PString Left(
01520       PINDEX len   
01521     ) const;
01522 
01537     PString Right(
01538       PINDEX len   
01539     ) const;
01540 
01557     PString Mid(
01558       PINDEX start,             
01559       PINDEX len = P_MAX_INDEX  
01560     ) const;
01561 
01562 
01570     PString LeftTrim() const;
01571 
01579     PString RightTrim() const;
01580 
01589     PString Trim() const;
01590 
01591 
01600     PString ToLower() const;
01601 
01610     PString ToUpper() const;
01611 
01612 
01614     PStringArray Tokenise(
01615       const PString & separators,
01617       BOOL onePerSeparator = TRUE
01619     ) const;
01644     PStringArray Tokenise(
01645       const char * cseparators,
01647       BOOL onePerSeparator = TRUE
01649     ) const;
01650 
01664     PStringArray Lines() const;
01666 
01683     PString & sprintf(
01684       const char * cfmt,   
01685       ...                  
01686     );
01687 
01702     friend PString psprintf(
01703       const char * cfmt,   
01704       ...                  
01705     );
01706 
01708     PString & vsprintf(
01709       const PString & fmt, 
01710       va_list args         
01711     );
01726     PString & vsprintf(
01727       const char * cfmt,   
01728       va_list args         
01729     );
01730 
01732     friend PString pvsprintf(
01733       const char * cfmt,   
01734       va_list args         
01735     );
01750     friend PString pvsprintf(
01751       const PString & fmt, 
01752       va_list args         
01753     );
01754 
01755 
01768     long AsInteger(
01769       unsigned base = 10    
01770     ) const;
01783     DWORD AsUnsigned(
01784       unsigned base = 10    
01785     ) const;
01799     PInt64 AsInt64(
01800       unsigned base = 10    
01801     ) const;
01815     PUInt64 AsUnsigned64(
01816       unsigned base = 10    
01817     ) const;
01818 
01829     double AsReal() const;
01830      
01834     PWORDArray AsUCS2() const;
01835 
01846     PBYTEArray ToPascal() const;
01847 
01856     PString ToLiteral() const;
01857 
01865     operator const unsigned char *() const;
01866 
01869     operator std::string () const
01870     { return std::string(theArray); }
01871 
01873 
01874 
01875   protected:
01876     void InternalFromUCS2(
01877       const WORD * ptr,
01878       PINDEX len
01879     );
01880     virtual Comparison InternalCompare(
01881       PINDEX offset,      // Offset into string to compare.
01882       char c              // Character to compare against.
01883     ) const;
01884     virtual Comparison InternalCompare(
01885       PINDEX offset,      // Offset into string to compare.
01886       PINDEX length,      // Number of characters to compare.
01887       const char * cstr   // C string to compare against.
01888     ) const;
01889     /* Internal function to compare the current string value against the
01890        specified C string.
01891 
01892        @return
01893        relative rank of the two strings.
01894      */
01895 
01896     PString(int dummy, const PString * str);
01897 };
01898 
01899 
01900 inline ostream & operator<<(ostream & stream, const PString & string)
01901 {
01902   string.PrintOn(stream);
01903   return stream;
01904 }
01905 
01906 
01908 
01918 class PCaselessString : public PString
01919 {
01920   PCLASSINFO(PCaselessString, PString);
01921 
01922   public:
01925     PCaselessString();
01926 
01930     PCaselessString(
01931       const char * cstr   
01932     );
01933 
01938     PCaselessString(
01939       const PString & str  
01940     );
01941 
01942 
01945     PCaselessString(
01946       const std::string & str  
01947       ) : PString(str)
01948     { }
01949 
01957     PCaselessString & operator=(
01958       const PString & str  
01959     );
01960 
01970     PCaselessString & operator=(
01971       const char * cstr  
01972     );
01973 
01982     PCaselessString & operator=(
01983       char ch            
01984     );
01985 
01986 
01987   // Overrides from class PObject
01992     virtual PObject * Clone() const;
01993 
01994   protected:
01995   // Overrides from class PString
01996     virtual Comparison InternalCompare(
01997       PINDEX offset,      // Offset into string to compare.
01998       char c              // Character to compare against.
01999     ) const;
02000     virtual Comparison InternalCompare(
02001       PINDEX offset,      // Offset into string to compare.
02002       PINDEX length,      // Number of characters to compare.
02003       const char * cstr   // C string to compare against.
02004     ) const;
02005     /* Internal function to compare the current string value against the
02006        specified C string.
02007 
02008        @return
02009        relative rank of the two strings or characters.
02010      */
02011 
02012     PCaselessString(int dummy, const PCaselessString * str);
02013 };
02014 
02016 
02017 class PStringStream;
02018 
02025 class PStringStream : public PString, public iostream
02026 {
02027   PCLASSINFO(PStringStream, PString);
02028 
02029   public:
02035     PStringStream();
02036 
02041     PStringStream(
02042       PINDEX fixedBufferSize
02043     );
02044 
02051     PStringStream(
02052       const PString & str   
02053     );
02054 
02059     PStringStream(
02060       const char * cstr   
02061     );
02062 
02065     virtual PString & MakeEmpty();
02066 
02078     PStringStream & operator=(
02079       const PStringStream & strm
02080     );
02081 
02093     PStringStream & operator=(
02094       const PString & str  
02095     );
02096 
02112     PStringStream & operator=(
02113       const char * cstr  
02114     );
02115 
02124     PStringStream & operator=(
02125       char ch            
02126     );
02127 
02128 
02130     virtual ~PStringStream();
02131 
02132 
02133   protected:
02134     virtual void AssignContents(const PContainer & cont);
02135 
02136   private:
02137     PStringStream(int, const PStringStream &) : iostream(cout.rdbuf()) { }
02138 
02139     class Buffer : public streambuf {
02140       public:
02141         Buffer(PStringStream & str, PINDEX size);
02142         Buffer(const Buffer & sbuf);
02143         Buffer & operator=(const Buffer & sbuf);
02144         virtual int overflow(int=EOF);
02145         virtual int underflow();
02146         virtual int sync();
02147 #ifdef __USE_STL__
02148         virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
02149         virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
02150 #else
02151         virtual streampos seekoff(streamoff, ios::seek_dir, int);
02152 #endif
02153         PStringStream & string;
02154         BOOL            fixedBufferSize;
02155     };
02156 };
02157 
02158 
02159 class PStringList;
02160 class PSortedStringList;
02161 
02174 #ifdef DOC_PLUS_PLUS
02175 class PStringArray : public PArray {
02176 #endif
02177   PDECLARE_ARRAY(PStringArray, PString);
02178   public:
02185     PStringArray(
02186       PINDEX count,                 
02187       char const * const * strarr,  
02188       BOOL caseless = FALSE         
02189     );
02192     PStringArray(
02193       const PString & str  
02194     );
02197     PStringArray(
02198       const PStringList & list  
02199     );
02202     PStringArray(
02203       const PSortedStringList & list  
02204     );
02205 
02209     PStringArray(
02210       const std::vector<PString> & vec
02211     )
02212     {
02213       for (std::vector<PString>::const_iterator r = vec.begin(); r != vec.end(); ++r)
02214         AppendString(*r);
02215     }
02216 
02220     PStringArray(
02221       const std::vector<std::string> & vec
02222     )
02223     {
02224       for (std::vector<std::string>::const_iterator r = vec.begin(); r != vec.end(); ++r)
02225         AppendString(PString(*r));
02226     }
02227 
02231     template <typename stlContainer>
02232     static PStringArray container(
02233       const stlContainer & vec
02234     )
02235     {
02236       PStringArray list;
02237       for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
02238         list.AppendString(PString(*r));
02239       return list;
02240     }
02241 
02243 
02251     virtual void ReadFrom(
02252       istream &strm   // Stream to read the objects contents from.
02253     );
02255 
02264     PINDEX GetStringsIndex(
02265       const PString & str 
02266     ) const;
02267 
02268     PString operator[](
02269       PINDEX index  
02270     ) const;
02271 
02279     PString & operator[](
02280       PINDEX index  
02281     );
02282 
02285     PINDEX AppendString(
02286       const PString & str 
02287     );
02288 
02294     PStringArray & operator +=(const PStringArray & array);
02295     PStringArray & operator +=(const PString & str);
02296 
02297 
02304     PStringArray operator + (const PStringArray & array);
02305     PStringArray operator + (const PString & str);
02306 
02314     char ** ToCharArray(
02315       PCharArray * storage = NULL
02316     ) const;
02318 };
02319 
02320 
02333 #ifdef DOC_PLUS_PLUS
02334 class PStringList : public PList {
02335 #endif
02336 PDECLARE_LIST(PStringList, PString);
02337   public:
02342     PStringList(
02343       PINDEX count,                 
02344       char const * const * strarr,  
02345       BOOL caseless = FALSE         
02346     );
02349     PStringList(
02350       const PString & str  
02351     );
02354     PStringList(
02355       const PStringArray & array  
02356     );
02359     PStringList(
02360       const PSortedStringList & list  
02361     );
02363 
02371     virtual void ReadFrom(
02372       istream &strm   // Stream to read the objects contents from.
02373     );
02375 
02380     PINDEX AppendString(
02381       const PString & str 
02382     );
02383 
02386     PINDEX InsertString(
02387       const PString & before,   
02388       const PString & str       
02389     );
02390 
02394     PINDEX GetStringsIndex(
02395       const PString & str   
02396     ) const;
02397 
02403     PStringList & operator +=(const PStringList & list);
02404     PStringList & operator +=(const PString & str);
02405 
02406 
02413     PStringList operator + (const PStringList & array);
02414     PStringList operator + (const PString & str);
02415 
02419     template <typename stlContainer>
02420     static PStringList container(
02421       const stlContainer & vec
02422     )
02423     {
02424       PStringList list;
02425       for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
02426         list.AppendString(PString(*r));
02427       return list;
02428     }
02430 };
02431 
02432 
02445 #ifdef DOC_PLUS_PLUS
02446 class PSortedStringList : public PSortedList {
02447 #endif
02448 PDECLARE_SORTED_LIST(PSortedStringList, PString);
02449   public:
02454     PSortedStringList(
02455       PINDEX count,                 
02456       char const * const * strarr,  
02457       BOOL caseless = FALSE         
02458     );
02461     PSortedStringList(
02462       const PString & str  
02463     );
02466     PSortedStringList(
02467       const PStringArray & array  
02468     );
02471     PSortedStringList(
02472       const PStringList & list  
02473     );
02475 
02483     virtual void ReadFrom(
02484       istream &strm   // Stream to read the objects contents from.
02485     );
02487 
02493     PINDEX AppendString(
02494       const PString & str 
02495     );
02496 
02500     PINDEX GetStringsIndex(
02501       const PString & str   
02502     ) const;
02503 
02508     PINDEX GetNextStringsIndex(
02509       const PString & str   
02510     ) const;
02512 
02513   protected:
02514     PINDEX InternalStringSelect(
02515       const char * str,
02516       PINDEX len,
02517       Element * thisElement
02518     ) const;
02519 };
02520 
02521 
02538 #ifdef DOC_PLUS_PLUS
02539 class PStringSet : public PSet {
02540 #endif
02541 PDECLARE_SET(PStringSet, PString, TRUE);
02542   public:
02547     PStringSet(
02548       PINDEX count,                 
02549       char const * const * strarr,  
02550       BOOL caseless = FALSE         
02551     );
02554     PStringSet(
02555       const PString & str  
02556     );
02558 
02566     virtual void ReadFrom(
02567       istream &strm   
02568     );
02570 
02574     void Include(
02575       const PString & key 
02576     );
02578     PStringSet & operator+=(
02579       const PString & key 
02580     );
02582     void Exclude(
02583       const PString & key 
02584     );
02586     PStringSet & operator-=(
02587       const PString & key 
02588     );
02590 };
02591 
02592 
02593 #ifdef PHAS_TEMPLATES
02594 
02602 template <class K> class PStringDictionary : public PAbstractDictionary
02603 {
02604   PCLASSINFO(PStringDictionary, PAbstractDictionary);
02605 
02606   public:
02615     PStringDictionary()
02616       : PAbstractDictionary() { }
02618 
02625     virtual PObject * Clone() const
02626       { return PNEW PStringDictionary(0, this); }
02628 
02643     const PString & operator[](const K & key) const
02644       { return (const PString &)GetRefAt(key); }
02645 
02659     PString operator()(const K & key, const char * dflt = "") const
02660       { if (AbstractContains(key)) return (*this)[key]; return dflt; }
02661 
02670     BOOL Contains(
02671       const K & key   // Key to look for in the dictionary.
02672       ) const { return AbstractContains(key); }
02673 
02685     virtual PString * RemoveAt(
02686       const K & key   // Key for position in dictionary to get object.
02687     ) {
02688         PString * s = GetAt(key); AbstractSetAt(key, NULL);
02689         return reference->deleteObjects ? (s ? (PString *)-1 : NULL) : s;
02690       }
02691 
02698     virtual PString * GetAt(
02699       const K & key   // Key for position in dictionary to get object.
02700     ) const { return (PString *)AbstractGetAt(key); }
02701 
02710     virtual BOOL SetDataAt(
02711       PINDEX index,        // Ordinal index in the dictionary.
02712       const PString & str  // New string value to put into the dictionary.
02713     ) { return PAbstractDictionary::SetDataAt(index, PNEW PString(str)); }
02714 
02726     virtual BOOL SetAt(
02727       const K & key,       // Key for position in dictionary to add object.
02728       const PString & str  // New string value to put into the dictionary.
02729     ) { return AbstractSetAt(key, PNEW PString(str)); }
02730 
02742     const K & GetKeyAt(PINDEX index) const
02743       { return (const K &)AbstractGetKeyAt(index); }
02744 
02756     PString & GetDataAt(PINDEX index) const
02757       { return (PString &)AbstractGetDataAt(index); }
02759 
02760   protected:
02761     PStringDictionary(int dummy, const PStringDictionary * c)
02762       : PAbstractDictionary(dummy, c) { }
02763 };
02764 
02765 
02780 #define PDECLARE_STRING_DICTIONARY(cls, K) \
02781   PDECLARE_CLASS(cls, PStringDictionary<K>) \
02782   protected: \
02783     cls(int dummy, const cls * c) \
02784       : PStringDictionary<K>(dummy, c) { } \
02785   public: \
02786     cls() \
02787       : PStringDictionary<K>() { } \
02788     virtual PObject * Clone() const \
02789       { return PNEW cls(0, this); } \
02790 
02791 
02804 #define PSTRING_DICTIONARY(cls, K) typedef PStringDictionary<K> cls
02805 
02806 
02807 #else // PHAS_TEMPLATES
02808 
02809 
02810 #define PSTRING_DICTIONARY(cls, K) \
02811   class cls : public PAbstractDictionary { \
02812   PCLASSINFO(cls, PAbstractDictionary) \
02813   protected: \
02814     inline cls(int dummy, const cls * c) \
02815       : PAbstractDictionary(dummy, c) { } \
02816   public: \
02817     inline cls() \
02818       : PAbstractDictionary() { } \
02819     inline PObject * Clone() const \
02820       { return PNEW cls(0, this); } \
02821     inline PString & operator[](const K & key) const \
02822       { return (PString &)GetRefAt(key); } \
02823     inline PString operator()(const K & key, const char * dflt = "") const \
02824       { if (Contains(key)) return (PString &)GetRefAt(key); return dflt; } \
02825     virtual BOOL Contains(const K & key) const \
02826       { return AbstractContains(key); } \
02827     virtual PString * RemoveAt(const K & key) \
02828       { PString * s = GetAt(key); AbstractSetAt(key, NULL); \
02829         return reference->deleteObjects ? (s ? (PString *)-1 : NULL) : s; } \
02830     virtual PString * GetAt(const K & key) const \
02831       { return (PString *)AbstractGetAt(key); } \
02832     virtual BOOL SetDataAt(PINDEX index, const PString & str) \
02833       { return PAbstractDictionary::SetDataAt(index,PNEW PString(str));} \
02834     virtual BOOL SetAt(const K & key, const PString & str) \
02835       { return AbstractSetAt(key, PNEW PString(str)); } \
02836     inline const K & GetKeyAt(PINDEX index) const \
02837       { return (const K &)AbstractGetKeyAt(index); } \
02838     inline PString & GetDataAt(PINDEX index) const \
02839       { return (PString &)AbstractGetDataAt(index); } \
02840   }
02841 
02842 #define PDECLARE_STRING_DICTIONARY(cls, K) \
02843   PSTRING_DICTIONARY(cls##_PTemplate, K); \
02844   PDECLARE_CLASS(cls, cls##_PTemplate) \
02845   protected: \
02846     cls(int dummy, const cls * c) \
02847       : cls##_PTemplate(dummy, c) { } \
02848   public: \
02849     cls() \
02850       : cls##_PTemplate() { } \
02851     virtual PObject * Clone() const \
02852       { return PNEW cls(0, this); } \
02853 
02854 #endif // PHAS_TEMPLATES
02855 
02856 
02871 #ifdef DOC_PLUS_PLUS
02872 class POrdinalToString : public PStringDictionary {
02873 #endif
02874 PDECLARE_STRING_DICTIONARY(POrdinalToString, POrdinalKey);
02875   public:
02878 
02879     struct Initialiser {
02881       PINDEX key;
02883       const char * value;
02884     };
02887     POrdinalToString(
02888       PINDEX count,                
02889       const Initialiser * init     
02890     );
02892 
02900     virtual void ReadFrom(
02901       istream &strm   // Stream to read the objects contents from.
02902     );
02904 };
02905 
02918 #ifdef DOC_PLUS_PLUS
02919 class PStringToOrdinal : public POrdinalDictionary {
02920 #endif
02921 PDECLARE_ORDINAL_DICTIONARY(PStringToOrdinal, PString);
02922   public:
02925 
02926     struct Initialiser {
02928       const char * key;
02930       PINDEX value;
02931     };
02934     PStringToOrdinal(
02935       PINDEX count,                
02936       const Initialiser * init,    
02937       BOOL caseless = FALSE        
02938     );
02940 
02948     virtual void ReadFrom(
02949       istream &strm   // Stream to read the objects contents from.
02950     );
02952 };
02953 
02954 
02968 #ifdef DOC_PLUS_PLUS
02969 class PStringToString : public PStringDictionary {
02970 #endif
02971 PDECLARE_STRING_DICTIONARY(PStringToString, PString);
02972   public:
02975 
02976     struct Initialiser {
02978       const char * key;
02980       const char * value;
02981     };
02984     PStringToString(
02985       PINDEX count,                
02986       const Initialiser * init,    
02987       BOOL caselessKeys = FALSE,   
02988       BOOL caselessValues = FALSE  
02989     );
02991 
02999     virtual void ReadFrom(
03000       istream &strm   // Stream to read the objects contents from.
03001     );
03003 };
03004 
03005 
03011 class PRegularExpression : public PObject
03012 {
03013   PCLASSINFO(PRegularExpression, PObject);
03014 
03015   public:
03018 
03019     enum {
03021       Extended = 1,
03023       IgnoreCase = 2,
03028       AnchorNewLine = 4
03029     };
03031     enum {
03038       NotBeginningOfLine = 1,
03040       NotEndofLine = 2
03041     };
03042 
03044     PRegularExpression();
03045 
03048     PRegularExpression(
03049       const PString & pattern,    
03050       int flags = IgnoreCase      
03051     );
03052 
03055     PRegularExpression(
03056       const char * cpattern,      
03057       int flags = IgnoreCase      
03058     );
03059 
03063     PRegularExpression(
03064       const PRegularExpression &
03065     );
03066 
03070     PRegularExpression & operator =(
03071       const PRegularExpression &
03072     );
03073 
03075     ~PRegularExpression();
03077 
03080 
03081     enum ErrorCodes {
03083       NoError = 0,    
03085       NoMatch,      
03086 
03087       // POSIX regcomp return error codes.  (In the order listed in the standard.)
03089       BadPattern,  
03091       CollateError,  
03093       BadClassType,  
03095       BadEscape,    
03097       BadSubReg,
03099       UnmatchedBracket, 
03101       UnmatchedParen,
03103       UnmatchedBrace,
03105       BadBR,        
03107       RangeError,  
03109       OutOfMemory,
03111       BadRepitition,
03112 
03113       /* Error codes we've added.  */
03115       PrematureEnd,
03117       TooBig,
03119       UnmatchedRParen,
03121       NotCompiled
03122     };
03123 
03129     ErrorCodes GetErrorCode() const;
03130 
03137     PString GetErrorText() const;
03139 
03143     BOOL Compile(
03144       const PString & pattern,    
03145       int flags = IgnoreCase      
03146     );
03154     BOOL Compile(
03155       const char * cpattern,      
03156       int flags = IgnoreCase      
03157     );
03158 
03159 
03161     BOOL Execute(
03162       const PString & str,    
03163       PINDEX & start,         
03164       int flags = 0           
03165     ) const;
03167     BOOL Execute(
03168       const PString & str,    
03169       PINDEX & start,         
03170       PINDEX & len,           
03171       int flags = 0           
03172     ) const;
03174     BOOL Execute(
03175       const char * cstr,      
03176       PINDEX & start,         
03177       int flags = 0           
03178     ) const;
03180     BOOL Execute(
03181       const char * cstr,      
03182       PINDEX & start,         
03183       PINDEX & len,           
03184       int flags = 0           
03185     ) const;
03187     BOOL Execute(
03188       const PString & str,    
03189       PIntArray & starts,     
03190       int flags = 0           
03191     ) const;
03193     BOOL Execute(
03194       const PString & str,    
03195       PIntArray & starts,     
03196       PIntArray & ends,       
03197       int flags = 0           
03198     ) const;
03200     BOOL Execute(
03201       const char * cstr,      
03202       PIntArray & starts,     
03203       int flags = 0           
03204     ) const;
03220     BOOL Execute(
03221       const char * cstr,      
03222       PIntArray & starts,     
03223       PIntArray & ends,       
03224       int flags = 0           
03225     ) const;
03227 
03236     static PString EscapeString(
03237       const PString & str     
03238     );
03240 
03241   protected:
03242     PString patternSaved;
03243     int flagsSaved;
03244 
03245     void * expression;
03246     int lastError;
03247 };
03248 
03249 PString psprintf(const char * cfmt, ...);
03250 
03251 #endif // #ifndef __PSTRING__
03252 // End Of File ///////////////////////////////////////////////////////////////

Generated on Mon Sep 1 09:41:07 2008 for PWLib by  doxygen 1.5.6