# 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  * $Revision: 27359 $
    00030  * $Author: rjongbloed $
    00031  * $Date: 2012-03-28 21:17:54 -0500 (Wed, 28 Mar 2012) $
    00032  */
    00033
    00034 #ifndef PTLIB_STRING_H
    00035 #define PTLIB_STRING_H
    00036
    00037 #ifdef P_USE_PRAGMA
    00038 #pragma interface
    00039 #endif
    00040
    00041 #include <string>
    00042 #include <vector>
    00043 #include <ptlib/array.h>
    00044
    00046 // PString class
    00047
    00048 class PStringArray;
    00049 class PRegularExpression;
    00050 class PString;
    00051
    00055 PString psprintf(
    00056   const char * fmt,
    00057   ...
    00058 );
    00059
    00063 PString pvsprintf(
    00064   const char * fmt,
    00065   va_list arg
    00066 );
    00067
    00068 #if (defined(_WIN32) || defined(_WIN32_WCE)) && (!defined(_NATIVE_WCHAR_T_DEFINED)) && (!defined(__MINGW32__))
    00069 PBASEARRAY(PWCharArray, unsigned short);
    00070 #else
    00071 PBASEARRAY(PWCharArray, wchar_t);
    00072 #endif
    00073
    00108 class PString : public PCharArray
    00109 {
    00110   PCLASSINFO(PString, PCharArray);
    00111
    00112 //  using namespace std;
    00113
    00114   public:
    00115     typedef const char * Initialiser;
    00116
    00122     PINLINE PString();
    00123
    00127     PINLINE PString(
    00128       const PString & str
    00129     );
    00130
    00133     PINLINE PString(
    00134       const std::string & str
    00135     );
    00136
    00145     PString(
    00146       const char * cstr
    00147     );
    00148
    00153     PString(
    00154       const wchar_t * ustr
    00155     );
    00156
    00170     PString(
    00171       const char * cstr,
    00172       PINDEX len
    00173     );
    00174
    00185     PString(
    00186       const wchar_t * ustr,
    00187       PINDEX len
    00188     );
    00189
    00200     PString(
    00201       const PWCharArray & ustr
    00202     );
    00203
    00212     PString(
    00213       char ch
    00214     );
    00215
    00220     PString(
    00221       short n
    00222     );
    00223
    00228     PString(
    00229       unsigned short n
    00230     );
    00231
    00236     PString(
    00237       int n
    00238     );
    00239
    00244     PString(
    00245       unsigned int n
    00246     );
    00247
    00252     PString(
    00253       long n
    00254     );
    00255
    00260     PString(
    00261       unsigned long n
    00262     );
    00263
    00268     PString(
    00269       PInt64 n
    00270     );
    00271
    00276     PString(
    00277       PUInt64 n
    00278     );
    00279
    00280
    00281     enum ConversionType {
    00282       Pascal,   // Data is a length byte followed by characters.
    00283       Basic,    // Data is two length bytes followed by characters.
    00284       Literal,  // Data is C language style string with \\ escape codes.
    00285       Signed,   // Convert a signed integer to a string.
    00286       Unsigned, // Convert an unsigned integer to a string.
    00287       Decimal,  // Convert a real number to a string in decimal format.
    00288       Exponent, // Convert a real number to a string in exponent format.
    00289       Printf,   // Formatted output, sprintf() style function.
    00290       NumConversionTypes
    00291     };
    00292     /* Type of conversion to make in the conversion constructors.
    00293      */
    00294
    00295     /* Contruct a new string converting from the spcified data source into
    00296        a string array.
    00297      */
    00298     PString(
    00299       ConversionType type,
    00300       const char * str,
    00301       ...
    00302     );
    00303     PString(
    00304       ConversionType type,
    00305       long value,
    00306       unsigned base = 10
    00307     );
    00308     PString(
    00309       ConversionType type,
    00310       double value,
    00311       unsigned places
    00312     );
    00313
    00321     PString & operator=(
    00322       const PString & str
    00323     );
    00324
    00332     PString & operator=(
    00333       const std::string & str
    00334     ) { return operator=(str.c_str()); }
    00335
    00345     PString & operator=(
    00346       const char * cstr
    00347     );
    00348
    00357     PString & operator=(
    00358       char ch
    00359     );
    00360
    00365     PString & operator=(
    00366       short n
    00367     );
    00368
    00373     PString & operator=(
    00374       unsigned short n
    00375     );
    00376
    00381     PString & operator=(
    00382       int n
    00383     );
    00384
    00389     PString & operator=(
    00390       unsigned int n
    00391     );
    00392
    00397     PString & operator=(
    00398       long n
    00399     );
    00400
    00405     PString & operator=(
    00406       unsigned long n
    00407     );
    00408
    00413     PString & operator=(
    00414       PInt64 n
    00415     );
    00416
    00421     PString & operator=(
    00422       PUInt64 n
    00423     );
    00424
    00427     virtual PString & MakeEmpty();
    00428
    00431     static PString Empty();
    00433
    00440     virtual PObject * Clone() const;
    00441
    00451     virtual Comparison Compare(
    00452       const PObject & obj
    00453     ) const;
    00454
    00457     virtual void PrintOn(
    00458       ostream & strm
    00459     ) const;
    00460
    00466     virtual void ReadFrom(
    00467       istream & strm
    00468     );
    00469
    00483     virtual PINDEX HashFunction() const;
    00485
    00500     virtual PBoolean SetSize(
    00501       PINDEX newSize
    00502     );
    00503
    00512     virtual PBoolean IsEmpty() const;
    00513
    00522     virtual PBoolean MakeUnique();
    00524
    00525
    00538     PBoolean MakeMinimumSize();
    00539
    00548     PINLINE PINDEX GetLength() const;
    00549
    00556     bool operator!() const;
    00558
    00567     PString operator+(
    00568       const PString & str
    00569     ) const;
    00570
    00582     PString operator+(
    00583       const char * cstr
    00584     ) const;
    00585
    00597     PString operator+(
    00598       char ch
    00599     ) const;
    00600
    00612     friend PString operator+(
    00613       const char * cstr,
    00614       const PString & str
    00615     );
    00616
    00628     friend PString operator+(
    00629       char  ch,
    00630       const PString & str
    00631     );
    00632
    00638     PString & operator+=(
    00639       const PString & str
    00640     );
    00641
    00651     PString & operator+=(
    00652       const char * cstr
    00653     );
    00654
    00664     PString & operator+=(
    00665       char ch
    00666     );
    00667
    00668
    00675     PString operator&(
    00676       const PString & str
    00677     ) const;
    00678
    00695     PString operator&(
    00696       const char * cstr
    00697     ) const;
    00698
    00715     PString operator&(
    00716       char ch
    00717     ) const;
    00718
    00735     friend PString operator&(
    00736       const char * cstr,
    00737       const PString & str
    00738     );
    00739
    00756     friend PString operator&(
    00757       char  ch,
    00758       const PString & str
    00759     );
    00760
    00766     PString & operator&=(
    00767       const PString & str
    00768     );
    00769
    00784     PString & operator&=(
    00785       const char * cstr
    00786     );
    00787
    00788
    00803     PString & operator&=(
    00804       char ch
    00805     );
    00807
    00808
    00816     bool operator*=(
    00817       const PString & str
    00818     ) const;
    00819
    00827     bool operator==(
    00828       const PObject & str
    00829     ) const;
    00830
    00838     bool operator!=(
    00839       const PObject & str
    00840     ) const;
    00841
    00849     bool operator<(
    00850       const PObject & str
    00851     ) const;
    00852
    00860     bool operator>(
    00861       const PObject & str
    00862     ) const;
    00863
    00871     bool operator<=(
    00872       const PObject & str
    00873     ) const;
    00874
    00882     bool operator>=(
    00883       const PObject & str
    00884     ) const;
    00885
    00886
    00897     bool operator*=(
    00898       const char * cstr
    00899     ) const;
    00900
    00911     bool operator==(
    00912       const char * cstr
    00913     ) const;
    00914
    00925     bool operator!=(
    00926       const char * cstr
    00927     ) const;
    00928
    00939     bool operator<(
    00940       const char * cstr
    00941     ) const;
    00942
    00953     bool operator>(
    00954       const char * cstr
    00955     ) const;
    00956
    00967     bool operator<=(
    00968       const char * cstr
    00969     ) const;
    00970
    00981     bool operator>=(
    00982       const char * cstr
    00983     ) const;
    00984
    00996     Comparison NumCompare(
    00997       const PString & str,
    00998       PINDEX count = P_MAX_INDEX,
    00999       PINDEX offset = 0
    01000     ) const;
    01001
    01013     Comparison NumCompare(
    01014       const char * cstr,
    01015       PINDEX count = P_MAX_INDEX,
    01016       PINDEX offset = 0
    01017     ) const;
    01019
    01020
    01024     PINDEX Find(
    01025       char ch,
    01026       PINDEX offset = 0
    01027     ) const;
    01028
    01030     PINDEX Find(
    01031       const PString & str,
    01032       PINDEX offset = 0
    01033     ) const;
    01034
    01035     /* Locate the position within the string of the character or substring. The
    01036        search will begin at the character offset provided.
    01037
    01038        If <code>offset</code> is beyond the length of the string, then the
    01039        function will always return P_MAX_INDEX.
    01040
    01041        The matching will be for identical character or string. If a search
    01042        ignoring case is required then the string should be converted to a
    01043        PCaselessString before the search is made.
    01044
    01045        @return
    01046        position of character or substring in the string, or P_MAX_INDEX if the
    01047        character or substring is not in the string.
    01048      */
    01049     PINDEX Find(
    01050       const char * cstr,
    01051       PINDEX offset = 0
    01052     ) const;
    01053
    01055     PINDEX FindLast(
    01056       char ch,
    01057       PINDEX offset = P_MAX_INDEX
    01058     ) const;
    01059
    01061     PINDEX FindLast(
    01062       const PString & str,
    01063       PINDEX offset = P_MAX_INDEX
    01064     ) const;
    01065
    01083     PINDEX FindLast(
    01084       const char * cstr,
    01085       PINDEX offset = P_MAX_INDEX
    01086     ) const;
    01087
    01089     PINDEX FindOneOf(
    01090       const PString & set,
    01091       PINDEX offset = 0
    01092     ) const;
    01093
    01108     PINDEX FindOneOf(
    01109       const char * cset,
    01110       PINDEX offset = 0
    01111     ) const;
    01112
    01114     PINDEX FindSpan(
    01115       const PString & set,
    01116       PINDEX offset = 0
    01117     ) const;
    01118
    01134     PINDEX FindSpan(
    01135       const char * cset,
    01136       PINDEX offset = 0
    01137     ) const;
    01138
    01149     PINDEX FindRegEx(
    01150       const PRegularExpression & regex,
    01151       PINDEX offset = 0
    01152     ) const;
    01153
    01164     PBoolean FindRegEx(
    01165       const PRegularExpression & regex,
    01166       PINDEX & pos,
    01167       PINDEX & len,
    01168       PINDEX offset = 0,
    01169       PINDEX maxPos = P_MAX_INDEX
    01170     ) const;
    01171
    01172
    01175     PBoolean MatchesRegEx(
    01176       const PRegularExpression & regex
    01177     ) const;
    01178
    01189     void Replace(
    01190       const PString & target,
    01191       const PString & subs,
    01192       PBoolean all = false,
    01193       PINDEX offset = 0
    01194     );
    01195
    01203     void Splice(
    01204       const PString & str,
    01205       PINDEX pos,
    01206       PINDEX len = 0
    01207     );
    01208
    01216     void Splice(
    01217       const char * cstr,
    01218       PINDEX pos,
    01219       PINDEX len = 0
    01220     );
    01221
    01228     void Delete(
    01229       PINDEX start,
    01230       PINDEX len
    01231     );
    01233
    01234
    01254     PString operator()(
    01255       PINDEX start,
    01256       PINDEX end
    01257     ) const;
    01258
    01273     PString Left(
    01274       PINDEX len
    01275     ) const;
    01276
    01291     PString Right(
    01292       PINDEX len
    01293     ) const;
    01294
    01311     PString Mid(
    01312       PINDEX start,
    01313       PINDEX len = P_MAX_INDEX
    01314     ) const;
    01315
    01316
    01324     PString LeftTrim() const;
    01325
    01333     PString RightTrim() const;
    01334
    01343     PString Trim() const;
    01344
    01345
    01354     PString ToLower() const;
    01355
    01364     PString ToUpper() const;
    01365
    01366
    01368     PStringArray Tokenise(
    01369       const PString & separators,
    01371       PBoolean onePerSeparator = true
    01373     ) const;
    01398     PStringArray Tokenise(
    01399       const char * cseparators,
    01401       PBoolean onePerSeparator = true
    01403     ) const;
    01404
    01418     PStringArray Lines() const;
    01420
    01437     PString & sprintf(
    01438       const char * cfmt,
    01439       ...
    01440     );
    01441
    01456     friend PString psprintf(
    01457       const char * cfmt,
    01458       ...
    01459     );
    01460
    01462     PString & vsprintf(
    01463       const PString & fmt,
    01464       va_list args
    01465     );
    01480     PString & vsprintf(
    01481       const char * cfmt,
    01482       va_list args
    01483     );
    01484
    01486     friend PString pvsprintf(
    01487       const char * cfmt,
    01488       va_list args
    01489     );
    01504     friend PString pvsprintf(
    01505       const PString & fmt,
    01506       va_list args
    01507     );
    01508
    01509
    01522     long AsInteger(
    01523       unsigned base = 10
    01524     ) const;
    01537     DWORD AsUnsigned(
    01538       unsigned base = 10
    01539     ) const;
    01553     PInt64 AsInt64(
    01554       unsigned base = 10
    01555     ) const;
    01569     PUInt64 AsUnsigned64(
    01570       unsigned base = 10
    01571     ) const;
    01572
    01583     double AsReal() const;
    01584
    01588     PWCharArray AsUCS2() const;
    01589
    01600     PBYTEArray ToPascal() const;
    01601
    01610     PString ToLiteral() const;
    01611
    01619     operator const unsigned char *() const;
    01620
    01623     operator std::string () const
    01624     { return std::string(theArray); }
    01626
    01627
    01628   protected:
    01629     void InternalFromUCS2(
    01630       const wchar_t * ptr,
    01631       PINDEX len
    01632     );
    01633     virtual Comparison InternalCompare(
    01634       PINDEX offset,      // Offset into string to compare.
    01635       char c              // Character to compare against.
    01636     ) const;
    01637     virtual Comparison InternalCompare(
    01638       PINDEX offset,      // Offset into string to compare.
    01639       PINDEX length,      // Number of characters to compare.
    01640       const char * cstr   // C string to compare against.
    01641     ) const;
    01642
    01643     /* Internal function to compare the current string value against the
    01644        specified C string.
    01645
    01646        @return
    01647        relative rank of the two strings.
    01648      */
    01649     PString(int dummy, const PString * str);
    01650
    01651     PString(PContainerReference & reference) : PCharArray(reference) { }
    01652 };
    01653
    01654
    01655 inline ostream & operator<<(ostream & stream, const PString & string)
    01656 {
    01657   string.PrintOn(stream);
    01658   return stream;
    01659 }
    01660
    01661
    01662 inline wostream & operator<<(wostream & stream, const PString & string)
    01663 {
    01664   return stream << (const char *)string;
    01665 }
    01666
    01667
    01668 #ifdef _WIN32
    01669   class PWideString : public PWCharArray {
    01670     PCLASSINFO(PWideString, PWCharArray);
    01671
    01672     public:
    01673     typedef const wchar_t * Initialiser;
    01674
    01675       PWideString() { }
    01676       PWideString(const PWCharArray & arr) : PWCharArray(arr) { }
    01677       PWideString(const PString     & str) : PWCharArray(str.AsUCS2()) { }
    01678       PWideString(const char        * str) : PWCharArray(PString(str).AsUCS2()) { }
    01679       PWideString & operator=(const PWideString & str) { PWCharArray::operator=(str); return *this; }
    01680       PWideString & operator=(const PString     & str) { PWCharArray::operator=(str.AsUCS2()); return *this; }
    01681       PWideString & operator=(const std::string & str) { PWCharArray::operator=(PString(str.c_str()).AsUCS2()); return *this; }
    01682       PWideString & operator=(const char        * str) { PWCharArray::operator=(PString(str).AsUCS2()); return *this; }
    01683       friend inline ostream & operator<<(ostream & stream, const PWideString & string) { return stream << PString(string); }
    01684
    01685     protected:
    01686       PWideString(PContainerReference & reference) : PWCharArray(reference) { }
    01687   };
    01688
    01689   #ifdef UNICODE
    01690     typedef PWideString PVarString;
    01691   #else
    01692     typedef PString PVarString;
    01693   #endif
    01694 #endif
    01695
    01696
    01698
    01708 class PCaselessString : public PString
    01709 {
    01710   PCLASSINFO(PCaselessString, PString);
    01711
    01712   public:
    01715     PCaselessString();
    01716
    01720     PCaselessString(
    01721       const char * cstr
    01722     );
    01723
    01728     PCaselessString(
    01729       const PString & str
    01730     );
    01731
    01732
    01735     PCaselessString(
    01736       const std::string & str
    01737       ) : PString(str)
    01738     { }
    01739
    01747     PCaselessString & operator=(
    01748       const PString & str
    01749     );
    01750
    01758     PCaselessString & operator=(
    01759       const std::string & str
    01760     ) { return operator=(str.c_str()); }
    01761
    01771     PCaselessString & operator=(
    01772       const char * cstr
    01773     );
    01774
    01783     PCaselessString & operator=(
    01784       char ch
    01785     );
    01786
    01787
    01788   // Overrides from class PObject
    01793     virtual PObject * Clone() const;
    01794
    01795   protected:
    01796   // Overrides from class PString
    01797     virtual Comparison InternalCompare(
    01798       PINDEX offset,      // Offset into string to compare.
    01799       char c              // Character to compare against.
    01800     ) const;
    01801     virtual Comparison InternalCompare(
    01802       PINDEX offset,      // Offset into string to compare.
    01803       PINDEX length,      // Number of characters to compare.
    01804       const char * cstr   // C string to compare against.
    01805     ) const;
    01806     /* Internal function to compare the current string value against the
    01807        specified C string.
    01808
    01809        @return
    01810        relative rank of the two strings or characters.
    01811      */
    01812
    01813     PCaselessString(int dummy, const PCaselessString * str);
    01814     PCaselessString(PContainerReference & reference) : PString(reference) { }
    01815 };
    01816
    01817
    01819
    01833 template <class ParentString>
    01834 class PConstantString : public ParentString
    01835 {
    01836   private:
    01837     PContainerReference m_staticReference;
    01838   public:
    01839     PConstantString(typename ParentString::Initialiser init)
    01840       : ParentString(m_staticReference)
    01841       , m_staticReference((PINDEX)strlen(init)+1, true)
    01842     {
    01843       this->theArray = (char *)init;
    01844     }
    01845     ~PConstantString() { this->Destruct(); }
    01846
    01847     virtual PBoolean SetSize(PINDEX) { return false; }
    01848     virtual void AssignContents(const PContainer &) { PAssertAlways(PInvalidParameter); }
    01849     virtual void DestroyReference() { }
    01850
    01851   private:
    01852     PConstantString(const PConstantString &)
    01853       : ParentString(m_staticReference)
    01854       , m_staticReference(0, true)
    01855       { }
    01856     void operator=(const PConstantString &) { }
    01857 };
    01858
    01859
    01861 typedef PConstantString<PString>         PConstString;
    01862
    01864 typedef PConstantString<PCaselessString> PConstCaselessString;
    01865
    01866
    01867
    01869
    01870 class PStringStream;
    01871
    01878 class PStringStream : public PString, public iostream
    01879 {
    01880   PCLASSINFO(PStringStream, PString);
    01881
    01882   public:
    01888     PStringStream();
    01889
    01894     PStringStream(
    01895       PINDEX fixedBufferSize
    01896     );
    01897
    01904     PStringStream(
    01905       const PString & str
    01906     );
    01907
    01912     PStringStream(
    01913       const char * cstr
    01914     );
    01915
    01918     virtual PString & MakeEmpty();
    01919
    01931     PStringStream & operator=(
    01932       const PStringStream & strm
    01933     );
    01934
    01946     PStringStream & operator=(
    01947       const PString & str
    01948     );
    01949
    01965     PStringStream & operator=(
    01966       const char * cstr
    01967     );
    01968
    01977     PStringStream & operator=(
    01978       char ch
    01979     );
    01980
    01981
    01983     virtual ~PStringStream();
    01984
    01985
    01986   protected:
    01987     virtual void AssignContents(const PContainer & cont);
    01988
    01989   private:
    01990     PStringStream(int, const PStringStream &) : iostream(cout.rdbuf()) { }
    01991
    01992     class Buffer : public streambuf {
    01993       public:
    01994         Buffer(PStringStream & str, PINDEX size);
    01995         Buffer(const Buffer & sbuf);
    01996         Buffer & operator=(const Buffer & sbuf);
    01997         virtual int_type overflow(int_type = EOF);
    01998         virtual int_type underflow();
    01999         virtual int sync();
    02000         virtual pos_type seekoff(off_type, ios_base::seekdir, ios_base::openmode = ios_base::in | ios_base::out);
    02001         virtual pos_type seekpos(pos_type, ios_base::openmode = ios_base::in | ios_base::out);
    02002         PStringStream & string;
    02003         PBoolean            fixedBufferSize;
    02004     };
    02005 };
    02006
    02007
    02008 class PStringList;
    02009 class PSortedStringList;
    02010
    02023 #ifdef DOC_PLUS_PLUS
    02024 class PStringArray : public PArray {
    02025 #endif
    02026   PDECLARE_ARRAY(PStringArray, PString);
    02027   public:
    02034     PStringArray(
    02035       PINDEX count,
    02036       char const * const * strarr,
    02037       PBoolean caseless = false
    02038     );
    02041     PStringArray(
    02042       const PString & str
    02043     );
    02046     PStringArray(
    02047       const PStringList & list
    02048     );
    02051     PStringArray(
    02052       const PSortedStringList & list
    02053     );
    02054
    02058     PStringArray(
    02059       const std::vector<PString> & vec
    02060     )
    02061     {
    02062       for (std::vector<PString>::const_iterator r = vec.begin(); r != vec.end(); ++r)
    02063         AppendString(*r);
    02064     }
    02065
    02069     PStringArray(
    02070       const std::vector<std::string> & vec
    02071     )
    02072     {
    02073       for (std::vector<std::string>::const_iterator r = vec.begin(); r != vec.end(); ++r)
    02074         AppendString(PString(*r));
    02075     }
    02076
    02080     template <typename stlContainer>
    02081     static PStringArray container(
    02082       const stlContainer & vec
    02083     )
    02084     {
    02085       PStringArray list;
    02086       for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
    02087         list.AppendString(PString(*r));
    02088       return list;
    02089     }
    02090
    02092
    02101     virtual void ReadFrom(
    02102       istream &strm   // Stream to read the objects contents from.
    02103     );
    02105
    02114     PINDEX GetStringsIndex(
    02115       const PString & str
    02116     ) const;
    02117
    02118     PString operator[](
    02119       PINDEX index
    02120     ) const;
    02121
    02129     PString & operator[](
    02130       PINDEX index
    02131     );
    02132
    02135     PINDEX AppendString(
    02136       const PString & str
    02137     );
    02138
    02144     PStringArray & operator +=(const PStringArray & array);
    02145     PStringArray & operator +=(const PString & str);
    02146
    02147
    02154     PStringArray operator + (const PStringArray & array);
    02155     PStringArray operator + (const PString & str);
    02156
    02164     char ** ToCharArray(
    02165       PCharArray * storage = NULL
    02166     ) const;
    02168 };
    02169
    02170
    02183 #ifdef DOC_PLUS_PLUS
    02184 class PStringList : public PList {
    02185 #endif
    02186 PDECLARE_LIST(PStringList, PString);
    02187   public:
    02192     PStringList(
    02193       PINDEX count,
    02194       char const * const * strarr,
    02195       PBoolean caseless = false
    02196     );
    02199     PStringList(
    02200       const PString & str
    02201     );
    02204     PStringList(
    02205       const PStringArray & array
    02206     );
    02209     PStringList(
    02210       const PSortedStringList & list
    02211     );
    02213
    02222     virtual void ReadFrom(
    02223       istream &strm   // Stream to read the objects contents from.
    02224     );
    02226
    02231     PINDEX AppendString(
    02232       const PString & str
    02233     );
    02234
    02237     PINDEX InsertString(
    02238       const PString & before,
    02239       const PString & str
    02240     );
    02241
    02245     PINDEX GetStringsIndex(
    02246       const PString & str
    02247     ) const;
    02248
    02254     PStringList & operator +=(const PStringList & list);
    02255     PStringList & operator +=(const PString & str);
    02256
    02257
    02264     PStringList operator + (const PStringList & array);
    02265     PStringList operator + (const PString & str);
    02266
    02270     template <typename stlContainer>
    02271     static PStringList container(
    02272       const stlContainer & vec
    02273     )
    02274     {
    02275       PStringList list;
    02276       for (typename stlContainer::const_iterator r = vec.begin(); r != vec.end(); ++r)
    02277         list.AppendString(PString(*r));
    02278       return list;
    02279     }
    02281 };
    02282
    02283
    02295 #ifdef DOC_PLUS_PLUS
    02296 class PSortedStringList : public PSortedList {
    02297 #endif
    02298 PDECLARE_SORTED_LIST(PSortedStringList, PString);
    02299   public:
    02304     PSortedStringList(
    02305       PINDEX count,
    02306       char const * const * strarr,
    02307       PBoolean caseless = false
    02308     );
    02311     PSortedStringList(
    02312       const PString & str
    02313     );
    02316     PSortedStringList(
    02317       const PStringArray & array
    02318     );
    02321     PSortedStringList(
    02322       const PStringList & list
    02323     );
    02325
    02334     virtual void ReadFrom(
    02335       istream &strm   // Stream to read the objects contents from.
    02336     );
    02338
    02344     PINDEX AppendString(
    02345       const PString & str
    02346     );
    02347
    02351     PINDEX GetStringsIndex(
    02352       const PString & str
    02353     ) const;
    02354
    02359     PINDEX GetNextStringsIndex(
    02360       const PString & str
    02361     ) const;
    02363
    02364   protected:
    02365     PINDEX InternalStringSelect(
    02366       const char * str,
    02367       PINDEX len,
    02368       Element * thisElement,
    02369       Element * & lastElement
    02370     ) const;
    02371 };
    02372
    02373
    02390 #ifdef DOC_PLUS_PLUS
    02391 class PStringSet : public PSet {
    02392 #endif
    02393 PDECLARE_SET(PStringSet, PString, true);
    02394   public:
    02399     PStringSet(
    02400       PINDEX count,
    02401       char const * const * strarr,
    02402       PBoolean caseless = false
    02403     );
    02406     PStringSet(
    02407       const PString & str
    02408     );
    02411     PStringSet(
    02412       const PStringArray & strArray
    02413     );
    02416     PStringSet(
    02417       const PStringList & strList
    02418     );
    02420
    02429     virtual void ReadFrom(
    02430       istream &strm
    02431     );
    02433
    02437     void Include(
    02438       const PString & key
    02439     );
    02441     PStringSet & operator+=(
    02442       const PString & key
    02443     );
    02445     void Exclude(
    02446       const PString & key
    02447     );
    02449     PStringSet & operator-=(
    02450       const PString & key
    02451     );
    02453 };
    02454
    02455
    02463 template <class K> class PStringDictionary : public PAbstractDictionary
    02464 {
    02465   PCLASSINFO(PStringDictionary, PAbstractDictionary);
    02466
    02467   public:
    02476     PStringDictionary()
    02477       : PAbstractDictionary() { }
    02479
    02486     virtual PObject * Clone() const
    02487       { return PNEW PStringDictionary(0, this); }
    02489
    02504     const PString & operator[](const K & key) const
    02505       { return (const PString &)GetRefAt(key); }
    02506
    02520     PString operator()(const K & key, const char * dflt = NULL) const
    02521     {
    02522       PString * str = this->GetAt(key);
    02523       return str != NULL ? *str : PString(dflt);
    02524     }
    02525
    02534     PBoolean Contains(
    02535       const K & key   // Key to look for in the dictionary.
    02536       ) const { return AbstractContains(key); }
    02537
    02549     virtual PString * RemoveAt(
    02550       const K & key   // Key for position in dictionary to get object.
    02551     ) {
    02552         PString * s = GetAt(key); AbstractSetAt(key, NULL);
    02553         return reference->deleteObjects ? (s ? (PString *)-1 : NULL) : s;
    02554       }
    02555
    02562     virtual PString * GetAt(
    02563       const K & key   // Key for position in dictionary to get object.
    02564     ) const { return (PString *)AbstractGetAt(key); }
    02565
    02574     virtual PBoolean SetDataAt(
    02575       PINDEX index,        // Ordinal index in the dictionary.
    02576       const PString & str  // New string value to put into the dictionary.
    02577     ) { return PAbstractDictionary::SetDataAt(index, PNEW PString(str)); }
    02578
    02590     virtual PBoolean SetAt(
    02591       const K & key,       // Key for position in dictionary to add object.
    02592       const PString & str  // New string value to put into the dictionary.
    02593     ) { return AbstractSetAt(key, PNEW PString(str)); }
    02594
    02606     const K & GetKeyAt(PINDEX index) const
    02607       { return (const K &)AbstractGetKeyAt(index); }
    02608
    02620     PString & GetDataAt(PINDEX index) const
    02621       { return (PString &)AbstractGetDataAt(index); }
    02623
    02624   protected:
    02625     PStringDictionary(int dummy, const PStringDictionary * c)
    02626       : PAbstractDictionary(dummy, c) { }
    02627 };
    02628
    02629
    02644 #define PDECLARE_STRING_DICTIONARY(cls, K) \
    02645   PDECLARE_CLASS(cls, PStringDictionary<K>) \
    02646   protected: \
    02647     cls(int dummy, const cls * c) \
    02648       : PStringDictionary<K>(dummy, c) { } \
    02649   public: \
    02650     cls() \
    02651       : PStringDictionary<K>() { } \
    02652     virtual PObject * Clone() const \
    02653       { return PNEW cls(0, this); } \
    02654
    02655
    02668 #define PSTRING_DICTIONARY(cls, K) typedef PStringDictionary<K> cls
    02669
    02670
    02685 #ifdef DOC_PLUS_PLUS
    02686 class POrdinalToString : public PStringDictionary {
    02687 #endif
    02688 PDECLARE_STRING_DICTIONARY(POrdinalToString, POrdinalKey);
    02689   public:
    02692
    02693     struct Initialiser {
    02695       PINDEX key;
    02697       const char * value;
    02698     };
    02701     POrdinalToString(
    02702       PINDEX count,
    02703       const Initialiser * init
    02704     );
    02706
    02715     virtual void ReadFrom(
    02716       istream &strm   // Stream to read the objects contents from.
    02717     );
    02719 };
    02720
    02732 #ifdef DOC_PLUS_PLUS
    02733 class PStringToOrdinal : public POrdinalDictionary {
    02734 #endif
    02735 PDECLARE_ORDINAL_DICTIONARY(PStringToOrdinal, PString);
    02736   public:
    02739
    02740     struct Initialiser {
    02742       const char * key;
    02744       PINDEX value;
    02745     };
    02748     PStringToOrdinal(
    02749       PINDEX count,
    02750       const Initialiser * init,
    02751       PBoolean caseless = false
    02752     );
    02754
    02763     virtual void ReadFrom(
    02764       istream &strm   // Stream to read the objects contents from.
    02765     );
    02767 };
    02768
    02769
    02783 #ifdef DOC_PLUS_PLUS
    02784 class PStringToString : public PStringDictionary {
    02785 #endif
    02786 PDECLARE_STRING_DICTIONARY(PStringToString, PString);
    02787   public:
    02790
    02791     struct Initialiser {
    02793       const char * key;
    02795       const char * value;
    02796     };
    02799     PStringToString(
    02800       PINDEX count,
    02801       const Initialiser * init,
    02802       PBoolean caselessKeys = false,
    02803       PBoolean caselessValues = false
    02804     );
    02806
    02815     virtual void ReadFrom(
    02816       istream &strm   // Stream to read the objects contents from.
    02817     );
    02819
    02832     char ** ToCharArray(
    02833       bool withEqualSign,
    02834       PCharArray * storage = NULL
    02835     ) const;
    02836 };
    02837
    02838
    02845 class PStringOptions : public PStringToString
    02846 {
    02847   public:
    02848     PStringOptions() { }
    02849     PStringOptions(const PStringToString & other) : PStringToString(other) { }
    02850     PStringOptions & operator=(const PStringToString & other) { PStringToString::operator=(other); return *this; }
    02851
    02853     bool Contains(const char *              key   ) const { PConstCaselessString k(key); return PStringToString::Contains(k); }
    02854     bool Contains(const PString         &   key   ) const { return PStringToString::Contains(PCaselessString(key)); }
    02855     bool Contains(const PCaselessString &   key   ) const { return PStringToString::Contains(key); }
    02856     bool Contains(const PCaselessString & (*key)()) const { return PStringToString::Contains(key()); }
    02857
    02858     // Overide default PStringToString::SetAt() to make sure the key is caseless
    02859     PString * GetAt(const char *              key   ) const { PConstCaselessString k(key); return PStringToString::GetAt(k); }
    02860     PString * GetAt(const PString         &   key   ) const { return PStringToString::GetAt(PCaselessString(key)); }
    02861     PString * GetAt(const PCaselessString &   key   ) const { return PStringToString::GetAt(key); }
    02862     PString * GetAt(const PCaselessString & (*key)()) const { return PStringToString::GetAt(key()); }
    02863
    02864     // Overide default PStringToString::SetAt() to make sure the key is caseless
    02865     PBoolean SetAt(const char *              key,    const PString & data) { PConstCaselessString k(key); return SetAt(k, data); }
    02866     PBoolean SetAt(const PString         &   key,    const PString & data) { return SetAt(PCaselessString(key), data); }
    02867     PBoolean SetAt(const PCaselessString &   key,    const PString & data) { MakeUnique(); return PStringToString::SetAt(key, data); }
    02868     PBoolean SetAt(const PCaselessString & (*key)(), const PString & data) { return SetAt(key(), data); }
    02869
    02870     // Overide default PStringToString::RemoveAt() to make sure the key is caseless
    02871     PString * RemoveAt(const char *              key)    { PConstCaselessString k(key); return RemoveAt(k); }
    02872     PString * RemoveAt(const PString         &   key)    { return RemoveAt(PCaselessString(key)); }
    02873     PString * RemoveAt(const PCaselessString &   key)    { MakeUnique(); return PStringToString::RemoveAt(key); }
    02874     PString * RemoveAt(const PCaselessString & (*key)()) { return RemoveAt(key()); }
    02875
    02877     PString GetString(const char *              key,    const char * dflt = NULL) const { PConstCaselessString k(key); return GetString(k, dflt); }
    02878     PString GetString(const PString         &   key,    const char * dflt = NULL) const { return GetString(PCaselessString(key), dflt); }
    02879     PString GetString(const PCaselessString &   key,    const char * dflt = NULL) const;
    02880     PString GetString(const PCaselessString & (*key)(), const char * dflt = NULL) const { return GetString(key(), dflt); }
    02881
    02883     bool SetString(const char *              key,    const PString & value) { return SetAt(key, value); }
    02884     bool SetString(const PString         &   key,    const PString & value) { return SetAt(key, value); }
    02885     bool SetString(const PCaselessString &   key,    const PString & value) { return SetAt(key, value); }
    02886     bool SetString(const PCaselessString & (*key)(), const PString & value) { return SetAt(key, value); }
    02887
    02889     bool GetBoolean(const char *              key,    bool dflt = false) const { PConstCaselessString k(key); return GetBoolean(k, dflt); }
    02890     bool GetBoolean(const PString         &   key,    bool dflt = false) const { return GetBoolean(PCaselessString(key), dflt); }
    02891     bool GetBoolean(const PCaselessString &   key,    bool dflt = false) const;
    02892     bool GetBoolean(const PCaselessString & (*key)(), bool dflt = false) const { return GetBoolean(key(), dflt); }
    02893
    02895     void SetBoolean(const char *              key,    bool value) { PConstCaselessString k(key); SetBoolean(k, value); }
    02896     void SetBoolean(const PString         &   key,    bool value) { SetBoolean(PCaselessString(key), value); }
    02897     void SetBoolean(const PCaselessString &   key,    bool value) { SetAt(key, value ? "true" : "false"); }
    02898     void SetBoolean(const PCaselessString & (*key)(), bool value) { SetBoolean(key(), value); }
    02899
    02901     long GetInteger(const char *              key,    long dflt = 0) const { PConstCaselessString k(key); return GetInteger(k, dflt); }
    02902     long GetInteger(const PString         &   key,    long dflt = 0) const { return GetInteger(PCaselessString(key), dflt); }
    02903     long GetInteger(const PCaselessString &   key,    long dflt = 0) const;
    02904     long GetInteger(const PCaselessString & (*key)(), long dflt = 0) const { return GetInteger(key(), dflt); }
    02905
    02907     void SetInteger(const char *              key,    long value) { PConstCaselessString k(key); SetInteger(k, value); }
    02908     void SetInteger(const PString         &   key,    long value) { SetInteger(PCaselessString(key), value); }
    02909     void SetInteger(const PCaselessString &   key,    long value);
    02910     void SetInteger(const PCaselessString & (*key)(), long value) { SetInteger(key(), value); }
    02911
    02913     double GetReal(const char *              key,    double dflt = 0) const { PConstCaselessString k(key); return GetReal(k, dflt); }
    02914     double GetReal(const PString         &   key,    double dflt = 0) const { return GetReal(PCaselessString(key), dflt); }
    02915     double GetReal(const PCaselessString &   key,    double dflt = 0) const;
    02916     double GetReal(const PCaselessString & (*key)(), double dflt = 0) const { return GetReal(key(), dflt); }
    02917
    02919     void SetReal(const char *              key,    double value, int decimals) { PConstCaselessString k(key); SetReal(k, value, decimals); }
    02920     void SetReal(const PString         &   key,    double value, int decimals) { SetReal(PCaselessString(key), value, decimals); }
    02921     void SetReal(const PCaselessString &   key,    double value, int decimals);
    02922     void SetReal(const PCaselessString & (*key)(), double value, int decimals) { SetReal(key(), value, decimals); }
    02923
    02925     __inline bool Has(const char * key) const                 { return Contains(key); }
    02926     __inline bool Has(const PString & key) const              { return Contains(key); }
    02927     __inline bool Has(const PCaselessString & key) const      { return Contains(key); }
    02928     __inline bool Has(const PCaselessString & (*key)()) const { return Contains(key); }
    02929
    02931     __inline PString Get(const char *              key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    02932     __inline PString Get(const PString         &   key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    02933     __inline PString Get(const PCaselessString &   key,    const char * dflt = NULL) const { return GetString(key, dflt); }
    02934     __inline PString Get(const PCaselessString & (*key)(), const char * dflt = NULL) const { return GetString(key, dflt); }
    02935     __inline PString Get(const char *              key,    const PString & dflt) const { return GetString(key, dflt); }
    02936     __inline PString Get(const PString         &   key,    const PString & dflt) const { return GetString(key, dflt); }
    02937     __inline PString Get(const PCaselessString &   key,    const PString & dflt) const { return GetString(key, dflt); }
    02938     __inline PString Get(const PCaselessString & (*key)(), const PString & dflt) const { return GetString(key, dflt); }
    02939
    02941     __inline bool Set(const char *              key,    const PString & value) { return SetAt(key, value); }
    02942     __inline bool Set(const PString         &   key,    const PString & value) { return SetAt(key, value); }
    02943     __inline bool Set(const PCaselessString &   key,    const PString & value) { return SetAt(key, value); }
    02944     __inline bool Set(const PCaselessString & (*key)(), const PString & value) { return SetAt(key, value); }
    02945
    02947     __inline void Remove(const char *              key)    { RemoveAt(key); }
    02948     __inline void Remove(const PString         &   key)    { RemoveAt(key); }
    02949     __inline void Remove(const PCaselessString &   key)    { RemoveAt(key); }
    02950     __inline void Remove(const PCaselessString & (*key)()) { RemoveAt(key); }
    02951 };
    02952
    02953
    02959 class PRegularExpression : public PObject
    02960 {
    02961   PCLASSINFO(PRegularExpression, PObject);
    02962
    02963   public:
    02966
    02967     enum {
    02969       Extended = 1,
    02971       IgnoreCase = 2,
    02976       AnchorNewLine = 4
    02977     };
    02979     enum {
    02986       NotBeginningOfLine = 1,
    02988       NotEndofLine = 2
    02989     };
    02990
    02992     PRegularExpression();
    02993
    02996     PRegularExpression(
    02997       const PString & pattern,
    02998       int flags = IgnoreCase
    02999     );
    03000
    03003     PRegularExpression(
    03004       const char * cpattern,
    03005       int flags = IgnoreCase
    03006     );
    03007
    03011     PRegularExpression(
    03012       const PRegularExpression &
    03013     );
    03014
    03018     PRegularExpression & operator =(
    03019       const PRegularExpression &
    03020     );
    03021
    03023     ~PRegularExpression();
    03025
    03026
    03031     virtual void PrintOn(
    03032       ostream & strm
    03033     ) const;
    03035
    03038
    03039     enum ErrorCodes {
    03041       NoError = 0,
    03043       NoMatch,
    03044
    03045       // POSIX regcomp return error codes.  (In the order listed in the standard.)
    03047       BadPattern,
    03049       CollateError,
    03051       BadClassType,
    03053       BadEscape,
    03055       BadSubReg,
    03057       UnmatchedBracket,
    03059       UnmatchedParen,
    03061       UnmatchedBrace,
    03063       BadBR,
    03065       RangeError,
    03067       OutOfMemory,
    03069       BadRepitition,
    03070
    03071       /* Error codes we've added.  */
    03073       PrematureEnd,
    03075       TooBig,
    03077       UnmatchedRParen,
    03079       NotCompiled
    03080     };
    03081
    03087     ErrorCodes GetErrorCode() const;
    03088
    03095     PString GetErrorText() const;
    03096
    03098     const PString & GetPattern() const { return patternSaved; }
    03100
    03104     PBoolean Compile(
    03105       const PString & pattern,
    03106       int flags = IgnoreCase
    03107     );
    03115     PBoolean Compile(
    03116       const char * cpattern,
    03117       int flags = IgnoreCase
    03118     );
    03119
    03120
    03122     PBoolean Execute(
    03123       const PString & str,
    03124       PINDEX & start,
    03125       int flags = 0
    03126     ) const;
    03128     PBoolean Execute(
    03129       const PString & str,
    03130       PINDEX & start,
    03131       PINDEX & len,
    03132       int flags = 0
    03133     ) const;
    03135     PBoolean Execute(
    03136       const char * cstr,
    03137       PINDEX & start,
    03138       int flags = 0
    03139     ) const;
    03141     PBoolean Execute(
    03142       const char * cstr,
    03143       PINDEX & start,
    03144       PINDEX & len,
    03145       int flags = 0
    03146     ) const;
    03148     PBoolean Execute(
    03149       const PString & str,
    03150       PIntArray & starts,
    03151       int flags = 0
    03152     ) const;
    03154     PBoolean Execute(
    03155       const PString & str,
    03156       PIntArray & starts,
    03157       PIntArray & ends,
    03158       int flags = 0
    03159     ) const;
    03161     PBoolean Execute(
    03162       const char * cstr,
    03163       PIntArray & starts,
    03164       int flags = 0
    03165     ) const;
    03182     PBoolean Execute(
    03183       const char * cstr,
    03184       PIntArray & starts,
    03185       PIntArray & ends,
    03186       int flags = 0
    03187     ) const;
    03204     PBoolean Execute(
    03205       const char * cstr,
    03206       PStringArray & substring,
    03207       int flags = 0
    03208     ) const;
    03210
    03219     static PString EscapeString(
    03220       const PString & str
    03221     );
    03223
    03224   protected:
    03225     PString patternSaved;
    03226     int flagsSaved;
    03227
    03228     void * expression;
    03229     mutable ErrorCodes lastError;
    03230 };
    03231
    03232
    03233 #endif // PTLIB_STRING_H
    03234
    03235
    03236 // End Of File ///////////////////////////////////////////////////////////////