]> git.saurik.com Git - wxWidgets.git/blame - include/wx/string.h
Added simplistic makefile/project files for wxWinCE.
[wxWidgets.git] / include / wx / string.h
CommitLineData
3c67202d 1///////////////////////////////////////////////////////////////////////////////
c801d85f 2// Name: string.h
3c67202d 3// Purpose: wxString and wxArrayString classes
c801d85f
KB
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>
dd1eaa89 9// Licence: wxWindows license
3c67202d 10///////////////////////////////////////////////////////////////////////////////
c801d85f 11
e90c1d2a
VZ
12/*
13 Efficient string class [more or less] compatible with MFC CString,
14 wxWindows version 1 wxString and std::string and some handy functions
15 missing from string.h.
16*/
17
34138703
JS
18#ifndef _WX_WXSTRINGH__
19#define _WX_WXSTRINGH__
c801d85f 20
af49c4b8 21#if defined(__GNUG__) && !defined(__APPLE__)
e90c1d2a
VZ
22 #pragma interface "string.h"
23#endif
24
25// ----------------------------------------------------------------------------
26// conditinal compilation
27// ----------------------------------------------------------------------------
28
29// compile the std::string compatibility functions if defined
30#define wxSTD_STRING_COMPATIBILITY
31
e90c1d2a
VZ
32// ----------------------------------------------------------------------------
33// headers
34// ----------------------------------------------------------------------------
35
5737d05f
VZ
36#include "wx/defs.h" // everybody should include this
37
9dea36ef 38#if defined(__WXMAC__) || defined(__VISAGECPP__)
3f4a0c5b 39 #include <ctype.h>
17dff81c 40#endif
3f4a0c5b 41
91b8de8d
RR
42#ifdef __EMX__
43 #include <std.h>
44#endif
45
9dea36ef
DW
46#if defined(__VISAGECPP__) && __IBMCPP__ >= 400
47 // problem in VACPP V4 with including stdlib.h multiple times
48 // strconv includes it anyway
49# include <stdio.h>
50# include <string.h>
51# include <stdarg.h>
52# include <limits.h>
53#else
54# include <string.h>
55# include <stdio.h>
56# include <stdarg.h>
57# include <limits.h>
58# include <stdlib.h>
59#endif
c801d85f 60
57493f9f 61#ifdef HAVE_STRINGS_H
1bfcb0b6 62 #include <strings.h> // for strcasecmp()
d739313f 63#endif // HAVE_STRINGS_H
1bfcb0b6 64
e90c1d2a
VZ
65#include "wx/wxchar.h" // for wxChar
66#include "wx/buffer.h" // for wxCharBuffer
67#include "wx/strconv.h" // for wxConvertXXX() macros and wxMBConv classes
3f4a0c5b 68
c801d85f
KB
69// ---------------------------------------------------------------------------
70// macros
71// ---------------------------------------------------------------------------
72
5737d05f
VZ
73// casts [unfortunately!] needed to call some broken functions which require
74// "char *" instead of "const char *"
2bb67b80 75#define WXSTRINGCAST (wxChar *)(const wxChar *)
e90c1d2a
VZ
76#define wxCSTRINGCAST (wxChar *)(const wxChar *)
77#define wxMBSTRINGCAST (char *)(const char *)
78#define wxWCSTRINGCAST (wchar_t *)(const wchar_t *)
c801d85f 79
3c67202d 80// implementation only
5737d05f 81#define wxASSERT_VALID_INDEX(i) \
b1801e0e 82 wxASSERT_MSG( (size_t)(i) <= Len(), _T("invalid index in wxString") )
c801d85f 83
e90c1d2a
VZ
84// ----------------------------------------------------------------------------
85// constants
86// ----------------------------------------------------------------------------
87
66b6b045 88#if defined(__VISAGECPP__) && __IBMCPP__ >= 400
67b81440 89// must define this static for VA or else you get multiply defined symbols everywhere
5d33ed2c 90extern const unsigned int wxSTRING_MAXLEN;
66b6b045
DW
91
92#else
e90c1d2a
VZ
93// maximum possible length for a string means "take all string" everywhere
94// (as sizeof(StringData) is unknown here, we substract 100)
95const unsigned int wxSTRING_MAXLEN = UINT_MAX - 100;
96
66b6b045
DW
97#endif
98
e90c1d2a
VZ
99// ----------------------------------------------------------------------------
100// global data
101// ----------------------------------------------------------------------------
102
103// global pointer to empty string
104WXDLLEXPORT_DATA(extern const wxChar*) wxEmptyString;
6001e347 105
c801d85f 106// ---------------------------------------------------------------------------
e90c1d2a 107// global functions complementing standard C string library replacements for
3c67202d
VZ
108// strlen() and portable strcasecmp()
109//---------------------------------------------------------------------------
e90c1d2a
VZ
110
111// Use wxXXX() functions from wxchar.h instead! These functions are for
112// backwards compatibility only.
88150e60 113
3c67202d 114// checks whether the passed in pointer is NULL and if the string is empty
6d56eb5c 115inline bool IsEmpty(const char *p) { return (!p || !*p); }
c801d85f 116
3c67202d 117// safe version of strlen() (returns 0 if passed NULL pointer)
6d56eb5c 118inline size_t Strlen(const char *psz)
c801d85f
KB
119 { return psz ? strlen(psz) : 0; }
120
3c67202d 121// portable strcasecmp/_stricmp
6d56eb5c 122inline int Stricmp(const char *psz1, const char *psz2)
dd1eaa89 123{
91b8de8d 124#if defined(__VISUALC__) || ( defined(__MWERKS__) && defined(__INTEL__) )
dd1eaa89 125 return _stricmp(psz1, psz2);
91b8de8d 126#elif defined(__SC__)
2432b92d 127 return _stricmp(psz1, psz2);
91b8de8d 128#elif defined(__SALFORDC__)
a3ef5bf5 129 return stricmp(psz1, psz2);
dd1eaa89
VZ
130#elif defined(__BORLANDC__)
131 return stricmp(psz1, psz2);
7be1f0d9
JS
132#elif defined(__WATCOMC__)
133 return stricmp(psz1, psz2);
14704334
VS
134#elif defined(__DJGPP__)
135 return stricmp(psz1, psz2);
91b8de8d
RR
136#elif defined(__EMX__)
137 return stricmp(psz1, psz2);
e2c87f4c 138#elif defined(__WXPM__)
1777b9bb 139 return stricmp(psz1, psz2);
91b8de8d 140#elif defined(__UNIX__) || defined(__GNUWIN32__)
dd1eaa89 141 return strcasecmp(psz1, psz2);
8be97d65 142#elif defined(__MWERKS__) && !defined(__INTEL__)
17dff81c
SC
143 register char c1, c2;
144 do {
145 c1 = tolower(*psz1++);
146 c2 = tolower(*psz2++);
147 } while ( c1 && (c1 == c2) );
148
149 return c1 - c2;
dd1eaa89
VZ
150#else
151 // almost all compilers/libraries provide this function (unfortunately under
152 // different names), that's why we don't implement our own which will surely
153 // be more efficient than this code (uncomment to use):
154 /*
155 register char c1, c2;
156 do {
157 c1 = tolower(*psz1++);
158 c2 = tolower(*psz2++);
159 } while ( c1 && (c1 == c2) );
160
161 return c1 - c2;
162 */
163
164 #error "Please define string case-insensitive compare for your OS/compiler"
165#endif // OS/compiler
166}
c801d85f 167
f04f3991 168// return an empty wxString
f7bd2698 169class WXDLLEXPORT wxString; // not yet defined
e90c1d2a 170inline const wxString& wxGetEmptyString() { return *(wxString *)&wxEmptyString; }
f04f3991 171
c801d85f 172// ---------------------------------------------------------------------------
f04f3991 173// string data prepended with some housekeeping info (used by wxString class),
c801d85f
KB
174// is never used directly (but had to be put here to allow inlining)
175// ---------------------------------------------------------------------------
e90c1d2a 176
c801d85f
KB
177struct WXDLLEXPORT wxStringData
178{
179 int nRefs; // reference count
3c024cc2 180 size_t nDataLength, // actual string length
c801d85f
KB
181 nAllocLength; // allocated memory size
182
2bb67b80
OK
183 // mimics declaration 'wxChar data[nAllocLength]'
184 wxChar* data() const { return (wxChar*)(this + 1); }
c801d85f
KB
185
186 // empty string has a special ref count so it's never deleted
dbda9e86
JS
187 bool IsEmpty() const { return (nRefs == -1); }
188 bool IsShared() const { return (nRefs > 1); }
c801d85f
KB
189
190 // lock/unlock
dd1eaa89 191 void Lock() { if ( !IsEmpty() ) nRefs++; }
f6bcfd97
BP
192
193 // VC++ will refuse to inline this function but profiling shows that it
194 // is wrong
195#if defined(__VISUALC__) && (__VISUALC__ >= 1200)
196 __forceinline
197#endif
dd1eaa89 198 void Unlock() { if ( !IsEmpty() && --nRefs == 0) free(this); }
8fd0f20b 199
dd1eaa89 200 // if we had taken control over string memory (GetWriteBuf), it's
8fd0f20b 201 // intentionally put in invalid state
dbda9e86
JS
202 void Validate(bool b) { nRefs = (b ? 1 : 0); }
203 bool IsValid() const { return (nRefs != 0); }
c801d85f
KB
204};
205
c801d85f 206// ---------------------------------------------------------------------------
3c67202d
VZ
207// This is (yet another one) String class for C++ programmers. It doesn't use
208// any of "advanced" C++ features (i.e. templates, exceptions, namespaces...)
209// thus you should be able to compile it with practicaly any C++ compiler.
210// This class uses copy-on-write technique, i.e. identical strings share the
211// same memory as long as neither of them is changed.
212//
213// This class aims to be as compatible as possible with the new standard
214// std::string class, but adds some additional functions and should be at
215// least as efficient than the standard implementation.
216//
217// Performance note: it's more efficient to write functions which take "const
218// String&" arguments than "const char *" if you assign the argument to
219// another string.
220//
221// It was compiled and tested under Win32, Linux (libc 5 & 6), Solaris 5.5.
222//
223// To do:
224// - ressource support (string tables in ressources)
225// - more wide character (UNICODE) support
226// - regular expressions support
c801d85f 227// ---------------------------------------------------------------------------
3c67202d 228
3c67202d
VZ
229class WXDLLEXPORT wxString
230{
fbcb4166 231friend class WXDLLEXPORT wxArrayString;
c801d85f 232
3c67202d
VZ
233 // NB: special care was taken in arranging the member functions in such order
234 // that all inline functions can be effectively inlined, verify that all
235 // performace critical functions are still inlined if you change order!
dd1eaa89
VZ
236private:
237 // points to data preceded by wxStringData structure with ref count info
2bb67b80 238 wxChar *m_pchData;
dd1eaa89
VZ
239
240 // accessor to string data
241 wxStringData* GetStringData() const { return (wxStringData*)m_pchData - 1; }
242
6b95b20d
VZ
243 // string (re)initialization functions
244 // initializes the string to the empty value (must be called only from
245 // ctors, use Reinit() otherwise)
e90c1d2a 246 void Init() { m_pchData = (wxChar *)wxEmptyString; }
6b95b20d 247 // initializaes the string with (a part of) C-string
2bb67b80 248 void InitWith(const wxChar *psz, size_t nPos = 0, size_t nLen = wxSTRING_MAXLEN);
6b95b20d
VZ
249 // as Init, but also frees old data
250 void Reinit() { GetStringData()->Unlock(); Init(); }
251
252 // memory allocation
b1801e0e
GD
253 // allocates memory for string of length nLen
254 bool AllocBuffer(size_t nLen);
6b95b20d 255 // copies data to another string
b1801e0e 256 bool AllocCopy(wxString&, int, int) const;
6b95b20d 257 // effectively copies data to string
b1801e0e 258 bool AssignCopy(size_t, const wxChar *);
6b95b20d
VZ
259
260 // append a (sub)string
b1801e0e 261 bool ConcatSelf(int nLen, const wxChar *src);
6b95b20d
VZ
262
263 // functions called before writing to the string: they copy it if there
264 // are other references to our data (should be the only owner when writing)
b1801e0e
GD
265 bool CopyBeforeWrite();
266 bool AllocBeforeWrite(size_t);
6b95b20d 267
00b4a13e
VZ
268 // if we hadn't made these operators private, it would be possible to
269 // compile "wxString s; s = 17;" without any warnings as 17 is implicitly
270 // converted to char in C and we do have operator=(char)
271 //
272 // NB: we don't need other versions (short/long and unsigned) as attempt
273 // to assign another numeric type to wxString will now result in
274 // ambiguity between operator=(char) and operator=(int)
275 wxString& operator=(int);
276
277 // these methods are not implemented - there is _no_ conversion from int to
c606a9a4
VZ
278 // string, you're doing something wrong if the compiler wants to call it!
279 //
280 // try `s << i' or `s.Printf("%d", i)' instead
281 wxString(int);
c606a9a4 282
c801d85f 283public:
3c67202d
VZ
284 // constructors and destructor
285 // ctor for an empty string
b1801e0e 286 wxString() : m_pchData(NULL) { Init(); }
3c67202d 287 // copy ctor
b1801e0e 288 wxString(const wxString& stringSrc) : m_pchData(NULL)
6b95b20d 289 {
09443a26
VZ
290 wxASSERT_MSG( stringSrc.GetStringData()->IsValid(),
291 _T("did you forget to call UngetWriteBuf()?") );
6b95b20d
VZ
292
293 if ( stringSrc.IsEmpty() ) {
294 // nothing to do for an empty string
295 Init();
296 }
297 else {
298 m_pchData = stringSrc.m_pchData; // share same data
299 GetStringData()->Lock(); // => one more copy
300 }
301 }
3c67202d 302 // string containing nRepeat copies of ch
2bb67b80 303 wxString(wxChar ch, size_t nRepeat = 1);
3c67202d 304 // ctor takes first nLength characters from C string
566b84d2 305 // (default value of wxSTRING_MAXLEN means take all the string)
2bb67b80 306 wxString(const wxChar *psz, size_t nLength = wxSTRING_MAXLEN)
b1801e0e
GD
307 : m_pchData(NULL)
308 { InitWith(psz, 0, nLength); }
f6bcfd97 309 wxString(const wxChar *psz, wxMBConv& WXUNUSED(conv), size_t nLength = wxSTRING_MAXLEN)
b1801e0e
GD
310 : m_pchData(NULL)
311 { InitWith(psz, 0, nLength); }
e90c1d2a 312
2bb67b80
OK
313#if wxUSE_UNICODE
314 // from multibyte string
315 // (NB: nLength is right now number of Unicode characters, not
316 // characters in psz! So try not to use it yet!)
2b5f62a0 317 wxString(const char *psz, wxMBConv& conv, size_t nLength = wxSTRING_MAXLEN);
2bb67b80
OK
318 // from wxWCharBuffer (i.e. return from wxGetString)
319 wxString(const wxWCharBuffer& psz)
320 { InitWith(psz, 0, wxSTRING_MAXLEN); }
e90c1d2a 321#else // ANSI
3c67202d 322 // from C string (for compilers using unsigned char)
2bb67b80 323 wxString(const unsigned char* psz, size_t nLength = wxSTRING_MAXLEN)
b1801e0e
GD
324 : m_pchData(NULL)
325 { InitWith((const char*)psz, 0, nLength); }
e90c1d2a 326
6f841509 327#if wxUSE_WCHAR_T
2bb67b80 328 // from wide (Unicode) string
1c2e6a28 329 wxString(const wchar_t *pwz, wxMBConv& conv = wxConvLibc, size_t nLength = wxSTRING_MAXLEN);
e90c1d2a
VZ
330#endif // !wxUSE_WCHAR_T
331
2bb67b80
OK
332 // from wxCharBuffer
333 wxString(const wxCharBuffer& psz)
b1801e0e
GD
334 : m_pchData(NULL)
335 { InitWith(psz, 0, wxSTRING_MAXLEN); }
e90c1d2a
VZ
336#endif // Unicode/ANSI
337
3c67202d 338 // dtor is not virtual, this class must not be inherited from!
6b95b20d 339 ~wxString() { GetStringData()->Unlock(); }
c801d85f 340
3c67202d
VZ
341 // generic attributes & operations
342 // as standard strlen()
47d67540 343 size_t Len() const { return GetStringData()->nDataLength; }
3c67202d 344 // string contains any characters?
dd1eaa89 345 bool IsEmpty() const { return Len() == 0; }
dcfde592
VZ
346 // empty string is "FALSE", so !str will return TRUE
347 bool operator!() const { return IsEmpty(); }
735d1db6
VZ
348 // truncate the string to given length
349 wxString& Truncate(size_t uiLen);
3c67202d 350 // empty string contents
dd1eaa89
VZ
351 void Empty()
352 {
735d1db6 353 Truncate(0);
dd1eaa89 354
735d1db6 355 wxASSERT_MSG( IsEmpty(), _T("string not empty after call to Empty()?") );
7be07660 356 }
3c67202d 357 // empty the string and free memory
7be07660
VZ
358 void Clear()
359 {
360 if ( !GetStringData()->IsEmpty() )
361 Reinit();
362
09443a26
VZ
363 wxASSERT_MSG( !GetStringData()->nDataLength &&
364 !GetStringData()->nAllocLength,
365 _T("string should be empty after Clear()") );
dd1eaa89
VZ
366 }
367
3c67202d
VZ
368 // contents test
369 // Is an ascii value
c801d85f 370 bool IsAscii() const;
3c67202d 371 // Is a number
c801d85f 372 bool IsNumber() const;
3c67202d 373 // Is a word
c801d85f 374 bool IsWord() const;
c801d85f 375
3c67202d
VZ
376 // data access (all indexes are 0 based)
377 // read access
2bb67b80 378 wxChar GetChar(size_t n) const
5737d05f 379 { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
3c67202d 380 // read/write access
2bb67b80 381 wxChar& GetWritableChar(size_t n)
5737d05f 382 { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
3c67202d 383 // write access
2bb67b80 384 void SetChar(size_t n, wxChar ch)
5737d05f 385 { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); m_pchData[n] = ch; }
c801d85f 386
3c67202d 387 // get last character
2bb67b80 388 wxChar Last() const
09443a26
VZ
389 {
390 wxASSERT_MSG( !IsEmpty(), _T("wxString: index out of bounds") );
391
392 return m_pchData[Len() - 1];
393 }
394
3c67202d 395 // get writable last character
2bb67b80 396 wxChar& Last()
09443a26
VZ
397 {
398 wxASSERT_MSG( !IsEmpty(), _T("wxString: index out of bounds") );
399 CopyBeforeWrite();
400 return m_pchData[Len()-1];
401 }
c801d85f 402
d836ee96
VZ
403 /*
404 So why do we have all these overloaded operator[]s? A bit of history:
405 initially there was only one of them, taking size_t. Then people
406 started complaining because they wanted to use ints as indices (I
407 wonder why) and compilers were giving warnings about it, so we had to
408 add the operator[](int). Then it became apparent that you couldn't
409 write str[0] any longer because there was ambiguity between two
410 overloads and so you now had to write str[0u] (or, of course, use the
411 explicit casts to either int or size_t but nobody did this).
412
413 Finally, someone decided to compile wxWin on an Alpha machine and got
414 a surprize: str[0u] didn't compile there because it is of type
415 unsigned int and size_t is unsigned _long_ on Alpha and so there was
416 ambiguity between converting uint to int or ulong. To fix this one we
417 now add operator[](uint) for the machines where size_t is not already
418 the same as unsigned int - hopefully this fixes the problem (for some
419 time)
420
421 The only real fix is, of course, to remove all versions but the one
422 taking size_t...
423 */
424
3c67202d 425 // operator version of GetChar
2bb67b80 426 wxChar operator[](size_t n) const
5737d05f 427 { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
c5248639 428
3c67202d 429 // operator version of GetChar
2bb67b80 430 wxChar operator[](int n) const
5737d05f 431 { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
cd0b1709 432
f83db661 433 // operator version of GetWriteableChar
2bb67b80 434 wxChar& operator[](size_t n)
5737d05f 435 { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
d836ee96
VZ
436
437#ifndef wxSIZE_T_IS_UINT
438 // operator version of GetChar
439 wxChar operator[](unsigned int n) const
5737d05f 440 { wxASSERT_VALID_INDEX( n ); return m_pchData[n]; }
d836ee96 441
f83db661 442 // operator version of GetWriteableChar
d836ee96 443 wxChar& operator[](unsigned int n)
5737d05f 444 { wxASSERT_VALID_INDEX( n ); CopyBeforeWrite(); return m_pchData[n]; }
d836ee96 445#endif // size_t != unsigned int
c801d85f 446
3c67202d 447 // implicit conversion to C string
2bb67b80 448 operator const wxChar*() const { return m_pchData; }
e015c2a3 449
3c67202d 450 // explicit conversion to C string (use this with printf()!)
2bb67b80 451 const wxChar* c_str() const { return m_pchData; }
e015c2a3 452 // identical to c_str(), for wxWin 1.6x compatibility
6f841509 453 const wxChar* wx_str() const { return m_pchData; }
e015c2a3 454 // identical to c_str(), for MFC compatibility
2bb67b80 455 const wxChar* GetData() const { return m_pchData; }
e90c1d2a 456
e015c2a3
VZ
457 // conversion to/from plain (i.e. 7 bit) ASCII: this is useful for
458 // converting numbers or strings which are certain not to contain special
459 // chars (typically system functions, X atoms, environment variables etc.)
460 //
461 // the behaviour of these functions with the strings containing anything
462 // else than 7 bit ASCII characters is undefined, use at your own risk.
b1ac3b56 463#if wxUSE_UNICODE
2b5f62a0
VZ
464 static wxString FromAscii(const char *ascii); // string
465 static wxString FromAscii(const char ascii); // char
b1ac3b56 466 const wxCharBuffer ToAscii() const;
e015c2a3
VZ
467#else // ANSI
468 static wxString FromAscii(const char *ascii) { return wxString( ascii ); }
2b5f62a0 469 static wxString FromAscii(const char ascii) { return wxString( ascii ); }
e015c2a3
VZ
470 const char *ToAscii() const { return c_str(); }
471#endif // Unicode/!Unicode
b1ac3b56 472
2b5f62a0 473 // conversions with (possible) format conversions: have to return a
e90c1d2a 474 // buffer with temporary data
f6bcfd97
BP
475 //
476 // the functions defined (in either Unicode or ANSI) mode are mb_str() to
477 // return an ANSI (multibyte) string, wc_str() to return a wide string and
478 // fn_str() to return a string which should be used with the OS APIs
479 // accepting the file names. The return value is always the same, but the
480 // type differs because a function may either return pointer to the buffer
481 // directly or have to use intermediate buffer for translation.
2bb67b80 482#if wxUSE_UNICODE
f6bcfd97
BP
483 const wxCharBuffer mb_str(wxMBConv& conv = wxConvLibc) const
484 { return conv.cWC2MB(m_pchData); }
485
e90c1d2a
VZ
486 const wxWX2MBbuf mbc_str() const { return mb_str(*wxConvCurrent); }
487
f6bcfd97
BP
488 const wxChar* wc_str() const { return m_pchData; }
489
490 // for compatibility with !wxUSE_UNICODE version
491 const wxChar* wc_str(wxMBConv& WXUNUSED(conv)) const { return m_pchData; }
e90c1d2a 492
2bb67b80 493#if wxMBFILES
5f709e67 494 const wxCharBuffer fn_str() const { return mb_str(wxConvFile); }
e90c1d2a 495#else // !wxMBFILES
2bb67b80 496 const wxChar* fn_str() const { return m_pchData; }
e90c1d2a
VZ
497#endif // wxMBFILES/!wxMBFILES
498#else // ANSI
e90c1d2a 499 const wxChar* mb_str() const { return m_pchData; }
f6bcfd97
BP
500
501 // for compatibility with wxUSE_UNICODE version
502 const wxChar* mb_str(wxMBConv& WXUNUSED(conv)) const { return m_pchData; }
503
e90c1d2a 504 const wxWX2MBbuf mbc_str() const { return mb_str(); }
f6bcfd97 505
6f841509 506#if wxUSE_WCHAR_T
f6bcfd97
BP
507 const wxWCharBuffer wc_str(wxMBConv& conv) const
508 { return conv.cMB2WC(m_pchData); }
e90c1d2a 509#endif // wxUSE_WCHAR_T
f6bcfd97 510
2bb67b80 511 const wxChar* fn_str() const { return m_pchData; }
e90c1d2a 512#endif // Unicode/ANSI
c801d85f 513
3c67202d
VZ
514 // overloaded assignment
515 // from another wxString
c801d85f 516 wxString& operator=(const wxString& stringSrc);
3c67202d 517 // from a character
2bb67b80 518 wxString& operator=(wxChar ch);
3c67202d 519 // from a C string
2bb67b80 520 wxString& operator=(const wxChar *psz);
111bb7f2
OK
521#if wxUSE_UNICODE
522 // from wxWCharBuffer
b1801e0e
GD
523 wxString& operator=(const wxWCharBuffer& psz)
524 { (void) operator=((const wchar_t *)psz); return *this; }
e90c1d2a 525#else // ANSI
3c67202d 526 // from another kind of C string
c801d85f 527 wxString& operator=(const unsigned char* psz);
6f841509 528#if wxUSE_WCHAR_T
3c67202d 529 // from a wide string
c801d85f 530 wxString& operator=(const wchar_t *pwz);
6f841509 531#endif
111bb7f2 532 // from wxCharBuffer
b1801e0e
GD
533 wxString& operator=(const wxCharBuffer& psz)
534 { (void) operator=((const char *)psz); return *this; }
e90c1d2a 535#endif // Unicode/ANSI
3c67202d
VZ
536
537 // string concatenation
538 // in place concatenation
539 /*
540 Concatenate and return the result. Note that the left to right
541 associativity of << allows to write things like "str << str1 << str2
542 << ..." (unlike with +=)
543 */
544 // string += string
dd1eaa89
VZ
545 wxString& operator<<(const wxString& s)
546 {
09443a26
VZ
547 wxASSERT_MSG( s.GetStringData()->IsValid(),
548 _T("did you forget to call UngetWriteBuf()?") );
dd1eaa89
VZ
549
550 ConcatSelf(s.Len(), s);
551 return *this;
552 }
3c67202d 553 // string += C string
2bb67b80
OK
554 wxString& operator<<(const wxChar *psz)
555 { ConcatSelf(wxStrlen(psz), psz); return *this; }
3c67202d 556 // string += char
2bb67b80 557 wxString& operator<<(wxChar ch) { ConcatSelf(1, &ch); return *this; }
dd1eaa89 558
3c67202d 559 // string += string
6b95b20d 560 void operator+=(const wxString& s) { (void)operator<<(s); }
3c67202d 561 // string += C string
2bb67b80 562 void operator+=(const wxChar *psz) { (void)operator<<(psz); }
3c67202d 563 // string += char
2bb67b80
OK
564 void operator+=(wxChar ch) { (void)operator<<(ch); }
565
566 // string += buffer (i.e. from wxGetString)
567#if wxUSE_UNICODE
09443a26
VZ
568 wxString& operator<<(const wxWCharBuffer& s)
569 { (void)operator<<((const wchar_t *)s); return *this; }
570 void operator+=(const wxWCharBuffer& s)
571 { (void)operator<<((const wchar_t *)s); }
572#else // !wxUSE_UNICODE
573 wxString& operator<<(const wxCharBuffer& s)
574 { (void)operator<<((const char *)s); return *this; }
575 void operator+=(const wxCharBuffer& s)
576 { (void)operator<<((const char *)s); }
577#endif // wxUSE_UNICODE/!wxUSE_UNICODE
6b95b20d 578
3c67202d 579 // string += C string
09443a26
VZ
580 wxString& Append(const wxString& s)
581 {
582 // test for IsEmpty() to share the string if possible
583 if ( IsEmpty() )
584 *this = s;
585 else
586 ConcatSelf(s.Length(), s.c_str());
587 return *this;
588 }
2bb67b80
OK
589 wxString& Append(const wxChar* psz)
590 { ConcatSelf(wxStrlen(psz), psz); return *this; }
3c67202d 591 // append count copies of given character
2bb67b80 592 wxString& Append(wxChar ch, size_t count = 1u)
3c67202d 593 { wxString str(ch, count); return *this << str; }
8f06a017
RD
594 wxString& Append(const wxChar* psz, size_t nLen)
595 { ConcatSelf(nLen, psz); return *this; }
3c67202d
VZ
596
597 // prepend a string, return the string itself
598 wxString& Prepend(const wxString& str)
599 { *this = str + *this; return *this; }
600
601 // non-destructive concatenation
602 //
c33534e5 603 friend wxString WXDLLEXPORT operator+(const wxString& string1, const wxString& string2);
3c67202d 604 //
2bb67b80 605 friend wxString WXDLLEXPORT operator+(const wxString& string, wxChar ch);
3c67202d 606 //
2bb67b80 607 friend wxString WXDLLEXPORT operator+(wxChar ch, const wxString& string);
3c67202d 608 //
2bb67b80 609 friend wxString WXDLLEXPORT operator+(const wxString& string, const wxChar *psz);
3c67202d 610 //
2bb67b80 611 friend wxString WXDLLEXPORT operator+(const wxChar *psz, const wxString& string);
3c67202d
VZ
612
613 // stream-like functions
614 // insert an int into string
3ce65f6c
VZ
615 wxString& operator<<(int i)
616 { return (*this) << Format(_T("%d"), i); }
617 // insert an unsigned int into string
618 wxString& operator<<(unsigned int ui)
619 { return (*this) << Format(_T("%u"), ui); }
620 // insert a long into string
621 wxString& operator<<(long l)
622 { return (*this) << Format(_T("%ld"), l); }
623 // insert an unsigned long into string
624 wxString& operator<<(unsigned long ul)
625 { return (*this) << Format(_T("%lu"), ul); }
3c67202d 626 // insert a float into string
3ce65f6c
VZ
627 wxString& operator<<(float f)
628 { return (*this) << Format(_T("%f"), f); }
3c67202d 629 // insert a double into string
3ce65f6c
VZ
630 wxString& operator<<(double d)
631 { return (*this) << Format(_T("%g"), d); }
c84c52de 632
3c67202d 633 // string comparison
30b21f9a 634 // case-sensitive comparison (returns a value < 0, = 0 or > 0)
f33fee2a 635 int Cmp(const wxChar *psz) const { return wxStrcmp(c_str(), psz); }
3c67202d 636 // same as Cmp() but not case-sensitive
f33fee2a 637 int CmpNoCase(const wxChar *psz) const { return wxStricmp(c_str(), psz); }
3c67202d
VZ
638 // test for the string equality, either considering case or not
639 // (if compareWithCase then the case matters)
2bb67b80 640 bool IsSameAs(const wxChar *psz, bool compareWithCase = TRUE) const
3c67202d 641 { return (compareWithCase ? Cmp(psz) : CmpNoCase(psz)) == 0; }
f33fee2a
VZ
642 // comparison with a signle character: returns TRUE if equal
643 bool IsSameAs(wxChar c, bool compareWithCase = TRUE) const
644 {
645 return (Len() == 1) && (compareWithCase ? GetChar(0u) == c
646 : wxToupper(GetChar(0u)) == wxToupper(c));
647 }
3c67202d
VZ
648
649 // simple sub-string extraction
650 // return substring starting at nFirst of length nCount (or till the end
651 // if nCount = default value)
566b84d2 652 wxString Mid(size_t nFirst, size_t nCount = wxSTRING_MAXLEN) const;
3c67202d 653
f6bcfd97 654 // operator version of Mid()
3c67202d
VZ
655 wxString operator()(size_t start, size_t len) const
656 { return Mid(start, len); }
657
c0881dc3 658 // check that the string starts with prefix and return the rest of the
f6bcfd97
BP
659 // string in the provided pointer if it is not NULL, otherwise return
660 // FALSE
661 bool StartsWith(const wxChar *prefix, wxString *rest = NULL) const;
662
3c67202d 663 // get first nCount characters
c801d85f 664 wxString Left(size_t nCount) const;
3c67202d 665 // get last nCount characters
c801d85f 666 wxString Right(size_t nCount) const;
c0881dc3 667 // get all characters before the first occurance of ch
3c67202d 668 // (returns the whole string if ch not found)
2bb67b80 669 wxString BeforeFirst(wxChar ch) const;
3c67202d
VZ
670 // get all characters before the last occurence of ch
671 // (returns empty string if ch not found)
2bb67b80 672 wxString BeforeLast(wxChar ch) const;
3c67202d
VZ
673 // get all characters after the first occurence of ch
674 // (returns empty string if ch not found)
2bb67b80 675 wxString AfterFirst(wxChar ch) const;
3c67202d
VZ
676 // get all characters after the last occurence of ch
677 // (returns the whole string if ch not found)
2bb67b80 678 wxString AfterLast(wxChar ch) const;
3c67202d
VZ
679
680 // for compatibility only, use more explicitly named functions above
2bb67b80
OK
681 wxString Before(wxChar ch) const { return BeforeLast(ch); }
682 wxString After(wxChar ch) const { return AfterFirst(ch); }
3c67202d
VZ
683
684 // case conversion
c84c52de 685 // convert to upper case in place, return the string itself
c801d85f 686 wxString& MakeUpper();
c84c52de 687 // convert to upper case, return the copy of the string
03ab016d
JS
688 // Here's something to remember: BC++ doesn't like returns in inlines.
689 wxString Upper() const ;
c84c52de 690 // convert to lower case in place, return the string itself
c801d85f 691 wxString& MakeLower();
c84c52de 692 // convert to lower case, return the copy of the string
03ab016d 693 wxString Lower() const ;
c801d85f 694
3c67202d
VZ
695 // trimming/padding whitespace (either side) and truncating
696 // remove spaces from left or from right (default) side
c801d85f 697 wxString& Trim(bool bFromRight = TRUE);
3c67202d 698 // add nCount copies chPad in the beginning or at the end (default)
223d09f6 699 wxString& Pad(size_t nCount, wxChar chPad = wxT(' '), bool bFromRight = TRUE);
dd1eaa89 700
3c67202d
VZ
701 // searching and replacing
702 // searching (return starting index, or -1 if not found)
2bb67b80 703 int Find(wxChar ch, bool bFromEnd = FALSE) const; // like strchr/strrchr
3c67202d 704 // searching (return starting index, or -1 if not found)
2bb67b80 705 int Find(const wxChar *pszSub) const; // like strstr
3c67202d
VZ
706 // replace first (or all of bReplaceAll) occurences of substring with
707 // another string, returns the number of replacements made
2bb67b80
OK
708 size_t Replace(const wxChar *szOld,
709 const wxChar *szNew,
3c67202d
VZ
710 bool bReplaceAll = TRUE);
711
712 // check if the string contents matches a mask containing '*' and '?'
2bb67b80 713 bool Matches(const wxChar *szMask) const;
c801d85f 714
538f35cc
VZ
715 // conversion to numbers: all functions return TRUE only if the whole
716 // string is a number and put the value of this number into the pointer
717 // provided, the base is the numeric base in which the conversion should be
718 // done and must be comprised between 2 and 36 or be 0 in which case the
719 // standard C rules apply (leading '0' => octal, "0x" => hex)
cd0b1709 720 // convert to a signed integer
538f35cc 721 bool ToLong(long *val, int base = 10) const;
cd0b1709 722 // convert to an unsigned integer
538f35cc 723 bool ToULong(unsigned long *val, int base = 10) const;
cd0b1709
VZ
724 // convert to a double
725 bool ToDouble(double *val) const;
726
3c67202d
VZ
727 // formated input/output
728 // as sprintf(), returns the number of characters written or < 0 on error
7357f981
GD
729 // (take 'this' into account in attribute parameter count)
730 int Printf(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_2;
3c67202d 731 // as vprintf(), returns the number of characters written or < 0 on error
2bb67b80 732 int PrintfV(const wxChar* pszFormat, va_list argptr);
dd1eaa89 733
341e7d28 734 // returns the string containing the result of Printf() to it
7357f981 735 static wxString Format(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_1;
341e7d28
VZ
736 // the same as above, but takes a va_list
737 static wxString FormatV(const wxChar *pszFormat, va_list argptr);
738
3c67202d
VZ
739 // raw access to string memory
740 // ensure that string has space for at least nLen characters
dd1eaa89 741 // only works if the data of this string is not shared
b1801e0e 742 bool Alloc(size_t nLen);
3c67202d 743 // minimize the string's memory
dd1eaa89 744 // only works if the data of this string is not shared
b1801e0e 745 bool Shrink();
3c67202d
VZ
746 // get writable buffer of at least nLen bytes. Unget() *must* be called
747 // a.s.a.p. to put string back in a reasonable state!
2bb67b80 748 wxChar *GetWriteBuf(size_t nLen);
3c67202d 749 // call this immediately after GetWriteBuf() has been used
8fd0f20b 750 void UngetWriteBuf();
8f06a017 751 void UngetWriteBuf(size_t nLen);
c801d85f 752
3c67202d
VZ
753 // wxWindows version 1 compatibility functions
754
755 // use Mid()
756 wxString SubString(size_t from, size_t to) const
757 { return Mid(from, (to - from + 1)); }
758 // values for second parameter of CompareTo function
c801d85f 759 enum caseCompare {exact, ignoreCase};
3c67202d 760 // values for first parameter of Strip function
c801d85f 761 enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
8870c26e 762
7357f981
GD
763 // use Printf()
764 // (take 'this' into account in attribute parameter count)
765 int sprintf(const wxChar *pszFormat, ...) ATTRIBUTE_PRINTF_2;
c801d85f 766
3c67202d 767 // use Cmp()
2bb67b80 768 inline int CompareTo(const wxChar* psz, caseCompare cmp = exact) const
6b95b20d 769 { return cmp == exact ? Cmp(psz) : CmpNoCase(psz); }
c801d85f 770
3c67202d 771 // use Len
c801d85f 772 size_t Length() const { return Len(); }
3c67202d 773 // Count the number of characters
2bb67b80 774 int Freq(wxChar ch) const;
3c67202d 775 // use MakeLower
c801d85f 776 void LowerCase() { MakeLower(); }
3c67202d 777 // use MakeUpper
c801d85f 778 void UpperCase() { MakeUpper(); }
3c67202d 779 // use Trim except that it doesn't change this string
c801d85f
KB
780 wxString Strip(stripType w = trailing) const;
781
3c67202d 782 // use Find (more general variants not yet supported)
2bb67b80
OK
783 size_t Index(const wxChar* psz) const { return Find(psz); }
784 size_t Index(wxChar ch) const { return Find(ch); }
3c67202d 785 // use Truncate
c801d85f 786 wxString& Remove(size_t pos) { return Truncate(pos); }
28a156b1 787 wxString& RemoveLast(size_t n = 1) { return Truncate(Len() - n); }
c801d85f 788
3ed358cb 789 wxString& Remove(size_t nStart, size_t nLen) { return erase( nStart, nLen ); }
dd1eaa89 790
3c67202d 791 // use Find()
2bb67b80
OK
792 int First( const wxChar ch ) const { return Find(ch); }
793 int First( const wxChar* psz ) const { return Find(psz); }
3ed358cb 794 int First( const wxString &str ) const { return Find(str); }
2bb67b80 795 int Last( const wxChar ch ) const { return Find(ch, TRUE); }
3c67202d 796 bool Contains(const wxString& str) const { return Find(str) != -1; }
c801d85f 797
3c67202d 798 // use IsEmpty()
c801d85f 799 bool IsNull() const { return IsEmpty(); }
c801d85f 800
3c67202d
VZ
801#ifdef wxSTD_STRING_COMPATIBILITY
802 // std::string compatibility functions
dd1eaa89 803
2bc07607
VZ
804 // standard types
805 typedef wxChar value_type;
806 typedef const value_type *const_iterator;
807
3c67202d 808 // an 'invalid' value for string index
c801d85f 809 static const size_t npos;
dd1eaa89 810
3c67202d
VZ
811 // constructors
812 // take nLen chars starting at nPos
813 wxString(const wxString& str, size_t nPos, size_t nLen)
b1801e0e 814 : m_pchData(NULL)
3c67202d 815 {
09443a26
VZ
816 wxASSERT_MSG( str.GetStringData()->IsValid(),
817 _T("did you forget to call UngetWriteBuf()?") );
818
3c67202d
VZ
819 InitWith(str.c_str(), nPos, nLen == npos ? 0 : nLen);
820 }
821 // take all characters from pStart to pEnd
822 wxString(const void *pStart, const void *pEnd);
823
824 // lib.string.capacity
825 // return the length of the string
826 size_t size() const { return Len(); }
827 // return the length of the string
828 size_t length() const { return Len(); }
829 // return the maximum size of the string
566b84d2 830 size_t max_size() const { return wxSTRING_MAXLEN; }
3c67202d 831 // resize the string, filling the space with c if c != 0
223d09f6 832 void resize(size_t nSize, wxChar ch = wxT('\0'));
3c67202d
VZ
833 // delete the contents of the string
834 void clear() { Empty(); }
835 // returns true if the string is empty
836 bool empty() const { return IsEmpty(); }
252a752e 837 // inform string about planned change in size
2b5f62a0 838 void reserve(size_t sz) { Alloc(sz); }
3c67202d
VZ
839
840 // lib.string.access
841 // return the character at position n
2bb67b80 842 wxChar at(size_t n) const { return GetChar(n); }
3c67202d 843 // returns the writable character at position n
2bb67b80 844 wxChar& at(size_t n) { return GetWritableChar(n); }
3c67202d 845
2bc07607
VZ
846 // first valid index position
847 const_iterator begin() const { return wx_str(); }
848 // position one after the last valid one
849 const_iterator end() const { return wx_str() + length(); }
850
3c67202d
VZ
851 // lib.string.modifiers
852 // append a string
853 wxString& append(const wxString& str)
854 { *this += str; return *this; }
855 // append elements str[pos], ..., str[pos+n]
856 wxString& append(const wxString& str, size_t pos, size_t n)
857 { ConcatSelf(n, str.c_str() + pos); return *this; }
858 // append first n (or all if n == npos) characters of sz
2bb67b80
OK
859 wxString& append(const wxChar *sz, size_t n = npos)
860 { ConcatSelf(n == npos ? wxStrlen(sz) : n, sz); return *this; }
3c67202d
VZ
861
862 // append n copies of ch
2bb67b80 863 wxString& append(size_t n, wxChar ch) { return Pad(n, ch); }
3c67202d
VZ
864
865 // same as `this_string = str'
735d1db6
VZ
866 wxString& assign(const wxString& str)
867 { return *this = str; }
3c67202d
VZ
868 // same as ` = str[pos..pos + n]
869 wxString& assign(const wxString& str, size_t pos, size_t n)
735d1db6 870 { Empty(); return Append(str.c_str() + pos, n); }
3c67202d 871 // same as `= first n (or all if n == npos) characters of sz'
2bb67b80 872 wxString& assign(const wxChar *sz, size_t n = npos)
735d1db6 873 { Empty(); return Append(sz, n == npos ? wxStrlen(sz) : n); }
3c67202d 874 // same as `= n copies of ch'
2bb67b80 875 wxString& assign(size_t n, wxChar ch)
735d1db6 876 { Empty(); return Append(ch, n); }
3c67202d
VZ
877
878 // insert another string
879 wxString& insert(size_t nPos, const wxString& str);
880 // insert n chars of str starting at nStart (in str)
881 wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n)
2bb67b80 882 { return insert(nPos, wxString((const wxChar *)str + nStart, n)); }
3c67202d
VZ
883
884 // insert first n (or all if n == npos) characters of sz
2bb67b80 885 wxString& insert(size_t nPos, const wxChar *sz, size_t n = npos)
3c67202d
VZ
886 { return insert(nPos, wxString(sz, n)); }
887 // insert n copies of ch
2bb67b80 888 wxString& insert(size_t nPos, size_t n, wxChar ch)
3c67202d
VZ
889 { return insert(nPos, wxString(ch, n)); }
890
891 // delete characters from nStart to nStart + nLen
892 wxString& erase(size_t nStart = 0, size_t nLen = npos);
893
894 // replaces the substring of length nLen starting at nStart
2bb67b80 895 wxString& replace(size_t nStart, size_t nLen, const wxChar* sz);
3c67202d 896 // replaces the substring with nCount copies of ch
2bb67b80 897 wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxChar ch);
3c67202d
VZ
898 // replaces a substring with another substring
899 wxString& replace(size_t nStart, size_t nLen,
900 const wxString& str, size_t nStart2, size_t nLen2);
901 // replaces the substring with first nCount chars of sz
fb20fa43
VZ
902 wxString& replace(size_t nStart, size_t nLen,
903 const wxChar* sz, size_t nCount);
3c67202d
VZ
904
905 // swap two strings
906 void swap(wxString& str);
907
908 // All find() functions take the nStart argument which specifies the
909 // position to start the search on, the default value is 0. All functions
910 // return npos if there were no match.
911
912 // find a substring
913 size_t find(const wxString& str, size_t nStart = 0) const;
914
915 // VC++ 1.5 can't cope with this syntax.
3f4a0c5b 916#if !defined(__VISUALC__) || defined(__WIN32__)
3c67202d 917 // find first n characters of sz
2bb67b80 918 size_t find(const wxChar* sz, size_t nStart = 0, size_t n = npos) const;
fb20fa43 919#endif // VC++ 1.5
3c67202d
VZ
920
921 // Gives a duplicate symbol (presumably a case-insensitivity problem)
62448488 922#if !defined(__BORLANDC__)
3c67202d 923 // find the first occurence of character ch after nStart
2bb67b80 924 size_t find(wxChar ch, size_t nStart = 0) const;
62448488 925#endif
3c67202d
VZ
926 // rfind() family is exactly like find() but works right to left
927
928 // as find, but from the end
929 size_t rfind(const wxString& str, size_t nStart = npos) const;
930
931 // VC++ 1.5 can't cope with this syntax.
3f4a0c5b 932#if !defined(__VISUALC__) || defined(__WIN32__)
3c67202d 933 // as find, but from the end
2bb67b80 934 size_t rfind(const wxChar* sz, size_t nStart = npos,
3c67202d
VZ
935 size_t n = npos) const;
936 // as find, but from the end
2bb67b80 937 size_t rfind(wxChar ch, size_t nStart = npos) const;
fb20fa43 938#endif // VC++ 1.5
3c67202d
VZ
939
940 // find first/last occurence of any character in the set
941
969d318c
VZ
942 // as strpbrk() but starts at nStart, returns npos if not found
943 size_t find_first_of(const wxString& str, size_t nStart = 0) const
944 { return find_first_of(str.c_str(), nStart); }
945 // same as above
2bb67b80 946 size_t find_first_of(const wxChar* sz, size_t nStart = 0) const;
3c67202d 947 // same as find(char, size_t)
969d318c
VZ
948 size_t find_first_of(wxChar c, size_t nStart = 0) const
949 { return find(c, nStart); }
950 // find the last (starting from nStart) char from str in this string
951 size_t find_last_of (const wxString& str, size_t nStart = npos) const
952 { return find_last_of(str.c_str(), nStart); }
953 // same as above
954 size_t find_last_of (const wxChar* sz, size_t nStart = npos) const;
955 // same as above
956 size_t find_last_of(wxChar c, size_t nStart = npos) const
957 { return rfind(c, nStart); }
3c67202d
VZ
958
959 // find first/last occurence of any character not in the set
960
969d318c
VZ
961 // as strspn() (starting from nStart), returns npos on failure
962 size_t find_first_not_of(const wxString& str, size_t nStart = 0) const
963 { return find_first_not_of(str.c_str(), nStart); }
964 // same as above
965 size_t find_first_not_of(const wxChar* sz, size_t nStart = 0) const;
966 // same as above
2bb67b80 967 size_t find_first_not_of(wxChar ch, size_t nStart = 0) const;
969d318c 968 // as strcspn()
fb20fa43
VZ
969 size_t find_last_not_of(const wxString& str, size_t nStart = npos) const
970 { return find_first_not_of(str.c_str(), nStart); }
969d318c
VZ
971 // same as above
972 size_t find_last_not_of(const wxChar* sz, size_t nStart = npos) const;
973 // same as above
2bb67b80 974 size_t find_last_not_of(wxChar ch, size_t nStart = npos) const;
3c67202d
VZ
975
976 // All compare functions return -1, 0 or 1 if the [sub]string is less,
977 // equal or greater than the compare() argument.
978
979 // just like strcmp()
980 int compare(const wxString& str) const { return Cmp(str); }
981 // comparison with a substring
fb20fa43
VZ
982 int compare(size_t nStart, size_t nLen, const wxString& str) const
983 { return Mid(nStart, nLen).Cmp(str); }
3c67202d
VZ
984 // comparison of 2 substrings
985 int compare(size_t nStart, size_t nLen,
fb20fa43
VZ
986 const wxString& str, size_t nStart2, size_t nLen2) const
987 { return Mid(nStart, nLen).Cmp(str.Mid(nStart2, nLen2)); }
3c67202d 988 // just like strcmp()
2bb67b80 989 int compare(const wxChar* sz) const { return Cmp(sz); }
3c67202d
VZ
990 // substring comparison with first nCount characters of sz
991 int compare(size_t nStart, size_t nLen,
fb20fa43
VZ
992 const wxChar* sz, size_t nCount = npos) const
993 { return Mid(nStart, nLen).Cmp(wxString(sz, nCount)); }
3c67202d
VZ
994
995 // substring extraction
8c264b23
VZ
996 wxString substr(size_t nStart = 0, size_t nLen = npos) const
997 { return Mid(nStart, nLen); }
3c67202d 998#endif // wxSTD_STRING_COMPATIBILITY
c801d85f
KB
999};
1000
1001// ----------------------------------------------------------------------------
3c67202d
VZ
1002// The string array uses it's knowledge of internal structure of the wxString
1003// class to optimize string storage. Normally, we would store pointers to
1004// string, but as wxString is, in fact, itself a pointer (sizeof(wxString) is
1005// sizeof(char *)) we store these pointers instead. The cast to "wxString *" is
1006// really all we need to turn such pointer into a string!
1007//
1008// Of course, it can be called a dirty hack, but we use twice less memory and
1009// this approach is also more speed efficient, so it's probably worth it.
1010//
1011// Usage notes: when a string is added/inserted, a new copy of it is created,
1012// so the original string may be safely deleted. When a string is retrieved
1013// from the array (operator[] or Item() method), a reference is returned.
c801d85f 1014// ----------------------------------------------------------------------------
e90c1d2a 1015
fbcb4166 1016class WXDLLEXPORT wxArrayString
c801d85f
KB
1017{
1018public:
30b21f9a
VZ
1019 // type of function used by wxArrayString::Sort()
1020 typedef int (*CompareFunction)(const wxString& first,
1021 const wxString& second);
1022
3c67202d 1023 // constructors and destructor
0fe1f685 1024 // default ctor
b1801e0e
GD
1025 wxArrayString()
1026 : m_nSize(0), m_nCount(0), m_pItems(NULL), m_autoSort(FALSE)
1027 { Init(FALSE); }
0fe1f685
VZ
1028 // if autoSort is TRUE, the array is always sorted (in alphabetical order)
1029 //
1030 // NB: the reason for using int and not bool is that like this we can avoid
1031 // using this ctor for implicit conversions from "const char *" (which
1032 // we'd like to be implicitly converted to wxString instead!)
1033 //
1034 // of course, using explicit would be even better - if all compilers
1035 // supported it...
b1801e0e
GD
1036 wxArrayString(int autoSort)
1037 : m_nSize(0), m_nCount(0), m_pItems(NULL), m_autoSort(FALSE)
1038 { Init(autoSort != 0); }
3c67202d 1039 // copy ctor
c801d85f 1040 wxArrayString(const wxArrayString& array);
3c67202d 1041 // assignment operator
c801d85f 1042 wxArrayString& operator=(const wxArrayString& src);
3c67202d 1043 // not virtual, this class should not be derived from
c801d85f 1044 ~wxArrayString();
c801d85f 1045
3c67202d
VZ
1046 // memory management
1047 // empties the list, but doesn't release memory
c801d85f 1048 void Empty();
3c67202d 1049 // empties the list and releases memory
c801d85f 1050 void Clear();
3c67202d 1051 // preallocates memory for given number of items
c801d85f 1052 void Alloc(size_t nCount);
3c67202d 1053 // minimzes the memory usage (by freeing all extra memory)
dd1eaa89 1054 void Shrink();
3c67202d
VZ
1055
1056 // simple accessors
1057 // number of elements in the array
1058 size_t GetCount() const { return m_nCount; }
1059 // is it empty?
1060 bool IsEmpty() const { return m_nCount == 0; }
1061 // number of elements in the array (GetCount is preferred API)
1062 size_t Count() const { return m_nCount; }
1063
1064 // items access (range checking is done in debug version)
1065 // get item at position uiIndex
c801d85f 1066 wxString& Item(size_t nIndex) const
09443a26
VZ
1067 {
1068 wxASSERT_MSG( nIndex < m_nCount,
1069 _T("wxArrayString: index out of bounds") );
1070
1071 return *(wxString *)&(m_pItems[nIndex]);
1072 }
1073
3c67202d 1074 // same as Item()
c801d85f 1075 wxString& operator[](size_t nIndex) const { return Item(nIndex); }
3c67202d 1076 // get last item
09443a26
VZ
1077 wxString& Last() const
1078 {
1079 wxASSERT_MSG( !IsEmpty(),
1080 _T("wxArrayString: index out of bounds") );
1081 return Item(Count() - 1);
1082 }
3c67202d 1083
9d155f50
RL
1084 // return a wxString[], useful for the controls which
1085 // take one in their ctor. You must delete[] it yourself
1086 // once you are done with it. Will return NULL if the
1087 // ArrayString was empty.
1088 wxString* GetStringArray() const;
1089
3c67202d
VZ
1090 // item management
1091 // Search the element in the array, starting from the beginning if
1092 // bFromEnd is FALSE or from end otherwise. If bCase, comparison is case
1093 // sensitive (default). Returns index of the first item matched or
1094 // wxNOT_FOUND
2bb67b80 1095 int Index (const wxChar *sz, bool bCase = TRUE, bool bFromEnd = FALSE) const;
e01c8145
VZ
1096 // add new element at the end (if the array is not sorted), return its
1097 // index
2a39c386 1098 size_t Add(const wxString& str, size_t nInsert = 1);
3c67202d 1099 // add new element at given position
2a39c386 1100 void Insert(const wxString& str, size_t uiIndex, size_t nInsert = 1);
71e03035
VZ
1101 // expand the array to have count elements
1102 void SetCount(size_t count);
3c67202d 1103 // remove first item matching this value
2bb67b80 1104 void Remove(const wxChar *sz);
3c67202d 1105 // remove item by index
2a39c386
VZ
1106 void Remove(size_t nIndex, size_t nRemove = 1);
1107 void RemoveAt(size_t nIndex, size_t nRemove = 1) { Remove(nIndex, nRemove); }
c801d85f 1108
30b21f9a
VZ
1109 // sorting
1110 // sort array elements in alphabetical order (or reversed alphabetical
1111 // order if reverseOrder parameter is TRUE)
1112 void Sort(bool reverseOrder = FALSE);
1113 // sort array elements using specified comparaison function
1114 void Sort(CompareFunction compareFunction);
c801d85f 1115
f6bcfd97
BP
1116 // comparison
1117 // compare two arrays case sensitively
1118 bool operator==(const wxArrayString& a) const;
1119 // compare two arrays case sensitively
1120 bool operator!=(const wxArrayString& a) const { return !(*this == a); }
1121
e87271f3 1122protected:
0fe1f685 1123 void Init(bool autoSort); // common part of all ctors
e87271f3
VZ
1124 void Copy(const wxArrayString& src); // copies the contents of another array
1125
c801d85f 1126private:
2a39c386 1127 void Grow(size_t nIncrement = 0); // makes array bigger if needed
e87271f3 1128 void Free(); // free all the strings stored
c801d85f 1129
e87271f3 1130 void DoSort(); // common part of all Sort() variants
30b21f9a 1131
3c67202d 1132 size_t m_nSize, // current size of the array
c801d85f
KB
1133 m_nCount; // current number of elements
1134
e87271f3
VZ
1135 wxChar **m_pItems; // pointer to data
1136
1137 bool m_autoSort; // if TRUE, keep the array always sorted
1138};
1139
1140class WXDLLEXPORT wxSortedArrayString : public wxArrayString
1141{
1142public:
1143 wxSortedArrayString() : wxArrayString(TRUE)
1144 { }
1145 wxSortedArrayString(const wxArrayString& array) : wxArrayString(TRUE)
1146 { Copy(array); }
c801d85f
KB
1147};
1148
1d218550
VZ
1149// ----------------------------------------------------------------------------
1150// wxStringBuffer: a tiny class allowing to get a writable pointer into string
1151// ----------------------------------------------------------------------------
1152
1153class WXDLLEXPORT wxStringBuffer
1154{
1155public:
1156 wxStringBuffer(wxString& str, size_t lenWanted = 1024)
b1801e0e
GD
1157 : m_str(str), m_buf(NULL)
1158 { m_buf = m_str.GetWriteBuf(lenWanted); }
e015c2a3 1159
1d218550 1160 ~wxStringBuffer() { m_str.UngetWriteBuf(); }
e015c2a3 1161
1d218550 1162 operator wxChar*() const { return m_buf; }
e015c2a3 1163
1d218550
VZ
1164private:
1165 wxString& m_str;
1166 wxChar *m_buf;
e015c2a3
VZ
1167
1168 DECLARE_NO_COPY_CLASS(wxStringBuffer)
1d218550
VZ
1169};
1170
c801d85f 1171// ---------------------------------------------------------------------------
3c67202d 1172// wxString comparison functions: operator versions are always case sensitive
c801d85f 1173// ---------------------------------------------------------------------------
f33fee2a 1174
0cbe5ee3
VZ
1175inline bool operator==(const wxString& s1, const wxString& s2)
1176 { return (s1.Len() == s2.Len()) && (s1.Cmp(s2) == 0); }
1177inline bool operator==(const wxString& s1, const wxChar * s2)
1178 { return s1.Cmp(s2) == 0; }
1179inline bool operator==(const wxChar * s1, const wxString& s2)
1180 { return s2.Cmp(s1) == 0; }
1181inline bool operator!=(const wxString& s1, const wxString& s2)
1182 { return (s1.Len() != s2.Len()) || (s1.Cmp(s2) != 0); }
1183inline bool operator!=(const wxString& s1, const wxChar * s2)
1184 { return s1.Cmp(s2) != 0; }
1185inline bool operator!=(const wxChar * s1, const wxString& s2)
1186 { return s2.Cmp(s1) != 0; }
1187inline bool operator< (const wxString& s1, const wxString& s2)
1188 { return s1.Cmp(s2) < 0; }
1189inline bool operator< (const wxString& s1, const wxChar * s2)
1190 { return s1.Cmp(s2) < 0; }
1191inline bool operator< (const wxChar * s1, const wxString& s2)
1192 { return s2.Cmp(s1) > 0; }
1193inline bool operator> (const wxString& s1, const wxString& s2)
1194 { return s1.Cmp(s2) > 0; }
1195inline bool operator> (const wxString& s1, const wxChar * s2)
1196 { return s1.Cmp(s2) > 0; }
1197inline bool operator> (const wxChar * s1, const wxString& s2)
1198 { return s2.Cmp(s1) < 0; }
1199inline bool operator<=(const wxString& s1, const wxString& s2)
1200 { return s1.Cmp(s2) <= 0; }
1201inline bool operator<=(const wxString& s1, const wxChar * s2)
1202 { return s1.Cmp(s2) <= 0; }
1203inline bool operator<=(const wxChar * s1, const wxString& s2)
1204 { return s2.Cmp(s1) >= 0; }
1205inline bool operator>=(const wxString& s1, const wxString& s2)
1206 { return s1.Cmp(s2) >= 0; }
1207inline bool operator>=(const wxString& s1, const wxChar * s2)
1208 { return s1.Cmp(s2) >= 0; }
1209inline bool operator>=(const wxChar * s1, const wxString& s2)
1210 { return s2.Cmp(s1) <= 0; }
3c67202d 1211
f33fee2a
VZ
1212// comparison with char
1213inline bool operator==(wxChar c, const wxString& s) { return s.IsSameAs(c); }
1214inline bool operator==(const wxString& s, wxChar c) { return s.IsSameAs(c); }
1215inline bool operator!=(wxChar c, const wxString& s) { return !s.IsSameAs(c); }
1216inline bool operator!=(const wxString& s, wxChar c) { return !s.IsSameAs(c); }
1217
5ca07d0f
OK
1218#if wxUSE_UNICODE
1219inline bool operator==(const wxString& s1, const wxWCharBuffer& s2)
f33fee2a 1220 { return (s1.Cmp((const wchar_t *)s2) == 0); }
5ca07d0f 1221inline bool operator==(const wxWCharBuffer& s1, const wxString& s2)
f33fee2a 1222 { return (s2.Cmp((const wchar_t *)s1) == 0); }
f6bcfd97
BP
1223inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2)
1224 { return (s1.Cmp((const wchar_t *)s2) != 0); }
1225inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2)
1226 { return (s2.Cmp((const wchar_t *)s1) != 0); }
0cbe5ee3 1227#else // !wxUSE_UNICODE
5ca07d0f 1228inline bool operator==(const wxString& s1, const wxCharBuffer& s2)
f33fee2a 1229 { return (s1.Cmp((const char *)s2) == 0); }
5ca07d0f 1230inline bool operator==(const wxCharBuffer& s1, const wxString& s2)
f33fee2a 1231 { return (s2.Cmp((const char *)s1) == 0); }
f6bcfd97
BP
1232inline bool operator!=(const wxString& s1, const wxCharBuffer& s2)
1233 { return (s1.Cmp((const char *)s2) != 0); }
1234inline bool operator!=(const wxCharBuffer& s1, const wxString& s2)
1235 { return (s2.Cmp((const char *)s1) != 0); }
0cbe5ee3 1236#endif // wxUSE_UNICODE/!wxUSE_UNICODE
5ca07d0f 1237
ed7174ba 1238wxString WXDLLEXPORT operator+(const wxString& string1, const wxString& string2);
2bb67b80
OK
1239wxString WXDLLEXPORT operator+(const wxString& string, wxChar ch);
1240wxString WXDLLEXPORT operator+(wxChar ch, const wxString& string);
1241wxString WXDLLEXPORT operator+(const wxString& string, const wxChar *psz);
1242wxString WXDLLEXPORT operator+(const wxChar *psz, const wxString& string);
028a2b5d 1243#if wxUSE_UNICODE
6d56eb5c 1244inline wxString operator+(const wxString& string, const wxWCharBuffer& buf)
e90c1d2a 1245 { return string + (const wchar_t *)buf; }
6d56eb5c 1246inline wxString operator+(const wxWCharBuffer& buf, const wxString& string)
e90c1d2a 1247 { return (const wchar_t *)buf + string; }
0cbe5ee3 1248#else // !wxUSE_UNICODE
6d56eb5c 1249inline wxString operator+(const wxString& string, const wxCharBuffer& buf)
e90c1d2a 1250 { return string + (const char *)buf; }
6d56eb5c 1251inline wxString operator+(const wxCharBuffer& buf, const wxString& string)
e90c1d2a 1252 { return (const char *)buf + string; }
0cbe5ee3 1253#endif // wxUSE_UNICODE/!wxUSE_UNICODE
f04f3991 1254
c801d85f 1255// ---------------------------------------------------------------------------
3c67202d 1256// Implementation only from here until the end of file
c801d85f
KB
1257// ---------------------------------------------------------------------------
1258
e90c1d2a 1259// don't pollute the library user's name space
5737d05f 1260#undef wxASSERT_VALID_INDEX
e90c1d2a 1261
38830220 1262#if defined(wxSTD_STRING_COMPATIBILITY) && wxUSE_STD_IOSTREAM
c801d85f 1263
3f4a0c5b 1264#include "wx/ioswrap.h"
c801d85f 1265
dd107c50
VZ
1266WXDLLEXPORT wxSTD istream& operator>>(wxSTD istream&, wxString&);
1267WXDLLEXPORT wxSTD ostream& operator<<(wxSTD ostream&, const wxString&);
c801d85f 1268
3c67202d 1269#endif // wxSTD_STRING_COMPATIBILITY
c801d85f 1270
34138703 1271#endif // _WX_WXSTRINGH__