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