pstring.h

Go to the documentation of this file.

/*
 * pstring.h
 *
 * Character string class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: pstring.h,v $
 * Revision 1.94  2007/10/08 05:04:10  rjongbloed
 * Fixed bug introduced to prevent execution if had compiler error, did not allow
 *   for getting NoMatch error on execution and using an instance twice.
 * Also made lastError member mutable to clean up lots of cont casts.
 *
 * Revision 1.93  2007/06/29 02:47:28  rjongbloed
 * Added PString::FindSpan() function (strspn equivalent) with slightly nicer semantics.
 *
 * Revision 1.92  2007/04/08 01:53:16  ykiryanov
 * Build to support ptlib dll creation
 *
 * Revision 1.91  2006/08/11 08:18:57  csoutheren
 * Add PCaselessString constructor for std::string
 *
 * Revision 1.90  2006/08/11 04:44:48  csoutheren
 * Add operator to convert PString to std::string
 *
 * Revision 1.89  2006/07/10 09:15:28  shorne
 * Corrected PString::Tokenize() documentation Thx. David Corrie
 *
 * Revision 1.88  2006/06/30 00:56:31  csoutheren
 * Applied 1494931 - various pwlib bug fixes and enhancement
 * Thanks to Frederich Heem
 *
 * Revision 1.87  2006/06/21 03:28:41  csoutheren
 * Various cleanups thanks for Frederic Heem
 *
 * Revision 1.86  2006/04/09 07:05:40  rjongbloed
 * Moved output stream operator for PString from sockets code to string code and fixed
 *   its implemetation to continue to use PrintOn. Why it was added is unknown, probably
 *   a compiler issue, but it should not be in a random source file!
 *
 * Revision 1.85  2005/12/15 21:14:34  dsandras
 * Fixed from Alexander Larsson <alexl _AT__ redhat.com> for gcc 4.1 compilation. Thanks!
 *
 * Revision 1.84  2005/11/30 12:47:38  csoutheren
 * Removed tabs, reformatted some code, and changed tags for Doxygen
 *
 * Revision 1.83  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.82  2005/09/18 11:05:36  dominance
 * include/ptlib/channel.h, include/ptlib/pstring.h, src/ptlib/common/contain.cxx,
 * src/ptlib/common/pchannel.cxx:
 *   correct the STL defined checking to use proper syntax.
 *
 * include/ptlib/object.h:
 *   re-add typedef to compile on mingw
 *
 * make/ptlib-config.in:
 *   import a long-standing fix from the Debian packs which allows usage of
 *   ptlib-config without manually adding -lpt for each of the subsequent
 *   projects
 *
 * Revision 1.81  2004/12/22 04:04:36  dereksmithies
 * Modify description of parameters for PString::Replace()
 *
 * Revision 1.80  2004/11/23 11:33:08  csoutheren
 * Fixed problem with RemoveAt returning invalid pointer in some cases,
 * and added extra documentation on this case.
 * Thanks to Diego Tartara for pointing out this potential problem
 *
 * Revision 1.79  2004/10/21 13:04:20  rjongbloed
 * Fixed possibility of const operator[] on PStringArray returning a NULL reference. This
 *   function should return a non-lvalue PString anyway as it is const!
 *
 * Revision 1.78  2004/08/16 08:49:59  csoutheren
 * Removed error when compiling with gcc
 *
 * Revision 1.77  2004/08/16 06:40:59  csoutheren
 * Added adapters template to make device plugins available via the abstract factory interface
 *
 * Revision 1.76  2004/06/01 05:54:18  csoutheren
 * Added <vector> and <string>
 *
 * Revision 1.75  2004/06/01 05:21:38  csoutheren
 * Added conversions between std::string and PString, and vector<PString> and PStringArray
 *
 * Revision 1.74  2004/05/04 11:10:36  rjongbloed
 * Fixed usage of MakeEmpty() with PStringStream.
 *
 * Revision 1.73  2004/04/18 04:33:36  rjongbloed
 * Changed all operators that return BOOL to return standard type bool. This is primarily
 *   for improved compatibility with std STL usage removing many warnings.
 *
 * Revision 1.72  2004/04/11 13:26:25  csoutheren
 * Removed namespace problems and removed warnings for Windows <string>
 *
 * Revision 1.71  2004/04/09 06:38:10  rjongbloed
 * Fixed compatibility with STL based streams, eg as used by VC++2003
 *
 * Revision 1.70  2004/04/09 03:42:34  csoutheren
 * Removed all usages of "virtual inline" and "inline virtual"
 *
 * Revision 1.69  2004/04/03 06:54:22  rjongbloed
 * Many and various changes to support new Visual C++ 2003
 *
 * Revision 1.68  2004/02/23 00:44:38  csoutheren
 * A completely different, other regex include hack to avoid requiring
 * the sources when using a header-file only environment
 *
 * Revision 1.67  2004/02/23 00:26:05  csoutheren
 * Finally, a generic and elegant fix for the regex include hacks.  Thanks to Roger Hardiman
 *
 * Revision 1.66  2004/02/11 05:09:14  csoutheren
 * Fixed problems with regex libraries on Solaris, and with host OS numbering
 * being a quoted string rather than a number. Thanks to Chad Attermann
 * Fixed problems SSL detection problems thanks to Michal Zygmuntowicz
 *
 * Revision 1.65  2004/02/08 11:13:11  rjongbloed
 * Fixed crash in heavily loaded multi-threaded systems using simultaneous sorted
 *   lists, Thanks Federico Pinna, Fabrizio Ammollo and the gang at Reitek S.p.A.
 *
 * Revision 1.64  2004/01/18 13:43:48  rjongbloed
 * Fixed broken PString::MakeEmpty() function and moved implementations to .inl file.
 *
 * Revision 1.63  2004/01/17 18:15:24  csoutheren
 * Fixed multi-threading problem with PString::Empty
 * Created PString::MakeEmpty for efficient emptying of existing strings
 *
 * Revision 1.62  2004/01/16 13:24:37  csoutheren
 * Changed PString::Empty to be thread-safe
 * Fixed PContainer::SetMinSize and PAbstractArray::SetSize, thanks to 123@call2ua.com
 * Fixed PString::FindLast, thanks to Andreas Sikkema
 *
 * Revision 1.61  2003/12/13 23:08:46  csoutheren
 * Changed PRegularExpression to allow a copy constructor and operator =
 *
 * Revision 1.60  2003/12/10 03:28:50  csoutheren
 * Removed compile time warning under Linux
 *
 * Revision 1.59  2003/12/07 05:50:49  csoutheren
 * Blocked operator = for PRegularExpression
 *
 * Revision 1.58  2003/12/04 13:10:38  csoutheren
 * Made PRegularExpression copy constructor private to avoid accidental usage (and subsequent crash)
 *
 * Revision 1.57  2003/05/14 00:46:47  rjongbloed
 * Added constructor to string lists/arrays etc that takes a single PString.
 *
 * Revision 1.56  2003/03/31 01:23:56  robertj
 * Added ReadFrom functions for standard container classes such as
 *   PIntArray and PStringList etc
 *
 * Revision 1.55  2003/03/05 08:48:32  robertj
 * Added PStringArray::ToCharAray() function at suggestion of Ravelli Rossano
 *
 * Revision 1.54  2002/11/12 09:17:44  robertj
 * Added PString::NumCompare() as functional equivalent of strncmp().
 * Added PSortedStringList::GetNextStringsIndex() to do searches of binary
 *   tree on partal strings.
 *
 * Revision 1.53  2002/10/31 05:53:44  robertj
 * Now comprehensively stated that a PString is ALWAYS an 8 bit string as
 *   there are far too many inheerent assumptions every to make it 16 bit.
 * Added UTF-8/UCS-2 conversion functions to PString.
 *
 * Revision 1.52  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.51  2002/08/14 00:43:39  robertj
 * Added ability to have fixed maximum length PStringStream's so does not do
 *   unwanted malloc()'s while outputing data.
 *
 * Revision 1.50  2002/04/09 02:30:18  robertj
 * Removed GCC3 variable as __GNUC__ can be used instead, thanks jason Spence
 *
 * Revision 1.49  2002/02/15 04:29:31  robertj
 * Added PString::Empty() to return the primordial empty string. Saves on a
 *   couple of memory allocations for every empty string ever used.
 *
 * Revision 1.48  2002/01/26 23:55:55  craigs
 * Changed for GCC 3.0 compatibility, thanks to manty@manty.net
 *
 * Revision 1.47  2002/01/22 01:03:57  craigs
 * Added operator += and operator + functions to PStringArray and PStringList
 * Added AppendString operator to PStringArray
 *
 * Revision 1.46  2001/10/17 05:09:22  robertj
 * Added contructors and assigmnent operators so integer types can be
 *   automatically converted to strings.
 *
 * Revision 1.45  2001/08/11 07:57:30  rogerh
 * Add Mac OS Carbon changes from John Woods <jfw@jfwhome.funhouse.com>
 *
 * Revision 1.44  2001/04/18 04:10:15  robertj
 * Removed hash function for caseless strings as confuses mixed dictionaries.
 *
 * Revision 1.43  2001/04/18 01:20:58  robertj
 * Fixed problem with hash function for short strings, thanks Patrick Koorevaar.
 * Also fixed hash function for caseless strings.
 *
 * Revision 1.42  2001/02/21 03:38:37  robertj
 * Added ability to copy between various string lists/arrays etc during construction.
 *
 * Revision 1.41  2001/02/13 04:39:08  robertj
 * Fixed problem with operator= in container classes. Some containers will
 *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
 *   needed to add a new AssignContents() function to all containers.
 *
 * Revision 1.40  1999/08/22 12:13:43  robertj
 * Fixed warning when using inlines on older GNU compiler
 *
 * Revision 1.39  1999/05/28 14:01:22  robertj
 * Added initialisers to string containers (list, sorted list and set).
 *
 * Revision 1.38  1999/03/09 09:34:05  robertj
 * Fixed typo's.
 *
 * Revision 1.37  1999/03/09 02:59:50  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.36  1999/02/16 08:11:09  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.35  1998/09/23 06:21:12  robertj
 * Added open source copyright license.
 *
 * Revision 1.34  1998/01/26 00:33:46  robertj
 * Added FindRegEx function to PString that returns position and length.
 * Added Execute() functions to PRegularExpression that take PINDEX references instead of PIntArrays.
 * Added static function to PRegularExpression to escape all special operator characters in a string.
 *
 * Revision 1.33  1998/01/05 10:39:35  robertj
 * Fixed "typesafe" templates/macros for dictionaries, especially on GNU.
 *
 * Revision 1.32  1997/12/11 13:32:47  robertj
 * Added AsUnsigned() function to convert string to DWORD.
 *
 * Revision 1.31  1997/12/11 10:29:49  robertj
 * Added type correct Contains() function to dictionaries.
 *
 * Revision 1.30  1997/07/08 13:13:47  robertj
 * DLL support.
 *
 * Revision 1.29  1997/06/10 11:36:32  craigs
 * Added inline statements to allow compilation uder Unix
 *
 * Revision 1.28  1997/06/08 04:48:58  robertj
 * Added regular expressions.
 * Fixed non-template class descendent order.
 *
 * Revision 1.27  1997/05/16 12:10:12  robertj
 * Fixed G++ compatibility bug.
 *
 * Revision 1.26  1996/10/08 13:13:38  robertj
 * Added operator += and &= for char so no implicit PString construction.
 *
 * Revision 1.25  1996/09/14 12:52:39  robertj
 * Added operator! for !IsEmpty().
 *
 * Revision 1.24  1996/08/17 10:00:25  robertj
 * Changes for Windows DLL support.
 *
 * Revision 1.23  1996/05/26 03:27:02  robertj
 * Compatibility to GNU 2.7.x
 *
 * Revision 1.22  1996/03/31 08:51:22  robertj
 * Added RemoveAt() function to remove entries from dictionaries.
 *
 * Revision 1.21  1996/03/10 13:15:50  robertj
 * Added operator() to template version.
 *
 * Revision 1.20  1996/02/19 13:17:33  robertj
 * Removed PCaselessString hash function to fix dictionary match failure.
 * Added operator() to do string dictionary lookup with default value.
 *
 * Revision 1.19  1996/02/08 12:19:16  robertj
 * Added new operators to PString for case insensitive compare and spaced concatenate.
 *
 * Revision 1.18  1996/01/24 14:43:15  robertj
 * Added initialisers to string dictionaries.
 *
 * Revision 1.17  1996/01/23 13:15:17  robertj
 * Added Replace() function to strings.
 * Mac Metrowerks compiler support.
 * String searching algorithm rewrite.
 *
 * Revision 1.16  1996/01/02 12:04:31  robertj
 * Mac OS compatibility changes.
 * Removed requirement that PArray elements have parameterless constructor..
 *
 * Revision 1.15  1995/12/23 03:46:23  robertj
 * Added operators for include and exclude from string set.
 *
 * Revision 1.14  1995/10/14 15:02:56  robertj
 * Changed arrays to not break references, but strings still need to.
 *
 * Revision 1.13  1995/06/17 11:13:08  robertj
 * Documentation update.
 *
 * Revision 1.12  1995/06/17 00:43:40  robertj
 * Added flag for PStringArray constructor to create caseless strings.
 *
 * Revision 1.11  1995/06/04 12:34:57  robertj
 * Better C++ compatibility (with BC++)
 *
 * Revision 1.10  1995/04/02 09:27:23  robertj
 * Added "balloon" help.
 *
 * Revision 1.9  1995/03/14 12:42:16  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.8  1995/03/12  04:44:39  robertj
 * Fixed use of PCaselessString as dictionary key.
 *
 * Revision 1.7  1995/02/05  00:48:09  robertj
 * Fixed template version.
 *
 * Revision 1.6  1995/01/15  04:50:20  robertj
 * Added inlines on friend functions, required by GNU compiler.
 *
 * Revision 1.5  1995/01/10  11:43:41  robertj
 * Removed PString parameter in stdarg function for GNU C++ compatibility.
 *
 * Revision 1.4  1995/01/09  12:33:44  robertj
 * Removed unnecesary return value from I/O functions.
 * Changed function names due to Mac port.
 *
 * Revision 1.3  1994/12/21  11:53:21  robertj
 * Documentation and variable normalisation.
 *
 * Revision 1.2  1994/12/12  13:13:13  robertj
 * Fixed bugs in PString mods just made.
 *
 * Revision 1.1  1994/12/12  09:59:37  robertj
 * Initial revision
 *
 */
