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