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       /// get first nCount characters
 437   wxString Left(size_t nCount) const;
 438       /// get all characters before the first occurence of ch
 439       /// (returns the whole string if ch not found)
 440   wxString Left(char ch) const;
 441       /// get all characters before the last occurence of ch
 442       /// (returns empty string if ch not found)
 443   wxString Before(char ch) const;
 444       /// get all characters after the first occurence of ch
 445       /// (returns empty string if ch not found)
 446   wxString After(char ch) const;
 447       /// get last nCount characters
 448   wxString Right(size_t nCount) const;
 449       /// get all characters after the last occurence of ch
 450       /// (returns the whole string if ch not found)
 451   wxString Right(char ch) const;
 452     //@}
 453
 454     /** @name case conversion */
 455     //@{
 456       ///
 457   wxString& MakeUpper();
 458       ///
 459   wxString& MakeLower();
 460     //@}
 461
 462     /** @name trimming/padding whitespace (either side) and truncating */
 463     //@{
 464       /// remove spaces from left or from right (default) side
 465   wxString& Trim(bool bFromRight = TRUE);
 466       /// add nCount copies chPad in the beginning or at the end (default)
 467   wxString& Pad(size_t nCount, char chPad = ' ', bool bFromRight = TRUE);
 468       /// truncate string to given length
 469   wxString& Truncate(size_t uiLen);
 470     //@}
 471
 472     /** @name searching and replacing */
 473     //@{
 474       /// searching (return starting index, or -1 if not found)
 475   int Find(char ch, bool bFromEnd = FALSE) const;   // like strchr/strrchr
 476       /// searching (return starting index, or -1 if not found)
 477   int Find(const char *pszSub) const;               // like strstr
 478       /**
 479       replace first (or all) occurences of substring with another one
 480       @param  bReplaceAll: global replace (default) or only the first occurence
 481       @return the number of replacements made
 482       */
 483   size_t Replace(const char *szOld, const char *szNew, bool bReplaceAll = TRUE);
 484     //@}
 485
 486     /// check if the string contents matches a mask containing '*' and '?'
 487   bool Matches(const char *szMask) const;
 488   //@}
 489
 490   /** @name formated input/output */
 491   //@{
 492     /// as sprintf(), returns the number of characters written or < 0 on error
 493   int Printf(const char *pszFormat, ...);
 494     /// as vprintf(), returns the number of characters written or < 0 on error
 495   int PrintfV(const char* pszFormat, va_list argptr);
 496   //@}
 497
 498   /** @name raw access to string memory */
 499   //@{
 500     /// ensure that string has space for at least nLen characters
 501     // only works if the data of this string is not shared
 502   void Alloc(size_t nLen);
 503     /// minimize the string's memory
 504     // only works if the data of this string is not shared
 505   void Shrink();
 506     /**
 507         get writable buffer of at least nLen bytes.
 508         Unget() *must* be called a.s.a.p. to put string back in a reasonable
 509         state!
 510      */
 511   char *GetWriteBuf(size_t nLen);
 512     /// call this immediately after GetWriteBuf() has been used
 513   void UngetWriteBuf();
 514   //@}
 515
 516   /** @name wxWindows compatibility functions */
 517   //@{
 518     /// values for second parameter of CompareTo function
 519   enum caseCompare {exact, ignoreCase};
 520     /// values for first parameter of Strip function
 521   enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
 522     /// same as Printf()
 523   inline int sprintf(const char *pszFormat, ...)
 524   {
 525     va_list argptr;
 526     va_start(argptr, pszFormat);
 527     int iLen = PrintfV(pszFormat, argptr);
 528     va_end(argptr);
 529     return iLen;
 530   }
 531
 532     /// same as Cmp
 533   inline int CompareTo(const char* psz, caseCompare cmp = exact) const
 534     { return cmp == exact ? Cmp(psz) : CmpNoCase(psz); }
 535
 536     /// same as Mid (substring extraction)
 537   inline wxString  operator()(size_t start, size_t len) const
 538     { return Mid(start, len); }
 539
 540     /// same as += or <<
 541   inline wxString& Append(const char* psz) { return *this << psz; }
 542   inline wxString& Append(char ch, int count = 1)
 543     { wxString str(ch, count); (*this) += str; return *this; }
 544
 545     ///
 546   wxString& Prepend(const wxString& str)
 547     { *this = str + *this; return *this; }
 548     /// same as Len
 549   size_t Length() const { return Len(); }
 550     /// same as MakeLower
 551   void LowerCase() { MakeLower(); }
 552     /// same as MakeUpper
 553   void UpperCase() { MakeUpper(); }
 554     /// same as Trim except that it doesn't change this string
 555   wxString Strip(stripType w = trailing) const;
 556
 557     /// same as Find (more general variants not yet supported)
 558   size_t Index(const char* psz) const { return Find(psz); }
 559   size_t Index(char ch)         const { return Find(ch);  }
 560     /// same as Truncate
 561   wxString& Remove(size_t pos) { return Truncate(pos); }
 562   wxString& RemoveLast() { return Truncate(Len() - 1); }
 563
 564   wxString& Remove(size_t nStart, size_t nLen) { return erase( nStart, nLen ); }
 565
 566   int First( const char ch ) const { return Find(ch); }
 567   int First( const char* psz ) const { return Find(psz); }
 568   int First( const wxString &str ) const { return Find(str); }
 569
 570   int Last( const char ch ) const { return Find(ch, TRUE); }
 571
 572     /// same as IsEmpty
 573   bool IsNull() const { return IsEmpty(); }
 574   //@}
 575
 576 #ifdef  STD_STRING_COMPATIBILITY
 577   /** @name std::string compatibility functions */
 578
 579   /// an 'invalid' value for string index
 580   static const size_t npos;
 581
 582   //@{
 583     /** @name constructors */
 584     //@{
 585       /// take nLen chars starting at nPos
 586       wxString(const wxString& str, size_t nPos, size_t nLen = npos)
 587       {
 588         wxASSERT( str.GetStringData()->IsValid() );
 589         InitWith(str.c_str(), nPos, nLen == npos ? 0 : nLen);
 590       }
 591       /// take all characters from pStart to pEnd
 592       wxString(const void *pStart, const void *pEnd);
 593     //@}
 594     /** @name lib.string.capacity */
 595     //@{
 596       /// return the length of the string
 597       size_t size() const { return Len(); }
 598       /// return the length of the string
 599       size_t length() const { return Len(); }
 600       /// return the maximum size of the string
 601       size_t max_size() const { return STRING_MAXLEN; }
 602       /// resize the string, filling the space with c if c != 0
 603       void resize(size_t nSize, char ch = '\0');
 604       /// delete the contents of the string
 605       void clear() { Empty(); }
 606       /// returns true if the string is empty
 607       bool empty() const { return IsEmpty(); }
 608     //@}
 609     /** @name lib.string.access */
 610     //@{
 611       /// return the character at position n
 612       char at(size_t n) const { return GetChar(n); }
 613       /// returns the writable character at position n
 614       char& at(size_t n) { return GetWritableChar(n); }
 615     //@}
 616     /** @name lib.string.modifiers */
 617     //@{
 618       /** @name append something to the end of this one */
 619       //@{
 620         /// append a string
 621         wxString& append(const wxString& str)
 622           { *this += str; return *this; }
 623         /// append elements str[pos], ..., str[pos+n]
 624         wxString& append(const wxString& str, size_t pos, size_t n)
 625           { ConcatSelf(n, str.c_str() + pos); return *this; }
 626         /// append first n (or all if n == npos) characters of sz
 627         wxString& append(const char *sz, size_t n = npos)
 628           { ConcatSelf(n == npos ? Strlen(sz) : n, sz); return *this; }
 629
 630         /// append n copies of ch
 631         wxString& append(size_t n, char ch) { return Pad(n, ch); }
 632       //@}
 633
 634       /** @name replaces the contents of this string with another one */
 635       //@{
 636         /// same as `this_string = str'
 637         wxString& assign(const wxString& str) { return (*this) = str; }
 638         /// same as ` = str[pos..pos + n]
 639         wxString& assign(const wxString& str, size_t pos, size_t n)
 640           { return *this = wxString((const char *)str + pos, n); }
 641         /// same as `= first n (or all if n == npos) characters of sz'
 642         wxString& assign(const char *sz, size_t n = npos)
 643           { return *this = wxString(sz, n); }
 644         /// same as `= n copies of ch'
 645         wxString& assign(size_t n, char ch)
 646           { return *this = wxString(ch, n); }
 647
 648       //@}
 649
 650       /** @name inserts something at position nPos into this one */
 651       //@{
 652         /// insert another string
 653         wxString& insert(size_t nPos, const wxString& str);
 654         /// insert n chars of str starting at nStart (in str)
 655         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n)
 656           { return insert(nPos, wxString((const char *)str + nStart, n)); }
 657
 658         /// insert first n (or all if n == npos) characters of sz
 659         wxString& insert(size_t nPos, const char *sz, size_t n = npos)
 660           { return insert(nPos, wxString(sz, n)); }
 661         /// insert n copies of ch
 662         wxString& insert(size_t nPos, size_t n, char ch)
 663           { return insert(nPos, wxString(ch, n)); }
 664
 665       //@}
 666
 667       /** @name deletes a part of the string */
 668       //@{
 669         /// delete characters from nStart to nStart + nLen
 670         wxString& erase(size_t nStart = 0, size_t nLen = npos);
 671       //@}
 672
 673       /** @name replaces a substring of this string with another one */
 674       //@{
 675          /// replaces the substring of length nLen starting at nStart
 676          wxString& replace(size_t nStart, size_t nLen, const char* sz);
 677          /// replaces the substring with nCount copies of ch
 678          wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
 679          /// replaces a substring with another substring
 680          wxString& replace(size_t nStart, size_t nLen,
 681                          const wxString& str, size_t nStart2, size_t nLen2);
 682          /// replaces the substring with first nCount chars of sz
 683          wxString& replace(size_t nStart, size_t nLen,
 684                          const char* sz, size_t nCount);
 685       //@}
 686     //@}
 687
 688     /// swap two strings
 689     void swap(wxString& str);
 690
 691     /** @name string operations */
 692     //@{
 693       /** All find() functions take the nStart argument which specifies
 694           the position to start the search on, the default value is 0.
 695
 696           All functions return npos if there were no match.
 697
 698           @name string search
 699       */
 700       //@{
 701         /**
 702             @name find a match for the string/character in this string
 703         */
 704         //@{
 705           /// find a substring
 706           size_t find(const wxString& str, size_t nStart = 0) const;
 707
 708           // VC++ 1.5 can't cope with this syntax.
 709 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 710           /// find first n characters of sz
 711           size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
 712 #endif
 713           // Gives a duplicate symbol (presumably a case-insensitivity problem)
 714 #if !defined(__BORLANDC__)
 715           /// find the first occurence of character ch after nStart
 716           size_t find(char ch, size_t nStart = 0) const;
 717 #endif
 718           // wxWin compatibility
 719           inline bool Contains(const wxString& str) const { return Find(str) != -1; }
 720
 721         //@}
 722
 723         /**
 724           @name rfind() family is exactly like find() but works right to left
 725         */
 726         //@{
 727         /// as find, but from the end
 728         size_t rfind(const wxString& str, size_t nStart = npos) const;
 729         /// as find, but from the end
 730         // VC++ 1.5 can't cope with this syntax.
 731 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 732         size_t rfind(const char* sz, size_t nStart = npos,
 733                      size_t n = npos) const;
 734         /// as find, but from the end
 735         size_t rfind(char ch, size_t nStart = npos) const;
 736 #endif
 737         //@}
 738
 739         /**
 740           @name find first/last occurence of any character in the set
 741         */
 742         //@{
 743           ///
 744           size_t find_first_of(const wxString& str, size_t nStart = 0) const;
 745           ///
 746           size_t find_first_of(const char* sz, size_t nStart = 0) const;
 747           /// same as find(char, size_t)
 748           size_t find_first_of(char c, size_t nStart = 0) const;
 749
 750           ///
 751           size_t find_last_of (const wxString& str, size_t nStart = npos) const;
 752           ///
 753           size_t find_last_of (const char* s, size_t nStart = npos) const;
 754           /// same as rfind(char, size_t)
 755           size_t find_last_of (char c, size_t nStart = npos) const;
 756         //@}
 757
 758         /**
 759           @name find first/last occurence of any character not in the set
 760         */
 761         //@{
 762           ///
 763           size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
 764           ///
 765           size_t find_first_not_of(const char* s, size_t nStart = 0) const;
 766           ///
 767           size_t find_first_not_of(char ch, size_t nStart = 0) const;
 768
 769           ///
 770           size_t find_last_not_of(const wxString& str, size_t nStart=npos) const;
 771           ///
 772           size_t find_last_not_of(const char* s, size_t nStart = npos) const;
 773           ///
 774           size_t find_last_not_of(char ch, size_t nStart = npos) const;
 775         //@}
 776       //@}
 777
 778       /**
 779         All compare functions return -1, 0 or 1 if the [sub]string
 780         is less, equal or greater than the compare() argument.
 781
 782         @name comparison
 783       */
 784       //@{
 785         /// just like strcmp()
 786         int compare(const wxString& str) const { return Cmp(str); }
 787         /// comparison with a substring
 788         int compare(size_t nStart, size_t nLen, const wxString& str) const;
 789         /// comparison of 2 substrings
 790         int compare(size_t nStart, size_t nLen,
 791                     const wxString& str, size_t nStart2, size_t nLen2) const;
 792         /// just like strcmp()
 793         int compare(const char* sz) const { return Cmp(sz); }
 794         /// substring comparison with first nCount characters of sz
 795         int compare(size_t nStart, size_t nLen,
 796                     const char* sz, size_t nCount = npos) const;
 797       //@}
 798     wxString substr(size_t nStart = 0, size_t nLen = npos) const;
 799   //@}
 800 #endif
 801 };
 802
 803 // ----------------------------------------------------------------------------
 804 /** The string array uses it's knowledge of internal structure of the String
 805     class to optimize string storage. Normally, we would store pointers to
 806     string, but as String is, in fact, itself a pointer (sizeof(String) is
 807     sizeof(char *)) we store these pointers instead. The cast to "String *"
 808     is really all we need to turn such pointer into a string!
 809
 810     Of course, it can be called a dirty hack, but we use twice less memory
 811     and this approach is also more speed efficient, so it's probably worth it.
 812
 813     Usage notes: when a string is added/inserted, a new copy of it is created,
 814     so the original string may be safely deleted. When a string is retrieved
 815     from the array (operator[] or Item() method), a reference is returned.
 816
 817     @name wxArrayString
 818     @memo probably the most commonly used array type - array of strings
 819  */
 820 // ----------------------------------------------------------------------------
 821 class WXDLLEXPORT wxArrayString
 822 {
 823 public:
 824   /** @name ctors and dtor */
 825   //@{
 826     /// default ctor
 827   wxArrayString();
 828     /// copy ctor
 829   wxArrayString(const wxArrayString& array);
 830     /// assignment operator
 831   wxArrayString& operator=(const wxArrayString& src);
 832     /// not virtual, this class can't be derived from
 833  ~wxArrayString();
 834   //@}
 835
 836   /** @name memory management */
 837   //@{
 838     /// empties the list, but doesn't release memory
 839   void Empty();
 840     /// empties the list and releases memory
 841   void Clear();
 842     /// preallocates memory for given number of items
 843   void Alloc(size_t nCount);
 844     /// minimzes the memory usage (by freeing all extra memory)
 845   void Shrink();
 846   //@}
 847
 848   /** @name simple accessors */
 849   //@{
 850     /// number of elements in the array
 851   size_t  Count() const   { return m_nCount;      }
 852     /// is it empty?
 853   bool  IsEmpty() const { return m_nCount == 0; }
 854   //@}
 855
 856   /** @name items access (range checking is done in debug version) */
 857   //@{
 858     /// get item at position uiIndex
 859   wxString& Item(size_t nIndex) const
 860     { wxASSERT( nIndex < m_nCount ); return *(wxString *)&(m_pItems[nIndex]); }
 861     /// same as Item()
 862   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 863     /// get last item
 864   wxString& Last() const { wxASSERT( !IsEmpty() ); return Item(Count() - 1); }
 865   //@}
 866
 867   /** @name item management */
 868   //@{
 869     /**
 870       Search the element in the array, starting from the either side
 871       @param if bFromEnd reverse search direction
 872       @param if bCase, comparison is case sensitive (default)
 873       @return index of the first item matched or NOT_FOUND
 874       @see NOT_FOUND
 875      */
 876   int  Index (const char *sz, bool bCase = TRUE, bool bFromEnd = FALSE) const;
 877     /// add new element at the end
 878   void Add   (const wxString& str);
 879     /// add new element at given position
 880   void Insert(const wxString& str, size_t uiIndex);
 881     /// remove first item matching this value
 882   void Remove(const char *sz);
 883     /// remove item by index
 884   void Remove(size_t nIndex);
 885   //@}
 886
 887   /// sort array elements
 888   void Sort(bool bCase = TRUE, bool bReverse = FALSE);
 889
 890 private:
 891   void    Grow();     // makes array bigger if needed
 892   void    Free();     // free the string stored
 893
 894   size_t    m_nSize,    // current size of the array
 895           m_nCount;   // current number of elements
 896
 897   char  **m_pItems;   // pointer to data
 898 };
 899
 900 // ---------------------------------------------------------------------------
 901 /** @name wxString comparison functions
 902     @memo Comparisons are case sensitive
 903  */
 904 // ---------------------------------------------------------------------------
 905 //@{
 906 inline bool operator==(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) == 0; }
 907 ///
 908 inline bool operator==(const wxString& s1, const char  * s2) { return s1.Cmp(s2) == 0; }
 909 ///
 910 inline bool operator==(const char  * s1, const wxString& s2) { return s2.Cmp(s1) == 0; }
 911 ///
 912 inline bool operator!=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) != 0; }
 913 ///
 914 inline bool operator!=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) != 0; }
 915 ///
 916 inline bool operator!=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) != 0; }
 917 ///
 918 inline bool operator< (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <  0; }
 919 ///
 920 inline bool operator< (const wxString& s1, const char  * s2) { return s1.Cmp(s2) <  0; }
 921 ///
 922 inline bool operator< (const char  * s1, const wxString& s2) { return s2.Cmp(s1) >  0; }
 923 ///
 924 inline bool operator> (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >  0; }
 925 ///
 926 inline bool operator> (const wxString& s1, const char  * s2) { return s1.Cmp(s2) >  0; }
 927 ///
 928 inline bool operator> (const char  * s1, const wxString& s2) { return s2.Cmp(s1) <  0; }
 929 ///
 930 inline bool operator<=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <= 0; }
 931 ///
 932 inline bool operator<=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) <= 0; }
 933 ///
 934 inline bool operator<=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) >= 0; }
 935 ///
 936 inline bool operator>=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >= 0; }
 937 ///
 938 inline bool operator>=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) >= 0; }
 939 ///
 940 inline bool operator>=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) <= 0; }
 941 //@}
 942 wxString WXDLLEXPORT operator+(const wxString& string1,  const wxString& string2);
 943 wxString WXDLLEXPORT operator+(const wxString& string, char ch);
 944 wxString WXDLLEXPORT operator+(char ch, const wxString& string);
 945 wxString WXDLLEXPORT operator+(const wxString& string, const char *psz);
 946 wxString WXDLLEXPORT operator+(const char *psz, const wxString& string);
 947
 948 // ---------------------------------------------------------------------------
 949 /** @name Global functions complementing standard C string library
 950     @memo replacements for strlen() and portable strcasecmp()
 951  */
 952 // ---------------------------------------------------------------------------
 953
 954 #ifdef  STD_STRING_COMPATIBILITY
 955
 956 // fwd decl
 957 // Known not to work with wxUSE_IOSTREAMH set to 0, so
 958 // replacing with includes (on advice of ungod@pasdex.com.au)
 959 // class WXDLLEXPORT istream;
 960 #if wxUSE_IOSTREAMH
 961 // N.B. BC++ doesn't have istream.h, ostream.h
 962 #include <iostream.h>
 963 #else
 964 #include <istream>
 965 #  ifdef _MSC_VER
 966       using namespace std;
 967 #  endif
 968 #endif
 969
 970 WXDLLEXPORT istream& operator>>(istream& is, wxString& str);
 971
 972 #endif  //std::string compatibility
 973
 974 #endif  // _WX_WXSTRINGH__
 975
 976 //@}