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