#ifndef __PSTRING__
#define __PSTRING__

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <string>
#include <vector>
#include <ptlib/array.h>

// PString class

class PStringArray;
class PRegularExpression;

class PString : public PCharArray {
  PCLASSINFO(PString, PCharArray);

//  using namespace std;

  public:
    PINLINE PString();

    PINLINE PString(
      const PString & str  
    );

    PINLINE PString(
      const std::string & str
    );

    PString(
      const char * cstr 
    );

    PString(
      const WORD * ustr 
    );

    PString(
      const char * cstr,  
      PINDEX len          
    );

    PString(
      const WORD * ustr,  
      PINDEX len          
    );

    PString(
      const PWORDArray & ustr 
    );

    PString(
      char ch    
    );

    PString(
      short n   
    );

    PString(
      unsigned short n   
    );

    PString(
      int n   
    );

    PString(
      unsigned int n   
    );

    PString(
      long n   
    );

    PString(
      unsigned long n   
    );

    PString(
      PInt64 n   
    );

    PString(
      PUInt64 n   
    );

 
    enum ConversionType {
      Pascal,   // Data is a length byte followed by characters.
      Basic,    // Data is two length bytes followed by characters.
      Literal,  // Data is C language style string with \ escape codes.
      Signed,   // Convert a signed integer to a string.
      Unsigned, // Convert an unsigned integer to a string.
      Decimal,  // Convert a real number to a string in decimal format.
      Exponent, // Convert a real number to a string in exponent format.
      Printf,   // Formatted output, sprintf() style function.
      NumConversionTypes
    };
    /* Type of conversion to make in the conversion constructors.
     */

