Document domain parameter of wxTranslations::GetTranslatedString().
[wxWidgets.git] / 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 // Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
8 // Licence: wxWindows licence
9 ///////////////////////////////////////////////////////////////////////////////
10
11 /*
12 This header implements std::string-like string class, wxStringImpl, that is
13 used by wxString to store the data. Alternatively, if wxUSE_STD_STRING=1,
14 wxStringImpl is just a typedef to std:: string class.
15 */
16
17 #ifndef _WX_WXSTRINGIMPL_H__
18 #define _WX_WXSTRINGIMPL_H__
19
20 // ----------------------------------------------------------------------------
21 // headers
22 // ----------------------------------------------------------------------------
23
24 #include "wx/defs.h" // everybody should include this
25 #include "wx/chartype.h" // for wxChar
26 #include "wx/wxcrtbase.h" // for wxStrlen() etc.
27
28 #include <stdlib.h>
29
30 // ---------------------------------------------------------------------------
31 // macros
32 // ---------------------------------------------------------------------------
33
34 // implementation only
35 #define wxASSERT_VALID_INDEX(i) \
36 wxASSERT_MSG( (size_t)(i) <= length(), wxT("invalid index in wxString") )
37
38
39 // ----------------------------------------------------------------------------
40 // global data
41 // ----------------------------------------------------------------------------
42
43 // global pointer to empty string
44 extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxEmptyString;
45 #if wxUSE_UNICODE_UTF8
46 // FIXME-UTF8: we should have only one wxEmptyString
47 extern WXDLLIMPEXP_DATA_BASE(const wxStringCharType*) wxEmptyStringImpl;
48 #endif
49
50
51 // ----------------------------------------------------------------------------
52 // deal with various build options
53 // ----------------------------------------------------------------------------
54
55 // we use STL-based string internally if we use std::string at all now, there
56 // should be no reason to prefer our internal implement but if you really need
57 // it you can predefine wxUSE_STL_BASED_WXSTRING as 0 when building the library
58 #ifndef wxUSE_STL_BASED_WXSTRING
59 #define wxUSE_STL_BASED_WXSTRING wxUSE_STD_STRING
60 #endif
61
62 // in both cases we need to define wxStdString
63 #if wxUSE_STL_BASED_WXSTRING || wxUSE_STD_STRING
64
65 #include "wx/beforestd.h"
66 #include <string>
67 #include "wx/afterstd.h"
68
69 #ifdef HAVE_STD_WSTRING
70 typedef std::wstring wxStdWideString;
71 #else
72 typedef std::basic_string<wchar_t> wxStdWideString;
73 #endif
74
75 #if wxUSE_UNICODE_WCHAR
76 typedef wxStdWideString wxStdString;
77 #else
78 typedef std::string wxStdString;
79 #endif
80
81 #endif // wxUSE_STL_BASED_WXSTRING || wxUSE_STD_STRING
82
83
84 #if wxUSE_STL_BASED_WXSTRING
85
86 // we always want ctor from std::string when using std::string internally
87 #undef wxUSE_STD_STRING
88 #define wxUSE_STD_STRING 1
89
90 // the versions of std::string included with gcc 2.95 and VC6 (for which
91 // _MSC_VER == 1200) and eVC4 (_MSC_VER == 1201) lack clear() method
92 #if (defined(__GNUG__) && (__GNUG__ < 3)) || \
93 !wxCHECK_VISUALC_VERSION(7) || defined(__EVC4__)
94 #define wxSTRING_BASE_HASNT_CLEAR
95 #endif
96
97 typedef wxStdString wxStringImpl;
98 #else // if !wxUSE_STL_BASED_WXSTRING
99
100 // in non-STL mode, compare() is implemented in wxString and not wxStringImpl
101 #undef HAVE_STD_STRING_COMPARE
102
103 // ---------------------------------------------------------------------------
104 // string data prepended with some housekeeping info (used by wxString class),
105 // is never used directly (but had to be put here to allow inlining)
106 // ---------------------------------------------------------------------------
107
108 struct WXDLLIMPEXP_BASE wxStringData
109 {
110 int nRefs; // reference count
111 size_t nDataLength, // actual string length
112 nAllocLength; // allocated memory size
113
114 // mimics declaration 'wxStringCharType data[nAllocLength]'
115 wxStringCharType* data() const { return (wxStringCharType*)(this + 1); }
116
117 // empty string has a special ref count so it's never deleted
118 bool IsEmpty() const { return (nRefs == -1); }
119 bool IsShared() const { return (nRefs > 1); }
120
121 // lock/unlock
122 void Lock() { if ( !IsEmpty() ) nRefs++; }
123
124 // VC++ will refuse to inline Unlock but profiling shows that it is wrong
125 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
126 __forceinline
127 #endif
128 // VC++ free must take place in same DLL as allocation when using non dll
129 // run-time library (e.g. Multithreaded instead of Multithreaded DLL)
130 #if defined(__VISUALC__) && defined(_MT) && !defined(_DLL)
131 void Unlock() { if ( !IsEmpty() && --nRefs == 0) Free(); }
132 // we must not inline deallocation since allocation is not inlined
133 void Free();
134 #else
135 void Unlock() { if ( !IsEmpty() && --nRefs == 0) free(this); }
136 #endif
137
138 // if we had taken control over string memory (GetWriteBuf), it's
139 // intentionally put in invalid state
140 void Validate(bool b) { nRefs = (b ? 1 : 0); }
141 bool IsValid() const { return (nRefs != 0); }
142 };
143
144 class WXDLLIMPEXP_BASE wxStringImpl
145 {
146 public:
147 // an 'invalid' value for string index, moved to this place due to a CW bug
148 static const size_t npos;
149
150 protected:
151 // points to data preceded by wxStringData structure with ref count info
152 wxStringCharType *m_pchData;
153
154 // accessor to string data
155 wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
156
157 // string (re)initialization functions
158 // initializes the string to the empty value (must be called only from
159 // ctors, use Reinit() otherwise)
160 #if wxUSE_UNICODE_UTF8
161 void Init() { m_pchData = (wxStringCharType *)wxEmptyStringImpl; } // FIXME-UTF8
162 #else
163 void Init() { m_pchData = (wxStringCharType *)wxEmptyString; }
164 #endif
165 // initializes the string with (a part of) C-string
166 void InitWith(const wxStringCharType *psz, size_t nPos = 0, size_t nLen = npos);
167 // as Init, but also frees old data
168 void Reinit() { GetStringData()->Unlock(); Init(); }
169
170 // memory allocation
171 // allocates memory for string of length nLen
172 bool AllocBuffer(size_t nLen);
173 // effectively copies data to string
174 bool AssignCopy(size_t, const wxStringCharType *);
175
176 // append a (sub)string
177 bool ConcatSelf(size_t nLen, const wxStringCharType *src, size_t nMaxLen);
178 bool ConcatSelf(size_t nLen, const wxStringCharType *src)
179 { return ConcatSelf(nLen, src, nLen); }
180
181 // functions called before writing to the string: they copy it if there
182 // are other references to our data (should be the only owner when writing)
183 bool CopyBeforeWrite();
184 bool AllocBeforeWrite(size_t);
185
186 // compatibility with wxString
187 bool Alloc(size_t nLen);
188
189 public:
190 // standard types
191 typedef wxStringCharType value_type;
192 typedef wxStringCharType char_type;
193 typedef size_t size_type;
194 typedef value_type& reference;
195 typedef const value_type& const_reference;
196 typedef value_type* pointer;
197 typedef const value_type* const_pointer;
198
199 // macro to define the bulk of iterator and const_iterator classes
200 #define WX_DEFINE_STRINGIMPL_ITERATOR(iterator_name, ref_type, ptr_type) \
201 public: \
202 typedef wxStringCharType value_type; \
203 typedef ref_type reference; \
204 typedef ptr_type pointer; \
205 typedef int difference_type; \
206 \
207 iterator_name() : m_ptr(NULL) { } \
208 iterator_name(pointer ptr) : m_ptr(ptr) { } \
209 \
210 reference operator*() const { return *m_ptr; } \
211 \
212 iterator_name& operator++() { m_ptr++; return *this; } \
213 iterator_name operator++(int) \
214 { \
215 const iterator_name tmp(*this); \
216 m_ptr++; \
217 return tmp; \
218 } \
219 \
220 iterator_name& operator--() { m_ptr--; return *this; } \
221 iterator_name operator--(int) \
222 { \
223 const iterator_name tmp(*this); \
224 m_ptr--; \
225 return tmp; \
226 } \
227 \
228 iterator_name operator+(ptrdiff_t n) const \
229 { return iterator_name(m_ptr + n); } \
230 iterator_name operator-(ptrdiff_t n) const \
231 { return iterator_name(m_ptr - n); } \
232 iterator_name& operator+=(ptrdiff_t n) \
233 { m_ptr += n; return *this; } \
234 iterator_name& operator-=(ptrdiff_t n) \
235 { m_ptr -= n; return *this; } \
236 \
237 difference_type operator-(const iterator_name& i) const \
238 { return m_ptr - i.m_ptr; } \
239 \
240 bool operator==(const iterator_name& i) const \
241 { return m_ptr == i.m_ptr; } \
242 bool operator!=(const iterator_name& i) const \
243 { return m_ptr != i.m_ptr; } \
244 \
245 bool operator<(const iterator_name& i) const \
246 { return m_ptr < i.m_ptr; } \
247 bool operator>(const iterator_name& i) const \
248 { return m_ptr > i.m_ptr; } \
249 bool operator<=(const iterator_name& i) const \
250 { return m_ptr <= i.m_ptr; } \
251 bool operator>=(const iterator_name& i) const \
252 { return m_ptr >= i.m_ptr; } \
253 \
254 private: \
255 /* for wxStringImpl use only */ \
256 pointer GetPtr() const { return m_ptr; } \
257 \
258 friend class wxStringImpl; \
259 \
260 pointer m_ptr
261
262 // we need to declare const_iterator in wxStringImpl scope, the friend
263 // declaration inside iterator class itself is not enough, or at least not
264 // for g++ 3.4 (g++ 4 is ok)
265 class WXDLLIMPEXP_FWD_BASE const_iterator;
266
267 class WXDLLIMPEXP_BASE iterator
268 {
269 WX_DEFINE_STRINGIMPL_ITERATOR(iterator,
270 wxStringCharType&,
271 wxStringCharType*);
272
273 friend class const_iterator;
274 };
275
276 class WXDLLIMPEXP_BASE const_iterator
277 {
278 public:
279 const_iterator(iterator i) : m_ptr(i.m_ptr) { }
280
281 WX_DEFINE_STRINGIMPL_ITERATOR(const_iterator,
282 const wxStringCharType&,
283 const wxStringCharType*);
284 };
285
286 #undef WX_DEFINE_STRINGIMPL_ITERATOR
287
288
289 // constructors and destructor
290 // ctor for an empty string
291 wxStringImpl() { Init(); }
292 // copy ctor
293 wxStringImpl(const wxStringImpl& stringSrc)
294 {
295 wxASSERT_MSG( stringSrc.GetStringData()->IsValid(),
296 wxT("did you forget to call UngetWriteBuf()?") );
297
298 if ( stringSrc.empty() ) {
299 // nothing to do for an empty string
300 Init();
301 }
302 else {
303 m_pchData = stringSrc.m_pchData; // share same data
304 GetStringData()->Lock(); // => one more copy
305 }
306 }
307 // string containing nRepeat copies of ch
308 wxStringImpl(size_type nRepeat, wxStringCharType ch);
309 // ctor takes first nLength characters from C string
310 // (default value of npos means take all the string)
311 wxStringImpl(const wxStringCharType *psz)
312 { InitWith(psz, 0, npos); }
313 wxStringImpl(const wxStringCharType *psz, size_t nLength)
314 { InitWith(psz, 0, nLength); }
315 // take nLen chars starting at nPos
316 wxStringImpl(const wxStringImpl& str, size_t nPos, size_t nLen)
317 {
318 wxASSERT_MSG( str.GetStringData()->IsValid(),
319 wxT("did you forget to call UngetWriteBuf()?") );
320 Init();
321 size_t strLen = str.length() - nPos; nLen = strLen < nLen ? strLen : nLen;
322 InitWith(str.c_str(), nPos, nLen);
323 }
324 // take everything between start and end
325 wxStringImpl(const_iterator start, const_iterator end);
326
327
328 // ctor from and conversion to std::string
329 #if wxUSE_STD_STRING
330 wxStringImpl(const wxStdString& impl)
331 { InitWith(impl.c_str(), 0, impl.length()); }
332
333 operator wxStdString() const
334 { return wxStdString(c_str(), length()); }
335 #endif
336
337 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
338 // disable warning about Unlock() below not being inlined (first, it
339 // seems to be inlined nevertheless and second, even if it isn't, there
340 // is nothing we can do about this
341 #pragma warning(push)
342 #pragma warning (disable:4714)
343 #endif
344
345 // dtor is not virtual, this class must not be inherited from!
346 ~wxStringImpl()
347 {
348 GetStringData()->Unlock();
349 }
350
351 #if defined(__VISUALC__) && (__VISUALC__ >= 1200)
352 #pragma warning(pop)
353 #endif
354
355 // overloaded assignment
356 // from another wxString
357 wxStringImpl& operator=(const wxStringImpl& stringSrc);
358 // from a character
359 wxStringImpl& operator=(wxStringCharType ch);
360 // from a C string
361 wxStringImpl& operator=(const wxStringCharType *psz);
362
363 // return the length of the string
364 size_type length() const { return GetStringData()->nDataLength; }
365 // return the length of the string
366 size_type size() const { return length(); }
367 // return the maximum size of the string
368 size_type max_size() const { return npos; }
369 // resize the string, filling the space with c if c != 0
370 void resize(size_t nSize, wxStringCharType ch = '\0');
371 // delete the contents of the string
372 void clear() { erase(0, npos); }
373 // returns true if the string is empty
374 bool empty() const { return length() == 0; }
375 // inform string about planned change in size
376 void reserve(size_t sz) { Alloc(sz); }
377 size_type capacity() const { return GetStringData()->nAllocLength; }
378
379 // lib.string.access
380 // return the character at position n
381 value_type operator[](size_type n) const { return m_pchData[n]; }
382 value_type at(size_type n) const
383 { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
384 // returns the writable character at position n
385 reference operator[](size_type n) { CopyBeforeWrite(); return m_pchData[n]; }
386 reference at(size_type n)
387 {
388 wxASSERT_VALID_INDEX( n );
389 CopyBeforeWrite();
390 return m_pchData[n];
391 } // FIXME-UTF8: not useful for us...?
392
393 // lib.string.modifiers
394 // append elements str[pos], ..., str[pos+n]
395 wxStringImpl& append(const wxStringImpl& str, size_t pos, size_t n)
396 {
397 wxASSERT(pos <= str.length());
398 ConcatSelf(n, str.c_str() + pos, str.length() - pos);
399 return *this;
400 }
401 // append a string
402 wxStringImpl& append(const wxStringImpl& str)
403 { ConcatSelf(str.length(), str.c_str()); return *this; }
404 // append first n (or all if n == npos) characters of sz
405 wxStringImpl& append(const wxStringCharType *sz)
406 { ConcatSelf(wxStrlen(sz), sz); return *this; }
407 wxStringImpl& append(const wxStringCharType *sz, size_t n)
408 { ConcatSelf(n, sz); return *this; }
409 // append n copies of ch
410 wxStringImpl& append(size_t n, wxStringCharType ch);
411 // append from first to last
412 wxStringImpl& append(const_iterator first, const_iterator last)
413 { ConcatSelf(last - first, first.GetPtr()); return *this; }
414
415 // same as `this_string = str'
416 wxStringImpl& assign(const wxStringImpl& str)
417 { return *this = str; }
418 // same as ` = str[pos..pos + n]
419 wxStringImpl& assign(const wxStringImpl& str, size_t pos, size_t n)
420 { return replace(0, npos, str, pos, n); }
421 // same as `= first n (or all if n == npos) characters of sz'
422 wxStringImpl& assign(const wxStringCharType *sz)
423 { return replace(0, npos, sz, wxStrlen(sz)); }
424 wxStringImpl& assign(const wxStringCharType *sz, size_t n)
425 { return replace(0, npos, sz, n); }
426 // same as `= n copies of ch'
427 wxStringImpl& assign(size_t n, wxStringCharType ch)
428 { return replace(0, npos, n, ch); }
429 // assign from first to last
430 wxStringImpl& assign(const_iterator first, const_iterator last)
431 { return replace(begin(), end(), first, last); }
432
433 // first valid index position
434 const_iterator begin() const { return m_pchData; }
435 iterator begin();
436 // position one after the last valid one
437 const_iterator end() const { return m_pchData + length(); }
438 iterator end();
439
440 // insert another string
441 wxStringImpl& insert(size_t nPos, const wxStringImpl& str)
442 {
443 wxASSERT( str.GetStringData()->IsValid() );
444 return insert(nPos, str.c_str(), str.length());
445 }
446 // insert n chars of str starting at nStart (in str)
447 wxStringImpl& insert(size_t nPos, const wxStringImpl& str, size_t nStart, size_t n)
448 {
449 wxASSERT( str.GetStringData()->IsValid() );
450 wxASSERT( nStart < str.length() );
451 size_t strLen = str.length() - nStart;
452 n = strLen < n ? strLen : n;
453 return insert(nPos, str.c_str() + nStart, n);
454 }
455 // insert first n (or all if n == npos) characters of sz
456 wxStringImpl& insert(size_t nPos, const wxStringCharType *sz, size_t n = npos);
457 // insert n copies of ch
458 wxStringImpl& insert(size_t nPos, size_t n, wxStringCharType ch)
459 { return insert(nPos, wxStringImpl(n, ch)); }
460 iterator insert(iterator it, wxStringCharType ch)
461 { size_t idx = it - begin(); insert(idx, 1, ch); return begin() + idx; }
462 void insert(iterator it, const_iterator first, const_iterator last)
463 { insert(it - begin(), first.GetPtr(), last - first); }
464 void insert(iterator it, size_type n, wxStringCharType ch)
465 { insert(it - begin(), n, ch); }
466
467 // delete characters from nStart to nStart + nLen
468 wxStringImpl& erase(size_type pos = 0, size_type n = npos);
469 iterator erase(iterator first, iterator last)
470 {
471 size_t idx = first - begin();
472 erase(idx, last - first);
473 return begin() + idx;
474 }
475 iterator erase(iterator first);
476
477 // explicit conversion to C string (use this with printf()!)
478 const wxStringCharType* c_str() const { return m_pchData; }
479 const wxStringCharType* data() const { return m_pchData; }
480
481 // replaces the substring of length nLen starting at nStart
482 wxStringImpl& replace(size_t nStart, size_t nLen, const wxStringCharType* sz)
483 { return replace(nStart, nLen, sz, npos); }
484 // replaces the substring of length nLen starting at nStart
485 wxStringImpl& replace(size_t nStart, size_t nLen, const wxStringImpl& str)
486 { return replace(nStart, nLen, str.c_str(), str.length()); }
487 // replaces the substring with nCount copies of ch
488 wxStringImpl& replace(size_t nStart, size_t nLen,
489 size_t nCount, wxStringCharType ch)
490 { return replace(nStart, nLen, wxStringImpl(nCount, ch)); }
491 // replaces a substring with another substring
492 wxStringImpl& replace(size_t nStart, size_t nLen,
493 const wxStringImpl& str, size_t nStart2, size_t nLen2)
494 { return replace(nStart, nLen, str.substr(nStart2, nLen2)); }
495 // replaces the substring with first nCount chars of sz
496 wxStringImpl& replace(size_t nStart, size_t nLen,
497 const wxStringCharType* sz, size_t nCount);
498
499 wxStringImpl& replace(iterator first, iterator last, const_pointer s)
500 { return replace(first - begin(), last - first, s); }
501 wxStringImpl& replace(iterator first, iterator last, const_pointer s,
502 size_type n)
503 { return replace(first - begin(), last - first, s, n); }
504 wxStringImpl& replace(iterator first, iterator last, const wxStringImpl& s)
505 { return replace(first - begin(), last - first, s); }
506 wxStringImpl& replace(iterator first, iterator last, size_type n, wxStringCharType c)
507 { return replace(first - begin(), last - first, n, c); }
508 wxStringImpl& replace(iterator first, iterator last,
509 const_iterator first1, const_iterator last1)
510 { return replace(first - begin(), last - first, first1.GetPtr(), last1 - first1); }
511
512 // swap two strings
513 void swap(wxStringImpl& str);
514
515 // All find() functions take the nStart argument which specifies the
516 // position to start the search on, the default value is 0. All functions
517 // return npos if there were no match.
518
519 // find a substring
520 size_t find(const wxStringImpl& str, size_t nStart = 0) const;
521
522 // find first n characters of sz
523 size_t find(const wxStringCharType* sz, size_t nStart = 0, size_t n = npos) const;
524
525 // find the first occurrence of character ch after nStart
526 size_t find(wxStringCharType ch, size_t nStart = 0) const;
527
528 // rfind() family is exactly like find() but works right to left
529
530 // as find, but from the end
531 size_t rfind(const wxStringImpl& str, size_t nStart = npos) const;
532
533 // as find, but from the end
534 size_t rfind(const wxStringCharType* sz, size_t nStart = npos,
535 size_t n = npos) const;
536 // as find, but from the end
537 size_t rfind(wxStringCharType ch, size_t nStart = npos) const;
538
539 size_type copy(wxStringCharType* s, size_type n, size_type pos = 0);
540
541 // substring extraction
542 wxStringImpl substr(size_t nStart = 0, size_t nLen = npos) const;
543
544 // string += string
545 wxStringImpl& operator+=(const wxStringImpl& s) { return append(s); }
546 // string += C string
547 wxStringImpl& operator+=(const wxStringCharType *psz) { return append(psz); }
548 // string += char
549 wxStringImpl& operator+=(wxStringCharType ch) { return append(1, ch); }
550
551 // helpers for wxStringBuffer and wxStringBufferLength
552 wxStringCharType *DoGetWriteBuf(size_t nLen);
553 void DoUngetWriteBuf();
554 void DoUngetWriteBuf(size_t nLen);
555
556 friend class WXDLLIMPEXP_FWD_BASE wxString;
557 };
558
559 #endif // !wxUSE_STL_BASED_WXSTRING
560
561 // don't pollute the library user's name space
562 #undef wxASSERT_VALID_INDEX
563
564 #endif // _WX_WXSTRINGIMPL_H__