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