    /* Contruct a new string converting from the spcified data source into
       a string array.
     */
    PString(
      ConversionType type,  
      const char * str,    
      ...                 
    );
    PString(
      ConversionType type,  
      long value,           
      unsigned base = 10    
    );
    PString(
      ConversionType type,  
      double value,         
      unsigned places       
    );

    PString & operator=(
      const PString & str  
    );

    PString & operator=(
      const char * cstr  
    );

    PString & operator=(
      char ch            
    );

    PString & operator=(
      short n   
    );

    PString & operator=(
      unsigned short n   
    );

    PString & operator=(
      int n   
    );

    PString & operator=(
      unsigned int n   
    );

    PString & operator=(
      long n   
    );

    PString & operator=(
      unsigned long n   
    );

    PString & operator=(
      PInt64 n   
    );

    PString & operator=(
      PUInt64 n   
    );

    virtual PString & MakeEmpty();

    static PString Empty();

    virtual PObject * Clone() const;

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual void PrintOn(
      ostream & strm  
    ) const;

    virtual void ReadFrom(
      istream & strm  
    );

    virtual PINDEX HashFunction() const;

    virtual BOOL SetSize(
      PINDEX newSize  
    );

    virtual BOOL IsEmpty() const;

    virtual BOOL MakeUnique();


