include/wx/string.h

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