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