    BOOL MakeMinimumSize();

    PINLINE PINDEX GetLength() const;

    bool operator!() const;

    PString operator+(
      const PString & str   
    ) const;

    PString operator+(
      const char * cstr  
    ) const;

    PString operator+(
      char ch   
    ) const;

    friend PString operator+(
      const char * cstr,    
      const PString & str   
    );

    friend PString operator+(
      char  c,              
      const PString & str   
    );

    PString & operator+=(
      const PString & str   
    );

    PString & operator+=(
      const char * cstr  
    );

    PString & operator+=(
      char ch   
    );


    PString operator&(
      const PString & str   
    ) const;

    PString operator&(
      const char * cstr  
    ) const;

    PString operator&(
      char ch   
    ) const;

    friend PString operator&(
      const char * cstr,    
      const PString & str   
    );

    friend PString operator&(
      char  ch,              
      const PString & str   
    );

    PString & operator&=(
      const PString & str   
    );

    PString & operator&=(
      const char * cstr  
    );


    PString & operator&=(
      char ch  
    );


    bool operator*=(
      const PString & str  
    ) const;

    bool operator==(
      const PObject & str  
    ) const;

    bool operator!=(
      const PObject & str  
    ) const;

    bool operator<(
      const PObject & str  
    ) const;

    bool operator>(
      const PObject & str  
    ) const;

    bool operator<=(
      const PObject & str  
    ) const;

    bool operator>=(
      const PObject & str  
    ) const;


    bool operator*=(
      const char * cstr  
    ) const;

    bool operator==(
      const char * cstr  
    ) const;

    bool operator!=(
      const char * cstr  
    ) const;

    bool operator<(
      const char * cstr  
    ) const;

    bool operator>(
      const char * cstr  
    ) const;

    bool operator<=(
      const char * cstr  
    ) const;

    bool operator>=(
      const char * cstr  
    ) const;

    Comparison NumCompare(
      const PString & str,        
      PINDEX count = P_MAX_INDEX, 
      PINDEX offset = 0           
    ) const;

    Comparison NumCompare(
      const char * cstr,          
      PINDEX count = P_MAX_INDEX, 
      PINDEX offset = 0           
    ) const;


    PINDEX Find(
      char ch,              
      PINDEX offset = 0     
    ) const;

