]> git.saurik.com Git - wxWidgets.git/blob - interface/string.h
remove extra semicolons, correct virtual access
[wxWidgets.git] / interface / string.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: string.h
3 // Purpose: interface of wxStringBuffer
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxStringBuffer
11 @wxheader{string.h}
12
13 This tiny class allows to conveniently access the wxString
14 internal buffer as a writable pointer without any risk of forgetting to restore
15 the string to the usable state later.
16
17 For example, assuming you have a low-level OS function called
18 @c GetMeaningOfLifeAsString(char *) returning the value in the provided
19 buffer (which must be writable, of course) you might call it like this:
20
21 @code
22 wxString theAnswer;
23 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
24 if ( theAnswer != "42" )
25 {
26 wxLogError("Something is very wrong!");
27 }
28 @endcode
29
30 Note that the exact usage of this depends on whether on not wxUSE_STL is
31 enabled. If
32 wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
33 and
34 if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
35 buffer
36 wxString uses intact. In other words, relying on wxStringBuffer containing the
37 old
38 wxString data is probably not a good idea if you want to build your program in
39 both
40 with and without wxUSE_STL.
41
42 @library{wxbase}
43 @category{FIXME}
44 */
45 class wxStringBuffer
46 {
47 public:
48 /**
49 Constructs a writable string buffer object associated with the given string
50 and containing enough space for at least @a len characters. Basically, this
51 is equivalent to calling wxString::GetWriteBuf and
52 saving the result.
53 */
54 wxStringBuffer(const wxString& str, size_t len);
55
56 /**
57 Restores the string passed to the constructor to the usable state by calling
58 wxString::UngetWriteBuf on it.
59 */
60 ~wxStringBuffer();
61
62 /**
63 Returns the writable pointer to a buffer of the size at least equal to the
64 length specified in the constructor.
65 */
66 wxStringCharType* operator wxStringCharType *();
67 };
68
69
70
71 /**
72 @class wxString
73 @wxheader{string.h}
74
75 wxString is a class representing a Unicode character string.
76 wxString uses @c std::string internally to store its content
77 unless this is not supported by the compiler or disabled
78 specifically when building wxWidgets. Therefore wxString
79 inherits many features from @c std::string's. Most
80 implementations of @std::string are thread-safe and don't
81 use reference counting. By default, wxString uses @c std::string
82 internally even if wxUSE_STL is not defined.
83
84 Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per
85 character wchar_t) under Windows and UTF-8 under Unix, Linux and
86 OS X to store its content. Much work has been done to make existing
87 code using ANSI string literals work as before. If you need to have a
88 wxString that uses wchar_t on Unix and Linux, too, you can specify
89 this on the command line with the @c configure @c --disable-utf8 switch.
90
91 As a consequence of this change, iterating over a wxString by index
92 can become inefficient in UTF8 mode and iterators should be used instead:
93
94 @code
95 wxString s = "hello";
96 wxString::const_iterator i;
97 for (i = s.begin(); i != s.end(); ++i)
98 {
99 wxUniChar uni_ch = *i;
100 // do something with it
101 }
102 @endcode
103
104 Please see the
105 @ref overview_string "wxString overview" and the
106 @ref overview_unicode "Unicode overview" for more information
107 about it.
108
109 wxString uses the current locale encoding to convert any C string
110 literal to Unicode. The same is done for converting to and from
111 @c std::string and for the return value of c_str(). For this
112 conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv.
113
114 wxString implements most of the methods of the @c std::string class.
115 These standard functions are only listed here, but they are not
116 fully documented in this manual. Please see the STL documentation.
117 The behaviour of all these functions is identical to the behaviour
118 described there.
119
120 You may notice that wxString sometimes has several functions which do
121 the same thing like, for example, Length(), Len() and length() which
122 all return the string length. In all cases of such duplication the
123 @c std::string compatible method should be used.
124
125 Anything may be concatenated (appended to) with a string. However, you can't
126 append something to a C string (including literal constants), so to do this it
127 should be converted to a wxString first.
128
129 @li operator<<()
130 @li operator+=()
131 @li operator+()
132 @li Append()
133 @li Prepend()
134
135 A string may be constructed either from a C string, (some number of copies of)
136 a single character or a wide (UNICODE) string. For all constructors (except the
137 default which creates an empty string) there is also a corresponding assignment
138 operator.
139
140 @li wxString()
141 @li operator=()
142 @li ~wxString()
143
144 The MakeXXX() variants modify the string in place, while the other functions
145 return a new string which contains the original text converted to the upper or
146 lower case and leave the original string unchanged.
147
148 @li MakeUpper()
149 @li Upper()
150 @li MakeLower()
151 @li Lower()
152
153 Many functions in this section take a character index in the string. As with C
154 strings and/or arrays, the indices start from 0, so the first character of a
155 string is string[0]. Attempt to access a character beyond the end of the
156 string (which may be even 0 if the string is empty) will provoke an assert
157 failure in @ref overview_debugging "debug build", but no checks are
158 done in release builds.
159 This section also contains both implicit and explicit conversions to C style
160 strings. Although implicit conversion is quite convenient, it is advised to use
161 explicit c_str() method for the sake of clarity.
162
163 @li GetChar()
164 @li GetWritableChar()
165 @li SetChar()
166 @li Last()
167 @li operator[]()
168 @li c_str()
169 @li mb_str()
170 @li wc_str()
171 @li fn_str()
172
173 The default comparison function Cmp() is case-sensitive and
174 so is the default version of IsSameAs(). For case
175 insensitive comparisons you should use CmpNoCase() or
176 give a second parameter to IsSameAs. This last function is may be more
177 convenient if only equality of the strings matters because it returns a boolean
178 @true value if the strings are the same and not 0 (which is usually @false
179 in C)as Cmp() does.
180 Matches() is a poor man's regular expression matcher: it only understands
181 '*' and '?' metacharacters in the sense of DOS command line interpreter.
182 StartsWith() is helpful when parsing a line of text which should start
183 with some predefined prefix and is more efficient than doing direct string
184 comparison as you would also have to precalculate the length of the prefix then.
185
186 @li Cmp()
187 @li CmpNoCase()
188 @li IsSameAs()
189 @li Matches()
190 @li StartsWith()
191 @li EndsWith()
192
193 The string provides functions for conversion to signed and unsigned integer and
194 floating point numbers. All three functions take a pointer to the variable to
195 put the numeric value in and return @true if the @b entire string could be
196 converted to a number.
197
198 @li ToLong()
199 @li ToLongLong()
200 @li ToULong()
201 @li ToULongLong()
202 @li ToDouble()
203
204 These are "advanced" functions and they will be needed quite rarely.
205 Alloc() and Shrink() are only interesting for optimization purposes.
206 wxStringBuffer and wxStringBufferLength classes may be very useful
207 when working with some external API which requires the caller to provide
208 a writable buffer.
209
210 @li Alloc()
211 @li Shrink()
212 @li wxStringBuffer
213 @li wxStringBufferLength
214
215 Misc. other string functions.
216
217 @li Trim()
218 @li Truncate()
219 @li Pad()
220
221 These functions return the string length and check whether the string
222 is empty or empty it.
223
224 @li Len()
225 @li IsEmpty()
226 @li operator!()
227 @li Empty()
228 @li Clear()
229
230
231 These functions allow to extract substring from this string. All of them don't
232 modify the original string and return a new string containing the extracted
233 substring.
234
235 @li Mid()
236 @li operator()()
237 @li Left()
238 @li Right()
239 @li BeforeFirst()
240 @li BeforeLast()
241 @li AfterFirst()
242 @li AfterLast()
243 @li StartsWith()
244 @li EndsWith()
245
246 These functions replace the standard @e strchr() and @e strstr()
247 functions.
248
249 @li Find()
250 @li Replace()
251
252 Both formatted versions (Printf/() and stream-like insertion operators
253 exist (for basic types only). Additionally, the Format() function allows
254 to use simply append formatted value to a string:
255
256 @li Format()
257 @li FormatV()
258 @li Printf()
259 @li PrintfV()
260 @li operator>>()
261
262 These functions are deprecated, please consider using new wxWidgets 2.0
263 functions instead of them (or, even better, std::string compatible variants).
264
265 Contains(), First(), Freq(), IsAscii(), IsNull(),
266 IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
267 SubString(), UpperCase()
268
269 @library{wxbase}
270 @category{data}
271
272 @stdobjects
273 ::Objects:, ::wxEmptyString,
274
275 @see @ref overview_string "wxString overview", @ref overview_unicode
276 "Unicode overview"
277 */
278 class wxString
279 {
280 public:
281 /**
282 An 'invalid' value for string index
283 */
284 static const size_t npos;
285
286 /**
287 @name Standard types
288 */
289 //@{
290 typedef wxUniChar value_type;
291 typedef wxUniChar char_type;
292 typedef wxUniCharRef reference;
293 typedef wxChar* pointer;
294 typedef const wxChar* const_pointer;
295 typedef size_t size_type;
296 typedef wxUniChar const_reference;
297 //@}
298
299 /**
300 Default constructor
301 */
302 wxString();
303
304 /**
305 Creates a string from another string. Just increases the ref
306 count by 1.
307 */
308 wxString(const wxString& stringSrc);
309
310
311 /**
312 Constructs a string from the string literal @c psz using
313 the current locale encoding to convert it to Unicode (wxConvLibc).
314 */
315 wxString(const char *psz);
316
317 /**
318 Constructs a string from the string literal @c psz using
319 @c conv to convert it Unicode.
320 */
321 wxString(const char *psz, const wxMBConv& conv);
322
323 /**
324 Constructs a string from the first @ nLength character of the string literal @c psz using
325 the current locale encoding to convert it to Unicode (wxConvLibc).
326 */
327 wxString(const char *psz, size_t nLength);
328
329 /**
330 Constructs a string from the first @ nLength character of the string literal @c psz using
331 @c conv to convert it Unicode.
332 */
333 wxString(const char *psz, const wxMBConv& conv, size_t nLength);
334
335 /**
336 Constructs a string from the string literal @c pwz.
337 */
338 wxString(const wchar_t *pwz);
339
340 /**
341 Constructs a string from the first @ nLength characters of the string literal @c pwz.
342 */
343 wxString(const wchar_t *pwz, size_t nLength);
344
345 /**
346 Constructs a string from @c buf using the using
347 the current locale encoding to convert it to Unicode.
348 */
349 wxString(const wxCharBuffer& buf);
350
351 /**
352 Constructs a string from @c buf.
353 */
354 wxString(const wxWCharBuffer& buf);
355
356 /**
357 Constructs a string from @str using the using the current locale encoding
358 to convert it to Unicode (wxConvLibc).
359 */
360 wxString(const std::string& str);
361
362 /**
363 Constructs a string from @str.
364 */
365 wxString(const std::wstring& str);
366
367
368 /**
369 String destructor. Note that this is not virtual, so wxString must not be
370 inherited from.
371 */
372 ~wxString();
373
374 /**
375 Gets all the characters after the first occurrence of @e ch.
376 Returns the empty string if @a ch is not found.
377 */
378 wxString AfterFirst(wxUniChar ch) const;
379
380 /**
381 Gets all the characters after the last occurrence of @e ch.
382 Returns the whole string if @a ch is not found.
383 */
384 wxString AfterLast(wxUniChar ch) const;
385
386 /**
387 Preallocate enough space for wxString to store @a nLen characters.
388
389 Please note that this method does the same thing as the standard
390 reserve() one and shouldn't be used in new code.
391
392 This function may be used to increase speed when the string is
393 constructed by repeated concatenation as in
394
395 @code
396 // delete all vowels from the string
397 wxString DeleteAllVowels(const wxString& original)
398 {
399 wxString result;
400
401 size_t len = original.length();
402
403 result.Alloc(len);
404
405 for ( size_t n = 0; n < len; n++ )
406 {
407 if ( strchr("aeuio", tolower(original[n])) == NULL )
408 result += original[n];
409 }
410
411 return result;
412 }
413 @endcode
414
415 because it will avoid the need to reallocate string memory many times
416 (in case of long strings). Note that it does not set the maximal length
417 of a string -- it will still expand if more than @a nLen characters are
418 stored in it. Also, it does not truncate the existing string (use
419 Truncate() for this) even if its current length is greater than @a nLen.
420
421 @return @true if memory was successfully allocated, @false otherwise.
422 */
423 bool Alloc(size_t nLen);
424
425 //@{
426 /**
427 Appends the string or string literal or character.
428 */
429 wxString& Append(const char* psz, size_t nLen);
430 wxString& Append(const wchar_t* pwz, size_t nLen)
431 wxString &Append(const wxString &s);
432 wxString &Append(wxUniChar ch, size_t count = 1u);
433 //@}
434
435 /**
436 Gets all characters before the first occurrence of @e ch.
437 Returns the whole string if @a ch is not found.
438 */
439 wxString BeforeFirst(wxUniChar ch) const;
440
441 /**
442 Gets all characters before the last occurrence of @e ch.
443 Returns the empty string if @a ch is not found.
444 */
445 wxString BeforeLast(wxUniChar ch) const;
446
447
448 /**
449 Empties the string and frees memory occupied by it.
450 See also: Empty()
451 */
452 void Clear();
453
454 /**
455 Returns a deep copy of the string.
456
457 That is, the returned string is guaranteed to not share data with this
458 string when using reference-counted wxString implementation.
459
460 This method is primarily useful for passing strings between threads
461 (because wxString is not thread-safe). Unlike creating a copy using
462 @c wxString(c_str()), Clone() handles embedded NULs correctly.
463
464 @since 2.9.0
465 */
466 wxString Clone() const;
467
468 /**
469 Case-sensitive comparison.
470 Returns a positive value if the string is greater than the argument,
471 zero if it is equal to it or a negative value if it is less than the
472 argument (same semantics as the standard @e strcmp() function).
473
474 See also CmpNoCase(), IsSameAs().
475 */
476 int Cmp(const wxString& s) const;
477
478 /**
479 Case-insensitive comparison.
480 Returns a positive value if the string is greater than the argument,
481 zero if it is equal to it or a negative value if it is less than the
482 argument (same semantics as the standard @e strcmp() function).
483
484 See also Cmp(), IsSameAs().
485 */
486 int CmpNoCase(const wxString& s) const;
487
488
489 //@{
490 /**
491 Comparison operators
492 */
493 bool operator ==(const wxString& x, const wxString& y);
494 bool operator ==(const wxString& x, wxUniChar ch);
495 bool operator !=(const wxString& x, const wxString& y);
496 bool operator !=(const wxString& x, wxUniChar ch);
497 bool operator(const wxString& x, const wxString& y);
498 bool operator(const wxString& x, wxUniChar ch);
499 bool operator =(const wxString& x, const wxString& y);
500 bool operator =(const wxString& x, wxUniChar ch);
501 bool operator(const wxString& x, const wxString& y);
502 bool operator(const wxString& x, wxUniChar ch);
503 bool operator =(const wxString& x, const wxString& y);
504 bool operator =(const wxString& x, wxUniChar ch);
505 //@}
506
507
508 /**
509 Returns @true if target appears anywhere in wxString; else @false.
510 This is a wxWidgets 1.xx compatibility function; you should not use it in new
511 code.
512 */
513 bool Contains(const wxString& str) const;
514
515
516 /**
517 Makes the string empty, but doesn't free memory occupied by the string.
518 See also: Clear().
519 */
520 void Empty();
521
522 /**
523 This function can be used to test if the string ends with the specified
524 @e suffix. If it does, the function will return @true and put the
525 beginning of the string before the suffix into @a rest string if it is not
526 @NULL. Otherwise, the function returns @false and doesn't
527 modify the @e rest.
528 */
529 bool EndsWith(const wxString& suffix, wxString rest = NULL) const;
530
531 //@{
532 /**
533 Searches for the given string. Returns the starting index, or
534 @c wxNOT_FOUND if not found.
535 */
536 int Find(wxUniChar ch, bool fromEnd = false) const;
537 int Find(const wxString& sub) const;
538 //@}
539
540 //@{
541 /**
542 Same as Find().
543 This is a wxWidgets 1.xx compatibility function;
544 you should not use it in new code.
545 */
546 int First(wxUniChar ch) const;
547 int First(const wxString& str) const;
548 //@}
549
550 /**
551 This static function returns the string containing the result of calling
552 Printf() with the passed parameters on it.
553
554 @see FormatV(), Printf()
555 */
556 static wxString Format(const wxChar format, ...);
557
558 /**
559 This static function returns the string containing the result of calling
560 PrintfV() with the passed parameters on it.
561
562 @see Format(), PrintfV()
563 */
564 static wxString FormatV(const wxChar format, va_list argptr);
565
566 /**
567 Returns the number of occurrences of @a ch in the string.
568 This is a wxWidgets 1.xx compatibility function; you should not use it in new
569 code.
570 */
571 int Freq(wxUniChar ch) const;
572
573 //@{
574 /**
575 Converts given buffer of binary data from 8-bit string to wxString. In
576 Unicode build, the string is interpreted as being in ISO-8859-1
577 encoding. The version without @a len parameter takes NUL-terminated
578 data.
579
580 This is a convenience method useful when storing binary data in
581 wxString. It should be used @em only for that purpose and only in
582 conjunction with To8BitData(). Use mb_str() for conversion of character
583 data to known encoding.
584
585 @since 2.8.4
586
587 @see wxString::To8BitData()
588 */
589 static wxString From8BitData(const char* buf, size_t len);
590 static wxString From8BitData(const char* buf);
591 //@}
592
593 //@{
594 /**
595 Converts the string or character from an ASCII, 7-bit form
596 to the native wxString representation.
597 */
598 static wxString FromAscii(const char* s);
599 static wxString FromAscii(const unsigned char* s);
600 static wxString FromAscii(const char* s, size_t len);
601 static wxString FromAscii(const unsigned char* s, size_t len);
602 static wxString FromAscii(char c);
603 //@}
604
605 //@{
606 /**
607 Converts C string encoded in UTF-8 to wxString.
608 Note that this method assumes that @a s is a valid UTF-8 sequence and
609 doesn't do any validation in release builds, it's validity is only checked in
610 debug builds.
611 */
612 static wxString FromUTF8(const char* s);
613 static wxString FromUTF8(const char* s, size_t len);
614 //@}
615
616 /**
617 Returns the character at position @a n (read-only).
618 */
619 wxUniChar GetChar(size_t n) const;
620
621 /**
622 wxWidgets compatibility conversion. Same as c_str().
623 */
624 const wxCStrData* GetData() const;
625
626 /**
627 Returns a reference to the character at position @e n.
628 */
629 wxUniCharRef GetWritableChar(size_t n);
630
631 /**
632 Returns a writable buffer of at least @a len bytes.
633 It returns a pointer to a new memory block, and the
634 existing data will not be copied.
635 Call UngetWriteBuf() as soon as possible to put the
636 string back into a reasonable state.
637 This method is deprecated, please use wxStringBuffer or
638 wxStringBufferLength instead.
639 */
640 wxStringCharType* GetWriteBuf(size_t len);
641
642 /**
643 Returns @true if the string contains only ASCII characters.
644 This is a wxWidgets 1.xx compatibility function; you should not use it in new
645 code.
646 */
647 bool IsAscii() const;
648
649 /**
650 Returns @true if the string is empty.
651 */
652 bool IsEmpty() const;
653
654 /**
655 Returns @true if the string is empty (same as wxString::IsEmpty).
656 This is a wxWidgets 1.xx compatibility function; you should not use it in new
657 code.
658 */
659 bool IsNull() const;
660
661 /**
662 Returns @true if the string is an integer (with possible sign).
663 This is a wxWidgets 1.xx compatibility function; you should not use it in new
664 code.
665 */
666 bool IsNumber() const;
667
668 //@{
669 /**
670 Test whether the string is equal to the single character @e c. The test is
671 case-sensitive if @a caseSensitive is @true (default) or not if it is @c
672 @false.
673 Returns @true if the string is equal to the character, @false otherwise.
674 See also Cmp(), CmpNoCase()
675 */
676 bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
677 bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
678 //@}
679
680 /**
681 Returns @true if the string is a word.
682 This is a wxWidgets 1.xx compatibility function; you should not use it in new
683 code.
684 */
685 bool IsWord() const;
686
687 //@{
688 /**
689 Returns a reference to the last character (writable).
690 This is a wxWidgets 1.xx compatibility function;
691 you should not use it in new code.
692 */
693 wxUniCharRef Last();
694 const wxUniChar Last();
695 //@}
696
697 /**
698 Returns the first @a count characters of the string.
699 */
700 wxString Left(size_t count) const;
701
702 /**
703 Returns the length of the string.
704 */
705 size_t Len() const;
706
707 /**
708 Returns the length of the string (same as Len).
709 This is a wxWidgets 1.xx compatibility function; you should not use it in new
710 code.
711 */
712 size_t Length() const;
713
714 /**
715 Returns this string converted to the lower case.
716 */
717 wxString Lower() const;
718
719 /**
720 Same as MakeLower.
721 This is a wxWidgets 1.xx compatibility function; you should not use it in new
722 code.
723 */
724 void LowerCase();
725
726 /**
727 Converts all characters to lower case and returns the result.
728 */
729 wxString& MakeLower();
730
731 /**
732 Converts all characters to upper case and returns the result.
733 */
734 wxString& MakeUpper();
735
736 /**
737 Returns @true if the string contents matches a mask containing '*' and '?'.
738 */
739 bool Matches(const wxString& mask) const;
740
741 /**
742 Returns a substring starting at @e first, with length @e count, or the rest of
743 the string if @a count is the default value.
744 */
745 wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const;
746
747
748 /**
749 Adds @a count copies of @a pad to the beginning, or to the end of the
750 string (the default). Removes spaces from the left or from the right (default).
751 */
752 wxString& Pad(size_t count, wxUniChar pad = ' ',
753 bool fromRight = true);
754
755 /**
756 Prepends @a str to this string, returning a reference to this string.
757 */
758 wxString& Prepend(const wxString& str);
759
760 /**
761 Similar to the standard function @e sprintf(). Returns the number of
762 characters written, or an integer less than zero on error.
763 Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
764 Unix98-style positional parameters:
765
766 @note This function will use a safe version of @e vsprintf() (usually called
767 @e vsnprintf()) whenever available to always allocate the buffer of correct
768 size. Unfortunately, this function is not available on all platforms and the
769 dangerous @e vsprintf() will be used then which may lead to buffer overflows.
770 */
771 int Printf(const wxChar* pszFormat, ...);
772
773 /**
774 Similar to vprintf. Returns the number of characters written, or an integer
775 less than zero
776 on error.
777 */
778 int PrintfV(const wxChar* pszFormat, va_list argPtr);
779
780 //@{
781 /**
782 Removes @a len characters from the string, starting at @e pos.
783 This is a wxWidgets 1.xx compatibility function; you should not use it in new
784 code.
785 */
786 wxString Remove(size_t pos);
787 wxString Remove(size_t pos, size_t len);
788 //@}
789
790 /**
791 Removes the last character.
792 */
793 wxString RemoveLast();
794
795 /**
796 Replace first (or all) occurrences of substring with another one.
797 @e replaceAll: global replace (default), or only the first occurrence.
798 Returns the number of replacements made.
799 */
800 size_t Replace(const wxString& strOld, const wxString& strNew,
801 bool replaceAll = true);
802
803 /**
804 Returns the last @a count characters.
805 */
806 wxString Right(size_t count) const;
807
808 /**
809 Sets the character at position @e n.
810 */
811 void SetChar(size_t n, wxUniChar ch);
812
813 /**
814 Minimizes the string's memory. This can be useful after a call to
815 Alloc() if too much memory were preallocated.
816 */
817 void Shrink();
818
819 /**
820 This function can be used to test if the string starts with the specified
821 @e prefix. If it does, the function will return @true and put the rest
822 of the string (i.e. after the prefix) into @a rest string if it is not
823 @NULL. Otherwise, the function returns @false and doesn't modify the
824 @e rest.
825 */
826 bool StartsWith(const wxString& prefix, wxString rest = NULL) const;
827
828 /**
829 Strip characters at the front and/or end. The same as Trim except that it
830 doesn't change this string.
831 This is a wxWidgets 1.xx compatibility function; you should not use it in new
832 code.
833 */
834 wxString Strip(stripType s = trailing) const;
835
836 /**
837 Returns the part of the string between the indices @a from and @e to
838 inclusive.
839 This is a wxWidgets 1.xx compatibility function, use Mid()
840 instead (but note that parameters have different meaning).
841 */
842 wxString SubString(size_t from, size_t to) const;
843
844 //@{
845 /**
846 Converts the string to an 8-bit string in ISO-8859-1 encoding in the
847 form of a wxCharBuffer (Unicode builds only).
848
849 This is a convenience method useful when storing binary data in
850 wxString. It should be used @em only for this purpose. It is only valid
851 to call this method on strings created using From8BitData().
852
853 @since 2.8.4
854
855 @see wxString::From8BitData()
856 */
857 const char* To8BitData() const;
858 const wxCharBuffer To8BitData() const;
859 //@}
860
861 //@{
862 /**
863 Converts the string to an ASCII, 7-bit string in the form of
864 a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
865 Note that this conversion only works if the string contains only ASCII
866 characters. The @ref mbstr() mb_str method provides more
867 powerful means of converting wxString to C string.
868 */
869 const char* ToAscii() const;
870 const wxCharBuffer ToAscii() const;
871 //@}
872
873 /**
874 Attempts to convert the string to a floating point number. Returns @true on
875 success (the number is stored in the location pointed to by @e val) or @false
876 if the string does not represent such number (the value of @a val is not
877 modified in this case).
878
879 @see ToLong(), ToULong()
880 */
881 bool ToDouble(double val) const;
882
883 /**
884 Attempts to convert the string to a signed integer in base @e base. Returns
885 @true on success in which case the number is stored in the location
886 pointed to by @a val or @false if the string does not represent a
887 valid number in the given base (the value of @a val is not modified
888 in this case).
889 The value of @a base must be comprised between 2 and 36, inclusive, or
890 be a special value 0 which means that the usual rules of @c C numbers are
891 applied: if the number starts with @c 0x it is considered to be in base
892 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note
893 that you may not want to specify the base 0 if you are parsing the numbers
894 which may have leading zeroes as they can yield unexpected (to the user not
895 familiar with C) results.
896
897 @see ToDouble(), ToULong()
898 */
899 bool ToLong(long val, int base = 10) const;
900
901 /**
902 This is exactly the same as ToLong() but works with 64
903 bit integer numbers.
904 Notice that currently it doesn't work (always returns @false) if parsing of 64
905 bit numbers is not supported by the underlying C run-time library. Compilers
906 with C99 support and Microsoft Visual C++ version 7 and higher do support this.
907
908 @see ToLong(), ToULongLong()
909 */
910 bool ToLongLong(wxLongLong_t val, int base = 10) const;
911
912 /**
913 Attempts to convert the string to an unsigned integer in base @e base.
914 Returns @true on success in which case the number is stored in the
915 location pointed to by @a val or @false if the string does not
916 represent a valid number in the given base (the value of @a val is not
917 modified in this case). Please notice that this function
918 behaves in the same way as the standard @c strtoul() and so it simply
919 converts negative numbers to unsigned representation instead of rejecting them
920 (e.g. -1 is returned as @c ULONG_MAX).
921 See ToLong() for the more detailed
922 description of the @a base parameter.
923
924 @see ToDouble(), ToLong()
925 */
926 bool ToULong(unsigned long val, int base = 10) const;
927
928 /**
929 This is exactly the same as ToULong() but works with 64
930 bit integer numbers.
931 Please see ToLongLong() for additional remarks.
932 */
933 bool ToULongLong(wxULongLong_t val, int base = 10) const;
934
935 //@{
936 /**
937 Same as utf8_str().
938 */
939 const char* ToUTF8() const;
940 const wxCharBuffer ToUF8() const;
941 //@}
942
943 /**
944 Removes white-space (space, tabs, form feed, newline and carriage return) from
945 the left or from the right end of the string (right is default).
946 */
947 wxString& Trim(bool fromRight = true);
948
949 /**
950 Truncate the string to the given length.
951 */
952 wxString& Truncate(size_t len);
953
954 //@{
955 /**
956 Puts the string back into a reasonable state (in which it can be used
957 normally), after
958 GetWriteBuf() was called.
959 The version of the function without the @a len parameter will calculate the
960 new string length itself assuming that the string is terminated by the first
961 @c NUL character in it while the second one will use the specified length
962 and thus is the only version which should be used with the strings with
963 embedded @c NULs (it is also slightly more efficient as @c strlen()
964 doesn't have to be called).
965 This method is deprecated, please use
966 wxStringBuffer or
967 wxStringBufferLength instead.
968 */
969 void UngetWriteBuf();
970 void UngetWriteBuf(size_t len);
971 //@}
972
973 /**
974 Returns this string converted to upper case.
975 */
976 wxString Upper() const;
977
978 /**
979 The same as MakeUpper.
980 This is a wxWidgets 1.xx compatibility function; you should not use it in new
981 code.
982 */
983 void UpperCase();
984
985 /**
986 Returns a pointer to the string data (@c const char* when using UTF-8
987 internally, @c const wchar_t* when using UCS-2 internally).
988
989 Note that the returned value is not convertible to @c char* or
990 @c wchar_t*, use char_str() or wchar_str() if you need to pass
991 string value to a function expecting non-const pointer.
992 */
993 const wxCStrData c_str() const;
994
995 /**
996 Returns an object with string data that is implicitly convertible to
997 @c char* pointer. Note that any change to the returned buffer is lost and so
998 this function is only usable for passing strings to legacy libraries that
999 don't have const-correct API. Use wxStringBuffer if you want to modify
1000 the string.
1001
1002 @see c_str()
1003 */
1004 wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
1005
1006 //@{
1007 /**
1008 Returns string representation suitable for passing to OS' functions
1009 for file handling.
1010 */
1011 const wchar_t* fn_str() const;
1012 const char* fn_str() const;
1013 const wxCharBuffer fn_str() const;
1014 //@}
1015
1016 //@{
1017 /**
1018 Returns multibyte (C string) representation of the string.
1019 In Unicode build, converts using @e conv's wxMBConv::cWC2MB
1020 method and returns wxCharBuffer. In ANSI build, this function
1021 is same as c_str().
1022 The macro wxWX2MBbuf is defined as the correct return type (without const).
1023
1024 @see wxMBConv, c_str(), wc_str(), fn_str(), char_str()
1025 */
1026 const char* mb_str(const wxMBConv& conv = wxConvLibc) const;
1027 const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
1028 //@}
1029
1030 /**
1031 Extraction from a stream.
1032 */
1033 friend istream operator(istream& is, wxString& str);
1034
1035 //@{
1036 /**
1037 These functions work as C++ stream insertion operators: they insert the given
1038 value into the string. Precision or format cannot be set using them, you can
1039 use Printf() for this.
1040 */
1041 wxString operator(const wxString& str);
1042 wxString operator(wxUniChar ch);
1043 wxString operator(int i);
1044 wxString operator(float f);
1045 wxString operator(double d);
1046 //@}
1047
1048 /**
1049 Same as Mid (substring extraction).
1050 */
1051 wxString operator ()(size_t start, size_t len);
1052
1053 //@{
1054 /**
1055 Concatenation: these operators return a new string equal to the
1056 concatenation of the operands.
1057 */
1058 wxString operator +(const wxString& x, const wxString& y);
1059 wxString operator +(const wxString& x, wxUniChar y);
1060 //@}
1061
1062 //@{
1063 /**
1064 Concatenation in place: the argument is appended to the string.
1065 */
1066 void operator +=(const wxString& str);
1067 void operator +=(wxUniChar c);
1068 //@}
1069
1070 //@{
1071 /**
1072 Assignment: the effect of each operation is the same as for the corresponding
1073 constructor (see @ref construct() "wxString constructors").
1074 */
1075 wxString operator =(const wxString& str);
1076 wxString operator =(wxUniChar c);
1077 //@}
1078
1079 //@{
1080 /**
1081 Element extraction.
1082 */
1083 wxUniChar operator [](size_t i) const;
1084 wxUniCharRef operator [](size_t i);
1085 //@}
1086
1087 /**
1088 Empty string is @false, so !string will only return @true if the
1089 string is empty.
1090
1091 See also IsEmpty().
1092 */
1093 bool operator!() const;
1094
1095
1096 //@{
1097 /**
1098 Converts the strings contents to UTF-8 and returns it either as a
1099 temporary wxCharBuffer object or as a pointer to the internal
1100 string contents in UTF-8 build.
1101 */
1102 const char* utf8_str() const;
1103 const wxCharBuffer utf8_str() const;
1104 //@}
1105
1106 //@{
1107 /**
1108 Converts the strings contents to the wide character represention
1109 and returns it as a temporary wxWCharBuffer object or returns a
1110 pointer to the internal string contents in wide character mode.
1111
1112 The macro wxWX2WCbuf is defined as the correct return
1113 type (without const).
1114
1115 @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str()
1116 */
1117 const wchar_t* wc_str() const;
1118 const wxWCharBuffer wc_str() const;
1119 //@}
1120
1121 /**
1122 Returns an object with string data that is implicitly convertible to
1123 @c char* pointer. Note that changes to the returned buffer may or may
1124 not be lost (depending on the build) and so this function is only usable for
1125 passing strings to legacy libraries that don't have const-correct API. Use
1126 wxStringBuffer if you want to modify the string.
1127
1128 @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
1129 */
1130 wxWritableWCharBuffer wchar_str() const;
1131
1132 /**
1133 @name Iterator interface
1134
1135 These methods return iterators to the beginnnig or
1136 end of the string.
1137 */
1138 //@{
1139 const_iterator begin() const;
1140 iterator begin();
1141 const_iterator end() const;
1142 iterator end();
1143
1144 const_reverse_iterator rbegin() const;
1145 reverse_iterator rbegin();
1146 const_reverse_iterator rend() const;
1147 reverse_iterator rend();
1148 //@}
1149
1150 /**
1151 @name STL interface
1152
1153 The supported STL functions are listed here. Please see any
1154 STL reference for their documentation.
1155 */
1156 //@{
1157 size_t length() const;
1158 size_type size() const;
1159 size_type max_size() const;
1160 size_type capacity() const;
1161 void reserve(size_t sz);
1162
1163 void resize(size_t nSize, wxUniChar ch = '\0');
1164
1165 wxString& append(const wxString& str, size_t pos, size_t n);
1166 wxString& append(const wxString& str);
1167 wxString& append(const char *sz, size_t n);
1168 wxString& append(const wchar_t *sz, size_t n);
1169 wxString& append(size_t n, wxUniChar ch);
1170 wxString& append(const_iterator first, const_iterator last);
1171
1172 wxString& assign(const wxString& str, size_t pos, size_t n);
1173 wxString& assign(const wxString& str);
1174 wxString& assign(const char *sz, size_t n);
1175 wxString& assign(const wchar_t *sz, size_t n);
1176 wxString& assign(size_t n, wxUniChar ch);
1177 wxString& assign(const_iterator first, const_iterator last);
1178
1179 void clear();
1180
1181 int compare(const wxString& str) const;
1182 int compare(size_t nStart, size_t nLen, const wxString& str) const;
1183 int compare(size_t nStart, size_t nLen,
1184 const wxString& str, size_t nStart2, size_t nLen2) const;
1185 int compare(size_t nStart, size_t nLen,
1186 const char* sz, size_t nCount = npos) const;
1187 int compare(size_t nStart, size_t nLen,
1188 const wchar_t* sz, size_t nCount = npos) const;
1189
1190 bool empty() const;
1191
1192 wxString& erase(size_type pos = 0, size_type n = npos);
1193 iterator erase(iterator first, iterator last);
1194 iterator erase(iterator first);
1195
1196 size_t find(const wxString& str, size_t nStart = 0) const;
1197 size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
1198 size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const;
1199 size_t find(wxUniChar ch, size_t nStart = 0) const;
1200
1201 wxString& insert(size_t nPos, const wxString& str);
1202 wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
1203 wxString& insert(size_t nPos, const char *sz, size_t n);
1204 wxString& insert(size_t nPos, const wchar_t *sz, size_t n);
1205 wxString& insert(size_t nPos, size_t n, wxUniChar ch);
1206 iterator insert(iterator it, wxUniChar ch);
1207 void insert(iterator it, const_iterator first, const_iterator last);
1208 void insert(iterator it, size_type n, wxUniChar ch);
1209
1210 wxString& replace(size_t nStart, size_t nLen, const wxString& str);
1211 wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch);
1212 wxString& replace(size_t nStart, size_t nLen,
1213 const wxString& str, size_t nStart2, size_t nLen2);
1214 wxString& replace(size_t nStart, size_t nLen,
1215 const char* sz, size_t nCount);
1216 wxString& replace(size_t nStart, size_t nLen,
1217 const wchar_t* sz, size_t nCount);
1218 wxString& replace(size_t nStart, size_t nLen,
1219 const wxString& s, size_t nCount);
1220 wxString& replace(iterator first, iterator last, const wxString& s);
1221 wxString& replace(iterator first, iterator last, const char* s, size_type n);
1222 wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n);
1223 wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch);
1224 wxString& replace(iterator first, iterator last,
1225 const_iterator first1, const_iterator last1);
1226 wxString& replace(iterator first, iterator last,
1227 const char *first1, const char *last1);
1228 wxString& replace(iterator first, iterator last,
1229 const wchar_t *first1, const wchar_t *last1);
1230
1231 size_t rfind(const wxString& str, size_t nStart = npos) const;
1232 size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const;
1233 size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const;
1234 size_t rfind(wxUniChar ch, size_t nStart = npos) const;
1235
1236 wxString substr(size_t nStart = 0, size_t nLen = npos) const;
1237
1238 void swap(wxString& str);
1239
1240 //@}
1241
1242 };
1243
1244
1245 /**
1246 FIXME
1247 */
1248 wxString Objects:
1249 ;
1250
1251 /**
1252 FIXME
1253 */
1254 wxString wxEmptyString;
1255
1256
1257
1258
1259 /**
1260 @class wxStringBufferLength
1261 @wxheader{string.h}
1262
1263 This tiny class allows to conveniently access the wxString
1264 internal buffer as a writable pointer without any risk of forgetting to restore
1265 the string to the usable state later, and allows the user to set the internal
1266 length of the string.
1267
1268 For example, assuming you have a low-level OS function called
1269 @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
1270 buffer (which must be writable, of course), and returning the actual length
1271 of the string, you might call it like this:
1272
1273 @code
1274 wxString theAnswer;
1275 wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1276 int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1277 theAnswerBuffer.SetLength(nLength);
1278 if ( theAnswer != "42" )
1279 {
1280 wxLogError("Something is very wrong!");
1281 }
1282 @endcode
1283
1284 Note that the exact usage of this depends on whether on not wxUSE_STL is
1285 enabled. If
1286 wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
1287 and
1288 if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
1289 buffer
1290 wxString uses intact. In other words, relying on wxStringBuffer containing the
1291 old
1292 wxString data is probably not a good idea if you want to build your program in
1293 both
1294 with and without wxUSE_STL.
1295
1296 Note that SetLength @c must be called before wxStringBufferLength destructs.
1297
1298 @library{wxbase}
1299 @category{FIXME}
1300 */
1301 class wxStringBufferLength
1302 {
1303 public:
1304 /**
1305 Constructs a writable string buffer object associated with the given string
1306 and containing enough space for at least @a len characters. Basically, this
1307 is equivalent to calling wxString::GetWriteBuf and
1308 saving the result.
1309 */
1310 wxStringBufferLength(const wxString& str, size_t len);
1311
1312 /**
1313 Restores the string passed to the constructor to the usable state by calling
1314 wxString::UngetWriteBuf on it.
1315 */
1316 ~wxStringBufferLength();
1317
1318 /**
1319 Sets the internal length of the string referred to by wxStringBufferLength to
1320 @a nLength characters.
1321 Must be called before wxStringBufferLength destructs.
1322 */
1323 void SetLength(size_t nLength);
1324
1325 /**
1326 Returns the writable pointer to a buffer of the size at least equal to the
1327 length specified in the constructor.
1328 */
1329 wxChar* operator wxChar *();
1330 };
1331