include/wx/stringimpl.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/stringimpl.h
   3 // Purpose:     wxStringImpl class, implementation of wxString
   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 licence
  10 ///////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13     This header implements std::string-like string class, wxStringImpl, that is
  14     used by wxString to store the data. Alternatively, if wxUSE_STL=1,
  15     wxStringImpl is just a typedef to std:: string class.
  16 */
  17
  18 #ifndef _WX_WXSTRINGIMPL_H__
  19 #define _WX_WXSTRINGIMPL_H__
  20
  21 // ----------------------------------------------------------------------------
  22 // headers
  23 // ----------------------------------------------------------------------------
  24
  25 #include "wx/defs.h"        // everybody should include this
  26 #include "wx/wxchar.h"      // for wxChar, wxStrlen() etc.
  27
  28 // ---------------------------------------------------------------------------
  29 // macros
  30 // ---------------------------------------------------------------------------
  31
  32 // implementation only
  33 #define   wxASSERT_VALID_INDEX(i) \
  34     wxASSERT_MSG( (size_t)(i) <= length(), _T("invalid index in wxString") )
  35
  36
  37 // ----------------------------------------------------------------------------
  38 // global data
  39 // ----------------------------------------------------------------------------
  40
  41 // global pointer to empty string
  42 extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxEmptyString;
  43
  44
  45 // ----------------------------------------------------------------------------
  46 // deal with STL/non-STL/non-STL-but-wxUSE_STD_STRING
  47 // ----------------------------------------------------------------------------
  48
  49 #define wxUSE_STL_BASED_WXSTRING  wxUSE_STL
  50
  51 // in both cases we need to define wxStdString
  52 #if wxUSE_STL_BASED_WXSTRING || wxUSE_STD_STRING
  53
  54 #include "wx/beforestd.h"
  55 #include <string>
  56 #include "wx/afterstd.h"
  57
  58 #if wxUSE_UNICODE_WCHAR
  59     #ifdef HAVE_STD_WSTRING
  60         typedef std::wstring wxStdString;
  61     #else
  62         typedef std::basic_string<wxChar> wxStdString;
  63     #endif
  64 #else
  65     typedef std::string wxStdString;
  66 #endif
  67
  68 #endif // need <string>
  69
  70 #if wxUSE_STL_BASED_WXSTRING
  71
  72     // we always want ctor from std::string when using std::string internally
  73     #undef wxUSE_STD_STRING
  74     #define wxUSE_STD_STRING 1
  75
  76     #if (defined(__GNUG__) && (__GNUG__ < 3)) || \
  77         (defined(_MSC_VER) && (_MSC_VER <= 1200))
  78         #define wxSTRING_BASE_HASNT_CLEAR
  79     #endif
  80
  81     typedef wxStdString wxStringImpl;
  82 #else // if !wxUSE_STL_BASED_WXSTRING
  83
  84 // in non-STL mode, compare() is implemented in wxString and not wxStringImpl
  85 #undef HAVE_STD_STRING_COMPARE
  86
  87 // ---------------------------------------------------------------------------
  88 // string data prepended with some housekeeping info (used by wxString class),
  89 // is never used directly (but had to be put here to allow inlining)
  90 // ---------------------------------------------------------------------------
  91
  92 struct WXDLLIMPEXP_BASE wxStringData
  93 {
  94   int     nRefs;        // reference count
  95   size_t  nDataLength,  // actual string length
  96           nAllocLength; // allocated memory size
  97
  98   // mimics declaration 'wxChar data[nAllocLength]'
  99   wxChar* data() const { return (wxChar*)(this + 1); }
 100
 101   // empty string has a special ref count so it's never deleted
 102   bool  IsEmpty()   const { return (nRefs == -1); }
 103   bool  IsShared()  const { return (nRefs > 1);   }
 104
 105   // lock/unlock
 106   void  Lock()   { if ( !IsEmpty() ) nRefs++;                    }
 107
 108   // VC++ will refuse to inline Unlock but profiling shows that it is wrong
 109 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 110   __forceinline
 111 #endif
 112   // VC++ free must take place in same DLL as allocation when using non dll
 113   // run-time library (e.g. Multithreaded instead of Multithreaded DLL)
 114 #if defined(__VISUALC__) && defined(_MT) && !defined(_DLL)
 115   void  Unlock() { if ( !IsEmpty() && --nRefs == 0) Free();  }
 116   // we must not inline deallocation since allocation is not inlined
 117   void  Free();
 118 #else
 119   void  Unlock() { if ( !IsEmpty() && --nRefs == 0) free(this);  }
 120 #endif
 121
 122   // if we had taken control over string memory (GetWriteBuf), it's
 123   // intentionally put in invalid state
 124   void  Validate(bool b)  { nRefs = (b ? 1 : 0); }
 125   bool  IsValid() const   { return (nRefs != 0); }
 126 };
 127
 128 class WXDLLIMPEXP_BASE wxStringImpl
 129 {
 130 public:
 131   // an 'invalid' value for string index, moved to this place due to a CW bug
 132   static const size_t npos;
 133
 134 protected:
 135   // points to data preceded by wxStringData structure with ref count info
 136   wxStringCharType *m_pchData;
 137
 138   // accessor to string data
 139   wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
 140
 141   // string (re)initialization functions
 142     // initializes the string to the empty value (must be called only from
 143     // ctors, use Reinit() otherwise)
 144   void Init() { m_pchData = (wxStringCharType *)wxEmptyString; }
 145     // initializes the string with (a part of) C-string
 146   void InitWith(const wxStringCharType *psz, size_t nPos = 0, size_t nLen = npos);
 147     // as Init, but also frees old data
 148   void Reinit() { GetStringData()->Unlock(); Init(); }
 149
 150   // memory allocation
 151     // allocates memory for string of length nLen
 152   bool AllocBuffer(size_t nLen);
 153     // effectively copies data to string
 154   bool AssignCopy(size_t, const wxStringCharType *);
 155
 156   // append a (sub)string
 157   bool ConcatSelf(size_t nLen, const wxStringCharType *src, size_t nMaxLen);
 158   bool ConcatSelf(size_t nLen, const wxStringCharType *src)
 159     { return ConcatSelf(nLen, src, nLen); }
 160
 161   // functions called before writing to the string: they copy it if there
 162   // are other references to our data (should be the only owner when writing)
 163   bool CopyBeforeWrite();
 164   bool AllocBeforeWrite(size_t);
 165
 166     // compatibility with wxString
 167   bool Alloc(size_t nLen);
 168
 169 public:
 170   // standard types
 171   typedef wxStringCharType value_type;
 172   typedef wxStringCharType char_type;
 173   typedef size_t size_type;
 174   typedef value_type& reference;
 175   typedef const value_type& const_reference;
 176   typedef value_type* pointer;
 177   typedef const value_type* const_pointer;
 178   typedef value_type *iterator;
 179   typedef const value_type *const_iterator;
 180
 181   // constructors and destructor
 182     // ctor for an empty string
 183   wxStringImpl() { Init(); }
 184     // copy ctor
 185   wxStringImpl(const wxStringImpl& stringSrc)
 186   {
 187     wxASSERT_MSG( stringSrc.GetStringData()->IsValid(),
 188                   _T("did you forget to call UngetWriteBuf()?") );
 189
 190     if ( stringSrc.empty() ) {
 191       // nothing to do for an empty string
 192       Init();
 193     }
 194     else {
 195       m_pchData = stringSrc.m_pchData;            // share same data
 196       GetStringData()->Lock();                    // => one more copy
 197     }
 198   }
 199     // string containing nRepeat copies of ch
 200   wxStringImpl(size_type nRepeat, wxStringCharType ch);
 201     // ctor takes first nLength characters from C string
 202     // (default value of npos means take all the string)
 203   wxStringImpl(const wxStringCharType *psz)
 204       { InitWith(psz, 0, npos); }
 205   wxStringImpl(const wxStringCharType *psz, size_t nLength)
 206       { InitWith(psz, 0, nLength); }
 207     // take nLen chars starting at nPos
 208   wxStringImpl(const wxStringImpl& str, size_t nPos, size_t nLen)
 209   {
 210     wxASSERT_MSG( str.GetStringData()->IsValid(),
 211                   _T("did you forget to call UngetWriteBuf()?") );
 212     Init();
 213     size_t strLen = str.length() - nPos; nLen = strLen < nLen ? strLen : nLen;
 214     InitWith(str.c_str(), nPos, nLen);
 215   }
 216     // take all characters from pStart to pEnd
 217   wxStringImpl(const void *pStart, const void *pEnd);
 218
 219     // dtor is not virtual, this class must not be inherited from!
 220   ~wxStringImpl()
 221   {
 222 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 223       //RN - according to the above VC++ does indeed inline this,
 224       //even though it spits out two warnings
 225       #pragma warning (disable:4714)
 226 #endif
 227
 228       GetStringData()->Unlock();
 229   }
 230
 231 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
 232     //re-enable inlining warning
 233     #pragma warning (default:4714)
 234 #endif
 235   // overloaded assignment
 236     // from another wxString
 237   wxStringImpl& operator=(const wxStringImpl& stringSrc);
 238     // from a character
 239   wxStringImpl& operator=(wxStringCharType ch);
 240     // from a C string
 241   wxStringImpl& operator=(const wxStringCharType *psz);
 242
 243     // return the length of the string
 244   size_type length() const { return GetStringData()->nDataLength; }
 245     // return the length of the string
 246   size_type size() const { return length(); }
 247     // return the maximum size of the string
 248   size_type max_size() const { return npos; }
 249     // resize the string, filling the space with c if c != 0
 250   void resize(size_t nSize, wxStringCharType ch = '\0');
 251     // delete the contents of the string
 252   void clear() { erase(0, npos); }
 253     // returns true if the string is empty
 254   bool empty() const { return length() == 0; }
 255     // inform string about planned change in size
 256   void reserve(size_t sz) { Alloc(sz); }
 257   size_type capacity() const { return GetStringData()->nAllocLength; }
 258
 259   // lib.string.access
 260     // return the character at position n
 261   value_type at(size_type n) const
 262     { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
 263     // returns the writable character at position n
 264   reference at(size_type n)
 265   {
 266     wxASSERT_VALID_INDEX( n );
 267     CopyBeforeWrite();
 268     return m_pchData[n];
 269   } // FIXME-UTF8: not useful for us...?
 270
 271   // lib.string.modifiers
 272     // append elements str[pos], ..., str[pos+n]
 273   wxStringImpl& append(const wxStringImpl& str, size_t pos, size_t n)
 274   {
 275     wxASSERT(pos <= str.length());
 276     ConcatSelf(n, str.c_str() + pos, str.length() - pos);
 277     return *this;
 278   }
 279     // append a string
 280   wxStringImpl& append(const wxStringImpl& str)
 281     { ConcatSelf(str.length(), str.c_str()); return *this; }
 282     // append first n (or all if n == npos) characters of sz
 283   wxStringImpl& append(const wxStringCharType *sz)
 284     { ConcatSelf(wxStrlen(sz), sz); return *this; }
 285   wxStringImpl& append(const wxStringCharType *sz, size_t n)
 286     { ConcatSelf(n, sz); return *this; }
 287     // append n copies of ch
 288   wxStringImpl& append(size_t n, wxStringCharType ch);
 289     // append from first to last
 290   wxStringImpl& append(const_iterator first, const_iterator last)
 291     { ConcatSelf(last - first, first); return *this; }
 292
 293     // same as `this_string = str'
 294   wxStringImpl& assign(const wxStringImpl& str)
 295     { return *this = str; }
 296     // same as ` = str[pos..pos + n]
 297   wxStringImpl& assign(const wxStringImpl& str, size_t pos, size_t n)
 298     { clear(); return append(str, pos, n); }
 299     // same as `= first n (or all if n == npos) characters of sz'
 300   wxStringImpl& assign(const wxStringCharType *sz)
 301     { clear(); return append(sz, wxStrlen(sz)); }
 302   wxStringImpl& assign(const wxStringCharType *sz, size_t n)
 303     { clear(); return append(sz, n); }
 304     // same as `= n copies of ch'
 305   wxStringImpl& assign(size_t n, wxStringCharType ch)
 306     { clear(); return append(n, ch); }
 307     // assign from first to last
 308   wxStringImpl& assign(const_iterator first, const_iterator last)
 309     { clear(); return append(first, last); }
 310
 311     // first valid index position
 312   const_iterator begin() const { return m_pchData; }
 313   iterator begin();
 314     // position one after the last valid one
 315   const_iterator end() const { return m_pchData + length(); }
 316   iterator end();
 317
 318     // insert another string
 319   wxStringImpl& insert(size_t nPos, const wxStringImpl& str)
 320   {
 321     wxASSERT( str.GetStringData()->IsValid() );
 322     return insert(nPos, str.c_str(), str.length());
 323   }
 324     // insert n chars of str starting at nStart (in str)
 325   wxStringImpl& insert(size_t nPos, const wxStringImpl& str, size_t nStart, size_t n)
 326   {
 327     wxASSERT( str.GetStringData()->IsValid() );
 328     wxASSERT( nStart < str.length() );
 329     size_t strLen = str.length() - nStart;
 330     n = strLen < n ? strLen : n;
 331     return insert(nPos, str.c_str() + nStart, n);
 332   }
 333     // insert first n (or all if n == npos) characters of sz
 334   wxStringImpl& insert(size_t nPos, const wxStringCharType *sz, size_t n = npos);
 335     // insert n copies of ch
 336   wxStringImpl& insert(size_t nPos, size_t n, wxStringCharType ch)// FIXME-UTF8: tricky
 337     { return insert(nPos, wxStringImpl(n, ch)); }
 338   iterator insert(iterator it, wxStringCharType ch) // FIXME-UTF8: tricky
 339     { size_t idx = it - begin(); insert(idx, 1, ch); return begin() + idx; }
 340   void insert(iterator it, const_iterator first, const_iterator last)
 341     { insert(it - begin(), first, last - first); }
 342   void insert(iterator it, size_type n, wxStringCharType ch)
 343     { insert(it - begin(), n, ch); }
 344
 345     // delete characters from nStart to nStart + nLen
 346   wxStringImpl& erase(size_type pos = 0, size_type n = npos);
 347   iterator erase(iterator first, iterator last)
 348   {
 349     size_t idx = first - begin();
 350     erase(idx, last - first);
 351     return begin() + idx;
 352   }
 353   iterator erase(iterator first);
 354
 355   // explicit conversion to C string (use this with printf()!)
 356   const wxStringCharType* c_str() const { return m_pchData; }
 357   const wxStringCharType* data() const { return m_pchData; }
 358
 359     // replaces the substring of length nLen starting at nStart
 360   wxStringImpl& replace(size_t nStart, size_t nLen, const wxStringCharType* sz);
 361     // replaces the substring of length nLen starting at nStart
 362   wxStringImpl& replace(size_t nStart, size_t nLen, const wxStringImpl& str)
 363     { return replace(nStart, nLen, str.c_str()); }
 364     // replaces the substring with nCount copies of ch
 365   wxStringImpl& replace(size_t nStart, size_t nLen, size_t nCount, wxStringCharType ch);
 366     // replaces a substring with another substring
 367   wxStringImpl& replace(size_t nStart, size_t nLen,
 368                         const wxStringImpl& str, size_t nStart2, size_t nLen2);
 369     // replaces the substring with first nCount chars of sz
 370   wxStringImpl& replace(size_t nStart, size_t nLen,
 371                         const wxStringCharType* sz, size_t nCount);
 372   wxStringImpl& replace(iterator first, iterator last, const_pointer s)
 373     { return replace(first - begin(), last - first, s); }
 374   wxStringImpl& replace(iterator first, iterator last, const_pointer s,
 375                         size_type n)
 376     { return replace(first - begin(), last - first, s, n); }
 377   wxStringImpl& replace(iterator first, iterator last, const wxStringImpl& s)
 378     { return replace(first - begin(), last - first, s); }
 379   wxStringImpl& replace(iterator first, iterator last, size_type n, wxStringCharType c)
 380     { return replace(first - begin(), last - first, n, c); }
 381   wxStringImpl& replace(iterator first, iterator last,
 382                         const_iterator first1, const_iterator last1)
 383     { return replace(first - begin(), last - first, first1, last1 - first1); }
 384
 385     // swap two strings
 386   void swap(wxStringImpl& str);
 387
 388     // All find() functions take the nStart argument which specifies the
 389     // position to start the search on, the default value is 0. All functions
 390     // return npos if there were no match.
 391
 392     // find a substring
 393   size_t find(const wxStringImpl& str, size_t nStart = 0) const;
 394
 395     // find first n characters of sz
 396   size_t find(const wxStringCharType* sz, size_t nStart = 0, size_t n = npos) const;
 397
 398     // find the first occurence of character ch after nStart
 399   size_t find(wxStringCharType ch, size_t nStart = 0) const;
 400
 401     // rfind() family is exactly like find() but works right to left
 402
 403     // as find, but from the end
 404   size_t rfind(const wxStringImpl& str, size_t nStart = npos) const;
 405
 406     // as find, but from the end
 407   size_t rfind(const wxStringCharType* sz, size_t nStart = npos,
 408                size_t n = npos) const;
 409     // as find, but from the end
 410   size_t rfind(wxStringCharType ch, size_t nStart = npos) const;
 411
 412   size_type copy(wxStringCharType* s, size_type n, size_type pos = 0);
 413
 414   // substring extraction
 415   wxStringImpl substr(size_t nStart = 0, size_t nLen = npos) const;
 416
 417       // string += string
 418   wxStringImpl& operator+=(const wxStringImpl& s) { return append(s); }
 419       // string += C string
 420   wxStringImpl& operator+=(const wxStringCharType *psz) { return append(psz); }
 421       // string += char
 422   wxStringImpl& operator+=(wxStringCharType ch) { return append(1, ch); }
 423
 424 #if !wxUSE_UNICODE_UTF8
 425   // helpers for wxStringBuffer and wxStringBufferLength
 426   wxStringCharType *DoGetWriteBuf(size_t nLen);
 427   void DoUngetWriteBuf();
 428   void DoUngetWriteBuf(size_t nLen);
 429 #endif
 430
 431   friend class WXDLLIMPEXP_BASE wxString;
 432 };
 433
 434 #endif // !wxUSE_STL_BASED_WXSTRING
 435
 436 // don't pollute the library user's name space
 437 #undef wxASSERT_VALID_INDEX
 438
 439 #endif  // _WX_WXSTRINGIMPL_H__