    PINDEX Find(
      const PString & str,  
      PINDEX offset = 0     
    ) const;

    /* Locate the position within the string of the character or substring. The
       search will begin at the character offset provided.
       
       If #offset# is beyond the length of the string, then the
       function will always return #P_MAX_INDEX#.
       
       The matching will be for identical character or string. If a search
       ignoring case is required then the string should be converted to a
       #PCaselessString# before the search is made.

       @return
       position of character or substring in the string, or P_MAX_INDEX if the
       character or substring is not in the string.
     */
    PINDEX Find(
      const char * cstr,    
      PINDEX offset = 0     
    ) const;

    PINDEX FindLast(
      char ch,                     
      PINDEX offset = P_MAX_INDEX  
    ) const;

    PINDEX FindLast(
      const PString & str,         
      PINDEX offset = P_MAX_INDEX  
    ) const;

    PINDEX FindLast(
      const char * cstr,           
      PINDEX offset = P_MAX_INDEX  
    ) const;

    PINDEX FindOneOf(
      const PString & set,  
      PINDEX offset = 0     
    ) const;

    PINDEX FindOneOf(
      const char * cset,    
      PINDEX offset = 0     
    ) const;

    PINDEX FindSpan(
      const PString & set,  
      PINDEX offset = 0     
    ) const;

    PINDEX FindSpan(
      const char * cset,    
      PINDEX offset = 0     
    ) const;

    PINDEX FindRegEx(
      const PRegularExpression & regex, 
      PINDEX offset = 0                 
    ) const;

    BOOL FindRegEx(
      const PRegularExpression & regex, 
      PINDEX & pos,                     
      PINDEX & len,                     
      PINDEX offset = 0,                
      PINDEX maxPos = P_MAX_INDEX       
    ) const;


    void Replace(
      const PString & target,   
      const PString & subs,     
      BOOL all = FALSE,         
      PINDEX offset = 0         
    );

    void Splice(
      const PString & str,  
      PINDEX pos,           
      PINDEX len = 0        
    );

    void Splice(
      const char * cstr,    
      PINDEX pos,           
      PINDEX len = 0        
    );

    void Delete(
      PINDEX start,   
      PINDEX len      
    );


    PString operator()(
      PINDEX start,  
      PINDEX end     
    ) const;

    PString Left(
      PINDEX len   
    ) const;

    PString Right(
      PINDEX len   
    ) const;

    PString Mid(
      PINDEX start,             
      PINDEX len = P_MAX_INDEX  
    ) const;


    PString LeftTrim() const;

    PString RightTrim() const;

    PString Trim() const;


    PString ToLower() const;

    PString ToUpper() const;


    PStringArray Tokenise(
      const PString & separators,
      BOOL onePerSeparator = TRUE
    ) const;
    PStringArray Tokenise(
      const char * cseparators,
      BOOL onePerSeparator = TRUE
    ) const;

    PStringArray Lines() const;

    PString & sprintf(
      const char * cfmt,   
      ...                  
    );

    friend PString psprintf(
      const char * cfmt,   
      ...                  
    );

    PString & vsprintf(
      const PString & fmt, 
      va_list args         
    );
    PString & vsprintf(
      const char * cfmt,   
      va_list args         
    );

    friend PString pvsprintf(
      const char * cfmt,   
      va_list args         
    );
    friend PString pvsprintf(
      const PString & fmt, 
      va_list args         
    );


    long AsInteger(
      unsigned base = 10    
    ) const;
    DWORD AsUnsigned(
      unsigned base = 10    
    ) const;
    PInt64 AsInt64(
      unsigned base = 10    
    ) const;
    PUInt64 AsUnsigned64(
      unsigned base = 10    
    ) const;

    double AsReal() const;
     
    PWORDArray AsUCS2() const;

    PBYTEArray ToPascal() const;

    PString ToLiteral() const;

    operator const unsigned char *() const;

    operator std::string () const
    { return std::string(theArray); }

#ifdef _WIN32_WCE
        operator LPCWSTR() const
    { return AsUCS2(); }
#endif



  protected:
    void InternalFromUCS2(
      const WORD * ptr,
      PINDEX len
    );
    virtual Comparison InternalCompare(
      PINDEX offset,      // Offset into string to compare.
      char c              // Character to compare against.
    ) const;
    virtual Comparison InternalCompare(
      PINDEX offset,      // Offset into string to compare.
      PINDEX length,      // Number of characters to compare.
      const char * cstr   // C string to compare against.
    ) const;
    /* Internal function to compare the current string value against the
       specified C string.

       @return
       relative rank of the two strings.
     */

    PString(int dummy, const PString * str);
};


inline ostream & operator<<(ostream & stream, const PString & string)
{
  string.PrintOn(stream);
  return stream;
}



class PCaselessString : public PString
{
  PCLASSINFO(PCaselessString, PString);

  public:
    PCaselessString();

    PCaselessString(
      const char * cstr   
    );

    PCaselessString(
      const PString & str  
    );


