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