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