    PCaselessString(
      const std::string & str  
      ) : PString(str)
    { }

    PCaselessString & operator=(
      const PString & str  
    );

    PCaselessString & operator=(
      const char * cstr  
    );

    PCaselessString & operator=(
      char ch            
    );


  // Overrides from class PObject
    virtual PObject * Clone() const;

  protected:
  // Overrides from class PString
    virtual Comparison InternalCompare(
      PINDEX offset,      // Offset into string to compare.
      char c              // Character to compare against.
    ) const;
    virtual Comparison InternalCompare(
      PINDEX offset,      // Offset into string to compare.
      PINDEX length,      // Number of characters to compare.
      const char * cstr   // C string to compare against.
    ) const;
    /* Internal function to compare the current string value against the
       specified C string.

       @return
       relative rank of the two strings or characters.
     */

    PCaselessString(int dummy, const PCaselessString * str);
};


class PStringStream;

class PStringStream : public PString, public iostream
{
  PCLASSINFO(PStringStream, PString);

  public:
    PStringStream();

    PStringStream(
      PINDEX fixedBufferSize
    );

    PStringStream(
      const PString & str   
    );

    PStringStream(
      const char * cstr   
    );

    virtual PString & MakeEmpty();

    PStringStream & operator=(
      const PStringStream & strm
    );

    PStringStream & operator=(
      const PString & str  
    );

    PStringStream & operator=(
      const char * cstr  
    );

    PStringStream & operator=(
      char ch            
    );


    virtual ~PStringStream();


  protected:
    virtual void AssignContents(const PContainer & cont);

  private:
    PStringStream(int, const PStringStream &) : iostream(cout.rdbuf()) { }

    class Buffer : public streambuf {
      public:
        Buffer(PStringStream & str, PINDEX size);
        Buffer(const Buffer & sbuf);
        Buffer & operator=(const Buffer & sbuf);
        virtual int overflow(int=EOF);
        virtual int underflow();
        virtual int sync();
#ifdef __USE_STL__
        virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
        virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
#else
        virtual streampos seekoff(streamoff, ios::seek_dir, int);
#endif
        PStringStream & string;
        BOOL            fixedBufferSize;
    };
};


class PStringList;
class PSortedStringList;

#ifdef DOC_PLUS_PLUS
class PStringArray : public PArray {
#endif
  PDECLARE_ARRAY(PStringArray, PString);
  public:
    PStringArray(
      PINDEX count,                 
      char const * const * strarr,  
      BOOL caseless = FALSE         
    );
    PStringArray(
      const PString & str  
    );
    PStringArray(
      const PStringList & list  
    );
    PStringArray(
      const PSortedStringList & list  
    );

    PStringArray(
      const std::vector<PString> & vec
    )
    {
      for (std::vector<PString>::const_iterator r = vec.begin(); r != vec.end(); ++r)
        AppendString(*r);
    }

    PStringArray(
      const std::vector<std::string> & vec
    )
    {
      for (std::vector<std::string>::const_iterator r = vec.begin(); r != vec.end(); ++r)
        AppendString(PString(*r));
    }

    template <typename stlContainer>
    static PStringArray container(
      const stlContainer & vec
    )
    {
      PStringArray list;
      for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
        list.AppendString(PString(*r));
      return list;
    }


    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );

    PINDEX GetStringsIndex(
      const PString & str 
    ) const;

    PString operator[](
      PINDEX index  
    ) const;

    PString & operator[](
      PINDEX index  
    );

    PINDEX AppendString(
      const PString & str 
    );

    PStringArray & operator +=(const PStringArray & array);
    PStringArray & operator +=(const PString & str);


    PStringArray operator + (const PStringArray & array);
    PStringArray operator + (const PString & str);

    char ** ToCharArray(
      PCharArray * storage = NULL
    ) const;
};


#ifdef DOC_PLUS_PLUS
class PStringList : public PList {
#endif
PDECLARE_LIST(PStringList, PString);
  public:
    PStringList(
      PINDEX count,                 
      char const * const * strarr,  
      BOOL caseless = FALSE         
    );
    PStringList(
      const PString & str  
    );
    PStringList(
      const PStringArray & array  
    );
    PStringList(
      const PSortedStringList & list  
    );

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );

    PINDEX AppendString(
      const PString & str 
    );

    PINDEX InsertString(
      const PString & before,   
      const PString & str       
    );

    PINDEX GetStringsIndex(
      const PString & str   
    ) const;

    PStringList & operator +=(const PStringList & list);
    PStringList & operator +=(const PString & str);


    PStringList operator + (const PStringList & array);
    PStringList operator + (const PString & str);

    template <typename stlContainer>
    static PStringList container(
      const stlContainer & vec
    )
    {
      PStringList list;
      for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
        list.AppendString(PString(*r));
      return list;
    }
};


