include/wx/string.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        string.h
   3 // Purpose:     wxString class
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_WXSTRINGH__
  13 #define _WX_WXSTRINGH__
  14
  15 #ifdef __GNUG__
  16 #pragma interface "string.h"
  17 #endif
  18
  19 /* Dependencies (should be included before this header):
  20  *         string.h
  21  *         stdio.h
  22  *         stdarg.h
  23  *         limits.h
  24  */
  25 #include <string.h>
  26 #include <stdio.h>
  27 #include <stdarg.h>
  28 #include <limits.h>
  29 #include <stdlib.h>
  30
  31 #ifndef  WX_PRECOMP
  32   #include "wx/defs.h"     // Robert Roebling
  33   #ifdef    WXSTRING_IS_WXOBJECT
  34     #include "wx/object.h"
  35   #endif
  36 #endif
  37
  38 #include "wx/debug.h"
  39
  40 /** @name wxString library
  41     @memo Efficient wxString class [more or less] compatible with MFC CString,
  42           wxWindows wxString and std::string and some handy functions
  43           missing from string.h.
  44   */
  45 //@{
  46
  47 // ---------------------------------------------------------------------------
  48 // macros
  49 // ---------------------------------------------------------------------------
  50
  51 /** @name Macros
  52     @memo You can switch off wxString/std::string compatibility if desired
  53  */
  54 /// compile the std::string compatibility functions
  55 #define   STD_STRING_COMPATIBILITY
  56
  57 /// define to derive wxString from wxObject
  58 #undef    WXSTRING_IS_WXOBJECT
  59
  60 /// maximum possible length for a string means "take all string" everywhere
  61 //  (as sizeof(StringData) is unknown here we substract 100)
  62 #define   STRING_MAXLEN     (UINT_MAX - 100)
  63
  64 // 'naughty' cast
  65 #define   WXSTRINGCAST (char *)(const char *)
  66
  67 // NB: works only inside wxString class
  68 #define   ASSERT_VALID_INDEX(i) wxASSERT( (unsigned)(i) < Len() )
  69
  70 // ---------------------------------------------------------------------------
  71 /** @name Global functions complementing standard C string library
  72     @memo replacements for strlen() and portable strcasecmp()
  73  */
  74 // ---------------------------------------------------------------------------
  75
  76 WXDLLEXPORT_DATA(extern const char*) wxEmptyString;
  77
  78 /// checks whether the passed in pointer is NULL and if the string is empty
  79 inline bool WXDLLEXPORT IsEmpty(const char *p) { return !p || !*p; }
  80
  81 /// safe version of strlen() (returns 0 if passed NULL pointer)
  82 inline size_t  WXDLLEXPORT Strlen(const char *psz)
  83   { return psz ? strlen(psz) : 0; }
  84
  85 /// portable strcasecmp/_stricmp
  86 inline int WXDLLEXPORT Stricmp(const char *psz1, const char *psz2)
  87 {
  88 #if     defined(_MSC_VER)
  89   return _stricmp(psz1, psz2);
  90 #elif defined(__BORLANDC__)
  91   return stricmp(psz1, psz2);
  92 #elif defined(__WATCOMC__)
  93   return stricmp(psz1, psz2);
  94 #elif   defined(__UNIX__) || defined(__GNUWIN32__)
  95   return strcasecmp(psz1, psz2);
  96 #else
  97   // almost all compilers/libraries provide this function (unfortunately under
  98   // different names), that's why we don't implement our own which will surely
  99   // be more efficient than this code (uncomment to use):
 100   /*
 101     register char c1, c2;
 102     do {
 103       c1 = tolower(*psz1++);
 104       c2 = tolower(*psz2++);
 105     } while ( c1 && (c1 == c2) );
 106
 107     return c1 - c2;
 108   */
 109
 110   #error  "Please define string case-insensitive compare for your OS/compiler"
 111 #endif  // OS/compiler
 112 }
 113
 114 // ----------------------------------------------------------------------------
 115 // global data
 116 // ----------------------------------------------------------------------------
 117
 118 // global pointer to empty string
 119 WXDLLEXPORT_DATA(extern const char*) g_szNul;
 120
 121 // return an empty wxString
 122 class WXDLLEXPORT wxString; // not yet defined
 123 inline const wxString& wxGetEmptyString() { return *(wxString *)&g_szNul; }
 124
 125 // ---------------------------------------------------------------------------
 126 // string data prepended with some housekeeping info (used by wxString class),
 127 // is never used directly (but had to be put here to allow inlining)
 128 // ---------------------------------------------------------------------------
 129 struct WXDLLEXPORT wxStringData
 130 {
 131   int     nRefs;        // reference count
 132   size_t  nDataLength,  // actual string length
 133           nAllocLength; // allocated memory size
 134
 135   // mimics declaration 'char data[nAllocLength]'
 136   char* data() const { return (char*)(this + 1); }
 137
 138   // empty string has a special ref count so it's never deleted
 139   bool  IsEmpty()   const { return nRefs == -1; }
 140   bool  IsShared()  const { return nRefs > 1;   }
 141
 142   // lock/unlock
 143   void  Lock()   { if ( !IsEmpty() ) nRefs++;                    }
 144   void  Unlock() { if ( !IsEmpty() && --nRefs == 0) free(this);  }
 145
 146   // if we had taken control over string memory (GetWriteBuf), it's
 147   // intentionally put in invalid state
 148   void  Validate(bool b)  { nRefs = b ? 1 : 0; }
 149   bool  IsValid() const   { return nRefs != 0; }
 150 };
 151
 152 // ---------------------------------------------------------------------------
 153 /**
 154     This is (yet another one) String class for C++ programmers. It doesn't use
 155     any of "advanced" C++ features (i.e. templates, exceptions, namespaces...)
 156     thus you should be able to compile it with practicaly any C++ compiler.
 157     This class uses copy-on-write technique, i.e. identical strings share the
 158     same memory as long as neither of them is changed.
 159
 160     This class aims to be as compatible as possible with the new standard
 161     std::string class, but adds some additional functions and should be
 162     at least as efficient than the standard implementation.
 163
 164     Performance note: it's more efficient to write functions which take
 165     "const String&" arguments than "const char *" if you assign the argument
 166     to another string.
 167
 168     It was compiled and tested under Win32, Linux (libc 5 & 6), Solaris 5.5.
 169
 170     To do:
 171       - ressource support (string tables in ressources)
 172       - more wide character (UNICODE) support
 173       - regular expressions support
 174
 175 @memo     A non-template portable wxString class implementing copy-on-write.
 176 @author   VZ
 177 @version  1.3
 178 */
 179 // ---------------------------------------------------------------------------
 180 #ifdef  WXSTRING_IS_WXOBJECT
 181   class WXDLLEXPORT wxString : public wxObject
 182   {
 183     DECLARE_DYNAMIC_CLASS(wxString)
 184 #else   //WXSTRING_IS_WXOBJECT
 185   class WXDLLEXPORT wxString
 186   {
 187 #endif  //WXSTRING_IS_WXOBJECT
 188
 189 friend class WXDLLEXPORT wxArrayString;
 190
 191   // NB: special care was taken in arrangin the member functions in such order
 192   //     that all inline functions can be effectively inlined
 193 private:
 194   // points to data preceded by wxStringData structure with ref count info
 195   char *m_pchData;
 196
 197   // accessor to string data
 198   wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
 199
 200   // string (re)initialization functions
 201     // initializes the string to the empty value (must be called only from
 202     // ctors, use Reinit() otherwise)
 203   void Init() { m_pchData = (char *)g_szNul; }
 204     // initializaes the string with (a part of) C-string
 205   void InitWith(const char *psz, size_t nPos = 0, size_t nLen = STRING_MAXLEN);
 206     // as Init, but also frees old data
 207   void Reinit() { GetStringData()->Unlock(); Init(); }
 208
 209   // memory allocation
 210     // allocates memory for string of lenght nLen
 211   void AllocBuffer(size_t nLen);
 212     // copies data to another string
 213   void AllocCopy(wxString&, int, int) const;
 214     // effectively copies data to string
 215   void AssignCopy(size_t, const char *);
 216
 217   // append a (sub)string
 218   void ConcatSelf(int nLen, const char *src);
 219
 220   // functions called before writing to the string: they copy it if there
 221   // are other references to our data (should be the only owner when writing)
 222   void CopyBeforeWrite();
 223   void AllocBeforeWrite(size_t);
 224
 225 public:
 226   /** @name constructors & dtor */
 227   //@{
 228     /// ctor for an empty string
 229   wxString() { Init(); }
 230     /// copy ctor
 231   wxString(const wxString& stringSrc)
 232   {
 233     wxASSERT( stringSrc.GetStringData()->IsValid() );
 234
 235     if ( stringSrc.IsEmpty() ) {
 236       // nothing to do for an empty string
 237       Init();
 238     }
 239     else {
 240       m_pchData = stringSrc.m_pchData;            // share same data
 241       GetStringData()->Lock();                    // => one more copy
 242     }
 243   }
 244     /// string containing nRepeat copies of ch
 245   wxString(char ch, size_t nRepeat = 1);
 246     /// ctor takes first nLength characters from C string
 247     // (default value of STRING_MAXLEN means take all the string)
 248   wxString(const char *psz, size_t nLength = STRING_MAXLEN)
 249     { InitWith(psz, 0, nLength); }
 250     /// from C string (for compilers using unsigned char)
 251   wxString(const unsigned char* psz, size_t nLength = STRING_MAXLEN);
 252     /// from wide (UNICODE) string
 253   wxString(const wchar_t *pwz);
 254     /// dtor is not virtual, this class must not be inherited from!
 255  ~wxString() { GetStringData()->Unlock(); }
 256   //@}
 257
 258   /** @name generic attributes & operations */
 259   //@{
 260     /// as standard strlen()
 261   size_t Len() const { return GetStringData()->nDataLength; }
 262     /// string contains any characters?
 263   bool IsEmpty() const { return Len() == 0; }
 264     /// empty string contents
 265   void Empty()
 266   {
 267     if ( !IsEmpty() )
 268       Reinit();
 269
 270     // should be empty
 271     wxASSERT( GetStringData()->nDataLength == 0 );
 272   }
 273     /// empty the string and free memory
 274   void Clear()
 275   {
 276     if ( !GetStringData()->IsEmpty() )
 277       Reinit();
 278
 279     wxASSERT( GetStringData()->nDataLength == 0 );  // should be empty
 280     wxASSERT( GetStringData()->nAllocLength == 0 ); // and not own any memory
 281   }
 282
 283     /// Is an ascii value
 284   bool IsAscii() const;
 285     /// Is a number
 286   bool IsNumber() const;
 287     /// Is a word
 288   bool IsWord() const;
 289   //@}
 290
 291   /** @name data access (all indexes are 0 based) */
 292   //@{
 293     /// read access
 294     char  GetChar(size_t n) const
 295       { ASSERT_VALID_INDEX( n );  return m_pchData[n]; }
 296     /// read/write access
 297     char& GetWritableChar(size_t n)
 298       { ASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
 299     /// write access
 300     void  SetChar(size_t n, char ch)
 301       { ASSERT_VALID_INDEX( n ); CopyBeforeWrite(); m_pchData[n] = ch; }
 302
 303     /// get last character
 304     char  Last() const
 305       { wxASSERT( !IsEmpty() ); return m_pchData[Len() - 1]; }
 306     /// get writable last character
 307     char& Last()
 308       { wxASSERT( !IsEmpty() ); CopyBeforeWrite(); return m_pchData[Len()-1]; }
 309
 310     // on alpha-linux this gives overload problems:
 311     // Also on Solaris, so removing for now (JACS)
 312 #if ! defined(__ALPHA__)
 313     /// operator version of GetChar
 314     char  operator[](size_t n) const
 315       { ASSERT_VALID_INDEX( n ); return m_pchData[n]; }
 316 #endif
 317
 318     /// operator version of GetChar
 319     char  operator[](int n) const
 320       { ASSERT_VALID_INDEX( n ); return m_pchData[n]; }
 321     /// operator version of GetWritableChar
 322     char& operator[](size_t n)
 323       { ASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
 324
 325     /// implicit conversion to C string
 326     operator const char*() const { return m_pchData; }
 327     /// explicit conversion to C string (use this with printf()!)
 328     const char* c_str()   const { return m_pchData; }
 329     ///
 330     const char* GetData() const { return m_pchData; }
 331   //@}
 332
 333   /** @name overloaded assignment */
 334   //@{
 335     ///
 336   wxString& operator=(const wxString& stringSrc);
 337     ///
 338   wxString& operator=(char ch);
 339     ///
 340   wxString& operator=(const char *psz);
 341     ///
 342   wxString& operator=(const unsigned char* psz);
 343     ///
 344   wxString& operator=(const wchar_t *pwz);
 345   //@}
 346
 347   /** @name string concatenation */
 348   //@{
 349     /** @name in place concatenation */
 350     /** @name concatenate and return the result
 351         left to right associativity of << allows to write
 352         things like "str << str1 << str2 << ..."          */
 353     //@{
 354       /// as +=
 355   wxString& operator<<(const wxString& s)
 356   {
 357     wxASSERT( s.GetStringData()->IsValid() );
 358
 359     ConcatSelf(s.Len(), s);
 360     return *this;
 361   }
 362       /// as +=
 363   wxString& operator<<(const char *psz)
 364     { ConcatSelf(Strlen(psz), psz); return *this; }
 365       /// as +=
 366   wxString& operator<<(char ch) { ConcatSelf(1, &ch); return *this; }
 367     //@}
 368
 369     //@{
 370       /// string += string
 371   void operator+=(const wxString& s) { (void)operator<<(s); }
 372       /// string += C string
 373   void operator+=(const char *psz) { (void)operator<<(psz); }
 374       /// string += char
 375   void operator+=(char ch) { (void)operator<<(ch); }
 376     //@}
 377
 378     /** @name return resulting string */
 379     //@{
 380       ///
 381   friend wxString WXDLLEXPORT operator+(const wxString& string1,  const wxString& string2);
 382       ///
 383   friend wxString WXDLLEXPORT operator+(const wxString& string, char ch);
 384       ///
 385   friend wxString WXDLLEXPORT operator+(char ch, const wxString& string);
 386       ///
 387   friend wxString WXDLLEXPORT operator+(const wxString& string, const char *psz);
 388       ///
 389   friend wxString WXDLLEXPORT operator+(const char *psz, const wxString& string);
 390     //@}
 391   //@}
 392
 393   /** @name stream-like functions */
 394   //@{
 395         /// insert an int into string
 396     wxString& operator<<(int i);
 397         /// insert a float into string
 398     wxString& operator<<(float f);
 399         /// insert a double into string
 400     wxString& operator<<(double d);
 401   //@}
 402
 403   /** @name string comparison */
 404   //@{
 405     /**
 406     case-sensitive comparison
 407     @return 0 if equal, +1 if greater or -1 if less
 408     @see CmpNoCase, IsSameAs
 409     */
 410   int  Cmp(const char *psz) const { return strcmp(c_str(), psz); }
 411     /**
 412     case-insensitive comparison, return code as for wxString::Cmp()
 413     @see: Cmp, IsSameAs
 414     */
 415   int  CmpNoCase(const char *psz) const { return Stricmp(c_str(), psz); }
 416     /**
 417     test for string equality, case-sensitive (default) or not
 418     @param   bCase is TRUE by default (case matters)
 419     @return  TRUE if strings are equal, FALSE otherwise
 420     @see     Cmp, CmpNoCase
 421     */
 422   bool IsSameAs(const char *psz, bool bCase = TRUE) const
 423     { return !(bCase ? Cmp(psz) : CmpNoCase(psz)); }
 424   //@}
 425
 426   /** @name other standard string operations */
 427   //@{
 428     /** @name simple sub-string extraction
 429      */
 430     //@{
 431       /**
 432       return substring starting at nFirst of length
 433       nCount (or till the end if nCount = default value)
 434       */
 435   wxString Mid(size_t nFirst, size_t nCount = STRING_MAXLEN) const;
 436       /// Compatibility with wxWindows 1.xx
 437   wxString SubString(size_t from, size_t to) const
 438   {
 439       return Mid(from, (to - from + 1));
 440   }
 441       /// get first nCount characters
 442   wxString Left(size_t nCount) const;
 443       /// get all characters before the first occurence of ch
 444       /// (returns the whole string if ch not found)
 445   wxString Left(char ch) const;
 446       /// get all characters before the last occurence of ch
 447       /// (returns empty string if ch not found)
 448   wxString Before(char ch) const;
 449       /// get all characters after the first occurence of ch
 450       /// (returns empty string if ch not found)
 451   wxString After(char ch) const;
 452       /// get last nCount characters
 453   wxString Right(size_t nCount) const;
 454       /// get all characters after the last occurence of ch
 455       /// (returns the whole string if ch not found)
 456   wxString Right(char ch) const;
 457     //@}
 458
 459     /** @name case conversion */
 460     //@{
 461       ///
 462   wxString& MakeUpper();
 463       ///
 464   wxString& MakeLower();
 465     //@}
 466
 467     /** @name trimming/padding whitespace (either side) and truncating */
 468     //@{
 469       /// remove spaces from left or from right (default) side
 470   wxString& Trim(bool bFromRight = TRUE);
 471       /// add nCount copies chPad in the beginning or at the end (default)
 472   wxString& Pad(size_t nCount, char chPad = ' ', bool bFromRight = TRUE);
 473       /// truncate string to given length
 474   wxString& Truncate(size_t uiLen);
 475     //@}
 476
 477     /** @name searching and replacing */
 478     //@{
 479       /// searching (return starting index, or -1 if not found)
 480   int Find(char ch, bool bFromEnd = FALSE) const;   // like strchr/strrchr
 481       /// searching (return starting index, or -1 if not found)
 482   int Find(const char *pszSub) const;               // like strstr
 483       /**
 484       replace first (or all) occurences of substring with another one
 485       @param  bReplaceAll: global replace (default) or only the first occurence
 486       @return the number of replacements made
 487       */
 488   size_t Replace(const char *szOld, const char *szNew, bool bReplaceAll = TRUE);
 489     //@}
 490
 491     /// check if the string contents matches a mask containing '*' and '?'
 492   bool Matches(const char *szMask) const;
 493   //@}
 494
 495   /** @name formated input/output */
 496   //@{
 497     /// as sprintf(), returns the number of characters written or < 0 on error
 498   int Printf(const char *pszFormat, ...);
 499     /// as vprintf(), returns the number of characters written or < 0 on error
 500   int PrintfV(const char* pszFormat, va_list argptr);
 501   //@}
 502
 503   /** @name raw access to string memory */
 504   //@{
 505     /// ensure that string has space for at least nLen characters
 506     // only works if the data of this string is not shared
 507   void Alloc(size_t nLen);
 508     /// minimize the string's memory
 509     // only works if the data of this string is not shared
 510   void Shrink();
 511     /**
 512         get writable buffer of at least nLen bytes.
 513         Unget() *must* be called a.s.a.p. to put string back in a reasonable
 514         state!
 515      */
 516   char *GetWriteBuf(size_t nLen);
 517     /// call this immediately after GetWriteBuf() has been used
 518   void UngetWriteBuf();
 519   //@}
 520
 521   /** @name wxWindows compatibility functions */
 522   //@{
 523     /// values for second parameter of CompareTo function
 524   enum caseCompare {exact, ignoreCase};
 525     /// values for first parameter of Strip function
 526   enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
 527     /// same as Printf()
 528   inline int sprintf(const char *pszFormat, ...)
 529   {
 530     va_list argptr;
 531     va_start(argptr, pszFormat);
 532     int iLen = PrintfV(pszFormat, argptr);
 533     va_end(argptr);
 534     return iLen;
 535   }
 536
 537     /// same as Cmp
 538   inline int CompareTo(const char* psz, caseCompare cmp = exact) const
 539     { return cmp == exact ? Cmp(psz) : CmpNoCase(psz); }
 540
 541     /// same as Mid (substring extraction)
 542   inline wxString  operator()(size_t start, size_t len) const
 543     { return Mid(start, len); }
 544
 545     /// same as += or <<
 546   inline wxString& Append(const char* psz) { return *this << psz; }
 547   inline wxString& Append(char ch, int count = 1)
 548     { wxString str(ch, count); (*this) += str; return *this; }
 549
 550     ///
 551   wxString& Prepend(const wxString& str)
 552     { *this = str + *this; return *this; }
 553     /// same as Len
 554   size_t Length() const { return Len(); }
 555     /// Count the number of characters
 556   int Freq(char ch) const;
 557     /// same as MakeLower
 558   void LowerCase() { MakeLower(); }
 559     /// same as MakeUpper
 560   void UpperCase() { MakeUpper(); }
 561     /// same as Trim except that it doesn't change this string
 562   wxString Strip(stripType w = trailing) const;
 563
 564     /// same as Find (more general variants not yet supported)
 565   size_t Index(const char* psz) const { return Find(psz); }
 566   size_t Index(char ch)         const { return Find(ch);  }
 567     /// same as Truncate
 568   wxString& Remove(size_t pos) { return Truncate(pos); }
 569   wxString& RemoveLast() { return Truncate(Len() - 1); }
 570
 571   wxString& Remove(size_t nStart, size_t nLen) { return erase( nStart, nLen ); }
 572
 573   int First( const char ch ) const { return Find(ch); }
 574   int First( const char* psz ) const { return Find(psz); }
 575   int First( const wxString &str ) const { return Find(str); }
 576
 577   int Last( const char ch ) const { return Find(ch, TRUE); }
 578
 579     /// same as IsEmpty
 580   bool IsNull() const { return IsEmpty(); }
 581   //@}
 582
 583 #ifdef  STD_STRING_COMPATIBILITY
 584   /** @name std::string compatibility functions */
 585
 586   /// an 'invalid' value for string index
 587   static const size_t npos;
 588
 589   //@{
 590     /** @name constructors */
 591     //@{
 592       /// take nLen chars starting at nPos
 593       wxString(const wxString& str, size_t nPos, size_t nLen = npos)
 594       {
 595         wxASSERT( str.GetStringData()->IsValid() );
 596         InitWith(str.c_str(), nPos, nLen == npos ? 0 : nLen);
 597       }
 598       /// take all characters from pStart to pEnd
 599       wxString(const void *pStart, const void *pEnd);
 600     //@}
 601     /** @name lib.string.capacity */
 602     //@{
 603       /// return the length of the string
 604       size_t size() const { return Len(); }
 605       /// return the length of the string
 606       size_t length() const { return Len(); }
 607       /// return the maximum size of the string
 608       size_t max_size() const { return STRING_MAXLEN; }
 609       /// resize the string, filling the space with c if c != 0
 610       void resize(size_t nSize, char ch = '\0');
 611       /// delete the contents of the string
 612       void clear() { Empty(); }
 613       /// returns true if the string is empty
 614       bool empty() const { return IsEmpty(); }
 615     //@}
 616     /** @name lib.string.access */
 617     //@{
 618       /// return the character at position n
 619       char at(size_t n) const { return GetChar(n); }
 620       /// returns the writable character at position n
 621       char& at(size_t n) { return GetWritableChar(n); }
 622     //@}
 623     /** @name lib.string.modifiers */
 624     //@{
 625       /** @name append something to the end of this one */
 626       //@{
 627         /// append a string
 628         wxString& append(const wxString& str)
 629           { *this += str; return *this; }
 630         /// append elements str[pos], ..., str[pos+n]
 631         wxString& append(const wxString& str, size_t pos, size_t n)
 632           { ConcatSelf(n, str.c_str() + pos); return *this; }
 633         /// append first n (or all if n == npos) characters of sz
 634         wxString& append(const char *sz, size_t n = npos)
 635           { ConcatSelf(n == npos ? Strlen(sz) : n, sz); return *this; }
 636
 637         /// append n copies of ch
 638         wxString& append(size_t n, char ch) { return Pad(n, ch); }
 639       //@}
 640
 641       /** @name replaces the contents of this string with another one */
 642       //@{
 643         /// same as `this_string = str'
 644         wxString& assign(const wxString& str) { return (*this) = str; }
 645         /// same as ` = str[pos..pos + n]
 646         wxString& assign(const wxString& str, size_t pos, size_t n)
 647           { return *this = wxString((const char *)str + pos, n); }
 648         /// same as `= first n (or all if n == npos) characters of sz'
 649         wxString& assign(const char *sz, size_t n = npos)
 650           { return *this = wxString(sz, n); }
 651         /// same as `= n copies of ch'
 652         wxString& assign(size_t n, char ch)
 653           { return *this = wxString(ch, n); }
 654
 655       //@}
 656
 657       /** @name inserts something at position nPos into this one */
 658       //@{
 659         /// insert another string
 660         wxString& insert(size_t nPos, const wxString& str);
 661         /// insert n chars of str starting at nStart (in str)
 662         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n)
 663           { return insert(nPos, wxString((const char *)str + nStart, n)); }
 664
 665         /// insert first n (or all if n == npos) characters of sz
 666         wxString& insert(size_t nPos, const char *sz, size_t n = npos)
 667           { return insert(nPos, wxString(sz, n)); }
 668         /// insert n copies of ch
 669         wxString& insert(size_t nPos, size_t n, char ch)
 670           { return insert(nPos, wxString(ch, n)); }
 671
 672       //@}
 673
 674       /** @name deletes a part of the string */
 675       //@{
 676         /// delete characters from nStart to nStart + nLen
 677         wxString& erase(size_t nStart = 0, size_t nLen = npos);
 678       //@}
 679
 680       /** @name replaces a substring of this string with another one */
 681       //@{
 682          /// replaces the substring of length nLen starting at nStart
 683          wxString& replace(size_t nStart, size_t nLen, const char* sz);
 684          /// replaces the substring with nCount copies of ch
 685          wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
 686          /// replaces a substring with another substring
 687          wxString& replace(size_t nStart, size_t nLen,
 688                          const wxString& str, size_t nStart2, size_t nLen2);
 689          /// replaces the substring with first nCount chars of sz
 690          wxString& replace(size_t nStart, size_t nLen,
 691                          const char* sz, size_t nCount);
 692       //@}
 693     //@}
 694
 695     /// swap two strings
 696     void swap(wxString& str);
 697
 698     /** @name string operations */
 699     //@{
 700       /** All find() functions take the nStart argument which specifies
 701           the position to start the search on, the default value is 0.
 702
 703           All functions return npos if there were no match.
 704
 705           @name string search
 706       */
 707       //@{
 708         /**
 709             @name find a match for the string/character in this string
 710         */
 711         //@{
 712           /// find a substring
 713           size_t find(const wxString& str, size_t nStart = 0) const;
 714
 715           // VC++ 1.5 can't cope with this syntax.
 716 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 717           /// find first n characters of sz
 718           size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
 719 #endif
 720           // Gives a duplicate symbol (presumably a case-insensitivity problem)
 721 #if !defined(__BORLANDC__)
 722           /// find the first occurence of character ch after nStart
 723           size_t find(char ch, size_t nStart = 0) const;
 724 #endif
 725           // wxWin compatibility
 726           inline bool Contains(const wxString& str) const { return Find(str) != -1; }
 727
 728         //@}
 729
 730         /**
 731           @name rfind() family is exactly like find() but works right to left
 732         */
 733         //@{
 734         /// as find, but from the end
 735         size_t rfind(const wxString& str, size_t nStart = npos) const;
 736         /// as find, but from the end
 737         // VC++ 1.5 can't cope with this syntax.
 738 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 739         size_t rfind(const char* sz, size_t nStart = npos,
 740                      size_t n = npos) const;
 741         /// as find, but from the end
 742         size_t rfind(char ch, size_t nStart = npos) const;
 743 #endif
 744         //@}
 745
 746         /**
 747           @name find first/last occurence of any character in the set
 748         */
 749         //@{
 750           ///
 751           size_t find_first_of(const wxString& str, size_t nStart = 0) const;
 752           ///
 753           size_t find_first_of(const char* sz, size_t nStart = 0) const;
 754           /// same as find(char, size_t)
 755           size_t find_first_of(char c, size_t nStart = 0) const;
 756
 757           ///
 758           size_t find_last_of (const wxString& str, size_t nStart = npos) const;
 759           ///
 760           size_t find_last_of (const char* s, size_t nStart = npos) const;
 761           /// same as rfind(char, size_t)
 762           size_t find_last_of (char c, size_t nStart = npos) const;
 763         //@}
 764
 765         /**
 766           @name find first/last occurence of any character not in the set
 767         */
 768         //@{
 769           ///
 770           size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
 771           ///
 772           size_t find_first_not_of(const char* s, size_t nStart = 0) const;
 773           ///
 774           size_t find_first_not_of(char ch, size_t nStart = 0) const;
 775
 776           ///
 777           size_t find_last_not_of(const wxString& str, size_t nStart=npos) const;
 778           ///
 779           size_t find_last_not_of(const char* s, size_t nStart = npos) const;
 780           ///
 781           size_t find_last_not_of(char ch, size_t nStart = npos) const;
 782         //@}
 783       //@}
 784
 785       /**
 786         All compare functions return -1, 0 or 1 if the [sub]string
 787         is less, equal or greater than the compare() argument.
 788
 789         @name comparison
 790       */
 791       //@{
 792         /// just like strcmp()
 793         int compare(const wxString& str) const { return Cmp(str); }
 794         /// comparison with a substring
 795         int compare(size_t nStart, size_t nLen, const wxString& str) const;
 796         /// comparison of 2 substrings
 797         int compare(size_t nStart, size_t nLen,
 798                     const wxString& str, size_t nStart2, size_t nLen2) const;
 799         /// just like strcmp()
 800         int compare(const char* sz) const { return Cmp(sz); }
 801         /// substring comparison with first nCount characters of sz
 802         int compare(size_t nStart, size_t nLen,
 803                     const char* sz, size_t nCount = npos) const;
 804       //@}
 805     wxString substr(size_t nStart = 0, size_t nLen = npos) const;
 806   //@}
 807 #endif
 808 };
 809
 810 // ----------------------------------------------------------------------------
 811 /** The string array uses it's knowledge of internal structure of the String
 812     class to optimize string storage. Normally, we would store pointers to
 813     string, but as String is, in fact, itself a pointer (sizeof(String) is
 814     sizeof(char *)) we store these pointers instead. The cast to "String *"
 815     is really all we need to turn such pointer into a string!
 816
 817     Of course, it can be called a dirty hack, but we use twice less memory
 818     and this approach is also more speed efficient, so it's probably worth it.
 819
 820     Usage notes: when a string is added/inserted, a new copy of it is created,
 821     so the original string may be safely deleted. When a string is retrieved
 822     from the array (operator[] or Item() method), a reference is returned.
 823
 824     @name wxArrayString
 825     @memo probably the most commonly used array type - array of strings
 826  */
 827 // ----------------------------------------------------------------------------
 828 class WXDLLEXPORT wxArrayString
 829 {
 830 public:
 831   /** @name ctors and dtor */
 832   //@{
 833     /// default ctor
 834   wxArrayString();
 835     /// copy ctor
 836   wxArrayString(const wxArrayString& array);
 837     /// assignment operator
 838   wxArrayString& operator=(const wxArrayString& src);
 839     /// not virtual, this class can't be derived from
 840  ~wxArrayString();
 841   //@}
 842
 843   /** @name memory management */
 844   //@{
 845     /// empties the list, but doesn't release memory
 846   void Empty();
 847     /// empties the list and releases memory
 848   void Clear();
 849     /// preallocates memory for given number of items
 850   void Alloc(size_t nCount);
 851     /// minimzes the memory usage (by freeing all extra memory)
 852   void Shrink();
 853   //@}
 854
 855   /** @name simple accessors */
 856   //@{
 857     /// number of elements in the array
 858   size_t  Count() const   { return m_nCount;      }
 859     /// is it empty?
 860   bool  IsEmpty() const { return m_nCount == 0; }
 861   //@}
 862
 863   /** @name items access (range checking is done in debug version) */
 864   //@{
 865     /// get item at position uiIndex
 866   wxString& Item(size_t nIndex) const
 867     { wxASSERT( nIndex < m_nCount ); return *(wxString *)&(m_pItems[nIndex]); }
 868     /// same as Item()
 869   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 870     /// get last item
 871   wxString& Last() const { wxASSERT( !IsEmpty() ); return Item(Count() - 1); }
 872   //@}
 873
 874   /** @name item management */
 875   //@{
 876     /**
 877       Search the element in the array, starting from the either side
 878       @param if bFromEnd reverse search direction
 879       @param if bCase, comparison is case sensitive (default)
 880       @return index of the first item matched or NOT_FOUND
 881       @see NOT_FOUND
 882      */
 883   int  Index (const char *sz, bool bCase = TRUE, bool bFromEnd = FALSE) const;
 884     /// add new element at the end
 885   void Add   (const wxString& str);
 886     /// add new element at given position
 887   void Insert(const wxString& str, size_t uiIndex);
 888     /// remove first item matching this value
 889   void Remove(const char *sz);
 890     /// remove item by index
 891   void Remove(size_t nIndex);
 892   //@}
 893
 894   /// sort array elements
 895   void Sort(bool bCase = TRUE, bool bReverse = FALSE);
 896
 897 private:
 898   void    Grow();     // makes array bigger if needed
 899   void    Free();     // free the string stored
 900
 901   size_t    m_nSize,    // current size of the array
 902           m_nCount;   // current number of elements
 903
 904   char  **m_pItems;   // pointer to data
 905 };
 906
 907 // ---------------------------------------------------------------------------
 908 /** @name wxString comparison functions
 909     @memo Comparisons are case sensitive
 910  */
 911 // ---------------------------------------------------------------------------
 912 //@{
 913 inline bool operator==(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) == 0; }
 914 ///
 915 inline bool operator==(const wxString& s1, const char  * s2) { return s1.Cmp(s2) == 0; }
 916 ///
 917 inline bool operator==(const char  * s1, const wxString& s2) { return s2.Cmp(s1) == 0; }
 918 ///
 919 inline bool operator!=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) != 0; }
 920 ///
 921 inline bool operator!=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) != 0; }
 922 ///
 923 inline bool operator!=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) != 0; }
 924 ///
 925 inline bool operator< (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <  0; }
 926 ///
 927 inline bool operator< (const wxString& s1, const char  * s2) { return s1.Cmp(s2) <  0; }
 928 ///
 929 inline bool operator< (const char  * s1, const wxString& s2) { return s2.Cmp(s1) >  0; }
 930 ///
 931 inline bool operator> (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >  0; }
 932 ///
 933 inline bool operator> (const wxString& s1, const char  * s2) { return s1.Cmp(s2) >  0; }
 934 ///
 935 inline bool operator> (const char  * s1, const wxString& s2) { return s2.Cmp(s1) <  0; }
 936 ///
 937 inline bool operator<=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <= 0; }
 938 ///
 939 inline bool operator<=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) <= 0; }
 940 ///
 941 inline bool operator<=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) >= 0; }
 942 ///
 943 inline bool operator>=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >= 0; }
 944 ///
 945 inline bool operator>=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) >= 0; }
 946 ///
 947 inline bool operator>=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) <= 0; }
 948 //@}
 949 wxString WXDLLEXPORT operator+(const wxString& string1,  const wxString& string2);
 950 wxString WXDLLEXPORT operator+(const wxString& string, char ch);
 951 wxString WXDLLEXPORT operator+(char ch, const wxString& string);
 952 wxString WXDLLEXPORT operator+(const wxString& string, const char *psz);
 953 wxString WXDLLEXPORT operator+(const char *psz, const wxString& string);
 954
 955 // ---------------------------------------------------------------------------
 956 /** @name Global functions complementing standard C string library
 957     @memo replacements for strlen() and portable strcasecmp()
 958  */
 959 // ---------------------------------------------------------------------------
 960
 961 #ifdef  STD_STRING_COMPATIBILITY
 962
 963 // fwd decl
 964 // Known not to work with wxUSE_IOSTREAMH set to 0, so
 965 // replacing with includes (on advice of ungod@pasdex.com.au)
 966 // class WXDLLEXPORT istream;
 967 #if wxUSE_IOSTREAMH
 968 // N.B. BC++ doesn't have istream.h, ostream.h
 969 #include <iostream.h>
 970 #else
 971 #include <istream>
 972 #  ifdef _MSC_VER
 973       using namespace std;
 974 #  endif
 975 #endif
 976
 977 WXDLLEXPORT istream& operator>>(istream& is, wxString& str);
 978
 979 #endif  //std::string compatibility
 980
 981 #endif  // _WX_WXSTRINGH__
 982
 983 //@}