include/wx/string.h

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