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