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): ______________________________________.
 *
 * $Revision: 31109 $
 * $Author: ededu $
 * $Date: 2013-12-18 22:26:43 +1100 (Wed, 18 Dec 2013) $
 */

#ifndef PTLIB_STRING_H
#define PTLIB_STRING_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


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


// PString class

class PStringArray;
class PRegularExpression;
class PString;

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

PString pvsprintf(
  const char * fmt, 
  va_list arg       
);


#ifdef P_HAS_WCHAR

typedef PBaseArray<wchar_t> PWCharArray;
#endif


class PString : public PCharArray
{
    PCLASSINFO(PString, PCharArray);
  public:
    typedef const char * Initialiser;

    PString();

    PString(
      const PString & str  
    );

    PString(
      const PCharArray & buf  
    );

    PString(
      const PBYTEArray & buf  
    );

    PString(
      const std::string & str
    );

    PString(
      const char * cstr 
    );

#ifdef P_HAS_WCHAR
    PString(
      const wchar_t * ustr 
    );
#endif

    PString(
      const char * cstr,  
      PINDEX len          
    );

#ifdef P_HAS_WCHAR
    PString(
      const wchar_t * ustr,  
      PINDEX len          
    );

    PString(
      const PWCharArray & ustr 
    );
#endif

    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   
    );

 
    /* Type of conversion to make in the conversion constructors.
     */
    enum ConversionType {
      Pascal,   
      Basic,    
      Literal,  
      Signed,   
      Unsigned, 
      Decimal,  
      Exponent, 
      ScaleSI,  
      Printf,   
      NumConversionTypes
    };

    /* Contruct a new string converting from the spcified data source into
       a string array.
     */
    PString(
      ConversionType type,  
      const char * str,    
      ...                 
    );
    PString(
      ConversionType type, 
      PInt64 value,        
      unsigned param = 10  
    );
    PString(ConversionType type, PUInt64        value, unsigned param = 10);
    PString(ConversionType type, unsigned long  value, unsigned param = 10);
    PString(ConversionType type,   signed long  value, unsigned param = 10);
    PString(ConversionType type, unsigned int   value, unsigned param = 10);
    PString(ConversionType type,   signed int   value, unsigned param = 10);
    PString(ConversionType type, unsigned short value, unsigned param = 10);
    PString(ConversionType type,   signed short value, unsigned param = 10);
    PString(ConversionType type, unsigned char  value, unsigned param = 10);
    PString(ConversionType type,   signed char  value, unsigned param = 10);

    /* Contruct a new string converting from the spcified data source into
       a string array.
     */
    PString(
      ConversionType type,  
      double value,         
      unsigned places       
    );

    PString & operator=(
      const PString & str  
    );

    PString & operator=(
      const std::string & str  
    ) { return operator=(str.c_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 const 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 PBoolean SetSize(
      PINDEX newSize  
    );

    virtual PBoolean IsEmpty() const;

    virtual PBoolean MakeUnique();


    bool MakeMinimumSize(
      PINDEX newLength = 0  
    );

    virtual PINDEX GetLength() const { return m_length; }

    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  ch,             
      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 PString & str  
    ) const;

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

    bool operator<(
      const PString & str  
    ) const;

    bool operator>(
      const PString & str  
    ) const;

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

    bool operator>=(
      const PString & 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;

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

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

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

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

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

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

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

    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 <code>offset</code> 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;

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


    PBoolean MatchesRegEx(
      const PRegularExpression & regex 
    ) const;

    void Replace(
      const PString & target,   
      const PString & subs,     
      PBoolean 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;


    bool Split(
      char delimiter,   
      PString & before, 
      PString & after,  
      bool trim = true  
    ) const;


    PStringArray Tokenise(
      const PString & separators,
      PBoolean onePerSeparator = true
    ) const;
    PStringArray Tokenise(
      const char * cseparators,
      PBoolean 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;
     
#ifdef P_HAS_WCHAR

    PWCharArray AsUCS2() const;
#endif

    PBYTEArray ToPascal() const;

    PString ToLiteral() const;

    PString FromLiteral(
      PINDEX & offset
    ) const;

    operator const unsigned char *() const;

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

    char * GetPointerAndSetLength(
      PINDEX len    
    );

    virtual const char * GetPointer(PINDEX = 0) const { return (const char *)(*this); }



  protected:
#ifdef P_HAS_WCHAR
    void InternalFromUCS2(
      const wchar_t * ptr,
      PINDEX len
    );
#endif
    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);

    virtual void AssignContents(const PContainer &);
    PString(PContainerReference & reference_, PINDEX len)
      : PCharArray(reference_)
      , m_length(len)
      { }

  protected:
    mutable PINDEX m_length; // Length of the string, always at least one less than GetSize()
};


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

#ifdef P_HAS_WOSTREAM
inline wostream & operator<<(wostream & stream, const PString & string)
{
  return stream << (const char *)string;
}
#endif


#ifdef _WIN32
  class PWideString : public PWCharArray {
    PCLASSINFO(PWideString, PWCharArray);

    public:
    typedef const wchar_t * Initialiser;

      PWideString() { }
      PWideString(const PWCharArray & arr) : PWCharArray(arr) { }
      PWideString(const PString     & str) : PWCharArray(str.AsUCS2()) { }
      PWideString(const char        * str) : PWCharArray(PString(str).AsUCS2()) { }
      PWideString & operator=(const PWideString & str) { PWCharArray::operator=(str); return *this; }
      PWideString & operator=(const PString     & str) { PWCharArray::operator=(str.AsUCS2()); return *this; }
      PWideString & operator=(const std::string & str) { PWCharArray::operator=(PString(str.c_str()).AsUCS2()); return *this; }
      PWideString & operator=(const char        * str) { PWCharArray::operator=(PString(str).AsUCS2()); return *this; }
      friend inline ostream & operator<<(ostream & stream, const PWideString & string) { return stream << PString(string); }

    protected:
      PWideString(PContainerReference & reference_) : PWCharArray(reference_) { }
  };

  #ifdef UNICODE
    typedef PWideString PVarString;
  #else
    typedef PString PVarString;
  #endif
#endif



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 std::string & str  
    ) { return operator=(str.c_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);
    PCaselessString(PContainerReference & reference_, PINDEX len) : PString(reference_, len) { }
};



template <class ParentString>
class PConstantString : public ParentString
{
  private:
    PContainerReference m_staticReference;
  public:
    PConstantString(typename ParentString::Initialiser init)
      : ParentString(m_staticReference, init != NULL ? strlen(init) : 0)
      , P_DISABLE_MSVC_WARNINGS(4267 4355, m_staticReference(this->m_length+1, true))
    {
      this->theArray = (char *)(init != NULL ? init : "");
    }
    ~PConstantString() { this->Destruct(); }

    virtual PBoolean SetSize(PINDEX s) { return s <= this->m_length+1; }
    virtual void AssignContents(const PContainer &) { PAssertAlways(PInvalidParameter); }
    virtual void DestroyReference() { }

  private:
    PConstantString(const PConstantString &)
      : ParentString(m_staticReference)
      , m_staticReference(0, true)
      { }
    void operator=(const PConstantString &) { }
};


typedef PConstantString<PString>         PConstString;

typedef PConstantString<PCaselessString> PConstCaselessString;




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

  public:
    PStringStream();

    PStringStream(
      PINDEX fixedBufferSize
    );

    PStringStream(
      const PString & str   
    );

    PStringStream(
      const char * cstr   
    );

    virtual ~PStringStream();

    virtual PString & MakeEmpty();

    PStringStream & operator=(
      const PStringStream & strm
    );

    PStringStream & operator=(
      const PString & str  
    );

    PStringStream & operator=(
      const char * cstr  
    );

    PStringStream & operator=(
      char ch            
    );

    virtual PINDEX GetLength() const;

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

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

    class Buffer : public streambuf {
      public:
        Buffer(PStringStream & str, PINDEX size);
        Buffer(const Buffer & sbuf);
        Buffer & operator=(const Buffer & sbuf);
        virtual int_type overflow(int_type = EOF);
        virtual int_type underflow();
        virtual int sync();
        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);
        PCharArray & string;
        PBoolean     fixedBufferSize;
    };
};


