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