include/wx/string.h

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