#ifdef DOC_PLUS_PLUS
class PSortedStringList : public PSortedList {
#endif
PDECLARE_SORTED_LIST(PSortedStringList, PString);
  public:
    PSortedStringList(
      PINDEX count,                 
      char const * const * strarr,  
      BOOL caseless = FALSE         
    );
    PSortedStringList(
      const PString & str  
    );
    PSortedStringList(
      const PStringArray & array  
    );
    PSortedStringList(
      const PStringList & list  
    );

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );

    PINDEX AppendString(
      const PString & str 
    );

    PINDEX GetStringsIndex(
      const PString & str   
    ) const;

    PINDEX GetNextStringsIndex(
      const PString & str   
    ) const;

  protected:
    PINDEX InternalStringSelect(
      const char * str,
      PINDEX len,
      Element * thisElement
    ) const;
};


#ifdef DOC_PLUS_PLUS
class PStringSet : public PSet {
#endif
PDECLARE_SET(PStringSet, PString, TRUE);
  public:
    PStringSet(
      PINDEX count,                 
      char const * const * strarr,  
      BOOL caseless = FALSE         
    );
    PStringSet(
      const PString & str  
    );

    virtual void ReadFrom(
      istream &strm   
    );

    void Include(
      const PString & key 
    );
    PStringSet & operator+=(
      const PString & key 
    );
    void Exclude(
      const PString & key 
    );
    PStringSet & operator-=(
      const PString & key 
    );
};


#ifdef PHAS_TEMPLATES

template <class K> class PStringDictionary : public PAbstractDictionary
{
  PCLASSINFO(PStringDictionary, PAbstractDictionary);

  public:
    PStringDictionary()
      : PAbstractDictionary() { }

    virtual PObject * Clone() const
      { return PNEW PStringDictionary(0, this); }

    const PString & operator[](const K & key) const
      { return (const PString &)GetRefAt(key); }

    PString operator()(const K & key, const char * dflt = "") const
      { if (AbstractContains(key)) return (*this)[key]; return dflt; }

    BOOL Contains(
      const K & key   // Key to look for in the dictionary.
      ) const { return AbstractContains(key); }

    virtual PString * RemoveAt(
      const K & key   // Key for position in dictionary to get object.
    ) {
        PString * s = GetAt(key); AbstractSetAt(key, NULL);
        return reference->deleteObjects ? (s ? (PString *)-1 : NULL) : s;
      }

    virtual PString * GetAt(
      const K & key   // Key for position in dictionary to get object.
    ) const { return (PString *)AbstractGetAt(key); }

    virtual BOOL SetDataAt(
      PINDEX index,        // Ordinal index in the dictionary.
      const PString & str  // New string value to put into the dictionary.
    ) { return PAbstractDictionary::SetDataAt(index, PNEW PString(str)); }

    virtual BOOL SetAt(
      const K & key,       // Key for position in dictionary to add object.
      const PString & str  // New string value to put into the dictionary.
    ) { return AbstractSetAt(key, PNEW PString(str)); }

    const K & GetKeyAt(PINDEX index) const
      { return (const K &)AbstractGetKeyAt(index); }

    PString & GetDataAt(PINDEX index) const
      { return (PString &)AbstractGetDataAt(index); }

  protected:
    PStringDictionary(int dummy, const PStringDictionary * c)
      : PAbstractDictionary(dummy, c) { }
};


#define PDECLARE_STRING_DICTIONARY(cls, K) \
  PDECLARE_CLASS(cls, PStringDictionary<K>) \
  protected: \
    cls(int dummy, const cls * c) \
      : PStringDictionary<K>(dummy, c) { } \
  public: \
    cls() \
      : PStringDictionary<K>() { } \
    virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \


#define PSTRING_DICTIONARY(cls, K) typedef PStringDictionary<K> cls


#else // PHAS_TEMPLATES


#define PSTRING_DICTIONARY(cls, K) \
  class cls : public PAbstractDictionary { \
  PCLASSINFO(cls, PAbstractDictionary) \
  protected: \
    inline cls(int dummy, const cls * c) \
      : PAbstractDictionary(dummy, c) { } \
  public: \
    inline cls() \
      : PAbstractDictionary() { } \
    inline PObject * Clone() const \
      { return PNEW cls(0, this); } \
    inline PString & operator[](const K & key) const \
      { return (PString &)GetRefAt(key); } \
    inline PString operator()(const K & key, const char * dflt = "") const \
      { if (Contains(key)) return (PString &)GetRefAt(key); return dflt; } \
    virtual BOOL Contains(const K & key) const \
      { return AbstractContains(key); } \
    virtual PString * RemoveAt(const K & key) \
      { PString * s = GetAt(key); AbstractSetAt(key, NULL); \
        return reference->deleteObjects ? (s ? (PString *)-1 : NULL) : s; } \
    virtual PString * GetAt(const K & key) const \
      { return (PString *)AbstractGetAt(key); } \
    virtual BOOL SetDataAt(PINDEX index, const PString & str) \
      { return PAbstractDictionary::SetDataAt(index,PNEW PString(str));} \
    virtual BOOL SetAt(const K & key, const PString & str) \
      { return AbstractSetAt(key, PNEW PString(str)); } \
    inline const K & GetKeyAt(PINDEX index) const \
      { return (const K &)AbstractGetKeyAt(index); } \
    inline PString & GetDataAt(PINDEX index) const \
      { return (PString &)AbstractGetDataAt(index); } \
  }