#define PSTRSTRM(arg) dynamic_cast<const PString &>(PStringStream() << std::flush << arg)


class PStringList;
class PSortedStringList;

class PStringArray : public PArray<PString>
{
    typedef PArray<PString> ParentClass;
    PCLASSINFO(PStringArray, ParentClass);

  protected:
    inline PStringArray(int dummy, const PStringArray * c)
      : ParentClass(dummy, c) { }

  public:

    inline PStringArray(PINDEX initialSize = 0)
      : ParentClass(initialSize) { }

    PStringArray(
      PINDEX count,                 
      char const * const * strarr,  
      PBoolean 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.
    );

    virtual PObject * Clone() const
    {
      return new PStringArray(0, this);
    }

    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;
};


class PStringList : public PList<PString>
{
    typedef PList<PString> ParentClass;
    PCLASSINFO(PStringList, ParentClass);

  protected:
    PStringList(int dummy, const PStringList * c)
      : ParentClass(dummy, c) { }

  public:
    PStringList()
      : ParentClass() { }

    PStringList(
      PINDEX count,                 
      char const * const * strarr,  
      PBoolean 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.
    );

    virtual PObject * Clone() const
    {
      return new PStringList(0, this);
    }

    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,  
      PBoolean 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,
      PSortedListElement * thisElement,
      PSortedListElement * & lastElement
    ) const;
};


