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