#define PDECLARE_STRING_DICTIONARY(cls, K) \
  PSTRING_DICTIONARY(cls##_PTemplate, K); \
  PDECLARE_CLASS(cls, cls##_PTemplate) \
  protected: \
    cls(int dummy, const cls * c) \
      : cls##_PTemplate(dummy, c) { } \
  public: \
    cls() \
      : cls##_PTemplate() { } \
    virtual PObject * Clone() const \
      { return PNEW cls(0, this); } \

#endif // PHAS_TEMPLATES


#ifdef DOC_PLUS_PLUS
class POrdinalToString : public PStringDictionary {
#endif
PDECLARE_STRING_DICTIONARY(POrdinalToString, POrdinalKey);
  public:

    struct Initialiser {
      PINDEX key;
      const char * value;
    };
    POrdinalToString(
      PINDEX count,                
      const Initialiser * init     
    );

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );
};

#ifdef DOC_PLUS_PLUS
class PStringToOrdinal : public POrdinalDictionary {
#endif
PDECLARE_ORDINAL_DICTIONARY(PStringToOrdinal, PString);
  public:

    struct Initialiser {
      const char * key;
      PINDEX value;
    };
    PStringToOrdinal(
      PINDEX count,                
      const Initialiser * init,    
      BOOL caseless = FALSE        
    );

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );
};


#ifdef DOC_PLUS_PLUS
class PStringToString : public PStringDictionary {
#endif
PDECLARE_STRING_DICTIONARY(PStringToString, PString);
  public:

    struct Initialiser {
      const char * key;
      const char * value;
    };
    PStringToString(
      PINDEX count,                
      const Initialiser * init,    
      BOOL caselessKeys = FALSE,   
      BOOL caselessValues = FALSE  
    );

    virtual void ReadFrom(
      istream &strm   // Stream to read the objects contents from.
    );
};


class PRegularExpression : public PObject
{
  PCLASSINFO(PRegularExpression, PObject);

  public:

    enum {
      Extended = 1,
      IgnoreCase = 2,
      AnchorNewLine = 4
    };
    enum {
      NotBeginningOfLine = 1,
      NotEndofLine = 2
    };

    PRegularExpression();

    PRegularExpression(
      const PString & pattern,    
      int flags = IgnoreCase      
    );

    PRegularExpression(
      const char * cpattern,      
      int flags = IgnoreCase      
    );

    PRegularExpression(
      const PRegularExpression &
    );

    PRegularExpression & operator =(
      const PRegularExpression &
    );

    ~PRegularExpression();


    enum ErrorCodes {
      NoError = 0,    
      NoMatch,      

      // POSIX regcomp return error codes.  (In the order listed in the standard.)
      BadPattern,  
      CollateError,  
      BadClassType,  
      BadEscape,    
      BadSubReg,
      UnmatchedBracket, 
      UnmatchedParen,
      UnmatchedBrace,
      BadBR,        
      RangeError,  
      OutOfMemory,
      BadRepitition,

      /* Error codes we've added.  */
      PrematureEnd,
      TooBig,
      UnmatchedRParen,
      NotCompiled
    };

    ErrorCodes GetErrorCode() const;

    PString GetErrorText() const;

    BOOL Compile(
      const PString & pattern,    
      int flags = IgnoreCase      
    );
    BOOL Compile(
      const char * cpattern,      
      int flags = IgnoreCase      
    );


    BOOL Execute(
      const PString & str,    
      PINDEX & start,         
      int flags = 0           
    ) const;
    BOOL Execute(
      const PString & str,    
      PINDEX & start,         
      PINDEX & len,           
      int flags = 0           
    ) const;
    BOOL Execute(
      const char * cstr,      
      PINDEX & start,         
      int flags = 0           
    ) const;
    BOOL Execute(
      const char * cstr,      
      PINDEX & start,         
      PINDEX & len,           
      int flags = 0           
    ) const;
    BOOL Execute(
      const PString & str,    
      PIntArray & starts,     
      int flags = 0           
    ) const;
    BOOL Execute(
      const PString & str,    
      PIntArray & starts,     
      PIntArray & ends,       
      int flags = 0           
    ) const;
    BOOL Execute(
      const char * cstr,      
      PIntArray & starts,     
      int flags = 0           
    ) const;
    BOOL Execute(
      const char * cstr,      
      PIntArray & starts,     
      PIntArray & ends,       
      int flags = 0           
    ) const;

    static PString EscapeString(
      const PString & str     
    );

  protected:
    PString patternSaved;
    int flagsSaved;

    void * expression;
    mutable ErrorCodes lastError;
};

PString psprintf(const char * cfmt, ...);

#endif // #ifndef __PSTRING__
// End Of File ///////////////////////////////////////////////////////////////

---