include/wx/string.h

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