class PStringSet : public PSet<PString>
{
    typedef PSet<PString> BaseClass;
    PCLASSINFO(PStringSet, BaseClass);

  protected:
    PStringSet(int dummy, const PStringSet * c)
      : BaseClass(dummy, c) { }

  public:
    PStringSet(PBoolean initialDeleteObjects = true)
      : BaseClass(initialDeleteObjects) { }

    PStringSet(
      PINDEX count,                 
      char const * const * strarr,  
      PBoolean caseless = false         
    );

    PStringSet(
      const PString & str  
    );
    PStringSet(
      const PStringArray & strArray  
    );
    PStringSet(
      const PStringList & strList  
    );

    virtual void ReadFrom(
      istream &strm   
    );

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

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


template <class K> class PStringDictionary : public PDictionary<K, PString>
{
  typedef PDictionary<K, PString> ParentClass;
  PCLASSINFO(PStringDictionary, ParentClass);

  public:
    PStringDictionary()
      : ParentClass() { }

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

    PString operator()(const K & key, const char * dflt = NULL) const
    {
      PString * str = this->GetAt(key);
      return str != NULL ? *str : PString(dflt);
    }

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

  protected:
    PStringDictionary(int dummy, const PStringDictionary * c)
      : ParentClass(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


#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,    
      PBoolean 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,    
      PBoolean caselessKeys = false,   
      PBoolean caselessValues = false  
    );

    PStringToString(
      const PString & str  
    ) { FromString(str); }

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

    char ** ToCharArray(
      bool withEqualSign,
      PCharArray * storage = NULL
    ) const;

    void FromString(
      const PString & str  
    );
};


class PStringOptions : public PStringToString 
{
  public:
    PStringOptions() { }
    PStringOptions(const PString & str) : PStringToString(str) { }
    PStringOptions(const PStringToString & other) : PStringToString(other) { }
    PStringOptions & operator=(const PStringToString & other) { PStringToString::operator=(other); return *this; }

    bool Contains(const char *              key   ) const { PConstCaselessString k(key); return PStringToString::Contains(k); }
    bool Contains(const PString         &   key   ) const { return PStringToString::Contains(PCaselessString(key)); }
    bool Contains(const PCaselessString &   key   ) const { return PStringToString::Contains(key); }
    bool Contains(const PCaselessString & (*key)()) const { return PStringToString::Contains(key()); }

    // Overide default PStringToString::SetAt() to make sure the key is caseless
    PString * GetAt(const char *              key   ) const { PConstCaselessString k(key); return PStringToString::GetAt(k); }
    PString * GetAt(const PString         &   key   ) const { return PStringToString::GetAt(PCaselessString(key)); }
    PString * GetAt(const PCaselessString &   key   ) const { return PStringToString::GetAt(key); }
    PString * GetAt(const PCaselessString & (*key)()) const { return PStringToString::GetAt(key()); }

    // Overide default PStringToString::SetAt() to make sure the key is caseless
    PBoolean SetAt(const char *              key,    const PString & data) { PConstCaselessString k(key); return SetAt(k, data); }
    PBoolean SetAt(const PString         &   key,    const PString & data) { return SetAt(PCaselessString(key), data); }
    PBoolean SetAt(const PCaselessString &   key,    const PString & data) { MakeUnique(); return PStringToString::SetAt(key, data); }
    PBoolean SetAt(const PCaselessString & (*key)(), const PString & data) { return SetAt(key(), data); }

