]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: string.h | |
3 | // Purpose: interface of wxStringBuffer, wxString | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | ||
10 | /** | |
11 | @class wxString | |
12 | ||
13 | The wxString class has been completely rewritten for wxWidgets 3.0 | |
14 | and this change was actually the main reason for the calling that | |
15 | version wxWidgets 3.0. | |
16 | ||
17 | wxString is a class representing a Unicode character string. | |
18 | wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined) | |
19 | to store its content (unless this is not supported by the compiler or disabled | |
20 | specifically when building wxWidgets) and it therefore inherits | |
21 | many features from @c std::basic_string. (Note that most implementations of | |
22 | @c std::basic_string are thread-safe and don't use reference counting.) | |
23 | ||
24 | These @c std::basic_string standard functions are only listed here, but | |
25 | they are not fully documented in this manual; see the STL documentation | |
26 | (http://www.cppreference.com/wiki/string/start) for more info. | |
27 | The behaviour of all these functions is identical to the behaviour | |
28 | described there. | |
29 | ||
30 | You may notice that wxString sometimes has several functions which do | |
31 | the same thing like Length(), Len() and length() which all return the | |
32 | string length. In all cases of such duplication the @c std::string | |
33 | compatible methods should be used. | |
34 | ||
35 | For informations about the internal encoding used by wxString and | |
36 | for important warnings and advices for using it, please read | |
37 | the @ref overview_string. | |
38 | ||
39 | Since wxWidgets 3.0 wxString always stores Unicode strings, so you should | |
40 | be sure to read also @ref overview_unicode. | |
41 | ||
42 | ||
43 | @section string_index Index of the member groups | |
44 | ||
45 | Links for quick access to the various categories of wxString functions: | |
46 | - @ref_member_group{ctor, Constructors and assignment operators} | |
47 | - @ref_member_group{length, Length functions} | |
48 | - @ref_member_group{ch_access, Character access functions} | |
49 | - @ref_member_group{conv, Conversions functions} | |
50 | - @ref_member_group{concat, Concatenation functions} | |
51 | - @ref_member_group{cmp, Comparison functions} | |
52 | - @ref_member_group{substring, Substring extraction functions} | |
53 | - @ref_member_group{caseconv, Case conversion functions} | |
54 | - @ref_member_group{search, Searching and replacing functions} | |
55 | - @ref_member_group{numconv, Conversion to numbers functions} | |
56 | - @ref_member_group{fmt, Formatting and printing functions} | |
57 | - @ref_member_group{mem, Memory management functions} | |
58 | - @ref_member_group{misc, Miscellaneous functions} | |
59 | - @ref_member_group{iter, Iterator interface functions} | |
60 | - @ref_member_group{stl, STL interface functions} | |
61 | ||
62 | ||
63 | @library{wxbase} | |
64 | @category{data} | |
65 | ||
66 | @stdobjects | |
67 | ::wxEmptyString | |
68 | ||
69 | @see @ref overview_string, @ref overview_unicode, | |
70 | @ref group_funcmacro_string "String-related functions", wxUString, | |
71 | wxCharBuffer, wxUniChar, wxStringTokenizer, wxStringBuffer, wxStringBufferLength | |
72 | */ | |
73 | class wxString | |
74 | { | |
75 | public: | |
76 | /** | |
77 | @name Standard types | |
78 | ||
79 | Types used with wxString. | |
80 | */ | |
81 | //@{ | |
82 | typedef wxUniChar value_type; | |
83 | typedef wxUniChar char_type; | |
84 | typedef wxUniCharRef reference; | |
85 | typedef wxChar* pointer; | |
86 | typedef const wxChar* const_pointer; | |
87 | typedef size_t size_type; | |
88 | typedef wxUniChar const_reference; | |
89 | //@} | |
90 | ||
91 | ||
92 | /** | |
93 | @member_group_name{ctor, Constructors and assignment operators} | |
94 | ||
95 | A string may be constructed either from a C string, (some number of copies of) | |
96 | a single character or a wide (Unicode) string. For all constructors (except the | |
97 | default which creates an empty string) there is also a corresponding assignment | |
98 | operator. | |
99 | ||
100 | See also the assign() STL-like function. | |
101 | */ | |
102 | //@{ | |
103 | ||
104 | /** | |
105 | Default constructor | |
106 | */ | |
107 | wxString(); | |
108 | ||
109 | /** | |
110 | Creates a string from another string. | |
111 | Just increases the ref count by 1. | |
112 | */ | |
113 | wxString(const wxString& stringSrc); | |
114 | ||
115 | /** | |
116 | Construct a string consisting of @a nRepeat copies of ch. | |
117 | */ | |
118 | wxString(wxUniChar ch, size_t nRepeat = 1); | |
119 | ||
120 | /** | |
121 | Construct a string consisting of @a nRepeat copies of ch. | |
122 | */ | |
123 | wxString(wxUniCharRef ch, size_t nRepeat = 1); | |
124 | ||
125 | /** | |
126 | Construct a string consisting of @a nRepeat copies of ch | |
127 | converted to Unicode using the current locale encoding. | |
128 | */ | |
129 | wxString(char ch, size_t nRepeat = 1); | |
130 | ||
131 | /** | |
132 | Construct a string consisting of @a nRepeat copies of ch. | |
133 | */ | |
134 | wxString(wchar_t ch, size_t nRepeat = 1); | |
135 | ||
136 | /** | |
137 | Constructs a string from the string literal @a psz using | |
138 | the current locale encoding to convert it to Unicode (wxConvLibc). | |
139 | */ | |
140 | wxString(const char *psz); | |
141 | ||
142 | /** | |
143 | Constructs a string from the string literal @a psz using | |
144 | @a conv to convert it Unicode. | |
145 | */ | |
146 | wxString(const char *psz, const wxMBConv& conv); | |
147 | ||
148 | /** | |
149 | Constructs a string from the first @a nLength character of the string literal @a psz using | |
150 | the current locale encoding to convert it to Unicode (wxConvLibc). | |
151 | */ | |
152 | wxString(const char *psz, size_t nLength); | |
153 | ||
154 | /** | |
155 | Constructs a string from the first @a nLength character of the string literal @a psz using | |
156 | @a conv to convert it Unicode. | |
157 | */ | |
158 | wxString(const char *psz, const wxMBConv& conv, size_t nLength); | |
159 | ||
160 | /** | |
161 | Constructs a string from the string literal @a pwz. | |
162 | */ | |
163 | wxString(const wchar_t *pwz); | |
164 | ||
165 | /** | |
166 | Constructs a string from the first @a nLength characters of the string literal @a pwz. | |
167 | */ | |
168 | wxString(const wchar_t *pwz, size_t nLength); | |
169 | ||
170 | /** | |
171 | Constructs a string from @a buf using the using the current locale | |
172 | encoding to convert it to Unicode. | |
173 | */ | |
174 | wxString(const wxCharBuffer& buf); | |
175 | ||
176 | /** | |
177 | Constructs a string from @a buf. | |
178 | */ | |
179 | wxString(const wxWCharBuffer& buf); | |
180 | ||
181 | /** | |
182 | Constructs a string from @a str using the using the current locale encoding | |
183 | to convert it to Unicode (wxConvLibc). | |
184 | ||
185 | @see ToStdString() | |
186 | */ | |
187 | wxString(const std::string& str); | |
188 | ||
189 | /** | |
190 | Constructs a string from @a str. | |
191 | ||
192 | @see ToStdWstring() | |
193 | */ | |
194 | wxString(const std::wstring& str); | |
195 | ||
196 | /** | |
197 | String destructor. | |
198 | ||
199 | Note that this is not virtual, so wxString must not be inherited from. | |
200 | */ | |
201 | ~wxString(); | |
202 | ||
203 | /** | |
204 | Assignment: see the relative wxString constructor. | |
205 | */ | |
206 | wxString operator =(const wxString& str); | |
207 | ||
208 | /** | |
209 | Assignment: see the relative wxString constructor. | |
210 | */ | |
211 | wxString operator =(wxUniChar c); | |
212 | ||
213 | //@} | |
214 | ||
215 | ||
216 | ||
217 | /** | |
218 | @member_group_name{length, String length} | |
219 | ||
220 | These functions return the string length and/or check whether the string | |
221 | is empty. | |
222 | ||
223 | See also the length(), size() or empty() STL-like functions. | |
224 | */ | |
225 | //@{ | |
226 | ||
227 | ||
228 | /** | |
229 | Returns the length of the string. | |
230 | */ | |
231 | size_t Len() const; | |
232 | ||
233 | /** | |
234 | Returns the length of the string (same as Len). | |
235 | This is a wxWidgets 1.xx compatibility function; you should not use it in new | |
236 | code. | |
237 | */ | |
238 | size_t Length() const; | |
239 | ||
240 | /** | |
241 | Returns @true if the string is empty. | |
242 | */ | |
243 | bool IsEmpty() const; | |
244 | ||
245 | /** | |
246 | Returns @true if the string is empty (same as wxString::IsEmpty). | |
247 | This is a wxWidgets 1.xx compatibility function; you should not use it in new | |
248 | code. | |
249 | */ | |
250 | bool IsNull() const; | |
251 | ||
252 | /** | |
253 | Empty string is @false, so !string will only return @true if the | |
254 | string is empty. | |
255 | ||
256 | @see IsEmpty(). | |
257 | */ | |
258 | bool operator!() const; | |
259 | ||
260 | //@} | |
261 | ||
262 | ||
263 | ||
264 | /** | |
265 | @member_group_name{ch_access, Character access} | |
266 | ||
267 | Many functions below take a character index in the string. | |
268 | As with C strings and arrays, the indices start from 0, so the first character | |
269 | of a string is string[0]. An attempt to access a character beyond the end of the | |
270 | string (which may even be 0 if the string is empty) will provoke an assert | |
271 | failure in @ref overview_debugging "debug builds", but no checks are | |
272 | done in release builds. | |
273 | */ | |
274 | //@{ | |
275 | ||
276 | /** | |
277 | Returns the character at position @a n (read-only). | |
278 | */ | |
279 | wxUniChar GetChar(size_t n) const; | |
280 | ||
281 | /** | |
282 | wxWidgets compatibility conversion. Same as c_str(). | |
283 | */ | |
284 | const wxCStrData GetData() const; | |
285 | ||
286 | /** | |
287 | Returns a reference to the character at position @a n. | |
288 | */ | |
289 | wxUniCharRef GetWritableChar(size_t n); | |
290 | ||
291 | /** | |
292 | Returns a writable buffer of at least @a len bytes. | |
293 | ||
294 | It returns a pointer to a new memory block, and the existing data will not be copied. | |
295 | Call UngetWriteBuf() as soon as possible to put the string back into a reasonable state. | |
296 | ||
297 | This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. | |
298 | */ | |
299 | wxStringCharType* GetWriteBuf(size_t len); | |
300 | ||
301 | /** | |
302 | Puts the string back into a reasonable state (in which it can be used | |
303 | normally), after GetWriteBuf() was called. | |
304 | ||
305 | The version of the function without the @a len parameter will calculate the | |
306 | new string length itself assuming that the string is terminated by the first | |
307 | @c NUL character in it while the second one will use the specified length | |
308 | and thus is the only version which should be used with the strings with | |
309 | embedded @c NULs (it is also slightly more efficient as @c strlen() | |
310 | doesn't have to be called). | |
311 | ||
312 | This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. | |
313 | */ | |
314 | void UngetWriteBuf(); | |
315 | ||
316 | /** | |
317 | @overload | |
318 | */ | |
319 | void UngetWriteBuf(size_t len); | |
320 | ||
321 | /** | |
322 | Sets the character at position @e n. | |
323 | */ | |
324 | void SetChar(size_t n, wxUniChar ch); | |
325 | ||
326 | /** | |
327 | Returns a the last character. | |
328 | ||
329 | This is a wxWidgets 1.xx compatibility function; | |
330 | you should not use it in new code. | |
331 | */ | |
332 | wxUniChar Last() const; | |
333 | ||
334 | /** | |
335 | Returns a reference to the last character (writable). | |
336 | ||
337 | This is a wxWidgets 1.xx compatibility function; | |
338 | you should not use it in new code. | |
339 | */ | |
340 | wxUniCharRef Last(); | |
341 | ||
342 | /** | |
343 | Returns the @a i-th character of the string. | |
344 | */ | |
345 | wxUniChar operator [](size_t i) const; | |
346 | ||
347 | /** | |
348 | Returns a writable reference to the @a i-th character of the string. | |
349 | */ | |
350 | wxUniCharRef operator [](size_t i); | |
351 | ||
352 | //@} | |
353 | ||
354 | ||
355 | /** | |
356 | @member_group_name{conv, Conversions} | |
357 | ||
358 | This section contains both implicit and explicit conversions to C style | |
359 | strings. Although implicit conversion is quite convenient, you are advised | |
360 | to use wc_str() for the sake of clarity. | |
361 | */ | |
362 | //@{ | |
363 | ||
364 | /** | |
365 | Returns a lightweight intermediate class which is in turn implicitly | |
366 | convertible to both @c const @c char* and to @c const @c wchar_t*. | |
367 | Given this ambiguity it is mostly better to use wc_str(), mb_str() or | |
368 | utf8_str() instead. | |
369 | ||
370 | Please see the @ref overview_unicode for more information about it. | |
371 | ||
372 | Note that the returned value is not convertible to @c char* or | |
373 | @c wchar_t*, use char_str() or wchar_str() if you need to pass | |
374 | string value to a function expecting non-const pointer. | |
375 | ||
376 | @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str() | |
377 | */ | |
378 | wxCStrData c_str() const; | |
379 | ||
380 | /** | |
381 | Returns an object with string data that is implicitly convertible to | |
382 | @c char* pointer. Note that any change to the returned buffer is lost and so | |
383 | this function is only usable for passing strings to legacy libraries that | |
384 | don't have const-correct API. Use wxStringBuffer if you want to modify | |
385 | the string. | |
386 | ||
387 | @see c_str() | |
388 | */ | |
389 | wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; | |
390 | ||
391 | /** | |
392 | Returns buffer of the specified type containing the string data. | |
393 | ||
394 | This method is only useful in template code, otherwise you should | |
395 | directly call mb_str() or wc_str() if you need to retrieve a narrow or | |
396 | wide string from this wxString. The template parameter @a t should be | |
397 | either @c char or @c wchar_t. | |
398 | ||
399 | Notice that retrieving a char buffer in UTF-8 build will return the | |
400 | internal string representation in UTF-8 while in wchar_t build the char | |
401 | buffer will contain the conversion of the string to the encoding of the | |
402 | current locale (and so can fail). | |
403 | ||
404 | @param len | |
405 | If non-@NULL, filled with the length of the returned buffer. | |
406 | ||
407 | @return | |
408 | buffer containing the string contents in the specified type, | |
409 | notice that it may be @NULL if the conversion failed (e.g. Unicode | |
410 | string couldn't be converted to the current encoding when @a T is | |
411 | @c char). | |
412 | */ | |
413 | template <typename T> | |
414 | wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const; | |
415 | ||
416 | /** | |
417 | Returns a string representation suitable for passing to OS' functions | |
418 | for file handling. | |
419 | */ | |
420 | const wchar_t* fn_str() const; | |
421 | ||
422 | /** | |
423 | @overload | |
424 | */ | |
425 | const char* fn_str() const; | |
426 | ||
427 | /** | |
428 | @overload | |
429 | */ | |
430 | const wxCharBuffer fn_str() const; | |
431 | ||
432 | /** | |
433 | Returns the multibyte (C string) representation of the string | |
434 | using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. | |
435 | ||
436 | @see wc_str(), utf8_str(), c_str(), wxMBConv | |
437 | */ | |
438 | const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; | |
439 | ||
440 | /** | |
441 | Converts the strings contents to UTF-8 and returns it either as a | |
442 | temporary wxCharBuffer object or as a pointer to the internal | |
443 | string contents in UTF-8 build. | |
444 | ||
445 | @see wc_str(), c_str(), mb_str() | |
446 | */ | |
447 | const wxScopedCharBuffer utf8_str() const; | |
448 | ||
449 | /** | |
450 | Converts the strings contents to the wide character represention | |
451 | and returns it as a temporary wxWCharBuffer object (Unix and OS X) | |
452 | or returns a pointer to the internal string contents in wide character | |
453 | mode (Windows). | |
454 | ||
455 | The macro wxWX2WCbuf is defined as the correct return type (without const). | |
456 | ||
457 | @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() | |
458 | */ | |
459 | const wchar_t* wc_str() const; | |
460 | ||
461 | /** | |
462 | @overload | |
463 | */ | |
464 | const wxWCharBuffer wc_str() const; | |
465 | ||
466 | /** | |
467 | Returns an object with string data that is implicitly convertible to | |
468 | @c char* pointer. Note that changes to the returned buffer may or may | |
469 | not be lost (depending on the build) and so this function is only usable for | |
470 | passing strings to legacy libraries that don't have const-correct API. Use | |
471 | wxStringBuffer if you want to modify the string. | |
472 | ||
473 | @see mb_str(), wc_str(), fn_str(), c_str(), char_str() | |
474 | */ | |
475 | wxWritableWCharBuffer wchar_str() const; | |
476 | ||
477 | /** | |
478 | Explicit conversion to C string in the internal representation (either | |
479 | wchar_t* or UTF-8-encoded char*, depending on the build). | |
480 | */ | |
481 | const wxStringCharType *wx_str() const; | |
482 | ||
483 | /** | |
484 | Converts the string to an 8-bit string in ISO-8859-1 encoding in the | |
485 | form of a wxCharBuffer (Unicode builds only). | |
486 | ||
487 | This is a convenience method useful when storing binary data in | |
488 | wxString. It should be used @em only for this purpose. It is only valid | |
489 | to call this method on strings created using From8BitData(). | |
490 | ||
491 | @since 2.8.4 | |
492 | ||
493 | @see wxString::From8BitData() | |
494 | */ | |
495 | const wxScopedCharBuffer To8BitData() const; | |
496 | ||
497 | /** | |
498 | Converts the string to an ASCII, 7-bit string in the form of | |
499 | a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). | |
500 | Note that this conversion only works if the string contains only ASCII | |
501 | characters. The @ref mb_str() "mb_str" method provides more | |
502 | powerful means of converting wxString to C string. | |
503 | */ | |
504 | const char* ToAscii() const; | |
505 | ||
506 | /** | |
507 | @overload | |
508 | */ | |
509 | const wxCharBuffer ToAscii() const; | |
510 | ||
511 | /** | |
512 | Return the string as an std::string in current locale encoding. | |
513 | ||
514 | Note that if the conversion of (Unicode) string contents to the current | |
515 | locale fails, the return string will be empty. Be sure to check for | |
516 | this to avoid silent data loss. | |
517 | ||
518 | Instead of using this function it's also possible to write | |
519 | @code | |
520 | std::string s; | |
521 | wxString wxs; | |
522 | ... | |
523 | s = std::string(wxs); | |
524 | @endcode | |
525 | but using ToStdString() may make the code more clear. | |
526 | ||
527 | @since 2.9.1 | |
528 | */ | |
529 | std::string ToStdString() const; | |
530 | ||
531 | /** | |
532 | Return the string as an std::wstring. | |
533 | ||
534 | Unlike ToStdString(), there is no danger of data loss when using this | |
535 | function. | |
536 | ||
537 | @since 2.9.1 | |
538 | */ | |
539 | std::wstring ToStdWstring() const; | |
540 | ||
541 | /** | |
542 | Same as utf8_str(). | |
543 | */ | |
544 | const wxScopedCharBuffer ToUTF8() const; | |
545 | ||
546 | //@} | |
547 | ||
548 | ||
549 | /** | |
550 | @member_group_name{concat, Concatenation} | |
551 | ||
552 | Almost anything may be concatenated (appended to) with a string! | |
553 | ||
554 | Note that the various operator<<() overloads work as C++ stream insertion | |
555 | operators. They insert the given value into the string. | |
556 | Precision and format cannot be set using them. Use Printf() instead. | |
557 | ||
558 | See also the insert() and append() STL-like functions. | |
559 | */ | |
560 | //@{ | |
561 | ||
562 | /** | |
563 | Appends the string literal @a psz. | |
564 | */ | |
565 | wxString& Append(const char* psz); | |
566 | ||
567 | /** | |
568 | Appends the wide string literal @a pwz. | |
569 | */ | |
570 | wxString& Append(const wchar_t* pwz); | |
571 | ||
572 | /** | |
573 | Appends the string literal @a psz with max length @a nLen. | |
574 | */ | |
575 | wxString& Append(const char* psz, size_t nLen); | |
576 | ||
577 | /** | |
578 | Appends the wide string literal @a psz with max length @a nLen. | |
579 | */ | |
580 | wxString& Append(const wchar_t* pwz, size_t nLen); | |
581 | ||
582 | /** | |
583 | Appends the string @a s. | |
584 | */ | |
585 | wxString& Append(const wxString& s); | |
586 | ||
587 | /** | |
588 | Appends the character @a ch @a count times. | |
589 | */ | |
590 | wxString &Append(wxUniChar ch, size_t count = 1u); | |
591 | ||
592 | /** | |
593 | Prepends @a str to this string, returning a reference to this string. | |
594 | */ | |
595 | wxString& Prepend(const wxString& str); | |
596 | ||
597 | /** | |
598 | Concatenation: returns a new string equal to the concatenation of the operands. | |
599 | */ | |
600 | wxString operator +(const wxString& x, const wxString& y); | |
601 | ||
602 | /** | |
603 | @overload | |
604 | */ | |
605 | wxString operator +(const wxString& x, wxUniChar y); | |
606 | ||
607 | wxString& operator<<(const wxString& s); | |
608 | wxString& operator<<(const char* psz); | |
609 | wxString& operator<<(const wchar_t* pwz); | |
610 | wxString& operator<<(const wxCStrData& psz); | |
611 | wxString& operator<<(char ch); | |
612 | wxString& operator<<(unsigned char ch); | |
613 | wxString& operator<<(wchar_t ch); | |
614 | wxString& operator<<(const wxCharBuffer& s); | |
615 | wxString& operator<<(const wxWCharBuffer& s); | |
616 | wxString& operator<<(wxUniChar ch); | |
617 | wxString& operator<<(wxUniCharRef ch); | |
618 | wxString& operator<<(unsigned int ui); | |
619 | wxString& operator<<(long l); | |
620 | wxString& operator<<(unsigned long ul); | |
621 | wxString& operator<<(wxLongLong_t ll); | |
622 | wxString& operator<<(wxULongLong_t ul); | |
623 | wxString& operator<<(float f); | |
624 | wxString& operator<<(double d); | |
625 | ||
626 | /** | |
627 | Concatenation in place: the argument is appended to the string. | |
628 | */ | |
629 | void operator +=(const wxString& str); | |
630 | ||
631 | /** | |
632 | @overload | |
633 | */ | |
634 | void operator +=(wxUniChar c); | |
635 | ||
636 | //@} | |
637 | ||
638 | ||
639 | /** | |
640 | @member_group_name{cmp, Comparison} | |
641 | ||
642 | The default comparison function Cmp() is case-sensitive and so is the default | |
643 | version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase() | |
644 | or give a second parameter to IsSameAs(). This last function is maybe more | |
645 | convenient if only equality of the strings matters because it returns a boolean | |
646 | @true value if the strings are the same and not 0 (which is usually @false | |
647 | in C) as Cmp() does. | |
648 | ||
649 | Matches() is a poor man's regular expression matcher: it only understands | |
650 | '*' and '?' metacharacters in the sense of DOS command line interpreter. | |
651 | ||
652 | StartsWith() is helpful when parsing a line of text which should start | |
653 | with some predefined prefix and is more efficient than doing direct string | |
654 | comparison as you would also have to precalculate the length of the prefix. | |
655 | ||
656 | See also the compare() STL-like function. | |
657 | */ | |
658 | //@{ | |
659 | ||
660 | /** | |
661 | Case-sensitive comparison. | |
662 | Returns a positive value if the string is greater than the argument, | |
663 | zero if it is equal to it or a negative value if it is less than the | |
664 | argument (same semantics as the standard @c strcmp() function). | |
665 | ||
666 | @see CmpNoCase(), IsSameAs(). | |
667 | */ | |
668 | int Cmp(const wxString& s) const; | |
669 | ||
670 | /** | |
671 | Case-insensitive comparison. | |
672 | Returns a positive value if the string is greater than the argument, | |
673 | zero if it is equal to it or a negative value if it is less than the | |
674 | argument (same semantics as the standard @c strcmp() function). | |
675 | ||
676 | @see Cmp(), IsSameAs(). | |
677 | */ | |
678 | int CmpNoCase(const wxString& s) const; | |
679 | ||
680 | /** | |
681 | Test whether the string is equal to another string @a s. | |
682 | ||
683 | The test is case-sensitive if @a caseSensitive is @true (default) or not if it is | |
684 | @false. | |
685 | ||
686 | @return @true if the string is equal to the other one, @false otherwise. | |
687 | ||
688 | @see Cmp(), CmpNoCase() | |
689 | */ | |
690 | bool IsSameAs(const wxString& s, bool caseSensitive = true) const; | |
691 | ||
692 | /** | |
693 | Test whether the string is equal to the single character @a ch. | |
694 | ||
695 | The test is case-sensitive if @a caseSensitive is @true (default) or not if it is | |
696 | @false. | |
697 | ||
698 | @return @true if the string is equal to this character, @false otherwise. | |
699 | ||
700 | @see Cmp(), CmpNoCase() | |
701 | */ | |
702 | bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; | |
703 | ||
704 | /** | |
705 | Returns @true if the string contents matches a mask containing '*' and '?'. | |
706 | */ | |
707 | bool Matches(const wxString& mask) const; | |
708 | ||
709 | /** | |
710 | This function can be used to test if the string starts with the specified | |
711 | @a prefix. | |
712 | ||
713 | If it does, the function will return @true and put the rest of the string | |
714 | (i.e. after the prefix) into @a rest string if it is not @NULL. | |
715 | Otherwise, the function returns @false and doesn't modify the @a rest. | |
716 | */ | |
717 | bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; | |
718 | ||
719 | /** | |
720 | This function can be used to test if the string ends with the specified | |
721 | @e suffix. If it does, the function will return @true and put the | |
722 | beginning of the string before the suffix into @e rest string if it is not | |
723 | @NULL. Otherwise, the function returns @false and doesn't | |
724 | modify the @e rest. | |
725 | */ | |
726 | bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; | |
727 | ||
728 | //@} | |
729 | ||
730 | ||
731 | /** | |
732 | @member_group_name{substring, Substring extraction} | |
733 | ||
734 | These functions allow you to extract a substring from the string. The | |
735 | original string is not modified and the function returns the extracted | |
736 | substring. | |
737 | ||
738 | See also the at() and the substr() STL-like functions. | |
739 | */ | |
740 | ||
741 | /** | |
742 | Returns a substring starting at @e first, with length @e count, or the rest of | |
743 | the string if @a count is the default value. | |
744 | */ | |
745 | wxString Mid(size_t first, size_t nCount = wxString::npos) const; | |
746 | ||
747 | /** | |
748 | Returns the part of the string between the indices @a from and @a to | |
749 | inclusive. | |
750 | ||
751 | This is a wxWidgets 1.xx compatibility function, use Mid() | |
752 | instead (but note that parameters have different meaning). | |
753 | */ | |
754 | wxString SubString(size_t from, size_t to) const; | |
755 | ||
756 | /** | |
757 | Same as Mid() (substring extraction). | |
758 | */ | |
759 | wxString operator()(size_t start, size_t len) const; | |
760 | ||
761 | /** | |
762 | Returns the first @a count characters of the string. | |
763 | */ | |
764 | wxString Left(size_t count) const; | |
765 | ||
766 | /** | |
767 | Returns the last @a count characters. | |
768 | */ | |
769 | wxString Right(size_t count) const; | |
770 | ||
771 | /** | |
772 | Gets all the characters after the first occurrence of @e ch. | |
773 | Returns the empty string if @e ch is not found. | |
774 | */ | |
775 | wxString AfterFirst(wxUniChar ch) const; | |
776 | ||
777 | /** | |
778 | Gets all the characters after the last occurrence of @e ch. | |
779 | Returns the whole string if @e ch is not found. | |
780 | */ | |
781 | wxString AfterLast(wxUniChar ch) const; | |
782 | ||
783 | /** | |
784 | Gets all characters before the first occurrence of @e ch. | |
785 | Returns the whole string if @a ch is not found. | |
786 | */ | |
787 | wxString BeforeFirst(wxUniChar ch) const; | |
788 | ||
789 | /** | |
790 | Gets all characters before the last occurrence of @e ch. | |
791 | Returns the empty string if @a ch is not found. | |
792 | */ | |
793 | wxString BeforeLast(wxUniChar ch) const; | |
794 | ||
795 | //@} | |
796 | ||
797 | ||
798 | /** | |
799 | @member_group_name{caseconv, Case conversion} | |
800 | ||
801 | The MakeXXX() variants modify the string in place, while the other functions | |
802 | return a new string which contains the original text converted to the upper or | |
803 | lower case and leave the original string unchanged. | |
804 | */ | |
805 | //@{ | |
806 | ||
807 | /** | |
808 | Return the copy of the string with the first string character in the | |
809 | upper case and the subsequent ones in the lower case. | |
810 | ||
811 | @since 2.9.0 | |
812 | ||
813 | @see MakeCapitalized() | |
814 | */ | |
815 | wxString Capitalize() const; | |
816 | ||
817 | /** | |
818 | Returns this string converted to the lower case. | |
819 | ||
820 | @see MakeLower() | |
821 | */ | |
822 | wxString Lower() const; | |
823 | ||
824 | /** | |
825 | Same as MakeLower. | |
826 | This is a wxWidgets 1.xx compatibility function; you should not use it in new | |
827 | code. | |
828 | */ | |
829 | void LowerCase(); | |
830 | ||
831 | /** | |
832 | Converts the first characters of the string to the upper case and all | |
833 | the subsequent ones to the lower case and returns the result. | |
834 | ||
835 | @since 2.9.0 | |
836 | ||
837 | @see Capitalize() | |
838 | */ | |
839 | wxString& MakeCapitalized(); | |
840 | ||
841 | /** | |
842 | Converts all characters to lower case and returns the reference to the | |
843 | modified string. | |
844 | ||
845 | @see Lower() | |
846 | */ | |
847 | wxString& MakeLower(); | |
848 | ||
849 | /** | |
850 | Converts all characters to upper case and returns the reference to the | |
851 | modified string. | |
852 | ||
853 | @see Upper() | |
854 | */ | |
855 | wxString& MakeUpper(); | |
856 | ||
857 | /** | |
858 | Returns this string converted to upper case. | |
859 | ||
860 | @see MakeUpper() | |
861 | */ | |
862 | wxString Upper() const; | |
863 | ||
864 | /** | |
865 | The same as MakeUpper(). | |
866 | ||
867 | This is a wxWidgets 1.xx compatibility function; you should not use it in new | |
868 | code. | |
869 | */ | |
870 | void UpperCase(); | |
871 | ||
872 | //@} | |
873 | ||
874 | ||
875 | /** | |
876 | @member_group_name{search, Searching and replacing} | |
877 | ||
878 | These functions replace the standard @c strchr() and @c strstr() | |
879 | functions. | |
880 | ||
881 | See also the find(), rfind(), replace() STL-like functions. | |
882 | */ | |
883 | //@{ | |
884 | ||
885 | /** | |
886 | Searches for the given character @a ch. | |
887 | Returns the position or @c wxNOT_FOUND if not found. | |
888 | */ | |
889 | int Find(wxUniChar ch, bool fromEnd = false) const; | |
890 | ||
891 | /** | |
892 | Searches for the given string @a sub. | |
893 | Returns the starting position or @c wxNOT_FOUND if not found. | |
894 | */ | |
895 | int Find(const wxString& sub) const; | |
896 | ||
897 | /** | |
898 | Same as Find(). | |
899 | ||
900 | This is a wxWidgets 1.xx compatibility function; | |
901 | you should not use it in new code. | |
902 | */ | |
903 | int First(wxUniChar ch) const; | |
904 | ||
905 | /** | |
906 | Same as Find(). | |
907 | ||
908 | This is a wxWidgets 1.xx compatibility function; | |
909 | you should not use it in new code. | |
910 | */ | |
911 | int First(const wxString& str) const; | |
912 | ||
913 | /** | |
914 | Replace first (or all) occurrences of substring with another one. | |
915 | ||
916 | @param strOld | |
917 | The string to search for replacing. | |
918 | @param strNew | |
919 | The substitution string. | |
920 | @param replaceAll | |
921 | If @true a global replace will be done (default), otherwise only the | |
922 | first occurrence will be replaced. | |
923 | ||
924 | Returns the number of replacements made. | |
925 | */ | |
926 | size_t Replace(const wxString& strOld, const wxString& strNew, | |
927 | bool replaceAll = true); | |
928 | ||
929 | //@} | |
930 | ||
931 | ||
932 | ||
933 | /** | |
934 | @member_group_name{numconv, Conversion to numbers} | |
935 | ||
936 | The string provides functions for conversion to signed and unsigned integer and | |
937 | floating point numbers. | |
938 | ||
939 | All functions take a pointer to the variable to put the numeric value | |
940 | in and return @true if the @b entire string could be converted to a | |
941 | number. Notice if there is a valid number in the beginning of the | |
942 | string, it is returned in the output parameter even if the function | |
943 | returns @false because there is more text following it. | |
944 | */ | |
945 | //@{ | |
946 | ||
947 | /** | |
948 | Attempts to convert the string to a floating point number. | |
949 | ||
950 | Returns @true on success (the number is stored in the location pointed to by | |
951 | @a val) or @false if the string does not represent such number (the value of | |
952 | @a val may still be modified in this case). | |
953 | ||
954 | Note that unlike ToCDouble() this function uses a localized version of | |
955 | @c wxStrtod() and thus needs as decimal point (and thousands separator) the | |
956 | locale-specific decimal point. Thus you should use this function only when | |
957 | you are sure that this string contains a floating point number formatted with | |
958 | the rules of the locale currently in use (see wxLocale). | |
959 | ||
960 | Refer to the docs of the standard function @c strtod() for more details about | |
961 | the supported syntax. | |
962 | ||
963 | @see ToCDouble(), ToLong(), ToULong() | |
964 | */ | |
965 | bool ToDouble(double* val) const; | |
966 | ||
967 | /** | |
968 | Variant of ToDouble() always working in "C" locale. | |
969 | ||
970 | Works like ToDouble() but unlike it this function expects the floating point | |
971 | number to be formatted always with the rules dictated by the "C" locale | |
972 | (in particular, the decimal point must be a dot), independently from the | |
973 | current application-wide locale (see wxLocale). | |
974 | ||
975 | @see ToDouble(), ToLong(), ToULong() | |
976 | */ | |
977 | bool ToCDouble(double* val) const; | |
978 | ||
979 | /** | |
980 | Attempts to convert the string to a signed integer in base @a base. | |
981 | ||
982 | Returns @true on success in which case the number is stored in the location | |
983 | pointed to by @a val or @false if the string does not represent a | |
984 | valid number in the given base (the value of @a val may still be | |
985 | modified in this case). | |
986 | ||
987 | The value of @a base must be comprised between 2 and 36, inclusive, or | |
988 | be a special value 0 which means that the usual rules of @c C numbers are | |
989 | applied: if the number starts with @c 0x it is considered to be in base | |
990 | 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note | |
991 | that you may not want to specify the base 0 if you are parsing the numbers | |
992 | which may have leading zeroes as they can yield unexpected (to the user not | |
993 | familiar with C) results. | |
994 | ||
995 | Note that unlike ToCLong() this function uses a localized version of | |
996 | @c wxStrtol(). Thus you should use this function only when you are sure | |
997 | that this string contains an integer number formatted with | |
998 | the rules of the locale currently in use (see wxLocale). | |
999 | ||
1000 | Refer to the docs of the standard function @c strtol() for more details about | |
1001 | the supported syntax. | |
1002 | ||
1003 | @see ToCDouble(), ToDouble(), ToULong() | |
1004 | */ | |
1005 | bool ToLong(long* val, int base = 10) const; | |
1006 | ||
1007 | /** | |
1008 | Variant of ToLong() always working in "C" locale. | |
1009 | ||
1010 | Works like ToLong() but unlike it this function expects the integer | |
1011 | number to be formatted always with the rules dictated by the "C" locale, | |
1012 | independently from the current application-wide locale (see wxLocale). | |
1013 | ||
1014 | @see ToDouble(), ToLong(), ToULong() | |
1015 | */ | |
1016 | bool ToCLong(long* val, int base = 10) const; | |
1017 | ||
1018 | /** | |
1019 | This is exactly the same as ToLong() but works with 64 bit integer numbers. | |
1020 | ||
1021 | Notice that currently it doesn't work (always returns @false) if parsing of 64 | |
1022 | bit numbers is not supported by the underlying C run-time library. Compilers | |
1023 | with C99 support and Microsoft Visual C++ version 7 and higher do support this. | |
1024 | ||
1025 | @see ToLong(), ToULongLong() | |
1026 | */ | |
1027 | bool ToLongLong(wxLongLong_t* val, int base = 10) const; | |
1028 | ||
1029 | /** | |
1030 | Attempts to convert the string to an unsigned integer in base @a base. | |
1031 | ||
1032 | Returns @true on success in which case the number is stored in the | |
1033 | location pointed to by @a val or @false if the string does not | |
1034 | represent a valid number in the given base (the value of @a val may | |
1035 | still be modified in this case). | |
1036 | ||
1037 | Please notice that this function behaves in the same way as the standard | |
1038 | @c strtoul() and so it simply converts negative numbers to unsigned | |
1039 | representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX). | |
1040 | ||
1041 | See ToLong() for the more detailed description of the @a base parameter | |
1042 | (and of the locale-specific behaviour of this function). | |
1043 | ||
1044 | @see ToCULong(), ToDouble(), ToLong() | |
1045 | */ | |
1046 | bool ToULong(unsigned long* val, int base = 10) const; | |
1047 | ||
1048 | /** | |
1049 | Variant of ToULong() always working in "C" locale. | |
1050 | ||
1051 | Works like ToULong() but unlike it this function expects the integer | |
1052 | number to be formatted always with the rules dictated by the "C" locale, | |
1053 | independently from the current application-wide locale (see wxLocale). | |
1054 | ||
1055 | @see ToDouble(), ToLong(), ToULong() | |
1056 | */ | |
1057 | bool ToCULong(unsigned long* val, int base = 10) const; | |
1058 | ||
1059 | /** | |
1060 | This is exactly the same as ToULong() but works with 64 bit integer | |
1061 | numbers. | |
1062 | ||
1063 | Please see ToLongLong() for additional remarks. | |
1064 | */ | |
1065 | bool ToULongLong(wxULongLong_t* val, int base = 10) const; | |
1066 | ||
1067 | //@} | |
1068 | ||
1069 | ||
1070 | /** | |
1071 | @member_group_name{fmt, Formatting and printing} | |
1072 | ||
1073 | Both formatted versions (Printf/() and stream-like insertion operators | |
1074 | exist (for basic types only). | |
1075 | ||
1076 | See also the static Format() and FormatV() functions. | |
1077 | */ | |
1078 | //@{ | |
1079 | ||
1080 | /** | |
1081 | Similar to the standard function @e sprintf(). Returns the number of | |
1082 | characters written, or an integer less than zero on error. | |
1083 | Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports | |
1084 | Unix98-style positional parameters: | |
1085 | ||
1086 | @code | |
1087 | wxString str; | |
1088 | ||
1089 | str.Printf(wxT("%d %d %d"), 1, 2, 3); | |
1090 | // str now contains "1 2 3" | |
1091 | ||
1092 | str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3); | |
1093 | // str now contains "2 3 1" | |
1094 | @endcode | |
1095 | ||
1096 | @note This function will use a safe version of @e vsprintf() (usually called | |
1097 | @e vsnprintf()) whenever available to always allocate the buffer of correct | |
1098 | size. Unfortunately, this function is not available on all platforms and the | |
1099 | dangerous @e vsprintf() will be used then which may lead to buffer overflows. | |
1100 | */ | |
1101 | int Printf(const wxString& pszFormat, ...); | |
1102 | ||
1103 | /** | |
1104 | Similar to vprintf. Returns the number of characters written, or an integer | |
1105 | less than zero | |
1106 | on error. | |
1107 | */ | |
1108 | int PrintfV(const wxString& pszFormat, va_list argPtr); | |
1109 | ||
1110 | //@} | |
1111 | ||
1112 | ||
1113 | /** | |
1114 | @member_group_name{mem, Memory management} | |
1115 | ||
1116 | The following are "advanced" functions and they will be needed rarely. | |
1117 | Alloc() and Shrink() are only interesting for optimization purposes. | |
1118 | wxStringBuffer and wxStringBufferLength classes may be very useful when working | |
1119 | with some external API which requires the caller to provide a writable buffer. | |
1120 | ||
1121 | See also the reserve() and resize() STL-like functions. | |
1122 | */ | |
1123 | //@{ | |
1124 | ||
1125 | /** | |
1126 | Preallocate enough space for wxString to store @a nLen characters. | |
1127 | ||
1128 | Please note that this method does the same thing as the standard | |
1129 | reserve() one and shouldn't be used in new code. | |
1130 | ||
1131 | This function may be used to increase speed when the string is | |
1132 | constructed by repeated concatenation as in | |
1133 | ||
1134 | @code | |
1135 | // delete all vowels from the string | |
1136 | wxString DeleteAllVowels(const wxString& original) | |
1137 | { | |
1138 | wxString result; | |
1139 | ||
1140 | size_t len = original.length(); | |
1141 | ||
1142 | result.Alloc(len); | |
1143 | ||
1144 | for ( size_t n = 0; n < len; n++ ) | |
1145 | { | |
1146 | if ( strchr("aeuio", tolower(original[n])) == NULL ) | |
1147 | result += original[n]; | |
1148 | } | |
1149 | ||
1150 | return result; | |
1151 | } | |
1152 | @endcode | |
1153 | ||
1154 | because it will avoid the need to reallocate string memory many times | |
1155 | (in case of long strings). Note that it does not set the maximal length | |
1156 | of a string -- it will still expand if more than @a nLen characters are | |
1157 | stored in it. Also, it does not truncate the existing string (use | |
1158 | Truncate() for this) even if its current length is greater than @a nLen. | |
1159 | ||
1160 | @return @true if memory was successfully allocated, @false otherwise. | |
1161 | */ | |
1162 | bool Alloc(size_t nLen); | |
1163 | ||
1164 | /** | |
1165 | Minimizes the string's memory. This can be useful after a call to | |
1166 | Alloc() if too much memory were preallocated. | |
1167 | */ | |
1168 | bool Shrink(); | |
1169 | ||
1170 | /** | |
1171 | Returns a deep copy of the string. | |
1172 | ||
1173 | That is, the returned string is guaranteed to not share data with this | |
1174 | string when using reference-counted wxString implementation. | |
1175 | ||
1176 | This method is primarily useful for passing strings between threads | |
1177 | (because wxString is not thread-safe). Unlike creating a copy using | |
1178 | @c wxString(c_str()), Clone() handles embedded NULs correctly. | |
1179 | ||
1180 | @since 2.9.0 | |
1181 | */ | |
1182 | wxString Clone() const; | |
1183 | ||
1184 | /** | |
1185 | Empties the string and frees memory occupied by it. | |
1186 | ||
1187 | @see Empty() | |
1188 | */ | |
1189 | void Clear(); | |
1190 | ||
1191 | //@} | |
1192 | ||
1193 | ||
1194 | ||
1195 | /** | |
1196 | @member_group_name{misc, Miscellaneous} | |
1197 | ||
1198 | Miscellaneous other string functions. | |
1199 | */ | |
1200 | //@{ | |
1201 | ||
1202 | /** | |
1203 | Returns @true if target appears anywhere in wxString; else @false. | |
1204 | ||
1205 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1206 | */ | |
1207 | bool Contains(const wxString& str) const; | |
1208 | ||
1209 | /** | |
1210 | Makes the string empty, but doesn't free memory occupied by the string. | |
1211 | ||
1212 | @see Clear(). | |
1213 | */ | |
1214 | void Empty(); | |
1215 | ||
1216 | /** | |
1217 | Returns the number of occurrences of @e ch in the string. | |
1218 | ||
1219 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1220 | */ | |
1221 | int Freq(wxUniChar ch) const; | |
1222 | ||
1223 | /** | |
1224 | Returns @true if the string contains only ASCII characters. | |
1225 | See wxUniChar::IsAscii for more details. | |
1226 | ||
1227 | This is a wxWidgets 1.xx compatibility function; you should not use it in new | |
1228 | code. | |
1229 | */ | |
1230 | bool IsAscii() const; | |
1231 | ||
1232 | /** | |
1233 | Returns @true if the string is an integer (with possible sign). | |
1234 | ||
1235 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1236 | */ | |
1237 | bool IsNumber() const; | |
1238 | ||
1239 | /** | |
1240 | Returns @true if the string is a word. | |
1241 | ||
1242 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1243 | */ | |
1244 | bool IsWord() const; | |
1245 | ||
1246 | /** | |
1247 | Adds @a count copies of @a chPad to the beginning, or to the end of the | |
1248 | string (the default). | |
1249 | ||
1250 | Removes spaces from the left or from the right (default). | |
1251 | */ | |
1252 | wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); | |
1253 | ||
1254 | /** | |
1255 | Removes all characters from the string starting at @a pos. | |
1256 | Use Truncate() as a more readable alternative. | |
1257 | ||
1258 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1259 | */ | |
1260 | wxString& Remove(size_t pos); | |
1261 | ||
1262 | /** | |
1263 | Removes @a len characters from the string, starting at @a pos. | |
1264 | ||
1265 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1266 | */ | |
1267 | wxString& Remove(size_t pos, size_t len); | |
1268 | ||
1269 | /** | |
1270 | Removes the last character. | |
1271 | */ | |
1272 | wxString& RemoveLast(size_t n = 1); | |
1273 | ||
1274 | /** | |
1275 | Strip characters at the front and/or end. | |
1276 | ||
1277 | This is the same as Trim() except that it doesn't change this string. | |
1278 | ||
1279 | This is a wxWidgets 1.xx compatibility function; you should not use it in new code. | |
1280 | */ | |
1281 | wxString Strip(stripType s = trailing) const; | |
1282 | ||
1283 | /** | |
1284 | Removes white-space (space, tabs, form feed, newline and carriage return) from | |
1285 | the left or from the right end of the string (right is default). | |
1286 | */ | |
1287 | wxString& Trim(bool fromRight = true); | |
1288 | ||
1289 | /** | |
1290 | Truncate the string to the given length. | |
1291 | */ | |
1292 | wxString& Truncate(size_t len); | |
1293 | ||
1294 | //@} | |
1295 | ||
1296 | ||
1297 | ||
1298 | ||
1299 | /** | |
1300 | @member_group_name{iter, Iterator interface} | |
1301 | ||
1302 | These methods return iterators to the beginnnig or end of the string. | |
1303 | ||
1304 | Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) | |
1305 | for their documentation. | |
1306 | */ | |
1307 | //@{ | |
1308 | ||
1309 | const_iterator begin() const; | |
1310 | iterator begin(); | |
1311 | const_iterator end() const; | |
1312 | iterator end(); | |
1313 | ||
1314 | const_reverse_iterator rbegin() const; | |
1315 | reverse_iterator rbegin(); | |
1316 | const_reverse_iterator rend() const; | |
1317 | reverse_iterator rend(); | |
1318 | ||
1319 | //@} | |
1320 | ||
1321 | ||
1322 | ||
1323 | /** | |
1324 | @member_group_name{stl, STL interface} | |
1325 | ||
1326 | The supported STL functions are listed here. | |
1327 | ||
1328 | Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) | |
1329 | for their documentation. | |
1330 | */ | |
1331 | //@{ | |
1332 | ||
1333 | wxString& append(const wxString& str, size_t pos, size_t n); | |
1334 | wxString& append(const wxString& str); | |
1335 | wxString& append(const char *sz, size_t n); | |
1336 | wxString& append(const wchar_t *sz, size_t n); | |
1337 | wxString& append(size_t n, wxUniChar ch); | |
1338 | wxString& append(const_iterator first, const_iterator last); | |
1339 | ||
1340 | wxString& assign(const wxString& str, size_t pos, size_t n); | |
1341 | wxString& assign(const wxString& str); | |
1342 | wxString& assign(const char *sz, size_t n); | |
1343 | wxString& assign(const wchar_t *sz, size_t n); | |
1344 | wxString& assign(size_t n, wxUniChar ch); | |
1345 | wxString& assign(const_iterator first, const_iterator last); | |
1346 | ||
1347 | wxUniChar at(size_t n) const; | |
1348 | wxUniCharRef at(size_t n); | |
1349 | ||
1350 | void clear(); | |
1351 | ||
1352 | size_type capacity() const; | |
1353 | ||
1354 | int compare(const wxString& str) const; | |
1355 | int compare(size_t nStart, size_t nLen, const wxString& str) const; | |
1356 | int compare(size_t nStart, size_t nLen, | |
1357 | const wxString& str, size_t nStart2, size_t nLen2) const; | |
1358 | int compare(size_t nStart, size_t nLen, | |
1359 | const char* sz, size_t nCount = npos) const; | |
1360 | int compare(size_t nStart, size_t nLen, | |
1361 | const wchar_t* sz, size_t nCount = npos) const; | |
1362 | ||
1363 | wxCStrData data() const; | |
1364 | ||
1365 | bool empty() const; | |
1366 | ||
1367 | wxString& erase(size_type pos = 0, size_type n = npos); | |
1368 | iterator erase(iterator first, iterator last); | |
1369 | iterator erase(iterator first); | |
1370 | ||
1371 | size_t find(const wxString& str, size_t nStart = 0) const; | |
1372 | size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; | |
1373 | size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const; | |
1374 | size_t find(wxUniChar ch, size_t nStart = 0) const; | |
1375 | size_t find_first_of(const char* sz, size_t nStart = 0) const; | |
1376 | size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const; | |
1377 | size_t find_first_of(const char* sz, size_t nStart, size_t n) const; | |
1378 | size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const; | |
1379 | size_t find_first_of(wxUniChar c, size_t nStart = 0) const; | |
1380 | size_t find_last_of (const wxString& str, size_t nStart = npos) const; | |
1381 | size_t find_last_of (const char* sz, size_t nStart = npos) const; | |
1382 | size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const; | |
1383 | size_t find_last_of(const char* sz, size_t nStart, size_t n) const; | |
1384 | size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const; | |
1385 | size_t find_last_of(wxUniChar c, size_t nStart = npos) const; | |
1386 | size_t find_first_not_of(const wxString& str, size_t nStart = 0) const; | |
1387 | size_t find_first_not_of(const char* sz, size_t nStart = 0) const; | |
1388 | size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const; | |
1389 | size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const; | |
1390 | size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const; | |
1391 | size_t find_first_not_of(wxUniChar ch, size_t nStart = 0) const; | |
1392 | size_t find_last_not_of(const wxString& str, size_t nStart = npos) const; | |
1393 | size_t find_last_not_of(const char* sz, size_t nStart = npos) const; | |
1394 | size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const; | |
1395 | size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const; | |
1396 | size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) const; | |
1397 | ||
1398 | wxString& insert(size_t nPos, const wxString& str); | |
1399 | wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); | |
1400 | wxString& insert(size_t nPos, const char *sz, size_t n); | |
1401 | wxString& insert(size_t nPos, const wchar_t *sz, size_t n); | |
1402 | wxString& insert(size_t nPos, size_t n, wxUniChar ch); | |
1403 | iterator insert(iterator it, wxUniChar ch); | |
1404 | void insert(iterator it, const_iterator first, const_iterator last); | |
1405 | void insert(iterator it, size_type n, wxUniChar ch); | |
1406 | ||
1407 | size_t length() const; | |
1408 | ||
1409 | size_type max_size() const; | |
1410 | ||
1411 | void reserve(size_t sz); | |
1412 | void resize(size_t nSize, wxUniChar ch = '\0'); | |
1413 | ||
1414 | wxString& replace(size_t nStart, size_t nLen, const wxString& str); | |
1415 | wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch); | |
1416 | wxString& replace(size_t nStart, size_t nLen, | |
1417 | const wxString& str, size_t nStart2, size_t nLen2); | |
1418 | wxString& replace(size_t nStart, size_t nLen, | |
1419 | const char* sz, size_t nCount); | |
1420 | wxString& replace(size_t nStart, size_t nLen, | |
1421 | const wchar_t* sz, size_t nCount); | |
1422 | wxString& replace(size_t nStart, size_t nLen, | |
1423 | const wxString& s, size_t nCount); | |
1424 | wxString& replace(iterator first, iterator last, const wxString& s); | |
1425 | wxString& replace(iterator first, iterator last, const char* s, size_type n); | |
1426 | wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n); | |
1427 | wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch); | |
1428 | wxString& replace(iterator first, iterator last, | |
1429 | const_iterator first1, const_iterator last1); | |
1430 | wxString& replace(iterator first, iterator last, | |
1431 | const char *first1, const char *last1); | |
1432 | wxString& replace(iterator first, iterator last, | |
1433 | const wchar_t *first1, const wchar_t *last1); | |
1434 | ||
1435 | size_t rfind(const wxString& str, size_t nStart = npos) const; | |
1436 | size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const; | |
1437 | size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const; | |
1438 | size_t rfind(wxUniChar ch, size_t nStart = npos) const; | |
1439 | ||
1440 | size_type size() const; | |
1441 | wxString substr(size_t nStart = 0, size_t nLen = npos) const; | |
1442 | void swap(wxString& str); | |
1443 | ||
1444 | //@} | |
1445 | ||
1446 | ||
1447 | ||
1448 | // STATIC FUNCTIONS | |
1449 | // Keep these functions separed from the other groups or Doxygen gets confused | |
1450 | // ----------------------------------------------------------------------------- | |
1451 | ||
1452 | /** | |
1453 | An 'invalid' value for string index | |
1454 | */ | |
1455 | static const size_t npos; | |
1456 | ||
1457 | /** | |
1458 | This static function returns the string containing the result of calling | |
1459 | Printf() with the passed parameters on it. | |
1460 | ||
1461 | @see FormatV(), Printf() | |
1462 | */ | |
1463 | static wxString Format(const wxString& format, ...); | |
1464 | ||
1465 | /** | |
1466 | This static function returns the string containing the result of calling | |
1467 | PrintfV() with the passed parameters on it. | |
1468 | ||
1469 | @see Format(), PrintfV() | |
1470 | */ | |
1471 | static wxString FormatV(const wxString& format, va_list argptr); | |
1472 | ||
1473 | //@{ | |
1474 | /** | |
1475 | Converts given buffer of binary data from 8-bit string to wxString. In | |
1476 | Unicode build, the string is interpreted as being in ISO-8859-1 | |
1477 | encoding. The version without @e len parameter takes NUL-terminated | |
1478 | data. | |
1479 | ||
1480 | This is a convenience method useful when storing binary data in | |
1481 | wxString. It should be used @em only for that purpose and only in | |
1482 | conjunction with To8BitData(). Use mb_str() for conversion of character | |
1483 | data to known encoding. | |
1484 | ||
1485 | @since 2.8.4 | |
1486 | ||
1487 | @see wxString::To8BitData() | |
1488 | */ | |
1489 | static wxString From8BitData(const char* buf, size_t len); | |
1490 | static wxString From8BitData(const char* buf); | |
1491 | //@} | |
1492 | ||
1493 | //@{ | |
1494 | /** | |
1495 | Converts the string or character from an ASCII, 7-bit form | |
1496 | to the native wxString representation. | |
1497 | */ | |
1498 | static wxString FromAscii(const char* s); | |
1499 | static wxString FromAscii(const unsigned char* s); | |
1500 | static wxString FromAscii(const char* s, size_t len); | |
1501 | static wxString FromAscii(const unsigned char* s, size_t len); | |
1502 | static wxString FromAscii(char c); | |
1503 | //@} | |
1504 | ||
1505 | /** | |
1506 | Returns a string with the textual representation of the number in C | |
1507 | locale. | |
1508 | ||
1509 | Unlike FromDouble() the string returned by this function always uses | |
1510 | the period character as decimal separator, independently of the current | |
1511 | locale. | |
1512 | ||
1513 | @since 2.9.1 | |
1514 | ||
1515 | @see ToCDouble() | |
1516 | */ | |
1517 | static wxString FromCDouble(double val); | |
1518 | ||
1519 | /** | |
1520 | Returns a string with the textual representation of the number. | |
1521 | ||
1522 | This is a simple wrapper for @code wxString::Format("%g", val) | |
1523 | @endcode. | |
1524 | ||
1525 | Notice that the string returned by this function uses the decimal | |
1526 | separator appropriate for the current locale, e.g. @c "," and not a | |
1527 | period in French locale. Use FromCDouble() if this is unwanted. | |
1528 | ||
1529 | @since 2.9.1 | |
1530 | ||
1531 | @see ToDouble() | |
1532 | */ | |
1533 | static wxString FromDouble(double val); | |
1534 | ||
1535 | //@{ | |
1536 | /** | |
1537 | Converts C string encoded in UTF-8 to wxString. | |
1538 | ||
1539 | If @a s is not a valid UTF-8 string, an empty string is returned. | |
1540 | ||
1541 | Notice that when using UTF-8 wxWidgets build there is a more efficient | |
1542 | alternative to this function called FromUTF8Unchecked() which, unlike | |
1543 | this one, doesn't check that the input string is valid. | |
1544 | ||
1545 | @since 2.8.4 | |
1546 | */ | |
1547 | static wxString FromUTF8(const char* s); | |
1548 | static wxString FromUTF8(const char* s, size_t len); | |
1549 | //@} | |
1550 | ||
1551 | //@{ | |
1552 | /** | |
1553 | Converts C string encoded in UTF-8 to wxString without checking its | |
1554 | validity. | |
1555 | ||
1556 | This method assumes that @a s is a valid UTF-8 sequence and doesn't do | |
1557 | any validation (although an assert failure is triggered in debug builds | |
1558 | if the string is invalid). Only use it if you are absolutely sure that | |
1559 | @a s is a correct UTF-8 string (e.g. because it comes from another | |
1560 | library using UTF-8) and if the performance matters, otherwise use | |
1561 | slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8 | |
1562 | string to this function will result in creating a corrupted wxString | |
1563 | and all the subsequent operations on it will be undefined. | |
1564 | ||
1565 | @since 2.8.9 | |
1566 | */ | |
1567 | static wxString FromUTF8Unchecked(const char* s); | |
1568 | static wxString FromUTF8Unchecked(const char* s, size_t len); | |
1569 | //@} | |
1570 | }; | |
1571 | ||
1572 | ||
1573 | ||
1574 | //@{ | |
1575 | /** | |
1576 | Comparison operator for string types. | |
1577 | */ | |
1578 | inline bool operator==(const wxString& s1, const wxString& s2); | |
1579 | inline bool operator!=(const wxString& s1, const wxString& s2); | |
1580 | inline bool operator< (const wxString& s1, const wxString& s2); | |
1581 | inline bool operator> (const wxString& s1, const wxString& s2); | |
1582 | inline bool operator<=(const wxString& s1, const wxString& s2); | |
1583 | inline bool operator>=(const wxString& s1, const wxString& s2); | |
1584 | inline bool operator==(const wxString& s1, const wxCStrData& s2); | |
1585 | inline bool operator==(const wxCStrData& s1, const wxString& s2); | |
1586 | inline bool operator!=(const wxString& s1, const wxCStrData& s2); | |
1587 | inline bool operator!=(const wxCStrData& s1, const wxString& s2); | |
1588 | inline bool operator==(const wxString& s1, const wxWCharBuffer& s2); | |
1589 | inline bool operator==(const wxWCharBuffer& s1, const wxString& s2); | |
1590 | inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2); | |
1591 | inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2); | |
1592 | inline bool operator==(const wxString& s1, const wxCharBuffer& s2); | |
1593 | inline bool operator==(const wxCharBuffer& s1, const wxString& s2); | |
1594 | inline bool operator!=(const wxString& s1, const wxCharBuffer& s2); | |
1595 | inline bool operator!=(const wxCharBuffer& s1, const wxString& s2); | |
1596 | //@} | |
1597 | ||
1598 | //@{ | |
1599 | /** | |
1600 | Comparison operators char types. | |
1601 | */ | |
1602 | inline bool operator==(const wxUniChar& c, const wxString& s); | |
1603 | inline bool operator==(const wxUniCharRef& c, const wxString& s); | |
1604 | inline bool operator==(char c, const wxString& s); | |
1605 | inline bool operator==(wchar_t c, const wxString& s); | |
1606 | inline bool operator==(int c, const wxString& s); | |
1607 | inline bool operator==(const wxString& s, const wxUniChar& c); | |
1608 | inline bool operator==(const wxString& s, const wxUniCharRef& c); | |
1609 | inline bool operator==(const wxString& s, char c); | |
1610 | inline bool operator==(const wxString& s, wchar_t c); | |
1611 | inline bool operator!=(const wxUniChar& c, const wxString& s); | |
1612 | inline bool operator!=(const wxUniCharRef& c, const wxString& s); | |
1613 | inline bool operator!=(char c, const wxString& s); | |
1614 | inline bool operator!=(wchar_t c, const wxString& s); | |
1615 | inline bool operator!=(int c, const wxString& s); | |
1616 | inline bool operator!=(const wxString& s, const wxUniChar& c); | |
1617 | inline bool operator!=(const wxString& s, const wxUniCharRef& c); | |
1618 | inline bool operator!=(const wxString& s, char c); | |
1619 | inline bool operator!=(const wxString& s, wchar_t c); | |
1620 | //@} | |
1621 | ||
1622 | /** | |
1623 | The global wxString instance of an empty string. | |
1624 | Used extensively in the entire wxWidgets API. | |
1625 | */ | |
1626 | wxString wxEmptyString; | |
1627 | ||
1628 | ||
1629 | ||
1630 | /** | |
1631 | @class wxStringBufferLength | |
1632 | ||
1633 | This tiny class allows you to conveniently access the wxString internal buffer | |
1634 | as a writable pointer without any risk of forgetting to restore the string to | |
1635 | the usable state later, and allows the user to set the internal length of the string. | |
1636 | ||
1637 | For example, assuming you have a low-level OS function called | |
1638 | @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided | |
1639 | buffer (which must be writable, of course), and returning the actual length | |
1640 | of the string, you might call it like this: | |
1641 | ||
1642 | @code | |
1643 | wxString theAnswer; | |
1644 | wxStringBufferLength theAnswerBuffer(theAnswer, 1024); | |
1645 | int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); | |
1646 | theAnswerBuffer.SetLength(nLength); | |
1647 | if ( theAnswer != "42" ) | |
1648 | wxLogError("Something is very wrong!"); | |
1649 | @endcode | |
1650 | ||
1651 | Note that the exact usage of this depends on whether or not wxUSE_STL is | |
1652 | enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty | |
1653 | character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from | |
1654 | wxString, keeping the same buffer wxString uses intact. In other words, | |
1655 | relying on wxStringBuffer containing the old wxString data is not a good | |
1656 | idea if you want to build your program both with and without wxUSE_STL. | |
1657 | ||
1658 | Note that wxStringBuffer::SetLength @b must be called before | |
1659 | wxStringBufferLength destructs. | |
1660 | ||
1661 | @library{wxbase} | |
1662 | @category{data} | |
1663 | */ | |
1664 | class wxStringBufferLength | |
1665 | { | |
1666 | public: | |
1667 | /** | |
1668 | Constructs a writable string buffer object associated with the given string | |
1669 | and containing enough space for at least @a len characters. | |
1670 | ||
1671 | Basically, this is equivalent to calling wxString::GetWriteBuf and | |
1672 | saving the result. | |
1673 | */ | |
1674 | wxStringBufferLength(const wxString& str, size_t len); | |
1675 | ||
1676 | /** | |
1677 | Restores the string passed to the constructor to the usable state by calling | |
1678 | wxString::UngetWriteBuf on it. | |
1679 | */ | |
1680 | ~wxStringBufferLength(); | |
1681 | ||
1682 | /** | |
1683 | Sets the internal length of the string referred to by wxStringBufferLength to | |
1684 | @a nLength characters. | |
1685 | ||
1686 | Must be called before wxStringBufferLength destructs. | |
1687 | */ | |
1688 | void SetLength(size_t nLength); | |
1689 | ||
1690 | /** | |
1691 | Returns the writable pointer to a buffer of the size at least equal to the | |
1692 | length specified in the constructor. | |
1693 | */ | |
1694 | wxChar* operator wxChar *(); | |
1695 | }; | |
1696 | ||
1697 | ||
1698 | /** | |
1699 | @class wxStringBuffer | |
1700 | ||
1701 | This tiny class allows you to conveniently access the wxString internal buffer | |
1702 | as a writable pointer without any risk of forgetting to restore the string | |
1703 | to the usable state later. | |
1704 | ||
1705 | For example, assuming you have a low-level OS function called | |
1706 | @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided | |
1707 | buffer (which must be writable, of course) you might call it like this: | |
1708 | ||
1709 | @code | |
1710 | wxString theAnswer; | |
1711 | GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); | |
1712 | if ( theAnswer != "42" ) | |
1713 | wxLogError("Something is very wrong!"); | |
1714 | @endcode | |
1715 | ||
1716 | Note that the exact usage of this depends on whether or not @c wxUSE_STL is | |
1717 | enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty | |
1718 | character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from | |
1719 | wxString, keeping the same buffer wxString uses intact. In other words, | |
1720 | relying on wxStringBuffer containing the old wxString data is not a good | |
1721 | idea if you want to build your program both with and without @c wxUSE_STL. | |
1722 | ||
1723 | @library{wxbase} | |
1724 | @category{data} | |
1725 | */ | |
1726 | class wxStringBuffer | |
1727 | { | |
1728 | public: | |
1729 | /** | |
1730 | Constructs a writable string buffer object associated with the given string | |
1731 | and containing enough space for at least @a len characters. | |
1732 | Basically, this is equivalent to calling wxString::GetWriteBuf() and | |
1733 | saving the result. | |
1734 | */ | |
1735 | wxStringBuffer(const wxString& str, size_t len); | |
1736 | ||
1737 | /** | |
1738 | Restores the string passed to the constructor to the usable state by calling | |
1739 | wxString::UngetWriteBuf() on it. | |
1740 | */ | |
1741 | ~wxStringBuffer(); | |
1742 | ||
1743 | /** | |
1744 | Returns the writable pointer to a buffer of the size at least equal to the | |
1745 | length specified in the constructor. | |
1746 | */ | |
1747 | wxStringCharType* operator wxStringCharType *(); | |
1748 | }; | |
1749 | ||
1750 | ||
1751 | /** @addtogroup group_funcmacro_string */ | |
1752 | //@{ | |
1753 | ||
1754 | /** | |
1755 | Allows to extend a function with the signature: | |
1756 | @code bool SomeFunc(const wxUniChar& c) @endcode | |
1757 | which operates on a single character, to an entire wxString. | |
1758 | ||
1759 | E.g. if you want to check if an entire string contains only digits, | |
1760 | you can do: | |
1761 | @code | |
1762 | if (wxStringCheck<wxIsdigit>(myString)) | |
1763 | ... // the entire string contains oly digits! | |
1764 | else | |
1765 | ... // at least one character of myString is not a digit | |
1766 | @endcode | |
1767 | ||
1768 | @return @true if the given function returns a non-zero value for all | |
1769 | characters of the @a val string. | |
1770 | */ | |
1771 | template<bool (T)(const wxUniChar& c)> | |
1772 | inline bool wxStringCheck(const wxString& val); | |
1773 | ||
1774 | //@} |