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