    // Overide default PStringToString::RemoveAt() to make sure the key is caseless
    PString * RemoveAt(const char *              key)    { PConstCaselessString k(key); return RemoveAt(k); }
    PString * RemoveAt(const PString         &   key)    { return RemoveAt(PCaselessString(key)); }
    PString * RemoveAt(const PCaselessString &   key)    { MakeUnique(); return PStringToString::RemoveAt(key); }
    PString * RemoveAt(const PCaselessString & (*key)()) { return RemoveAt(key()); }

    PString GetString(const char *              key,    const char * dflt = NULL) const { PConstCaselessString k(key); return GetString(k, dflt); }
    PString GetString(const PString         &   key,    const char * dflt = NULL) const { return GetString(PCaselessString(key), dflt); }
    PString GetString(const PCaselessString &   key,    const char * dflt = NULL) const;
    PString GetString(const PCaselessString & (*key)(), const char * dflt = NULL) const { return GetString(key(), dflt); }

    bool SetString(const char *              key,    const PString & value) { return SetAt(key, value); }
    bool SetString(const PString         &   key,    const PString & value) { return SetAt(key, value); }
    bool SetString(const PCaselessString &   key,    const PString & value) { return SetAt(key, value); }
    bool SetString(const PCaselessString & (*key)(), const PString & value) { return SetAt(key, value); }

    bool GetBoolean(const char *              key,    bool dflt = false) const { PConstCaselessString k(key); return GetBoolean(k, dflt); }
    bool GetBoolean(const PString         &   key,    bool dflt = false) const { return GetBoolean(PCaselessString(key), dflt); }
    bool GetBoolean(const PCaselessString &   key,    bool dflt = false) const;
    bool GetBoolean(const PCaselessString & (*key)(), bool dflt = false) const { return GetBoolean(key(), dflt); }

    void SetBoolean(const char *              key,    bool value) { PConstCaselessString k(key); SetBoolean(k, value); }
    void SetBoolean(const PString         &   key,    bool value) { SetBoolean(PCaselessString(key), value); }
    void SetBoolean(const PCaselessString &   key,    bool value) { SetAt(key, value ? "true" : "false"); }
    void SetBoolean(const PCaselessString & (*key)(), bool value) { SetBoolean(key(), value); }

    long GetInteger(const char *              key,    long dflt = 0) const { PConstCaselessString k(key); return GetInteger(k, dflt); }
    long GetInteger(const PString         &   key,    long dflt = 0) const { return GetInteger(PCaselessString(key), dflt); }
    long GetInteger(const PCaselessString &   key,    long dflt = 0) const;
    long GetInteger(const PCaselessString & (*key)(), long dflt = 0) const { return GetInteger(key(), dflt); }

    void SetInteger(const char *              key,    long value) { PConstCaselessString k(key); SetInteger(k, value); }
    void SetInteger(const PString         &   key,    long value) { SetInteger(PCaselessString(key), value); }
    void SetInteger(const PCaselessString &   key,    long value);
    void SetInteger(const PCaselessString & (*key)(), long value) { SetInteger(key(), value); }

    template<typename E> E GetEnum(const char *              key,    E dflt) const { PConstCaselessString k(key); return GetEnum(k, dflt); }
    template<typename E> E GetEnum(const PString         &   key,    E dflt) const { return GetEnum(PCaselessString(key), dflt); }
    template<typename E> E GetEnum(const PCaselessString &   key,    E dflt) const { return (E)GetInteger(key, dflt); }
    template<typename E> E GetEnum(const PCaselessString & (*key)(), E dflt) const { return GetEnum(key(), dflt); }

    template<typename E> void SetEnum(const char *              key,    E value) { PConstCaselessString k(key); SetInteger(k, value); }
    template<typename E> void SetEnum(const PString         &   key,    E value) { SetInteger(PCaselessString(key), value); }
    template<typename E> void SetEnum(const PCaselessString &   key,    E value) { SetInteger(key, value); }
    template<typename E> void SetEnum(const PCaselessString & (*key)(), E value) { SetInteger(key(), value); }

    double GetReal(const char *              key,    double dflt = 0) const { PConstCaselessString k(key); return GetReal(k, dflt); }
    double GetReal(const PString         &   key,    double dflt = 0) const { return GetReal(PCaselessString(key), dflt); }
    double GetReal(const PCaselessString &   key,    double dflt = 0) const;
    double GetReal(const PCaselessString & (*key)(), double dflt = 0) const { return GetReal(key(), dflt); }

