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