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 #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   //@}
 359
 360   // get writable buffer of at least nLen characters
 361   char *GetWriteBuf(size_t nLen);
 362
 363   /** @name wxWindows compatibility functions */
 364   //@{
 365     /// values for second parameter of CompareTo function
 366   enum caseCompare {exact, ignoreCase};
 367     /// values for first parameter of Strip function
 368   enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
 369     /// same as Printf()
 370   inline int sprintf(const char *pszFormat, ...)
 371   {
 372     va_list argptr;
 373     va_start(argptr, pszFormat);
 374     int iLen = PrintfV(pszFormat, argptr);
 375     va_end(argptr);
 376     return iLen;
 377   }
 378
 379     /// same as Cmp
 380   inline int CompareTo(const char* psz, caseCompare cmp = exact) const
 381   { return cmp == exact ? Cmp(psz) : CmpNoCase(psz); }
 382
 383     /// same as Mid (substring extraction)
 384   inline wxString  operator()(size_t start, size_t len) const { return Mid(start, len); }
 385
 386     /// same as += or <<
 387   inline wxString& Append(const char* psz) { return *this << psz; }
 388   inline wxString& Append(char ch, int count = 1) { wxString str(ch, count); (*this) += str; return *this; }
 389
 390     ///
 391   wxString& Prepend(const wxString& str) { *this = str + *this; return *this; }
 392     /// same as Len
 393   size_t Length() const { return Len(); }
 394     /// same as MakeLower
 395   void LowerCase() { MakeLower(); }
 396     /// same as MakeUpper
 397   void UpperCase() { MakeUpper(); }
 398     /// same as Trim except that it doesn't change this string
 399   wxString Strip(stripType w = trailing) const;
 400
 401     /// same as Find (more general variants not yet supported)
 402   size_t Index(const char* psz) const { return Find(psz); }
 403   size_t Index(char ch)         const { return Find(ch);  }
 404     /// same as Truncate
 405   wxString& Remove(size_t pos) { return Truncate(pos); }
 406   wxString& RemoveLast() { return Truncate(Len() - 1); }
 407
 408   // Robert Roebling
 409
 410   wxString& Remove(size_t nStart, size_t nLen) { return erase( nStart, nLen ); }
 411
 412   size_t First( const char ch ) const { return find(ch); }
 413   size_t First( const char* psz ) const { return find(psz); }
 414   size_t First( const wxString &str ) const { return find(str); }
 415
 416   size_t Last( const char ch ) const { return rfind(ch,0); }
 417   size_t Last( const char* psz ) const { return rfind(psz,0); }
 418   size_t Last( const wxString &str ) const { return rfind(str,0); }
 419
 420     /// same as IsEmpty
 421   bool IsNull() const { return IsEmpty(); }
 422   //@}
 423
 424 #ifdef  STD_STRING_COMPATIBILITY
 425   /** @name std::string compatibility functions */
 426
 427   /// an 'invalid' value for string index
 428   static const size_t npos;
 429
 430   //@{
 431     /** @name constructors */
 432     //@{
 433       /// take nLen chars starting at nPos
 434       wxString(const wxString& s, size_t nPos, size_t nLen = npos);
 435       /// take all characters from pStart to pEnd
 436       wxString(const void *pStart, const void *pEnd);
 437     //@}
 438     /** @name lib.string.capacity */
 439     //@{
 440       /// return the length of the string
 441       size_t size() const { return Len(); }
 442       /// return the length of the string
 443       size_t length() const { return Len(); }
 444       /// return the maximum size of the string
 445       size_t max_size() const { return STRING_MAXLEN; }
 446       /// resize the string, filling the space with c if c != 0
 447       void resize(size_t nSize, char ch = '\0');
 448       /// delete the contents of the string
 449       void clear() { Empty(); }
 450       /// returns true if the string is empty
 451       bool empty() const { return IsEmpty(); }
 452     //@}
 453     /** @name lib.string.access */
 454     //@{
 455       /// return the character at position n
 456       char at(size_t n) const { return GetChar(n); }
 457       /// returns the writable character at position n
 458       char& at(size_t n) { return GetWritableChar(n); }
 459     //@}
 460     /** @name lib.string.modifiers */
 461     //@{
 462       /** @name append something to the end of this one */
 463       //@{
 464         /// append a string
 465         wxString& append(const wxString& str)
 466           { *this += str; return *this; }
 467         /// append elements str[pos], ..., str[pos+n]
 468         wxString& append(const wxString& str, size_t pos, size_t n)
 469           { ConcatSelf(n, str.c_str() + pos); return *this; }
 470         /// append first n (or all if n == npos) characters of sz
 471         wxString& append(const char *sz, size_t n = npos)
 472           { ConcatSelf(n == npos ? Strlen(sz) : n, sz); return *this; }
 473
 474         /// append n copies of ch
 475         wxString& append(size_t n, char ch) { return Pad(n, ch); }
 476       //@}
 477
 478       /** @name replaces the contents of this string with another one */
 479       //@{
 480         /// same as `this_string = str'
 481         wxString& assign(const wxString& str) { return (*this) = str; }
 482         /// same as ` = str[pos..pos + n]
 483         wxString& assign(const wxString& str, size_t pos, size_t n)
 484           { return *this = wxString((const char *)str + pos, n); }
 485         /// same as `= first n (or all if n == npos) characters of sz'
 486         wxString& assign(const char *sz, size_t n = npos)
 487           { return *this = wxString(sz, n); }
 488         /// same as `= n copies of ch'
 489         wxString& assign(size_t n, char ch)
 490           { return *this = wxString(ch, n); }
 491
 492       //@}
 493
 494       /** @name inserts something at position nPos into this one */
 495       //@{
 496         /// insert another string
 497         wxString& insert(size_t nPos, const wxString& str);
 498         /// insert n chars of str starting at nStart (in str)
 499         wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n)
 500                     { return insert(nPos, wxString((const char *)str + nStart, n)); }
 501
 502         /// insert first n (or all if n == npos) characters of sz
 503         wxString& insert(size_t nPos, const char *sz, size_t n = npos)
 504           { return insert(nPos, wxString(sz, n)); }
 505         /// insert n copies of ch
 506         wxString& insert(size_t nPos, size_t n, char ch)
 507           { return insert(nPos, wxString(ch, n)); }
 508
 509       //@}
 510
 511       /** @name deletes a part of the string */
 512       //@{
 513         /// delete characters from nStart to nStart + nLen
 514         wxString& erase(size_t nStart = 0, size_t nLen = npos);
 515       //@}
 516
 517       /** @name replaces a substring of this string with another one */
 518       //@{
 519          /// replaces the substring of length nLen starting at nStart
 520          wxString& replace(size_t nStart, size_t nLen, const char* sz);
 521          /// replaces the substring with nCount copies of ch
 522          wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
 523          /// replaces a substring with another substring
 524          wxString& replace(size_t nStart, size_t nLen,
 525                          const wxString& str, size_t nStart2, size_t nLen2);
 526          /// replaces the substring with first nCount chars of sz
 527          wxString& replace(size_t nStart, size_t nLen,
 528                          const char* sz, size_t nCount);
 529       //@}
 530     //@}
 531
 532     /// swap two strings
 533     void swap(wxString& str);
 534
 535     /** @name string operations */
 536     //@{
 537       /** All find() functions take the nStart argument which specifies
 538           the position to start the search on, the default value is 0.
 539
 540           All functions return npos if there were no match.
 541
 542           @name string search
 543       */
 544       //@{
 545         /**
 546             @name find a match for the string/character in this string
 547         */
 548         //@{
 549           /// find a substring
 550           size_t find(const wxString& str, size_t nStart = 0) const;
 551
 552           // VC++ 1.5 can't cope with this syntax.
 553 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 554           /// find first n characters of sz
 555           size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
 556 #endif
 557           /// find the first occurence of character ch after nStart
 558           size_t find(char ch, size_t nStart = 0) const;
 559
 560                   // wxWin compatibility
 561                   inline bool Contains(const wxString& str) { return (Find(str) != -1); }
 562
 563         //@}
 564
 565         /**
 566           @name rfind() family is exactly like find() but works right to left
 567         */
 568         //@{
 569         /// as find, but from the end
 570         size_t rfind(const wxString& str, size_t nStart = npos) const;
 571         /// as find, but from the end
 572         // VC++ 1.5 can't cope with this syntax.
 573 #if ! (defined(_MSC_VER) && !defined(__WIN32__))
 574         size_t rfind(const char* sz, size_t nStart = npos,
 575                      size_t n = npos) const;
 576         /// as find, but from the end
 577         size_t rfind(char ch, size_t nStart = npos) const;
 578 #endif
 579         //@}
 580
 581         /**
 582           @name find first/last occurence of any character in the set
 583         */
 584         //@{
 585           ///
 586           size_t find_first_of(const wxString& str, size_t nStart = 0) const;
 587           ///
 588           size_t find_first_of(const char* sz, size_t nStart = 0) const;
 589           /// same as find(char, size_t)
 590           size_t find_first_of(char c, size_t nStart = 0) const;
 591
 592           ///
 593           size_t find_last_of (const wxString& str, size_t nStart = npos) const;
 594           ///
 595           size_t find_last_of (const char* s, size_t nStart = npos) const;
 596           /// same as rfind(char, size_t)
 597           size_t find_last_of (char c, size_t nStart = npos) const;
 598         //@}
 599
 600         /**
 601           @name find first/last occurence of any character not in the set
 602         */
 603         //@{
 604           ///
 605           size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
 606           ///
 607           size_t find_first_not_of(const char* s, size_t nStart = 0) const;
 608           ///
 609           size_t find_first_not_of(char ch, size_t nStart = 0) const;
 610
 611           ///
 612           size_t find_last_not_of(const wxString& str, size_t nStart=npos) const;
 613           ///
 614           size_t find_last_not_of(const char* s, size_t nStart = npos) const;
 615           ///
 616           size_t find_last_not_of(char ch, size_t nStart = npos) const;
 617         //@}
 618       //@}
 619
 620       /**
 621         All compare functions return -1, 0 or 1 if the [sub]string
 622         is less, equal or greater than the compare() argument.
 623
 624         @name comparison
 625       */
 626       //@{
 627         /// just like strcmp()
 628         int compare(const wxString& str) const { return Cmp(str); }
 629         /// comparaison with a substring
 630         int compare(size_t nStart, size_t nLen, const wxString& str) const;
 631         /// comparaison of 2 substrings
 632         int compare(size_t nStart, size_t nLen,
 633                     const wxString& str, size_t nStart2, size_t nLen2) const;
 634         /// just like strcmp()
 635         int compare(const char* sz) const { return Cmp(sz); }
 636         /// substring comparaison with first nCount characters of sz
 637         int compare(size_t nStart, size_t nLen,
 638                     const char* sz, size_t nCount = npos) const;
 639       //@}
 640     wxString substr(size_t nStart = 0, size_t nLen = npos) const;
 641   //@}
 642 #endif
 643
 644 protected:
 645   // points to data preceded by wxStringData structure with ref count info
 646   char *m_pchData;
 647
 648   // accessor to string data
 649   wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
 650
 651   // string (re)initialization functions
 652     // initializes the string to the empty value (must be called only from
 653     // ctors, use Reinit() otherwise)
 654   void Init() { m_pchData = (char *)g_szNul; }
 655     // initializaes the string with (a part of) C-string
 656   void InitWith(const char *psz, size_t nPos = 0, size_t nLen = STRING_MAXLEN);
 657     // as Init, but also frees old data
 658   inline void Reinit();
 659
 660   // memory allocation
 661     // allocates memory for string of lenght nLen
 662   void AllocBuffer(size_t nLen);
 663     // copies data to another string
 664   void AllocCopy(wxString&, int, int) const;
 665     // effectively copies data to string
 666   void AssignCopy(size_t, const char *);
 667
 668   // append a (sub)string
 669   void ConcatCopy(int nLen1, const char *src1, int nLen2, const char *src2);
 670   void ConcatSelf(int nLen, const char *src);
 671
 672   // functions called before writing to the string: they copy it if there
 673   // other references (should be the only owner when writing)
 674   void CopyBeforeWrite();
 675   void AllocBeforeWrite(size_t);
 676 };
 677
 678 // ----------------------------------------------------------------------------
 679 /** The string array uses it's knowledge of internal structure of the String
 680     class to optimize string storage. Normally, we would store pointers to
 681     string, but as String is, in fact, itself a pointer (sizeof(String) is
 682     sizeof(char *)) we store these pointers instead. The cast to "String *"
 683     is really all we need to turn such pointer into a string!
 684
 685     Of course, it can be called a dirty hack, but we use twice less memory
 686     and this approach is also more speed efficient, so it's probably worth it.
 687
 688     Usage notes: when a string is added/inserted, a new copy of it is created,
 689     so the original string may be safely deleted. When a string is retrieved
 690     from the array (operator[] or Item() method), a reference is returned.
 691
 692     @name wxArrayString
 693     @memo probably the most commonly used array type - array of strings
 694  */
 695 // ----------------------------------------------------------------------------
 696 class wxArrayString
 697 {
 698 public:
 699   /** @name ctors and dtor */
 700   //@{
 701     /// default ctor
 702   wxArrayString();
 703     /// copy ctor
 704   wxArrayString(const wxArrayString& array);
 705     /// assignment operator
 706   wxArrayString& operator=(const wxArrayString& src);
 707     /// not virtual, this class can't be derived from
 708  ~wxArrayString();
 709   //@}
 710
 711   /** @name memory management */
 712   //@{
 713     /// empties the list, but doesn't release memory
 714   void Empty();
 715     /// empties the list and releases memory
 716   void Clear();
 717     /// preallocates memory for given number of items
 718   void Alloc(size_t nCount);
 719   //@}
 720
 721   /** @name simple accessors */
 722   //@{
 723     /// number of elements in the array
 724   uint  Count() const   { return m_nCount;      }
 725     /// is it empty?
 726   bool  IsEmpty() const { return m_nCount == 0; }
 727   //@}
 728
 729   /** @name items access (range checking is done in debug version) */
 730   //@{
 731     /// get item at position uiIndex
 732   wxString& Item(size_t nIndex) const
 733     { wxASSERT( nIndex < m_nCount ); return *(wxString *)&(m_pItems[nIndex]); }
 734     /// same as Item()
 735   wxString& operator[](size_t nIndex) const { return Item(nIndex); }
 736     /// get last item
 737   wxString& Last() const { wxASSERT( !IsEmpty() ); return Item(Count() - 1); }
 738   //@}
 739
 740   /** @name item management */
 741   //@{
 742     /**
 743       Search the element in the array, starting from the either side
 744       @param if bFromEnd reverse search direction
 745       @param if bCase, comparaison is case sensitive (default)
 746       @return index of the first item matched or NOT_FOUND
 747       @see NOT_FOUND
 748      */
 749   int  Index (const char *sz, bool bCase = TRUE, bool bFromEnd = FALSE) const;
 750     /// add new element at the end
 751   void Add   (const wxString& str);
 752     /// add new element at given position
 753   void Insert(const wxString& str, uint uiIndex);
 754     /// remove first item matching this value
 755   void Remove(const char *sz);
 756     /// remove item by index
 757   void Remove(size_t nIndex);
 758   //@}
 759
 760   /// sort array elements
 761   void Sort(bool bCase = TRUE, bool bReverse = FALSE);
 762
 763 private:
 764   void    Grow();     // makes array bigger if needed
 765   void    Free();     // free the string stored
 766
 767   size_t  m_nSize,    // current size of the array
 768           m_nCount;   // current number of elements
 769
 770   char  **m_pItems;   // pointer to data
 771 };
 772
 773 // ---------------------------------------------------------------------------
 774 // implementation of inline functions
 775 // ---------------------------------------------------------------------------
 776
 777 // Put back into class, since BC++ can't create precompiled header otherwise
 778
 779 // ---------------------------------------------------------------------------
 780 /** @name wxString comparaison functions
 781     @memo Comparaisons are case sensitive
 782  */
 783 // ---------------------------------------------------------------------------
 784 //@{
 785 inline bool operator==(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) == 0; }
 786 ///
 787 inline bool operator==(const wxString& s1, const char  * s2) { return s1.Cmp(s2) == 0; }
 788 ///
 789 inline bool operator==(const char  * s1, const wxString& s2) { return s2.Cmp(s1) == 0; }
 790 ///
 791 inline bool operator!=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) != 0; }
 792 ///
 793 inline bool operator!=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) != 0; }
 794 ///
 795 inline bool operator!=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) != 0; }
 796 ///
 797 inline bool operator< (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <  0; }
 798 ///
 799 inline bool operator< (const wxString& s1, const char  * s2) { return s1.Cmp(s2) <  0; }
 800 ///
 801 inline bool operator< (const char  * s1, const wxString& s2) { return s2.Cmp(s1) >  0; }
 802 ///
 803 inline bool operator> (const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >  0; }
 804 ///
 805 inline bool operator> (const wxString& s1, const char  * s2) { return s1.Cmp(s2) >  0; }
 806 ///
 807 inline bool operator> (const char  * s1, const wxString& s2) { return s2.Cmp(s1) <  0; }
 808 ///
 809 inline bool operator<=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) <= 0; }
 810 ///
 811 inline bool operator<=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) <= 0; }
 812 ///
 813 inline bool operator<=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) >= 0; }
 814 ///
 815 inline bool operator>=(const wxString& s1, const wxString& s2) { return s1.Cmp(s2) >= 0; }
 816 ///
 817 inline bool operator>=(const wxString& s1, const char  * s2) { return s1.Cmp(s2) >= 0; }
 818 ///
 819 inline bool operator>=(const char  * s1, const wxString& s2) { return s2.Cmp(s1) <= 0; }
 820 //@}
 821
 822 // ---------------------------------------------------------------------------
 823 /** @name Global functions complementing standard C string library
 824     @memo replacements for strlen() and portable strcasecmp()
 825  */
 826 // ---------------------------------------------------------------------------
 827
 828 #ifdef  STD_STRING_COMPATIBILITY
 829
 830 // fwd decl
 831 class WXDLLEXPORT istream;
 832
 833 istream& WXDLLEXPORT operator>>(istream& is, wxString& str);
 834
 835 #endif  //std::string compatibility
 836
 837 #endif  // __WXSTRINGH__
 838
 839 //@}