    void SetReal(const char *              key,    double value, int decimals) { PConstCaselessString k(key); SetReal(k, value, decimals); }
    void SetReal(const PString         &   key,    double value, int decimals) { SetReal(PCaselessString(key), value, decimals); }
    void SetReal(const PCaselessString &   key,    double value, int decimals);
    void SetReal(const PCaselessString & (*key)(), double value, int decimals) { SetReal(key(), value, decimals); }

    __inline bool Has(const char * key) const                 { return Contains(key); }
    __inline bool Has(const PString & key) const              { return Contains(key); }
    __inline bool Has(const PCaselessString & key) const      { return Contains(key); }
    __inline bool Has(const PCaselessString & (*key)()) const { return Contains(key); }

    __inline PString Get(const char *              key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    __inline PString Get(const PString         &   key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    __inline PString Get(const PCaselessString &   key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    __inline PString Get(const PCaselessString & (*key)(), const char * dflt = NULL) const { return GetString(key, dflt); }
    __inline PString Get(const char *              key,    const PString & dflt) const { return GetString(key, dflt); }
    __inline PString Get(const PString         &   key,    const PString & dflt) const { return GetString(key, dflt); }
    __inline PString Get(const PCaselessString &   key,    const PString & dflt) const { return GetString(key, dflt); }
    __inline PString Get(const PCaselessString & (*key)(), const PString & dflt) const { return GetString(key, dflt); }

    __inline bool Set(const char *              key,    const PString & value) { return SetAt(key, value); }
    __inline bool Set(const PString         &   key,    const PString & value) { return SetAt(key, value); }
    __inline bool Set(const PCaselessString &   key,    const PString & value) { return SetAt(key, value); }
    __inline bool Set(const PCaselessString & (*key)(), const PString & value) { return SetAt(key, value); }

    __inline void Remove(const char *              key)    { RemoveAt(key); }
    __inline void Remove(const PString         &   key)    { RemoveAt(key); }
    __inline void Remove(const PCaselessString &   key)    { RemoveAt(key); }
    __inline void Remove(const PCaselessString & (*key)()) { RemoveAt(key); }
};


// Put include here as needs PString above to be defined.
#include <ptlib/bitwise_enum.h>


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

    P_DECLARE_BITWISE_ENUM(
      CompileOptions, 3,
      (
        Simple,         
        Extended,       
        IgnoreCase,     
        AnchorNewLine   
      )
    );

    P_DECLARE_BITWISE_ENUM(
      ExecOptions, 2,
      (
        Normal,             
        NotBeginningOfLine, 
        NotEndofLine        
      )
    );

    PRegularExpression();

    PRegularExpression(
      const PString & pattern,            
      CompileOptions options = IgnoreCase 
    );

    PRegularExpression(
      const char * cpattern,              
      CompileOptions options = IgnoreCase 
    );

    PRegularExpression(
      const PRegularExpression &
    );

    PRegularExpression & operator =(
      const PRegularExpression &
    );

    ~PRegularExpression();


    virtual void PrintOn(
      ostream & strm  
    ) const;


    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 { return m_lastError; }

    PString GetErrorText() const;

    const PString & GetPattern() const { return m_pattern; }

    bool Compile(
      const PString & pattern,            
      CompileOptions options = IgnoreCase 
    );
    bool Compile(
      const char * cpattern,              
      CompileOptions options = IgnoreCase 
    );


    bool Execute(
      const PString & str,          
      PINDEX & start,               
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const PString & str,          
      PINDEX & start,               
      PINDEX & len,                 
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const char * cstr,            
      PINDEX & start,               
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const char * cstr,            
      PINDEX & start,               
      PINDEX & len,                 
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const PString & str,          
      PIntArray & starts,           
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const PString & str,          
      PIntArray & starts,           
      PIntArray & ends,             
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const char * cstr,            
      PIntArray & starts,           
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const char * cstr,            
      PIntArray & starts,           
      PIntArray & ends,             
      ExecOptions options = Normal  
    ) const;
    bool Execute(
      const char * cstr,            
      PStringArray & substring,     
      ExecOptions options = Normal  
    ) const;

    static PString EscapeString(
      const PString & str     
    );

  protected:
    bool InternalCompile();
    void InternalClean();

    PString            m_pattern;
    CompileOptions     m_compileOptions;
    void             * m_compiledRegex;
    mutable ErrorCodes m_lastError;
};


#endif // PTLIB_STRING_H


// End Of File ///////////////////////////////////////////////////////////////