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