include/wx/string.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/string.h
   3 // Purpose:     wxString and wxArrayString classes
   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 licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13     Efficient string class [more or less] compatible with MFC CString,
  14     wxWidgets version 1 wxString and std::string and some handy functions
  15     missing from string.h.
  16 */
  17
  18 #ifndef _WX_WXSTRINGH__
  19 #define _WX_WXSTRINGH__
  20
  21 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
  22     #pragma interface "string.h"
  23 #endif
  24
  25 // ----------------------------------------------------------------------------
  26 // headers
  27 // ----------------------------------------------------------------------------
  28
  29 #include "wx/defs.h"        // everybody should include this
  30
  31 #if defined(__WXMAC__) || defined(__VISAGECPP__)
  32     #include <ctype.h>
  33 #endif
  34
  35 #if defined(__VISAGECPP__) && __IBMCPP__ >= 400
  36    // problem in VACPP V4 with including stdlib.h multiple times
  37    // strconv includes it anyway
  38 #  include <stdio.h>
  39 #  include <string.h>
  40 #  include <stdarg.h>
  41 #  include <limits.h>
  42 #else
  43 #  include <string.h>
  44 #  include <stdio.h>
  45 #  include <stdarg.h>
  46 #  include <limits.h>
  47 #  include <stdlib.h>
  48 #endif
  49
  50 #ifdef HAVE_STRCASECMP_IN_STRINGS_H
  51     #include <strings.h>    // for strcasecmp()
  52 #endif // HAVE_STRCASECMP_IN_STRINGS_H
  53
  54 #include "wx/wxchar.h"      // for wxChar
  55 #include "wx/buffer.h"      // for wxCharBuffer
  56 #include "wx/strconv.h"     // for wxConvertXXX() macros and wxMBConv classes
  57
  58 class WXDLLIMPEXP_BASE wxString;
  59
  60 // ---------------------------------------------------------------------------
  61 // macros
  62 // ---------------------------------------------------------------------------
  63
  64 // casts [unfortunately!] needed to call some broken functions which require
  65 // "char *" instead of "const char *"
  66 #define   WXSTRINGCAST (wxChar *)(const wxChar *)
  67 #define   wxCSTRINGCAST (wxChar *)(const wxChar *)
  68 #define   wxMBSTRINGCAST (char *)(const char *)
  69 #define   wxWCSTRINGCAST (wchar_t *)(const wchar_t *)
  70
  71 // implementation only
  72 #define   wxASSERT_VALID_INDEX(i) \
  73     wxASSERT_MSG( (size_t)(i) <= length(), _T("invalid index in wxString") )
  74
  75 // ----------------------------------------------------------------------------
  76 // constants
  77 // ----------------------------------------------------------------------------
  78
  79 #if defined(__VISAGECPP__) && __IBMCPP__ >= 400
  80 // must define this static for VA or else you get multiply defined symbols everywhere
  81 extern const unsigned int wxSTRING_MAXLEN;
  82
  83 #else
  84 // maximum possible length for a string means "take all string" everywhere
  85 //  (as sizeof(StringData) is unknown here, we substract 100)
  86 const unsigned int wxSTRING_MAXLEN = UINT_MAX - 100;
  87
  88 #endif
  89
  90 // ----------------------------------------------------------------------------
  91 // global data
  92 // ----------------------------------------------------------------------------
  93
  94 // global pointer to empty string
  95 extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxEmptyString;
  96
  97 // ---------------------------------------------------------------------------
  98 // global functions complementing standard C string library replacements for
  99 // strlen() and portable strcasecmp()
 100 //---------------------------------------------------------------------------
 101
 102 // Use wxXXX() functions from wxchar.h instead! These functions are for
 103 // backwards compatibility only.
 104
 105 // checks whether the passed in pointer is NULL and if the string is empty
 106 inline bool IsEmpty(const char *p) { return (!p || !*p); }
 107
 108 // safe version of strlen() (returns 0 if passed NULL pointer)
 109 inline size_t Strlen(const char *psz)
 110   { return psz ? strlen(psz) : 0; }
 111
 112 // portable strcasecmp/_stricmp
 113 inline int Stricmp(const char *psz1, const char *psz2)
 114 {
 115 #if defined(__VISUALC__) && defined(__WXWINCE__)
 116   register char c1, c2;
 117   do {
 118     c1 = tolower(*psz1++);
 119     c2 = tolower(*psz2++);
 120   } while ( c1 && (c1 == c2) );
 121
 122   return c1 - c2;
 123 #elif defined(__VISUALC__) || ( defined(__MWERKS__) && defined(__INTEL__) )
 124   return _stricmp(psz1, psz2);
 125 #elif defined(__SC__)
 126   return _stricmp(psz1, psz2);
 127 #elif defined(__SALFORDC__)
 128   return stricmp(psz1, psz2);
 129 #elif defined(__BORLANDC__)
 130   return stricmp(psz1, psz2);
 131 #elif defined(__WATCOMC__)
 132   return stricmp(psz1, psz2);
 133 #elif defined(__DJGPP__)
 134   return stricmp(psz1, psz2);
 135 #elif defined(__EMX__)
 136   return stricmp(psz1, psz2);
 137 #elif defined(__WXPM__)
 138   return stricmp(psz1, psz2);
 139 #elif defined(HAVE_STRCASECMP_IN_STRING_H) || \
 140       defined(HAVE_STRCASECMP_IN_STRINGS_H) || \
 141       defined(__GNUWIN32__)
 142   return strcasecmp(psz1, psz2);
 143 #elif defined(__MWERKS__) && !defined(__INTEL__)
 144   register char c1, c2;
 145   do {
 146     c1 = tolower(*psz1++);
 147     c2 = tolower(*psz2++);
 148   } while ( c1 && (c1 == c2) );
 149
 150   return c1 - c2;
 151 #else
 152   // almost all compilers/libraries provide this function (unfortunately under
 153   // different names), that's why we don't implement our own which will surely
 154   // be more efficient than this code (uncomment to use):
 155   /*
 156     register char c1, c2;
 157     do {
 158       c1 = tolower(*psz1++);
 159       c2 = tolower(*psz2++);
 160     } while ( c1 && (c1 == c2) );
 161
 162     return c1 - c2;
 163   */
 164
 165   #error  "Please define string case-insensitive compare for your OS/compiler"
 166 #endif  // OS/compiler
 167 }
 168
 169 #if wxUSE_STL
 170
 171 #include "wx/beforestd.h"
 172 #include <string>
 173 #include "wx/afterstd.h"
 174
 175 #if wxUSE_UNICODE
 176     #ifdef HAVE_STD_WSTRING
 177         typedef std::wstring wxStringBase;
 178     #else
 179         typedef std::basic_string<wxChar> wxStringBase;
 180     #endif
 181 #else
 182     typedef std::string wxStringBase;
 183 #endif
 184
 185 #if (defined(__GNUG__) && (__GNUG__ < 3)) || \
 186     (defined(_MSC_VER) && (_MSC_VER <= 1200))
 187     #define wxSTRING_BASE_HASNT_CLEAR
 188 #endif
 189
 190 #else // if !wxUSE_STL
 191
 192 #ifndef HAVE_STD_STRING_COMPARE
 193     #define HAVE_STD_STRING_COMPARE
 194 #endif
 195
 196 // ---------------------------------------------------------------------------
 197 // string data prepended with some housekeeping info (used by wxString class),
 198 // is never used directly (but had to be put here to allow inlining)
 199 // ---------------------------------------------------------------------------
 200
 201 struct WXDLLIMPEXP_BASE wxStringData
 202 {
 203   int     nRefs;        // reference count
 204   size_t  nDataLength,  // actual string length
 205           nAllocLength; // allocated memory size
 206
 207   // mimics declaration 'wxChar data[nAllocLength]'
 208   wxChar* data() const { return (wxChar*)(this + 1); }
 209
 210   // empty string has a special ref count so it's never deleted
 211   bool  IsEmpty()   const { return (nRefs == -1); }
 212   bool  IsShared()  const { return (nRefs > 1);   }
 213
 214   // lock/unlock
 215   void  Lock()   { if ( !IsEmpty() ) nRefs++;                    }
 216
 217   // VC++ will refuse to inline Unlock but profiling shows that it is wrong
 218 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 219   __forceinline
 220 #endif
 221   // VC++ free must take place in same DLL as allocation when using non dll
 222   // run-time library (e.g. Multithreaded instead of Multithreaded DLL)
 223 #if defined(__VISUALC__) && defined(_MT) && !defined(_DLL)
 224   void  Unlock() { if ( !IsEmpty() && --nRefs == 0) Free();  }
 225   // we must not inline deallocation since allocation is not inlined
 226   void  Free();
 227 #else
 228   void  Unlock() { if ( !IsEmpty() && --nRefs == 0) free(this);  }
 229 #endif
 230
 231   // if we had taken control over string memory (GetWriteBuf), it's
 232   // intentionally put in invalid state
 233   void  Validate(bool b)  { nRefs = (b ? 1 : 0); }
 234   bool  IsValid() const   { return (nRefs != 0); }
 235 };
 236
 237 class WXDLLIMPEXP_BASE wxStringBase
 238 {
 239 #if !wxUSE_STL
 240 friend class WXDLLIMPEXP_BASE wxArrayString;
 241 #endif
 242 public :
 243   // an 'invalid' value for string index, moved to this place due to a CW bug
 244   static const size_t npos;
 245 protected:
 246   // points to data preceded by wxStringData structure with ref count info
 247   wxChar *m_pchData;
 248
 249   // accessor to string data
 250   wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
 251
 252   // string (re)initialization functions
 253     // initializes the string to the empty value (must be called only from
 254     // ctors, use Reinit() otherwise)
 255   void Init() { m_pchData = (wxChar *)wxEmptyString; }
 256     // initializaes the string with (a part of) C-string
 257   void InitWith(const wxChar *psz, size_t nPos = 0, size_t nLen = npos);
 258     // as Init, but also frees old data
 259   void Reinit() { GetStringData()->Unlock(); Init(); }
 260
 261   // memory allocation
 262     // allocates memory for string of length nLen
 263   bool AllocBuffer(size_t nLen);
 264     // copies data to another string
 265   bool AllocCopy(wxString&, int, int) const;
 266     // effectively copies data to string
 267   bool AssignCopy(size_t, const wxChar *);
 268
 269   // append a (sub)string
 270   bool ConcatSelf(size_t nLen, const wxChar *src, size_t nMaxLen);
 271   bool ConcatSelf(size_t nLen, const wxChar *src)
 272     { return ConcatSelf(nLen, src, nLen); }
 273
 274   // functions called before writing to the string: they copy it if there
 275   // are other references to our data (should be the only owner when writing)
 276   bool CopyBeforeWrite();
 277   bool AllocBeforeWrite(size_t);
 278
 279     // compatibility with wxString
 280   bool Alloc(size_t nLen);
 281 public:
 282   // standard types
 283   typedef wxChar value_type;
 284   typedef wxChar char_type;
 285   typedef size_t size_type;
 286   typedef value_type& reference;
 287   typedef const value_type& const_reference;
 288   typedef value_type* pointer;
 289   typedef const value_type* const_pointer;
 290   typedef value_type *iterator;
 291   typedef const value_type *const_iterator;
 292
 293   // constructors and destructor
 294     // ctor for an empty string
 295   wxStringBase() { Init(); }
 296     // copy ctor
 297   wxStringBase(const wxStringBase& stringSrc)
 298   {
 299     wxASSERT_MSG( stringSrc.GetStringData()->IsValid(),
 300                   _T("did you forget to call UngetWriteBuf()?") );
 301
 302     if ( stringSrc.empty() ) {
 303       // nothing to do for an empty string
 304       Init();
 305     }
 306     else {
 307       m_pchData = stringSrc.m_pchData;            // share same data
 308       GetStringData()->Lock();                    // => one more copy
 309     }
 310   }
 311     // string containing nRepeat copies of ch
 312   wxStringBase(size_type nRepeat, wxChar ch);
 313     // ctor takes first nLength characters from C string
 314     // (default value of npos means take all the string)
 315   wxStringBase(const wxChar *psz)
 316       { InitWith(psz, 0, npos); }
 317   wxStringBase(const wxChar *psz, size_t nLength)
 318       { InitWith(psz, 0, nLength); }
 319   wxStringBase(const wxChar *psz, wxMBConv& WXUNUSED(conv), size_t nLength = npos)
 320       { InitWith(psz, 0, nLength); }
 321     // take nLen chars starting at nPos
 322   wxStringBase(const wxStringBase& str, size_t nPos, size_t nLen)
 323   {
 324     wxASSERT_MSG( str.GetStringData()->IsValid(),
 325                   _T("did you forget to call UngetWriteBuf()?") );
 326     Init();
 327     size_t strLen = str.length() - nPos; nLen = strLen < nLen ? strLen : nLen;
 328     InitWith(str.c_str(), nPos, nLen);
 329   }
 330     // take all characters from pStart to pEnd
 331   wxStringBase(const void *pStart, const void *pEnd);
 332
 333     // dtor is not virtual, this class must not be inherited from!
 334   ~wxStringBase()
 335   {
 336 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 337       //RN - according to the above VC++ does indeed inline this,
 338       //even though it spits out two warnings
 339       #pragma warning (disable:4714)
 340 #endif
 341
 342       GetStringData()->Unlock();
 343   }
 344
 345 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 346     //re-enable inlining warning
 347     #pragma warning (default:4714)
 348 #endif
 349   // overloaded assignment
 350     // from another wxString
 351   wxStringBase& operator=(const wxStringBase& stringSrc);
 352     // from a character
 353   wxStringBase& operator=(wxChar ch);
 354     // from a C string
 355   wxStringBase& operator=(const wxChar *psz);
 356
 357     // return the length of the string
 358   size_type size() const { return GetStringData()->nDataLength; }
 359     // return the length of the string
 360   size_type length() const { return size(); }
 361     // return the maximum size of the string
 362   size_type max_size() const { return wxSTRING_MAXLEN; }
 363     // resize the string, filling the space with c if c != 0
 364   void resize(size_t nSize, wxChar ch = wxT('\0'));
 365     // delete the contents of the string
 366   void clear() { erase(0, npos); }
 367     // returns true if the string is empty
 368   bool empty() const { return size() == 0; }
 369     // inform string about planned change in size
 370   void reserve(size_t sz) { Alloc(sz); }
 371   size_type capacity() const { return GetStringData()->nAllocLength; }
 372
 373   // lib.string.access
 374     // return the character at position n
 375   value_type at(size_type n) const
 376     { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
 377   value_type operator[](size_type n) const { return at(n); }
 378     // returns the writable character at position n
 379   reference at(size_type n)
 380     { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
 381   reference operator[](size_type n)
 382     { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
 383
 384   // lib.string.modifiers
 385     // append elements str[pos], ..., str[pos+n]
 386   wxStringBase& append(const wxStringBase& str, size_t pos, size_t n)
 387   {
 388     wxASSERT(pos <= str.length());
 389     ConcatSelf(n, str.c_str() + pos, str.length() - pos);
 390     return *this;
 391   }
 392     // append a string
 393   wxStringBase& append(const wxStringBase& str)
 394     { ConcatSelf(str.length(), str.c_str()); return *this; }
 395     // append first n (or all if n == npos) characters of sz
 396   wxStringBase& append(const wxChar *sz)
 397     { ConcatSelf(wxStrlen(sz), sz); return *this; }
 398   wxStringBase& append(const wxChar *sz, size_t n)
 399     { ConcatSelf(n, sz); return *this; }
 400     // append n copies of ch
 401   wxStringBase& append(size_t n, wxChar ch);
 402     // append from first to last
 403   wxStringBase& append(const_iterator first, const_iterator last)
 404     { ConcatSelf(last - first, first); return *this; }
 405
 406     // same as `this_string = str'
 407   wxStringBase& assign(const wxStringBase& str)
 408     { return *this = str; }
 409     // same as ` = str[pos..pos + n]
 410   wxStringBase& assign(const wxStringBase& str, size_t pos, size_t n)
 411     { clear(); return append(str, pos, n); }
 412     // same as `= first n (or all if n == npos) characters of sz'
 413   wxStringBase& assign(const wxChar *sz)
 414     { clear(); return append(sz, wxStrlen(sz)); }
 415   wxStringBase& assign(const wxChar *sz, size_t n)
 416     { clear(); return append(sz, n); }
 417     // same as `= n copies of ch'
 418   wxStringBase& assign(size_t n, wxChar ch)
 419     { clear(); return append(n, ch); }
 420     // assign from first to last
 421   wxStringBase& assign(const_iterator first, const_iterator last)
 422     { clear(); return append(first, last); }
 423
 424     // first valid index position
 425   const_iterator begin() const { return m_pchData; }
 426     // position one after the last valid one
 427   const_iterator end() const { return m_pchData + length(); }
 428
 429   // first valid index position
 430   iterator begin();
 431   // position one after the last valid one
 432   iterator end();
 433
 434     // insert another string
 435   wxStringBase& insert(size_t nPos, const wxStringBase& str)
 436   {
 437     wxASSERT( str.GetStringData()->IsValid() );
 438     return insert(nPos, str.c_str(), str.length());
 439   }
 440     // insert n chars of str starting at nStart (in str)
 441   wxStringBase& insert(size_t nPos, const wxStringBase& str, size_t nStart, size_t n)
 442   {
 443     wxASSERT( str.GetStringData()->IsValid() );
 444     wxASSERT( nStart < str.length() );
 445     size_t strLen = str.length() - nStart;
 446     n = strLen < n ? strLen : n;
 447     return insert(nPos, str.c_str() + nStart, n);
 448   }
 449     // insert first n (or all if n == npos) characters of sz
 450   wxStringBase& insert(size_t nPos, const wxChar *sz, size_t n = npos);
 451     // insert n copies of ch
 452   wxStringBase& insert(size_t nPos, size_t n, wxChar ch)
 453     { return insert(nPos, wxStringBase(n, ch)); }
 454   iterator insert(iterator it, wxChar ch)
 455     { size_t idx = it - begin(); insert(idx, 1, ch); return begin() + idx; }
 456   void insert(iterator it, const_iterator first, const_iterator last)
 457     { insert(it - begin(), first, last - first); }
 458   void insert(iterator it, size_type n, wxChar ch)
 459     { insert(it - begin(), n, ch); }
 460
 461     // delete characters from nStart to nStart + nLen
 462   wxStringBase& erase(size_type pos = 0, size_type n = npos);
 463   iterator erase(iterator first, iterator last)
 464   {
 465     size_t idx = first - begin();
 466     erase(idx, last - first);
 467     return begin() + idx;
 468   }
 469   iterator erase(iterator first);
 470
 471   // explicit conversion to C string (use this with printf()!)
 472   const wxChar* c_str() const { return m_pchData; }
 473   const wxChar* data() const { return m_pchData; }
 474
 475     // replaces the substring of length nLen starting at nStart
 476   wxStringBase& replace(size_t nStart, size_t nLen, const wxChar* sz);
 477     // replaces the substring of length nLen starting at nStart
 478   wxStringBase& replace(size_t nStart, size_t nLen, const wxStringBase& str)
 479     { return replace(nStart, nLen, str.c_str()); }
 480     // replaces the substring with nCount copies of ch
 481   wxStringBase& replace(size_t nStart, size_t nLen, size_t nCount, wxChar ch);
 482     // replaces a substring with another substring
 483   wxStringBase& replace(size_t nStart, size_t nLen,
 484                         const wxStringBase& str, size_t nStart2, size_t nLen2);
 485     // replaces the substring with first nCount chars of sz
 486   wxStringBase& replace(size_t nStart, size_t nLen,
 487                         const wxChar* sz, size_t nCount);
 488   wxStringBase& replace(iterator first, iterator last, const_pointer s)
 489     { return replace(first - begin(), last - first, s); }
 490   wxStringBase& replace(iterator first, iterator last, const_pointer s,
 491                         size_type n)
 492     { return replace(first - begin(), last - first, s, n); }
 493   wxStringBase& replace(iterator first, iterator last, const wxStringBase& s)
 494     { return replace(first - begin(), last - first, s); }
 495   wxStringBase& replace(iterator first, iterator last, size_type n, wxChar c)
 496     { return replace(first - begin(), last - first, n, c); }
 497   wxStringBase& replace(iterator first, iterator last,
 498                         const_iterator first1, const_iterator last1)
 499     { return replace(first - begin(), last - first, first1, last1 - first1); }
 500
 501     // swap two strings
 502   void swap(wxStringBase& str);
 503
 504     // All find() functions take the nStart argument which specifies the
 505     // position to start the search on, the default value is 0. All functions
 506     // return npos if there were no match.
 507
 508     // find a substring
 509   size_t find(const wxStringBase& str, size_t nStart = 0) const;
 510
 511   // VC++ 1.5 can't cope with this syntax.
 512 #if !defined(__VISUALC__) || defined(__WIN32__)
 513     // find first n characters of sz
 514   size_t find(const wxChar* sz, size_t nStart = 0, size_t n = npos) const;
 515 #endif // VC++ 1.5
 516
 517     // find the first occurence of character ch after nStart
 518   size_t find(wxChar ch, size_t nStart = 0) const;
 519
 520     // rfind() family is exactly like find() but works right to left
 521
 522     // as find, but from the end
 523   size_t rfind(const wxStringBase& str, size_t nStart = npos) const;
 524
 525   // VC++ 1.5 can't cope with this syntax.
 526     // as find, but from the end
 527   size_t rfind(const wxChar* sz, size_t nStart = npos,
 528                size_t n = npos) const;
 529     // as find, but from the end
 530   size_t rfind(wxChar ch, size_t nStart = npos) const;
 531
 532     // find first/last occurence of any character in the set
 533
 534     // as strpbrk() but starts at nStart, returns npos if not found
 535   size_t find_first_of(const wxStringBase& str, size_t nStart = 0) const
 536     { return find_first_of(str.c_str(), nStart); }
 537     // same as above
 538   size_t find_first_of(const wxChar* sz, size_t nStart = 0) const;
 539   size_t find_first_of(const wxChar* sz, size_t nStart, size_t n) const;
 540     // same as find(char, size_t)
 541   size_t find_first_of(wxChar c, size_t nStart = 0) const
 542     { return find(c, nStart); }
 543     // find the last (starting from nStart) char from str in this string
 544   size_t find_last_of (const wxStringBase& str, size_t nStart = npos) const
 545     { return find_last_of(str.c_str(), nStart); }
 546     // same as above
 547   size_t find_last_of (const wxChar* sz, size_t nStart = npos) const;
 548   size_t find_last_of(const wxChar* sz, size_t nStart, size_t n) const;
 549     // same as above
 550   size_t find_last_of(wxChar c, size_t nStart = npos) const
 551     { return rfind(c, nStart); }
 552
 553     // find first/last occurence of any character not in the set
 554
 555     // as strspn() (starting from nStart), returns npos on failure
 556   size_t find_first_not_of(const wxStringBase& str, size_t nStart = 0) const
 557     { return find_first_not_of(str.c_str(), nStart); }
 558     // same as above
 559   size_t find_first_not_of(const wxChar* sz, size_t nStart = 0) const;
 560   size_t find_first_not_of(const wxChar* sz, size_t nStart, size_t n) const;
 561     // same as above
 562   size_t find_first_not_of(wxChar ch, size_t nStart = 0) const;
 563     //  as strcspn()
 564   size_t find_last_not_of(const wxStringBase& str, size_t nStart = npos) const
 565     { return find_last_not_of(str.c_str(), nStart); }
 566     // same as above
 567   size_t find_last_not_of(const wxChar* sz, size_t nStart = npos) const;
 568   size_t find_last_not_of(const wxChar* sz, size_t nStart, size_t n) const;
 569     // same as above
 570   size_t find_last_not_of(wxChar ch, size_t nStart = npos) const;
 571
 572     // All compare functions return -1, 0 or 1 if the [sub]string is less,
 573     // equal or greater than the compare() argument.
 574
 575     // just like strcmp()
 576   int compare(const wxStringBase& str) const
 577     { return wxStrcmp(c_str(), str.c_str()); }
 578     // comparison with a substring
 579   int compare(size_t nStart, size_t nLen, const wxStringBase& str) const;
 580     // comparison of 2 substrings
 581   int compare(size_t nStart, size_t nLen,
 582               const wxStringBase& str, size_t nStart2, size_t nLen2) const;
 583     // just like strcmp()
 584   int compare(const wxChar* sz) const
 585     { return wxStrcmp(c_str(), sz); }
 586     // substring comparison with first nCount characters of sz
 587   int compare(size_t nStart, size_t nLen,
 588               const wxChar* sz, size_t nCount = npos) const;
 589
 590   size_type copy(wxChar* s, size_type n, size_type pos = 0);
 591
 592   // substring extraction
 593   wxStringBase substr(size_t nStart = 0, size_t nLen = npos) const;
 594
 595       // string += string
 596   wxStringBase& operator+=(const wxStringBase& s) { return append(s); }
 597       // string += C string
 598   wxStringBase& operator+=(const wxChar *psz) { return append(psz); }
 599       // string += char
 600   wxStringBase& operator+=(wxChar ch) { return append(1, ch); }
 601 };
 602
 603 #endif // !wxUSE_STL
 604
 605 // ---------------------------------------------------------------------------
 606 // This is (yet another one) String class for C++ programmers. It doesn't use
 607 // any of "advanced" C++ features (i.e. templates, exceptions, namespaces...)
 608 // thus you should be able to compile it with practicaly any C++ compiler.
 609 // This class uses copy-on-write technique, i.e. identical strings share the
 610 // same memory as long as neither of them is changed.
 611 //
 612 // This class aims to be as compatible as possible with the new standard
 613 // std::string class, but adds some additional functions and should be at
 614 // least as efficient than the standard implementation.
 615 //
 616 // Performance note: it's more efficient to write functions which take "const
 617 // String&" arguments than "const char *" if you assign the argument to
 618 // another string.
 619 //
 620 // It was compiled and tested under Win32, Linux (libc 5 & 6), Solaris 5.5.
 621 //
 622 // To do:
 623 //  - ressource support (string tables in ressources)
 624 //  - more wide character (UNICODE) support
 625 //  - regular expressions support
 626 // ---------------------------------------------------------------------------
 627
 628 class WXDLLIMPEXP_BASE wxString : public wxStringBase
 629 {
 630 #if !wxUSE_STL
 631 friend class WXDLLIMPEXP_BASE wxArrayString;
 632 #endif
 633
 634   // NB: special care was taken in arranging the member functions in such order
 635   //     that all inline functions can be effectively inlined, verify that all
 636   //     performace critical functions are still inlined if you change order!
 637 private:
 638   // if we hadn't made these operators private, it would be possible to
 639   // compile "wxString s; s = 17;" without any warnings as 17 is implicitly
 640   // converted to char in C and we do have operator=(char)
 641   //
 642   // NB: we don't need other versions (short/long and unsigned) as attempt
 643   //     to assign another numeric type to wxString will now result in
 644   //     ambiguity between operator=(char) and operator=(int)
 645   wxString& operator=(int);
 646
 647   // these methods are not implemented - there is _no_ conversion from int to
 648   // string, you're doing something wrong if the compiler wants to call it!
 649   //
 650   // try `s << i' or `s.Printf("%d", i)' instead
 651   wxString(int);
 652
 653 public:
 654   // constructors and destructor
 655     // ctor for an empty string
 656   wxString() : wxStringBase() { }
 657     // copy ctor
 658   wxString(const wxStringBase& stringSrc) : wxStringBase(stringSrc) { }
 659   wxString(const wxString& stringSrc) : wxStringBase(stringSrc) { }
 660     // string containing nRepeat copies of ch
 661   wxString(wxChar ch, size_t nRepeat = 1)
 662       : wxStringBase(nRepeat, ch) { }
 663   wxString(size_t nRepeat, wxChar ch)
 664       : wxStringBase(nRepeat, ch) { }
 665     // ctor takes first nLength characters from C string
 666     // (default value of npos means take all the string)
 667   wxString(const wxChar *psz)
 668       : wxStringBase(psz ? psz : wxT("")) { }
 669   wxString(const wxChar *psz, size_t nLength)
 670       : wxStringBase(psz, nLength) { }
 671   wxString(const wxChar *psz, wxMBConv& WXUNUSED(conv), size_t nLength = npos)
 672       : wxStringBase(psz, nLength == npos ? wxStrlen(psz) : nLength) { }
 673
 674 #if wxUSE_UNICODE
 675     // from multibyte string
 676   wxString(const char *psz, wxMBConv& conv, size_t nLength = npos);
 677     // from wxWCharBuffer (i.e. return from wxGetString)
 678   wxString(const wxWCharBuffer& psz) : wxStringBase(psz.data()) { }
 679 #else // ANSI
 680     // from C string (for compilers using unsigned char)
 681   wxString(const unsigned char* psz, size_t nLength = npos)
 682       : wxStringBase((const char*)psz, nLength) { }
 683
 684 #if wxUSE_WCHAR_T
 685     // from wide (Unicode) string
 686   wxString(const wchar_t *pwz, wxMBConv& conv = wxConvLibc, size_t nLength = npos);
 687 #endif // !wxUSE_WCHAR_T
 688
 689     // from wxCharBuffer
 690   wxString(const wxCharBuffer& psz)
 691       : wxStringBase(psz) { }
 692 #endif // Unicode/ANSI
 693
 694   // generic attributes & operations
 695     // as standard strlen()
 696   size_t Len() const { return length(); }
 697     // string contains any characters?
 698   bool IsEmpty() const { return empty(); }
 699     // empty string is "false", so !str will return true
 700   bool operator!() const { return IsEmpty(); }
 701     // truncate the string to given length
 702   wxString& Truncate(size_t uiLen);
 703     // empty string contents
 704   void Empty()
 705   {
 706     Truncate(0);
 707
 708     wxASSERT_MSG( IsEmpty(), _T("string not empty after call to Empty()?") );
 709   }
 710     // empty the string and free memory
 711   void Clear()
 712   {
 713     wxString tmp(wxEmptyString);
 714     swap(tmp);
 715   }
 716
 717   // contents test
 718     // Is an ascii value
 719   bool IsAscii() const;
 720     // Is a number
 721   bool IsNumber() const;
 722     // Is a word
 723   bool IsWord() const;
 724
 725   // data access (all indexes are 0 based)
 726     // read access
 727     wxChar  GetChar(size_t n) const
 728       { return operator[](n); }
 729     // read/write access
 730     wxChar& GetWritableChar(size_t n)
 731       { return operator[](n); }
 732     // write access
 733     void  SetChar(size_t n, wxChar ch)
 734       { operator[](n) = ch; }
 735
 736     // get last character
 737     wxChar  Last() const
 738       {
 739           wxASSERT_MSG( !IsEmpty(), _T("wxString: index out of bounds") );
 740
 741           return operator[](length() - 1);
 742       }
 743
 744     // get writable last character
 745     wxChar& Last()
 746       {
 747           wxASSERT_MSG( !IsEmpty(), _T("wxString: index out of bounds") );
 748           return operator[](length() - 1);
 749       }
 750
 751     /*
 752         So why do we have all these overloaded operator[]s? A bit of history:
 753         initially there was only one of them, taking size_t. Then people
 754         started complaining because they wanted to use ints as indices (I
 755         wonder why) and compilers were giving warnings about it, so we had to
 756         add the operator[](int). Then it became apparent that you couldn't
 757         write str[0] any longer because there was ambiguity between two
 758         overloads and so you now had to write str[0u] (or, of course, use the
 759         explicit casts to either int or size_t but nobody did this).
 760
 761         Finally, someone decided to compile wxWin on an Alpha machine and got
 762         a surprize: str[0u] didn't compile there because it is of type
 763         unsigned int and size_t is unsigned _long_ on Alpha and so there was
 764         ambiguity between converting uint to int or ulong. To fix this one we
 765         now add operator[](uint) for the machines where size_t is not already
 766         the same as unsigned int - hopefully this fixes the problem (for some
 767         time)
 768
 769         The only real fix is, of course, to remove all versions but the one
 770         taking size_t...
 771      */
 772
 773     // operator version of GetChar
 774     wxChar  operator[](int n) const
 775       { return wxStringBase::operator[](n); }
 776     wxChar& operator[](size_type n)
 777       { return wxStringBase::operator[](n); }
 778     wxChar operator[](size_type n) const
 779       { return wxStringBase::operator[](n); }
 780 #ifndef wxSIZE_T_IS_UINT
 781     // operator version of GetChar
 782     wxChar operator[](unsigned int n) const
 783       { return wxStringBase::operator[](n); }
 784
 785     // operator version of GetWriteableChar
 786     wxChar& operator[](unsigned int n)
 787       { return wxStringBase::operator[](n); }
 788 #endif // size_t != unsigned int
 789
 790     // implicit conversion to C string
 791     operator const wxChar*() const { return c_str(); }
 792
 793     // identical to c_str(), for wxWin 1.6x compatibility
 794     const wxChar* wx_str()  const { return c_str(); }
 795     // identical to c_str(), for MFC compatibility
 796     const wxChar* GetData() const { return c_str(); }
 797
 798     // conversion to/from plain (i.e. 7 bit) ASCII: this is useful for
 799     // converting numbers or strings which are certain not to contain special
 800     // chars (typically system functions, X atoms, environment variables etc.)
 801     //
 802     // the behaviour of these functions with the strings containing anything
 803     // else than 7 bit ASCII characters is undefined, use at your own risk.
 804 #if wxUSE_UNICODE
 805     static wxString FromAscii(const char *ascii);  // string
 806     static wxString FromAscii(const char ascii);   // char
 807     const wxCharBuffer ToAscii() const;
 808 #else // ANSI
 809     static wxString FromAscii(const char *ascii) { return wxString( ascii ); }
 810     static wxString FromAscii(const char ascii) { return wxString( ascii ); }
 811     const char *ToAscii() const { return c_str(); }
 812 #endif // Unicode/!Unicode
 813
 814     // conversions with (possible) format conversions: have to return a
 815     // buffer with temporary data
 816     //
 817     // the functions defined (in either Unicode or ANSI) mode are mb_str() to
 818     // return an ANSI (multibyte) string, wc_str() to return a wide string and
 819     // fn_str() to return a string which should be used with the OS APIs
 820     // accepting the file names. The return value is always the same, but the
 821     // type differs because a function may either return pointer to the buffer
 822     // directly or have to use intermediate buffer for translation.
 823 #if wxUSE_UNICODE
 824     const wxCharBuffer mb_str(wxMBConv& conv = wxConvLibc) const
 825         { return conv.cWC2MB(c_str()); }
 826
 827     const wxWX2MBbuf mbc_str() const { return mb_str(*wxConvCurrent); }
 828
 829     const wxChar* wc_str() const { return c_str(); }
 830
 831     // for compatibility with !wxUSE_UNICODE version
 832     const wxChar* wc_str(wxMBConv& WXUNUSED(conv)) const { return c_str(); }
 833
 834 #if wxMBFILES
 835     const wxCharBuffer fn_str() const { return mb_str(wxConvFile); }
 836 #else // !wxMBFILES
 837     const wxChar* fn_str() const { return c_str(); }
 838 #endif // wxMBFILES/!wxMBFILES
 839 #else // ANSI
 840     const wxChar* mb_str() const { return c_str(); }
 841
 842     // for compatibility with wxUSE_UNICODE version
 843     const wxChar* mb_str(wxMBConv& WXUNUSED(conv)) const { return c_str(); }
 844
 845     const wxWX2MBbuf mbc_str() const { return mb_str(); }
 846
 847 #if wxUSE_WCHAR_T
 848     const wxWCharBuffer wc_str(wxMBConv& conv) const
 849         { return conv.cMB2WC(c_str()); }
 850 #endif // wxUSE_WCHAR_T
 851
 852     const wxChar* fn_str() const { return c_str(); }
 853 #endif // Unicode/ANSI
 854
 855   // overloaded assignment
 856     // from another wxString
 857   wxString& operator=(const wxStringBase& stringSrc)
 858     { return (wxString&)wxStringBase::operator=(stringSrc); }
 859     // from a character
 860   wxString& operator=(wxChar ch)
 861     { return (wxString&)wxStringBase::operator=(ch); }
 862     // from a C string
 863   wxString& operator=(const wxChar *psz)
 864     { return (wxString&)wxStringBase::operator=(psz); }
 865 #if wxUSE_UNICODE
 866     // from wxWCharBuffer
 867   wxString& operator=(const wxWCharBuffer& psz)
 868     { (void) operator=((const wchar_t *)psz); return *this; }
 869 #else // ANSI
 870     // from another kind of C string
 871   wxString& operator=(const unsigned char* psz);
 872 #if wxUSE_WCHAR_T
 873     // from a wide string
 874   wxString& operator=(const wchar_t *pwz);
 875 #endif
 876     // from wxCharBuffer
 877   wxString& operator=(const wxCharBuffer& psz)
 878     { (void) operator=((const char *)psz); return *this; }
 879 #endif // Unicode/ANSI
 880
 881   // string concatenation
 882     // in place concatenation
 883     /*
 884         Concatenate and return the result. Note that the left to right
 885         associativity of << allows to write things like "str << str1 << str2
 886         << ..." (unlike with +=)
 887      */
 888       // string += string
 889   wxString& operator<<(const wxString& s)
 890   {
 891 #if !wxUSE_STL
 892     wxASSERT_MSG( s.GetStringData()->IsValid(),
 893                   _T("did you forget to call UngetWriteBuf()?") );
 894 #endif
 895
 896     append(s);
 897     return *this;
 898   }
 899       // string += C string
 900   wxString& operator<<(const wxChar *psz)
 901     { append(psz); return *this; }
 902       // string += char
 903   wxString& operator<<(wxChar ch) { append(1, ch); return *this; }
 904
 905       // string += buffer (i.e. from wxGetString)
 906 #if wxUSE_UNICODE
 907   wxString& operator<<(const wxWCharBuffer& s)
 908     { (void)operator<<((const wchar_t *)s); return *this; }
 909   void operator+=(const wxWCharBuffer& s)
 910     { (void)operator<<((const wchar_t *)s); }
 911 #else // !wxUSE_UNICODE
 912   wxString& operator<<(const wxCharBuffer& s)
 913     { (void)operator<<((const char *)s); return *this; }
 914   void operator+=(const wxCharBuffer& s)
 915     { (void)operator<<((const char *)s); }
 916 #endif // wxUSE_UNICODE/!wxUSE_UNICODE
 917
 918     // string += C string
 919   wxString& Append(const wxString& s)
 920     {
 921         // test for IsEmpty() to share the string if possible
 922         if ( IsEmpty() )
 923             *this = s;
 924         else
 925             append(s);
 926         return *this;
 927     }
 928   wxString& Append(const wxChar* psz)
 929     { append(psz); return *this; }
 930     // append count copies of given character
 931   wxString& Append(wxChar ch, size_t count = 1u)
 932     { append(count, ch); return *this; }
 933   wxString& Append(const wxChar* psz, size_t nLen)
 934     { append(psz, nLen); return *this; }
 935
 936     // prepend a string, return the string itself
 937   wxString& Prepend(const wxString& str)
 938     { *this = str + *this; return *this; }
 939
 940     // non-destructive concatenation
 941       //
 942   friend wxString WXDLLIMPEXP_BASE operator+(const wxString& string1,  const wxString& string2);
 943       //
 944   friend wxString WXDLLIMPEXP_BASE operator+(const wxString& string, wxChar ch);
 945       //
 946   friend wxString WXDLLIMPEXP_BASE operator+(wxChar ch, const wxString& string);
 947       //
 948   friend wxString WXDLLIMPEXP_BASE operator+(const wxString& string, const wxChar *psz);
 949       //
 950   friend wxString WXDLLIMPEXP_BASE operator+(const wxChar *psz, const wxString& string);
 951
 952   // stream-like functions
 953       // insert an int into string
 954   wxString& operator<<(int i)
 955     { return (*this) << Format(_T("%d"), i); }
 956       // insert an unsigned int into string
 957   wxString& operator<<(unsigned int ui)
 958     { return (*this) << Format(_T("%u"), ui); }
 959       // insert a long into string
 960   wxString& operator<<(long l)
 961     { return (*this) << Format(_T("%ld"), l); }
 962       // insert an unsigned long into string
 963   wxString& operator<<(unsigned long ul)
 964     { return (*this) << Format(_T("%lu"), ul); }
 965       // insert a float into string
 966   wxString& operator<<(float f)
 967     { return (*this) << Format(_T("%f"), f); }
 968       // insert a double into string
 969   wxString& operator<<(double d)
 970     { return (*this) << Format(_T("%g"), d); }
 971
 972   // string comparison
 973     // case-sensitive comparison (returns a value < 0, = 0 or > 0)
 974   int Cmp(const wxChar *psz) const { return wxStrcmp(c_str(), psz); }
 975     // same as Cmp() but not case-sensitive
 976   int CmpNoCase(const wxChar *psz) const { return wxStricmp(c_str(), psz); }
 977     // test for the string equality, either considering case or not
 978     // (if compareWithCase then the case matters)
 979   bool IsSameAs(const wxChar *psz, bool compareWithCase = true) const
 980     { return (compareWithCase ? Cmp(psz) : CmpNoCase(psz)) == 0; }
 981     // comparison with a signle character: returns true if equal
 982   bool IsSameAs(wxChar c, bool compareWithCase = true) const
 983     {
 984       return (length() == 1) && (compareWithCase ? GetChar(0u) == c
 985                               : wxToupper(GetChar(0u)) == wxToupper(c));
 986     }
 987
 988   // simple sub-string extraction
 989       // return substring starting at nFirst of length nCount (or till the end
 990       // if nCount = default value)
 991   wxString Mid(size_t nFirst, size_t nCount = npos) const;
 992
 993       // operator version of Mid()
 994   wxString  operator()(size_t start, size_t len) const
 995     { return Mid(start, len); }
 996
 997       // check that the string starts with prefix and return the rest of the
 998       // string in the provided pointer if it is not NULL, otherwise return
 999       // false
1000   bool StartsWith(const wxChar *prefix, wxString *rest = NULL) const;
1001
1002       // get first nCount characters
1003   wxString Left(size_t nCount) const;
1004       // get last nCount characters
1005   wxString Right(size_t nCount) const;
1006       // get all characters before the first occurance of ch
1007       // (returns the whole string if ch not found)
1008   wxString BeforeFirst(wxChar ch) const;
1009       // get all characters before the last occurence of ch
1010       // (returns empty string if ch not found)
1011   wxString BeforeLast(wxChar ch) const;
1012       // get all characters after the first occurence of ch
1013       // (returns empty string if ch not found)
1014   wxString AfterFirst(wxChar ch) const;
1015       // get all characters after the last occurence of ch
1016       // (returns the whole string if ch not found)
1017   wxString AfterLast(wxChar ch) const;
1018
1019     // for compatibility only, use more explicitly named functions above
1020   wxString Before(wxChar ch) const { return BeforeLast(ch); }
1021   wxString After(wxChar ch) const { return AfterFirst(ch); }
1022
1023   // case conversion
1024       // convert to upper case in place, return the string itself
1025   wxString& MakeUpper();
1026       // convert to upper case, return the copy of the string
1027       // Here's something to remember: BC++ doesn't like returns in inlines.
1028   wxString Upper() const ;
1029       // convert to lower case in place, return the string itself
1030   wxString& MakeLower();
1031       // convert to lower case, return the copy of the string
1032   wxString Lower() const ;
1033
1034   // trimming/padding whitespace (either side) and truncating
1035       // remove spaces from left or from right (default) side
1036   wxString& Trim(bool bFromRight = true);
1037       // add nCount copies chPad in the beginning or at the end (default)
1038   wxString& Pad(size_t nCount, wxChar chPad = wxT(' '), bool bFromRight = true);
1039
1040   // searching and replacing
1041       // searching (return starting index, or -1 if not found)
1042   int Find(wxChar ch, bool bFromEnd = false) const;   // like strchr/strrchr
1043       // searching (return starting index, or -1 if not found)
1044   int Find(const wxChar *pszSub) const;               // like strstr
1045       // replace first (or all of bReplaceAll) occurences of substring with
1046       // another string, returns the number of replacements made
1047   size_t Replace(const wxChar *szOld,
1048                  const wxChar *szNew,
1049                  bool bReplaceAll = true);
1050
1051     // check if the string contents matches a mask containing '*' and '?'
1052   bool Matches(const wxChar *szMask) const;
1053
1054     // conversion to numbers: all functions return true only if the whole
1055     // string is a number and put the value of this number into the pointer
1056     // provided, the base is the numeric base in which the conversion should be
1057     // done and must be comprised between 2 and 36 or be 0 in which case the
1058     // standard C rules apply (leading '0' => octal, "0x" => hex)
1059         // convert to a signed integer
1060     bool ToLong(long *val, int base = 10) const;
1061         // convert to an unsigned integer
1062     bool ToULong(unsigned long *val, int base = 10) const;
1063         // convert to a double
1064     bool ToDouble(double *val) const;
1065
1066   // formated input/output
1067     // as sprintf(), returns the number of characters written or < 0 on error
1068     // (take 'this' into account in attribute parameter count)
1069   int Printf(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_2;
1070     // as vprintf(), returns the number of characters written or < 0 on error
1071   int PrintfV(const wxChar* pszFormat, va_list argptr);
1072
1073     // returns the string containing the result of Printf() to it
1074   static wxString Format(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_1;
1075     // the same as above, but takes a va_list
1076   static wxString FormatV(const wxChar *pszFormat, va_list argptr);
1077
1078   // raw access to string memory
1079     // ensure that string has space for at least nLen characters
1080     // only works if the data of this string is not shared
1081   bool Alloc(size_t nLen) { reserve(nLen); /*return capacity() >= nLen;*/ return true; }
1082     // minimize the string's memory
1083     // only works if the data of this string is not shared
1084   bool Shrink();
1085 #if !wxUSE_STL
1086     // get writable buffer of at least nLen bytes. Unget() *must* be called
1087     // a.s.a.p. to put string back in a reasonable state!
1088   wxChar *GetWriteBuf(size_t nLen);
1089     // call this immediately after GetWriteBuf() has been used
1090   void UngetWriteBuf();
1091   void UngetWriteBuf(size_t nLen);
1092 #endif
1093
1094   // wxWidgets version 1 compatibility functions
1095
1096   // use Mid()
1097   wxString SubString(size_t from, size_t to) const
1098       { return Mid(from, (to - from + 1)); }
1099     // values for second parameter of CompareTo function
1100   enum caseCompare {exact, ignoreCase};
1101     // values for first parameter of Strip function
1102   enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
1103
1104   // use Printf()
1105   // (take 'this' into account in attribute parameter count)
1106   int sprintf(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_2;
1107
1108     // use Cmp()
1109   inline int CompareTo(const wxChar* psz, caseCompare cmp = exact) const
1110     { return cmp == exact ? Cmp(psz) : CmpNoCase(psz); }
1111
1112     // use Len
1113   size_t Length() const { return length(); }
1114     // Count the number of characters
1115   int Freq(wxChar ch) const;
1116     // use MakeLower
1117   void LowerCase() { MakeLower(); }
1118     // use MakeUpper
1119   void UpperCase() { MakeUpper(); }
1120     // use Trim except that it doesn't change this string
1121   wxString Strip(stripType w = trailing) const;
1122
1123     // use Find (more general variants not yet supported)
1124   size_t Index(const wxChar* psz) const { return Find(psz); }
1125   size_t Index(wxChar ch)         const { return Find(ch);  }
1126     // use Truncate
1127   wxString& Remove(size_t pos) { return Truncate(pos); }
1128   wxString& RemoveLast(size_t n = 1) { return Truncate(length() - n); }
1129
1130   wxString& Remove(size_t nStart, size_t nLen)
1131       { return (wxString&)erase( nStart, nLen ); }
1132
1133     // use Find()
1134   int First( const wxChar ch ) const { return Find(ch); }
1135   int First( const wxChar* psz ) const { return Find(psz); }
1136   int First( const wxString &str ) const { return Find(str); }
1137   int Last( const wxChar ch ) const { return Find(ch, true); }
1138   bool Contains(const wxString& str) const { return Find(str) != wxNOT_FOUND; }
1139
1140     // use IsEmpty()
1141   bool IsNull() const { return IsEmpty(); }
1142
1143   // std::string compatibility functions
1144
1145     // take nLen chars starting at nPos
1146   wxString(const wxString& str, size_t nPos, size_t nLen)
1147       : wxStringBase(str, nPos, nLen) { }
1148     // take all characters from pStart to pEnd
1149   wxString(const void *pStart, const void *pEnd)
1150       : wxStringBase((const wxChar*)pStart, (const wxChar*)pEnd) { }
1151 #if wxUSE_STL
1152   wxString(const_iterator first, const_iterator last)
1153       : wxStringBase(first, last) { }
1154 #endif
1155
1156   // lib.string.modifiers
1157     // append elements str[pos], ..., str[pos+n]
1158   wxString& append(const wxString& str, size_t pos, size_t n)
1159     { return (wxString&)wxStringBase::append(str, pos, n); }
1160     // append a string
1161   wxString& append(const wxString& str)
1162     { return (wxString&)wxStringBase::append(str); }
1163     // append first n (or all if n == npos) characters of sz
1164   wxString& append(const wxChar *sz)
1165     { return (wxString&)wxStringBase::append(sz); }
1166   wxString& append(const wxChar *sz, size_t n)
1167     { return (wxString&)wxStringBase::append(sz, n); }
1168     // append n copies of ch
1169   wxString& append(size_t n, wxChar ch)
1170     { return (wxString&)wxStringBase::append(n, ch); }
1171     // append from first to last
1172   wxString& append(const_iterator first, const_iterator last)
1173     { return (wxString&)wxStringBase::append(first, last); }
1174
1175     // same as `this_string = str'
1176   wxString& assign(const wxString& str)
1177     { return (wxString&)wxStringBase::assign(str); }
1178     // same as ` = str[pos..pos + n]
1179   wxString& assign(const wxString& str, size_t pos, size_t n)
1180     { return (wxString&)wxStringBase::assign(str, pos, n); }
1181     // same as `= first n (or all if n == npos) characters of sz'
1182   wxString& assign(const wxChar *sz)
1183     { return (wxString&)wxStringBase::assign(sz); }
1184   wxString& assign(const wxChar *sz, size_t n)
1185     { return (wxString&)wxStringBase::assign(sz, n); }
1186     // same as `= n copies of ch'
1187   wxString& assign(size_t n, wxChar ch)
1188     { return (wxString&)wxStringBase::assign(n, ch); }
1189     // assign from first to last
1190   wxString& assign(const_iterator first, const_iterator last)
1191     { return (wxString&)wxStringBase::assign(first, last); }
1192
1193     // string comparison
1194 #ifndef HAVE_STD_STRING_COMPARE
1195   int compare(const wxStringBase& str) const;
1196     // comparison with a substring
1197   int compare(size_t nStart, size_t nLen, const wxStringBase& str) const;
1198     // comparison of 2 substrings
1199   int compare(size_t nStart, size_t nLen,
1200               const wxStringBase& str, size_t nStart2, size_t nLen2) const;
1201     // just like strcmp()
1202   int compare(const wxChar* sz) const;
1203     // substring comparison with first nCount characters of sz
1204   int compare(size_t nStart, size_t nLen,
1205               const wxChar* sz, size_t nCount = npos) const;
1206 #endif // !defined HAVE_STD_STRING_COMPARE
1207
1208     // insert another string
1209   wxString& insert(size_t nPos, const wxString& str)
1210     { return (wxString&)wxStringBase::insert(nPos, str); }
1211     // insert n chars of str starting at nStart (in str)
1212   wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n)
1213     { return (wxString&)wxStringBase::insert(nPos, str, nStart, n); }
1214     // insert first n (or all if n == npos) characters of sz
1215   wxString& insert(size_t nPos, const wxChar *sz)
1216     { return (wxString&)wxStringBase::insert(nPos, sz); }
1217   wxString& insert(size_t nPos, const wxChar *sz, size_t n)
1218     { return (wxString&)wxStringBase::insert(nPos, sz, n); }
1219     // insert n copies of ch
1220   wxString& insert(size_t nPos, size_t n, wxChar ch)
1221     { return (wxString&)wxStringBase::insert(nPos, n, ch); }
1222   iterator insert(iterator it, wxChar ch)
1223     { return wxStringBase::insert(it, ch); }
1224   void insert(iterator it, const_iterator first, const_iterator last)
1225     { wxStringBase::insert(it, first, last); }
1226   void insert(iterator it, size_type n, wxChar ch)
1227     { wxStringBase::insert(it, n, ch); }
1228
1229     // delete characters from nStart to nStart + nLen
1230   wxString& erase(size_type pos = 0, size_type n = npos)
1231     { return (wxString&)wxStringBase::erase(pos, n); }
1232   iterator erase(iterator first, iterator last)
1233     { return wxStringBase::erase(first, last); }
1234   iterator erase(iterator first)
1235     { return wxStringBase::erase(first); }
1236
1237 #ifdef wxSTRING_BASE_HASNT_CLEAR
1238   void clear() { erase(); }
1239 #endif
1240
1241     // replaces the substring of length nLen starting at nStart
1242   wxString& replace(size_t nStart, size_t nLen, const wxChar* sz)
1243     { return (wxString&)wxStringBase::replace(nStart, nLen, sz); }
1244     // replaces the substring of length nLen starting at nStart
1245   wxString& replace(size_t nStart, size_t nLen, const wxString& str)
1246     { return (wxString&)wxStringBase::replace(nStart, nLen, str); }
1247     // replaces the substring with nCount copies of ch
1248   wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxChar ch)
1249     { return (wxString&)wxStringBase::replace(nStart, nLen, nCount, ch); }
1250     // replaces a substring with another substring
1251   wxString& replace(size_t nStart, size_t nLen,
1252                     const wxString& str, size_t nStart2, size_t nLen2)
1253     { return (wxString&)wxStringBase::replace(nStart, nLen, str,
1254                                               nStart2, nLen2); }
1255      // replaces the substring with first nCount chars of sz
1256   wxString& replace(size_t nStart, size_t nLen,
1257                     const wxChar* sz, size_t nCount)
1258     { return (wxString&)wxStringBase::replace(nStart, nLen, sz, nCount); }
1259   wxString& replace(iterator first, iterator last, const_pointer s)
1260     { return (wxString&)wxStringBase::replace(first, last, s); }
1261   wxString& replace(iterator first, iterator last, const_pointer s,
1262                     size_type n)
1263     { return (wxString&)wxStringBase::replace(first, last, s, n); }
1264   wxString& replace(iterator first, iterator last, const wxString& s)
1265     { return (wxString&)wxStringBase::replace(first, last, s); }
1266   wxString& replace(iterator first, iterator last, size_type n, wxChar c)
1267     { return (wxString&)wxStringBase::replace(first, last, n, c); }
1268   wxString& replace(iterator first, iterator last,
1269                     const_iterator first1, const_iterator last1)
1270     { return (wxString&)wxStringBase::replace(first, last, first1, last1); }
1271
1272       // string += string
1273   wxString& operator+=(const wxString& s)
1274     { return (wxString&)wxStringBase::operator+=(s); }
1275       // string += C string
1276   wxString& operator+=(const wxChar *psz)
1277     { return (wxString&)wxStringBase::operator+=(psz); }
1278       // string += char
1279   wxString& operator+=(wxChar ch)
1280     { return (wxString&)wxStringBase::operator+=(ch); }
1281 };
1282
1283 // define wxArrayString, for compatibility
1284 #if WXWIN_COMPATIBILITY_2_4 && !wxUSE_STL
1285     #include "wx/arrstr.h"
1286 #endif
1287
1288 #if wxUSE_STL
1289     // return an empty wxString (not very useful with wxUSE_STL == 1)
1290     inline const wxString wxGetEmptyString() { wxString(); }
1291 #else // !wxUSE_STL
1292     // return an empty wxString (more efficient than wxString() here)
1293     inline const wxString& wxGetEmptyString()
1294     {
1295         return *(wxString *)&wxEmptyString;
1296     }
1297 #endif // wxUSE_STL/!wxUSE_STL
1298
1299 // ----------------------------------------------------------------------------
1300 // wxStringBuffer: a tiny class allowing to get a writable pointer into string
1301 // ----------------------------------------------------------------------------
1302
1303 #if wxUSE_STL
1304
1305 class WXDLLIMPEXP_BASE wxStringBuffer
1306 {
1307 public:
1308     wxStringBuffer(wxString& str, size_t lenWanted = 1024)
1309         : m_str(str), m_buf(lenWanted)
1310         { }
1311
1312     ~wxStringBuffer() { m_str.assign(m_buf.data(), wxStrlen(m_buf.data())); }
1313
1314     operator wxChar*() { return m_buf.data(); }
1315
1316 private:
1317     wxString& m_str;
1318 #if wxUSE_UNICODE
1319     wxWCharBuffer m_buf;
1320 #else
1321     wxCharBuffer m_buf;
1322 #endif
1323
1324     DECLARE_NO_COPY_CLASS(wxStringBuffer)
1325 };
1326
1327 class WXDLLIMPEXP_BASE wxStringBufferLength
1328 {
1329 public:
1330     wxStringBufferLength(wxString& str, size_t lenWanted = 1024)
1331         : m_str(str), m_buf(lenWanted), m_len(0), m_lenSet(false)
1332         { }
1333
1334     ~wxStringBufferLength()
1335     {
1336         wxASSERT(m_lenSet);
1337         m_str.assign(m_buf.data(), m_len);
1338     }
1339
1340     operator wxChar*() { return m_buf.data(); }
1341     void SetLength(size_t length) { m_len = length; m_lenSet = true; }
1342
1343 private:
1344     wxString& m_str;
1345 #if wxUSE_UNICODE
1346     wxWCharBuffer m_buf;
1347 #else
1348     wxCharBuffer  m_buf;
1349 #endif
1350     size_t        m_len;
1351     bool          m_lenSet;
1352
1353     DECLARE_NO_COPY_CLASS(wxStringBufferLength)
1354 };
1355
1356 #else // if !wxUSE_STL
1357
1358 class WXDLLIMPEXP_BASE wxStringBuffer
1359 {
1360 public:
1361     wxStringBuffer(wxString& str, size_t lenWanted = 1024)
1362         : m_str(str), m_buf(NULL)
1363         { m_buf = m_str.GetWriteBuf(lenWanted); }
1364
1365     ~wxStringBuffer() { m_str.UngetWriteBuf(); }
1366
1367     operator wxChar*() const { return m_buf; }
1368
1369 private:
1370     wxString& m_str;
1371     wxChar   *m_buf;
1372
1373     DECLARE_NO_COPY_CLASS(wxStringBuffer)
1374 };
1375
1376 class WXDLLIMPEXP_BASE wxStringBufferLength
1377 {
1378 public:
1379     wxStringBufferLength(wxString& str, size_t lenWanted = 1024)
1380         : m_str(str), m_buf(NULL), m_len(0), m_lenSet(false)
1381         { m_buf = m_str.GetWriteBuf(lenWanted); }
1382
1383     ~wxStringBufferLength()
1384     {
1385         wxASSERT(m_lenSet);
1386         m_str.UngetWriteBuf(m_len);
1387     }
1388
1389     operator wxChar*() const { return m_buf; }
1390     void SetLength(size_t length) { m_len = length; m_lenSet = true; }
1391
1392 private:
1393     wxString& m_str;
1394     wxChar   *m_buf;
1395     size_t    m_len;
1396     bool      m_lenSet;
1397
1398     DECLARE_NO_COPY_CLASS(wxStringBufferLength)
1399 };
1400
1401 #endif // !wxUSE_STL
1402
1403 // ---------------------------------------------------------------------------
1404 // wxString comparison functions: operator versions are always case sensitive
1405 // ---------------------------------------------------------------------------
1406
1407 #if wxUSE_STL
1408
1409 inline bool operator==(const wxString& s1, const wxString& s2)
1410     { return s1.compare(s2) == 0; }
1411 inline bool operator==(const wxString& s1, const wxChar  * s2)
1412     { return s1.compare(s2) == 0; }
1413 inline bool operator==(const wxChar  * s1, const wxString& s2)
1414     { return s2.compare(s1) == 0; }
1415 inline bool operator!=(const wxString& s1, const wxString& s2)
1416     { return s1.compare(s2) != 0; }
1417 inline bool operator!=(const wxString& s1, const wxChar  * s2)
1418     { return s1.compare(s2) != 0; }
1419 inline bool operator!=(const wxChar  * s1, const wxString& s2)
1420     { return s2.compare(s1) != 0; }
1421 inline bool operator< (const wxString& s1, const wxString& s2)
1422     { return s1.compare(s2) <  0; }
1423 inline bool operator< (const wxString& s1, const wxChar  * s2)
1424     { return s1.compare(s2) <  0; }
1425 inline bool operator< (const wxChar  * s1, const wxString& s2)
1426     { return s2.compare(s1) >  0; }
1427 inline bool operator> (const wxString& s1, const wxString& s2)
1428     { return s1.compare(s2) >  0; }
1429 inline bool operator> (const wxString& s1, const wxChar  * s2)
1430     { return s1.compare(s2) >  0; }
1431 inline bool operator> (const wxChar  * s1, const wxString& s2)
1432     { return s2.compare(s1) <  0; }
1433 inline bool operator<=(const wxString& s1, const wxString& s2)
1434     { return s1.compare(s2) <= 0; }
1435 inline bool operator<=(const wxString& s1, const wxChar  * s2)
1436     { return s1.compare(s2) <= 0; }
1437 inline bool operator<=(const wxChar  * s1, const wxString& s2)
1438     { return s2.compare(s1) >= 0; }
1439 inline bool operator>=(const wxString& s1, const wxString& s2)
1440     { return s1.compare(s2) >= 0; }
1441 inline bool operator>=(const wxString& s1, const wxChar  * s2)
1442     { return s1.compare(s2) >= 0; }
1443 inline bool operator>=(const wxChar  * s1, const wxString& s2)
1444     { return s2.compare(s1) <= 0; }
1445
1446 #else // if !wxUSE_STL
1447
1448 inline bool operator==(const wxString& s1, const wxString& s2)
1449     { return (s1.Len() == s2.Len()) && (s1.Cmp(s2) == 0); }
1450 inline bool operator==(const wxString& s1, const wxChar  * s2)
1451     { return s1.Cmp(s2) == 0; }
1452 inline bool operator==(const wxChar  * s1, const wxString& s2)
1453     { return s2.Cmp(s1) == 0; }
1454 inline bool operator!=(const wxString& s1, const wxString& s2)
1455     { return (s1.Len() != s2.Len()) || (s1.Cmp(s2) != 0); }
1456 inline bool operator!=(const wxString& s1, const wxChar  * s2)
1457     { return s1.Cmp(s2) != 0; }
1458 inline bool operator!=(const wxChar  * s1, const wxString& s2)
1459     { return s2.Cmp(s1) != 0; }
1460 inline bool operator< (const wxString& s1, const wxString& s2)
1461     { return s1.Cmp(s2) < 0; }
1462 inline bool operator< (const wxString& s1, const wxChar  * s2)
1463     { return s1.Cmp(s2) <  0; }
1464 inline bool operator< (const wxChar  * s1, const wxString& s2)
1465     { return s2.Cmp(s1) >  0; }
1466 inline bool operator> (const wxString& s1, const wxString& s2)
1467     { return s1.Cmp(s2) >  0; }
1468 inline bool operator> (const wxString& s1, const wxChar  * s2)
1469     { return s1.Cmp(s2) >  0; }
1470 inline bool operator> (const wxChar  * s1, const wxString& s2)
1471     { return s2.Cmp(s1) <  0; }
1472 inline bool operator<=(const wxString& s1, const wxString& s2)
1473     { return s1.Cmp(s2) <= 0; }
1474 inline bool operator<=(const wxString& s1, const wxChar  * s2)
1475     { return s1.Cmp(s2) <= 0; }
1476 inline bool operator<=(const wxChar  * s1, const wxString& s2)
1477     { return s2.Cmp(s1) >= 0; }
1478 inline bool operator>=(const wxString& s1, const wxString& s2)
1479     { return s1.Cmp(s2) >= 0; }
1480 inline bool operator>=(const wxString& s1, const wxChar  * s2)
1481     { return s1.Cmp(s2) >= 0; }
1482 inline bool operator>=(const wxChar  * s1, const wxString& s2)
1483     { return s2.Cmp(s1) <= 0; }
1484
1485 #endif // !wxUSE_STL
1486
1487 // comparison with char
1488 inline bool operator==(wxChar c, const wxString& s) { return s.IsSameAs(c); }
1489 inline bool operator==(const wxString& s, wxChar c) { return s.IsSameAs(c); }
1490 inline bool operator!=(wxChar c, const wxString& s) { return !s.IsSameAs(c); }
1491 inline bool operator!=(const wxString& s, wxChar c) { return !s.IsSameAs(c); }
1492
1493 #if wxUSE_UNICODE
1494 inline bool operator==(const wxString& s1, const wxWCharBuffer& s2)
1495     { return (s1.Cmp((const wchar_t *)s2) == 0); }
1496 inline bool operator==(const wxWCharBuffer& s1, const wxString& s2)
1497     { return (s2.Cmp((const wchar_t *)s1) == 0); }
1498 inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2)
1499     { return (s1.Cmp((const wchar_t *)s2) != 0); }
1500 inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2)
1501     { return (s2.Cmp((const wchar_t *)s1) != 0); }
1502 #else // !wxUSE_UNICODE
1503 inline bool operator==(const wxString& s1, const wxCharBuffer& s2)
1504     { return (s1.Cmp((const char *)s2) == 0); }
1505 inline bool operator==(const wxCharBuffer& s1, const wxString& s2)
1506     { return (s2.Cmp((const char *)s1) == 0); }
1507 inline bool operator!=(const wxString& s1, const wxCharBuffer& s2)
1508     { return (s1.Cmp((const char *)s2) != 0); }
1509 inline bool operator!=(const wxCharBuffer& s1, const wxString& s2)
1510     { return (s2.Cmp((const char *)s1) != 0); }
1511 #endif // wxUSE_UNICODE/!wxUSE_UNICODE
1512
1513 #if !wxUSE_STL
1514
1515 wxString WXDLLIMPEXP_BASE operator+(const wxString& string1,  const wxString& string2);
1516 wxString WXDLLIMPEXP_BASE operator+(const wxString& string, wxChar ch);
1517 wxString WXDLLIMPEXP_BASE operator+(wxChar ch, const wxString& string);
1518 wxString WXDLLIMPEXP_BASE operator+(const wxString& string, const wxChar *psz);
1519 wxString WXDLLIMPEXP_BASE operator+(const wxChar *psz, const wxString& string);
1520
1521 #endif // !wxUSE_STL
1522
1523 #if wxUSE_UNICODE
1524 inline wxString operator+(const wxString& string, const wxWCharBuffer& buf)
1525     { return string + (const wchar_t *)buf; }
1526 inline wxString operator+(const wxWCharBuffer& buf, const wxString& string)
1527     { return (const wchar_t *)buf + string; }
1528 #else // !wxUSE_UNICODE
1529 inline wxString operator+(const wxString& string, const wxCharBuffer& buf)
1530     { return string + (const char *)buf; }
1531 inline wxString operator+(const wxCharBuffer& buf, const wxString& string)
1532     { return (const char *)buf + string; }
1533 #endif // wxUSE_UNICODE/!wxUSE_UNICODE
1534
1535 // ---------------------------------------------------------------------------
1536 // Implementation only from here until the end of file
1537 // ---------------------------------------------------------------------------
1538
1539 // don't pollute the library user's name space
1540 #undef wxASSERT_VALID_INDEX
1541
1542 #if wxUSE_STD_IOSTREAM
1543
1544 #include "wx/iosfwrap.h"
1545
1546 WXDLLIMPEXP_BASE wxSTD istream& operator>>(wxSTD istream&, wxString&);
1547 WXDLLIMPEXP_BASE wxSTD ostream& operator<<(wxSTD ostream&, const wxString&);
1548
1549 #endif  // wxSTD_STRING_COMPATIBILITY
1550
1551 #endif  // _WX_WXSTRINGH__