]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/wxstring.tex
Fixed two instances of : inbetween wxRect and method name (Inside and Intersects...
[wxWidgets.git] / docs / latex / wx / wxstring.tex
1 \section{\class{wxString}}\label{wxstring}
2
3 wxString is a class representing a character string. Please see the
4 \helpref{wxString overview}{wxstringoverview} for more information about it. As explained
5 there, wxString implements about 90\% of methods of the std::string class (iterators
6 are not supported, nor all methods which use them).
7 These standard functions are not documented in this manual so please see the STL documentation.
8 The behaviour of all these functions is identical to the behaviour described
9 there (except that wxString is sensitive to null character).
10
11 You may notice that wxString sometimes has many functions which do the same
12 thing like, for example, \helpref{Length()}{wxstringlength},
13 \helpref{Len()}{wxstringlen} and {\tt length()} which all return the string
14 length. In all cases of such duplication the {\tt std::string}-compatible
15 method ({\tt length()} in this case, always the lowercase version) should be
16 used as it will ensure smoother transition to {\tt std::string} when wxWidgets
17 starts using it instead of wxString.
18
19 \wxheading{Derived from}
20
21 None
22
23 \wxheading{Include files}
24
25 <wx/string.h>
26
27 \wxheading{Predefined objects}
28
29 Objects:
30
31 {\bf wxEmptyString}
32
33 \wxheading{See also}
34
35 \overview{Overview}{wxstringoverview}
36
37 \latexignore{\rtfignore{\wxheading{Function groups}}}
38
39 \membersection{Constructors and assignment operators}\label{constructorsinwxstring}
40
41 A string may be constructed either from a C string, (some number of copies of)
42 a single character or a wide (UNICODE) string. For all constructors (except the
43 default which creates an empty string) there is also a corresponding assignment
44 operator.
45
46 \helpref{wxString}{wxstringconstruct}\\
47 \helpref{operator $=$}{wxstringoperatorassign}\\
48 \helpref{\destruct{wxString}}{wxstringdestruct}
49
50 \membersection{String length}\label{lengthfunctionsinwxstring}
51
52 These functions return the string length and check whether the string is empty
53 or empty it.
54
55 \helpref{Len}{wxstringlen}\\
56 \helpref{IsEmpty}{wxstringisempty}\\
57 \helpref{operator!}{wxstringoperatornot}\\
58 \helpref{Empty}{wxstringempty}\\
59 \helpref{Clear}{wxstringclear}
60
61 \membersection{Character access}\label{characteraccessinwxstring}
62
63 Many functions in this section take a character index in the string. As with C
64 strings and/or arrays, the indices start from $0$, so the first character of a
65 string is string[$0$]. Attempt to access a character beyond the end of the
66 string (which may be even $0$ if the string is empty) will provoke an assert
67 failure in \helpref{debug build}{debuggingoverview}, but no checks are done in
68 release builds.
69
70 This section also contains both implicit and explicit conversions to C style
71 strings. Although implicit conversion is quite convenient, it is advised to use
72 explicit \helpref{c\_str()}{wxstringcstr} method for the sake of clarity. Also
73 see \helpref{overview}{wxstringadvices} for the cases where it is necessary to
74 use it.
75
76 \helpref{GetChar}{wxstringgetchar}\\
77 \helpref{GetWritableChar}{wxstringgetwritablechar}\\
78 \helpref{SetChar}{wxstringsetchar}\\
79 \helpref{Last}{wxstringlast}\\
80 \helpref{operator []}{wxstringoperatorbracket}\\
81 \helpref{c\_str}{wxstringcstr}\\
82 \helpref{mb\_str}{wxstringmbstr}\\
83 \helpref{wc\_str}{wxstringwcstr}\\
84 \helpref{fn\_str}{wxstringfnstr}\\
85 \helpref{operator const char*}{wxstringoperatorconstcharpt}
86
87 \membersection{Concatenation}\label{concatenationinwxstring}
88
89 Anything may be concatenated (appended to) with a string. However, you can't
90 append something to a C string (including literal constants), so to do this it
91 should be converted to a wxString first.
92
93 \helpref{operator \cinsert}{wxstringoperatorout}\\
94 \helpref{operator $+=$}{wxstringplusequal}\\
95 \helpref{operator $+$}{wxstringoperatorplus}\\
96 \helpref{Append}{wxstringappend}\\
97 \helpref{Prepend}{wxstringprepend}
98
99 \membersection{Comparison}\label{comparisoninwxstring}
100
101 The default comparison function \helpref{Cmp}{wxstringcmp} is case-sensitive and
102 so is the default version of \helpref{IsSameAs}{wxstringissameas}. For case
103 insensitive comparisons you should use \helpref{CmpNoCase}{wxstringcmpnocase} or
104 give a second parameter to IsSameAs. This last function is may be more
105 convenient if only equality of the strings matters because it returns a boolean
106 true value if the strings are the same and not 0 (which is usually false in C)
107 as {\tt Cmp()} does.
108
109 \helpref{Matches}{wxstringmatches} is a poor man's regular expression matcher:
110 it only understands '*' and '?' metacharacters in the sense of DOS command line
111 interpreter.
112
113 \helpref{StartsWith}{wxstringstartswith} is helpful when parsing a line of
114 text which should start with some predefined prefix and is more efficient than
115 doing direct string comparison as you would also have to precalculate the
116 length of the prefix then.
117
118 \helpref{Cmp}{wxstringcmp}\\
119 \helpref{CmpNoCase}{wxstringcmpnocase}\\
120 \helpref{IsSameAs}{wxstringissameas}\\
121 \helpref{Matches}{wxstringmatches}\\
122 \helpref{StartsWith}{wxstringstartswith}
123
124 \membersection{Substring extraction}\label{substringextractioninwxstring}
125
126 These functions allow to extract substring from this string. All of them don't
127 modify the original string and return a new string containing the extracted
128 substring.
129
130 \helpref{Mid}{wxstringmid}\\
131 \helpref{operator()}{wxstringoperatorparenth}\\
132 \helpref{Left}{wxstringleft}\\
133 \helpref{Right}{wxstringright}\\
134 \helpref{BeforeFirst}{wxstringbeforefirst}\\
135 \helpref{BeforeLast}{wxstringbeforelast}\\
136 \helpref{AfterFirst}{wxstringafterfirst}\\
137 \helpref{AfterLast}{wxstringafterlast}\\
138 \helpref{StartsWith}{wxstringstartswith}
139
140 \membersection{Case conversion}\label{caseconversioninwxstring}
141
142 The MakeXXX() variants modify the string in place, while the other functions
143 return a new string which contains the original text converted to the upper or
144 lower case and leave the original string unchanged.
145
146 \helpref{MakeUpper}{wxstringmakeupper}\\
147 \helpref{Upper}{wxstringupper}\\
148 \helpref{MakeLower}{wxstringmakelower}\\
149 \helpref{Lower}{wxstringlower}
150
151 \membersection{Searching and replacing}\label{searchingandreplacinginwxstring}
152
153 These functions replace the standard {\it strchr()} and {\it strstr()}
154 functions.
155
156 \helpref{Find}{wxstringfind}\\
157 \helpref{Replace}{wxstringreplace}
158
159 \membersection{Conversion to numbers}\label{conversiontonumbersinwxstring}
160
161 The string provides functions for conversion to signed and unsigned integer and
162 floating point numbers. All three functions take a pointer to the variable to
163 put the numeric value in and return true if the {\bf entire} string could be
164 converted to a number.
165
166 \helpref{ToLong}{wxstringtolong}\\
167 \helpref{ToULong}{wxstringtoulong}\\
168 \helpref{ToDouble}{wxstringtodouble}
169
170 \membersection{Writing values into the string}\label{writingintostringinwxstring}
171
172 Both formatted versions (\helpref{Printf}{wxstringprintf}) and stream-like
173 insertion operators exist (for basic types only). Additionally, the
174 \helpref{Format}{wxstringformat} function allows to use simply append
175 formatted value to a string:
176
177 \begin{verbatim}
178 // the following 2 snippets are equivalent
179
180 wxString s = "...";
181 s += wxString::Format("%d", n);
182
183 wxString s;
184 s.Printf("...%d", n);
185 \end{verbatim}
186
187 \helpref{Format}{wxstringformat}\\
188 \helpref{FormatV}{wxstringformatv}\\
189 \helpref{Printf}{wxstringprintf}\\
190 \helpref{PrintfV}{wxstringprintfv}\\
191 \helpref{operator \cinsert}{wxstringoperatorout}
192
193 \membersection{Memory management}\label{memoryinwxstring}
194
195 These are "advanced" functions and they will be needed quite rarely.
196 \helpref{Alloc}{wxstringalloc} and \helpref{Shrink}{wxstringshrink} are only
197 interesting for optimization purposes.
198 \helpref{GetWriteBuf}{wxstringgetwritebuf} may be very useful when working with
199 some external API which requires the caller to provide a writable buffer, but
200 extreme care should be taken when using it: before performing any other
201 operation on the string \helpref{UngetWriteBuf}{wxstringungetwritebuf} {\bf
202 must} be called!
203
204 \helpref{Alloc}{wxstringalloc}\\
205 \helpref{Shrink}{wxstringshrink}\\
206 \helpref{GetWriteBuf}{wxstringgetwritebuf}\\
207 \helpref{UngetWriteBuf}{wxstringungetwritebuf}
208
209 \membersection{Miscellaneous}\label{miscellaneousinwxstring}
210
211 Other string functions.
212
213 \helpref{Trim}{wxstringtrim}\\
214 \helpref{Pad}{wxstringpad}\\
215 \helpref{Truncate}{wxstringtruncate}
216
217 \membersection{wxWidgets 1.xx compatibility functions}\label{backwardcompatibilityinwxstring}
218
219 These functions are deprecated, please consider using new wxWidgets 2.0
220 functions instead of them (or, even better, std::string compatible variants).
221
222 \helpref{SubString}{wxstringsubstring}\\
223 \helpref{sprintf}{wxstringsprintf}\\
224 \helpref{CompareTo}{wxstringcompareto}\\
225 \helpref{Length}{wxstringlength}\\
226 \helpref{Freq}{wxstringfreq}\\
227 \helpref{LowerCase}{wxstringlowercase}\\
228 \helpref{UpperCase}{wxstringuppercase}\\
229 \helpref{Strip}{wxstringstrip}\\
230 \helpref{Index}{wxstringindex}\\
231 \helpref{Remove}{wxstringremove}\\
232 \helpref{First}{wxstringfirst}\\
233 \helpref{Last}{wxstringlast}\\
234 \helpref{Contains}{wxstringcontains}\\
235 \helpref{IsNull}{wxstringisnull}\\
236 \helpref{IsAscii}{wxstringisascii}\\
237 \helpref{IsNumber}{wxstringisnumber}\\
238 \helpref{IsWord}{wxstringisword}
239
240 \membersection{std::string compatibility functions}\label{wxstringat}
241
242 The supported functions are only listed here, please see any STL reference for
243 their documentation.
244
245 \begin{verbatim}
246 // take nLen chars starting at nPos
247 wxString(const wxString& str, size_t nPos, size_t nLen);
248 // take all characters from pStart to pEnd (poor man's iterators)
249 wxString(const void *pStart, const void *pEnd);
250
251 // lib.string.capacity
252 // return the length of the string
253 size_t size() const;
254 // return the length of the string
255 size_t length() const;
256 // return the maximum size of the string
257 size_t max_size() const;
258 // resize the string, filling the space with c if c != 0
259 void resize(size_t nSize, char ch = '\0');
260 // delete the contents of the string
261 void clear();
262 // returns true if the string is empty
263 bool empty() const;
264
265 // lib.string.access
266 // return the character at position n
267 char at(size_t n) const;
268 // returns the writable character at position n
269 char& at(size_t n);
270
271 // lib.string.modifiers
272 // append a string
273 wxString& append(const wxString& str);
274 // append elements str[pos], ..., str[pos+n]
275 wxString& append(const wxString& str, size_t pos, size_t n);
276 // append first n (or all if n == npos) characters of sz
277 wxString& append(const char *sz, size_t n = npos);
278
279 // append n copies of ch
280 wxString& append(size_t n, char ch);
281
282 // same as `this_string = str'
283 wxString& assign(const wxString& str);
284 // same as ` = str[pos..pos + n]
285 wxString& assign(const wxString& str, size_t pos, size_t n);
286 // same as `= first n (or all if n == npos) characters of sz'
287 wxString& assign(const char *sz, size_t n = npos);
288 // same as `= n copies of ch'
289 wxString& assign(size_t n, char ch);
290
291 // insert another string
292 wxString& insert(size_t nPos, const wxString& str);
293 // insert n chars of str starting at nStart (in str)
294 wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
295
296 // insert first n (or all if n == npos) characters of sz
297 wxString& insert(size_t nPos, const char *sz, size_t n = npos);
298 // insert n copies of ch
299 wxString& insert(size_t nPos, size_t n, char ch);
300
301 // delete characters from nStart to nStart + nLen
302 wxString& erase(size_t nStart = 0, size_t nLen = npos);
303
304 // replaces the substring of length nLen starting at nStart
305 wxString& replace(size_t nStart, size_t nLen, const char* sz);
306 // replaces the substring with nCount copies of ch
307 wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
308 // replaces a substring with another substring
309 wxString& replace(size_t nStart, size_t nLen,
310 const wxString& str, size_t nStart2, size_t nLen2);
311 // replaces the substring with first nCount chars of sz
312 wxString& replace(size_t nStart, size_t nLen,
313 const char* sz, size_t nCount);
314
315 // swap two strings
316 void swap(wxString& str);
317
318 // All find() functions take the nStart argument which specifies the
319 // position to start the search on, the default value is 0. All functions
320 // return npos if there were no match.
321
322 // find a substring
323 size_t find(const wxString& str, size_t nStart = 0) const;
324
325 // find first n characters of sz
326 size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
327
328 // find the first occurrence of character ch after nStart
329 size_t find(char ch, size_t nStart = 0) const;
330
331 // rfind() family is exactly like find() but works right to left
332
333 // as find, but from the end
334 size_t rfind(const wxString& str, size_t nStart = npos) const;
335
336 // as find, but from the end
337 size_t rfind(const char* sz, size_t nStart = npos,
338 size_t n = npos) const;
339 // as find, but from the end
340 size_t rfind(char ch, size_t nStart = npos) const;
341
342 // find first/last occurrence of any character in the set
343
344 //
345 size_t find_first_of(const wxString& str, size_t nStart = 0) const;
346 //
347 size_t find_first_of(const char* sz, size_t nStart = 0) const;
348 // same as find(char, size_t)
349 size_t find_first_of(char c, size_t nStart = 0) const;
350 //
351 size_t find_last_of (const wxString& str, size_t nStart = npos) const;
352 //
353 size_t find_last_of (const char* s, size_t nStart = npos) const;
354 // same as rfind(char, size_t)
355 size_t find_last_of (char c, size_t nStart = npos) const;
356
357 // find first/last occurrence of any character not in the set
358
359 //
360 size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
361 //
362 size_t find_first_not_of(const char* s, size_t nStart = 0) const;
363 //
364 size_t find_first_not_of(char ch, size_t nStart = 0) const;
365 //
366 size_t find_last_not_of(const wxString& str, size_t nStart=npos) const;
367 //
368 size_t find_last_not_of(const char* s, size_t nStart = npos) const;
369 //
370 size_t find_last_not_of(char ch, size_t nStart = npos) const;
371
372 // All compare functions return a negative, zero or positive value
373 // if the [sub]string is less, equal or greater than the compare() argument.
374
375 // just like strcmp()
376 int compare(const wxString& str) const;
377 // comparison with a substring
378 int compare(size_t nStart, size_t nLen, const wxString& str) const;
379 // comparison of 2 substrings
380 int compare(size_t nStart, size_t nLen,
381 const wxString& str, size_t nStart2, size_t nLen2) const;
382 // just like strcmp()
383 int compare(const char* sz) const;
384 // substring comparison with first nCount characters of sz
385 int compare(size_t nStart, size_t nLen,
386 const char* sz, size_t nCount = npos) const;
387
388 // substring extraction
389 wxString substr(size_t nStart = 0, size_t nLen = npos) const;
390 \end{verbatim}
391
392 %%%%% MEMBERS HERE %%%%%
393 \helponly{\insertatlevel{2}{
394
395 \wxheading{Members}
396
397 }}
398
399 \membersection{wxString::wxString}\label{wxstringconstruct}
400
401 \func{}{wxString}{\void}
402
403 Default constructor. Initializes the string to {\tt ""} (empty string).
404
405 \func{}{wxString}{\param{const wxString\&}{ x}}
406
407 Copy constructor.
408
409 \func{}{wxString}{\param{char}{ ch}, \param{size\_t}{ n = 1}}
410
411 Constructs a string of {\it n} copies of character {\it ch}.
412
413 \func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
414
415 Takes first {\it nLength} characters from the C string {\it psz}.
416 The default value of {\tt wxSTRING\_MAXLEN} means to take all the string.
417
418 Note that this constructor may be used even if {\it psz} points to a buffer
419 with binary data (i.e. containing {\tt NUL} characters) as long as you provide
420 the correct value for {\it nLength}. However, the default form of it works
421 only with strings without intermediate {\tt NUL}s because it uses
422 {\tt strlen()} to calculate the effective length and it would not give correct
423 results otherwise.
424
425 \func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
426
427 For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
428 The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
429
430 {\bf Note:} In Unicode build, all of the above constructors take
431 {\tt wchar\_t} arguments instead of {\tt char}.
432
433 \wxheading{Constructors with conversion}
434
435 The following constructors allow you to construct wxString from wide string
436 in ANSI build or from C string in Unicode build.
437
438 \func{}{wxString}{\param{const wchar\_t*}{ psz}, \param{wxMBConv\&}{ conv}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
439
440 Initializes the string from first \arg{nLength} characters of wide string.
441 The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
442 In ANSI build, \arg{conv}'s
443 \helpref{WC2MB}{wxmbconvwc2mb} method is called to
444 convert \arg{psz} to wide string. It is ignored in Unicode build.
445
446 \func{}{wxString}{\param{const char*}{ psz}, \param{wxMBConv\&}{ conv}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
447
448 Initializes the string from first \arg{nLength} characters of C string.
449 The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
450 In Unicode build, \arg{conv}'s
451 \helpref{MB2WC}{wxmbconvmb2wc} method is called to
452 convert \arg{psz} to wide string. It is ignored in ANSI build.
453
454 \wxheading{See also}
455
456 \helpref{wxMBConv classes}{mbconvclasses}, \helpref{mb\_str}{wxstringmbstr},
457 \helpref{wc\_str}{wxstringwcstr}
458
459 \membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
460
461 \func{}{\destruct{wxString}}{\void}
462
463 String destructor. Note that this is not virtual, so wxString must not be inherited from.
464
465 \membersection{wxString::Alloc}\label{wxstringalloc}
466
467 \func{void}{Alloc}{\param{size\_t}{ nLen}}
468
469 Preallocate enough space for wxString to store {\it nLen} characters. This function
470 may be used to increase speed when the string is constructed by repeated
471 concatenation as in
472
473 \begin{verbatim}
474
475 // delete all vowels from the string
476 wxString DeleteAllVowels(const wxString& original)
477 {
478 wxString result;
479
480 size_t len = original.length();
481
482 result.Alloc(len);
483
484 for ( size_t n = 0; n < len; n++ )
485 {
486 if ( strchr("aeuio", tolower(original[n])) == NULL )
487 result += original[n];
488 }
489
490 return result;
491 }
492
493 \end{verbatim}
494
495 because it will avoid the need to reallocate string memory many times (in case
496 of long strings). Note that it does not set the maximal length of a string - it
497 will still expand if more than {\it nLen} characters are stored in it. Also, it
498 does not truncate the existing string (use
499 \helpref{Truncate()}{wxstringtruncate} for this) even if its current length is
500 greater than {\it nLen}
501
502 \membersection{wxString::Append}\label{wxstringappend}
503
504 \func{wxString\&}{Append}{\param{const char*}{ psz}}
505
506 Concatenates {\it psz} to this string, returning a reference to it.
507
508 \func{wxString\&}{Append}{\param{char}{ ch}, \param{int}{ count = 1}}
509
510 Concatenates character {\it ch} to this string, {\it count} times, returning a reference
511 to it.
512
513 \membersection{wxString::AfterFirst}\label{wxstringafterfirst}
514
515 \constfunc{wxString}{AfterFirst}{\param{char}{ ch}}
516
517 Gets all the characters after the first occurrence of {\it ch}.
518 Returns the empty string if {\it ch} is not found.
519
520 \membersection{wxString::AfterLast}\label{wxstringafterlast}
521
522 \constfunc{wxString}{AfterLast}{\param{char}{ ch}}
523
524 Gets all the characters after the last occurrence of {\it ch}.
525 Returns the whole string if {\it ch} is not found.
526
527 \membersection{wxString::BeforeFirst}\label{wxstringbeforefirst}
528
529 \constfunc{wxString}{BeforeFirst}{\param{char}{ ch}}
530
531 Gets all characters before the first occurrence of {\it ch}.
532 Returns the whole string if {\it ch} is not found.
533
534 \membersection{wxString::BeforeLast}\label{wxstringbeforelast}
535
536 \constfunc{wxString}{BeforeLast}{\param{char}{ ch}}
537
538 Gets all characters before the last occurrence of {\it ch}.
539 Returns the empty string if {\it ch} is not found.
540
541 \membersection{wxString::c\_str}\label{wxstringcstr}
542
543 \constfunc{const char *}{c\_str}{\void}
544
545 Returns a pointer to the string data ({\tt const char*} in ANSI build,
546 {\tt const wchar\_t*} in Unicode build).
547
548 \wxheading{See also}
549
550 \helpref{mb\_str}{wxstringmbstr}, \helpref{wc\_str}{wxstringwcstr},
551 \helpref{fn\_str}{wxstringfnstr}
552
553 \membersection{wxString::Clear}\label{wxstringclear}
554
555 \func{void}{Clear}{\void}
556
557 Empties the string and frees memory occupied by it.
558
559 See also: \helpref{Empty}{wxstringempty}
560
561 \membersection{wxString::Cmp}\label{wxstringcmp}
562
563 \constfunc{int}{Cmp}{\param{const char*}{ psz}}
564
565 Case-sensitive comparison.
566
567 Returns a positive value if the string is greater than the argument, zero if
568 it is equal to it or a negative value if it is less than the argument (same semantics
569 as the standard {\it strcmp()} function).
570
571 See also \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}.
572
573 \membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
574
575 \constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
576
577 Case-insensitive comparison.
578
579 Returns a positive value if the string is greater than the argument, zero if
580 it is equal to it or a negative value if it is less than the argument (same semantics
581 as the standard {\it strcmp()} function).
582
583 See also \helpref{Cmp}{wxstringcmp}, \helpref{IsSameAs}{wxstringissameas}.
584
585 \membersection{wxString::CompareTo}\label{wxstringcompareto}
586
587 \begin{verbatim}
588 #define NO_POS ((int)(-1)) // undefined position
589 enum caseCompare {exact, ignoreCase};
590 \end{verbatim}
591
592 \constfunc{int}{CompareTo}{\param{const char*}{ psz}, \param{caseCompare}{ cmp = exact}}
593
594 Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
595
596 \membersection{wxString::Contains}\label{wxstringcontains}
597
598 \constfunc{bool}{Contains}{\param{const wxString\&}{ str}}
599
600 Returns 1 if target appears anywhere in wxString; else 0.
601
602 \membersection{wxString::Empty}\label{wxstringempty}
603
604 \func{void}{Empty}{\void}
605
606 Makes the string empty, but doesn't free memory occupied by the string.
607
608 See also: \helpref{Clear()}{wxstringclear}.
609
610 \membersection{wxString::Find}\label{wxstringfind}
611
612 \constfunc{int}{Find}{\param{char}{ ch}, \param{bool}{ fromEnd = false}}
613
614 Searches for the given character. Returns the starting index, or -1 if not found.
615
616 \constfunc{int}{Find}{\param{const char*}{ sz}}
617
618 Searches for the given string. Returns the starting index, or -1 if not found.
619
620 \membersection{wxString::First}\label{wxstringfirst}
621
622 \func{int}{First}{\param{char}{ c}}
623
624 \constfunc{int}{First}{\param{const char*}{ psz}}
625
626 \constfunc{int}{First}{\param{const wxString\&}{ str}}
627
628 Same as \helpref{Find}{wxstringfind}.
629
630 \membersection{wxString::fn\_str}\label{wxstringfnstr}
631
632 \constfunc{const wchar\_t*}{fn\_str}{\void}
633
634 \constfunc{const char*}{fn\_str}{\void}
635
636 \constfunc{const wxCharBuffer}{fn\_str}{\void}
637
638 Returns string representation suitable for passing to OS' functions for
639 file handling. In ANSI build, this is same as \helpref{c\_str}{wxstringcstr}.
640 In Unicode build, returned value can be either wide character string
641 or C string in charset matching the {\tt wxConvFile} object, depending on
642 the OS.
643
644 \wxheading{See also}
645
646 \helpref{wxMBConv}{wxmbconv},
647 \helpref{wc\_str}{wxstringwcstr}, \helpref{mb\_str}{wxstringwcstr}
648
649 \membersection{wxString::Format}\label{wxstringformat}
650
651 \func{static wxString}{Format}{\param{const wxChar }{*format}, \param{}{...}}
652
653 This static function returns the string containing the result of calling
654 \helpref{Printf}{wxstringprintf} with the passed parameters on it.
655
656 \wxheading{See also}
657
658 \helpref{FormatV}{wxstringformatv}, \helpref{Printf}{wxstringprintf}
659
660 \membersection{wxString::FormatV}\label{wxstringformatv}
661
662 \func{static wxString}{Format}{\param{const wxChar }{*format}, \param{va\_list }{argptr}}
663
664 This static function returns the string containing the result of calling
665 \helpref{PrintfV}{wxstringprintfv} with the passed parameters on it.
666
667 \wxheading{See also}
668
669 \helpref{Format}{wxstringformat}, \helpref{PrintfV}{wxstringprintfv}
670
671 \membersection{wxString::Freq}\label{wxstringfreq}
672
673 \constfunc{int}{Freq}{\param{char }{ch}}
674
675 Returns the number of occurrences of {\it ch} in the string.
676
677 \membersection{wxString::FromAscii}\label{wxstringfromascii}
678
679 \func{static wxString }{FromAscii}{\param{const char*}{ s}}
680
681 \func{static wxString }{FromAscii}{\param{const char}{ c}}
682
683 Converts the string or character from an ASCII, 7-bit form
684 to the native wxString representation. Most useful when using
685 a Unicode build of wxWidgets.
686 Use \helpref{wxString constructors}{wxstringconstruct} if you
687 need to convert from another charset.
688
689 \membersection{wxString::GetChar}\label{wxstringgetchar}
690
691 \constfunc{char}{GetChar}{\param{size\_t}{ n}}
692
693 Returns the character at position {\it n} (read-only).
694
695 \membersection{wxString::GetData}\label{wxstringgetdata}
696
697 \constfunc{const char*}{GetData}{\void}
698
699 wxWidgets compatibility conversion. Returns a constant pointer to the data in the string.
700
701 \membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
702
703 \func{char\&}{GetWritableChar}{\param{size\_t}{ n}}
704
705 Returns a reference to the character at position {\it n}.
706
707 \membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
708
709 \func{wxChar*}{GetWriteBuf}{\param{size\_t}{ len}}
710
711 Returns a writable buffer of at least {\it len} bytes.
712 It returns a pointer to a new memory block, and the
713 existing data will not be copied.
714
715 Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
716 to put the string back into a reasonable state.
717
718 \membersection{wxString::Index}\label{wxstringindex}
719
720 \constfunc{size\_t}{Index}{\param{char}{ ch}}
721
722 \constfunc{size\_t}{Index}{\param{const char*}{ sz}}
723
724 Same as \helpref{wxString::Find}{wxstringfind}.
725
726 % TODO
727 %\membersection{wxString::insert}\label{wxstringinsert}
728 % Wrong!
729 %\func{void}{insert}{\param{const wxString\&}{ str}, \param{size\_t}{ index}}
730 %
731 %Add new element at the given position.
732 %
733 \membersection{wxString::IsAscii}\label{wxstringisascii}
734
735 \constfunc{bool}{IsAscii}{\void}
736
737 Returns true if the string contains only ASCII characters.
738
739 \membersection{wxString::IsEmpty}\label{wxstringisempty}
740
741 \constfunc{bool}{IsEmpty}{\void}
742
743 Returns true if the string is empty.
744
745 \membersection{wxString::IsNull}\label{wxstringisnull}
746
747 \constfunc{bool}{IsNull}{\void}
748
749 Returns true if the string is empty (same as \helpref{IsEmpty}{wxstringisempty}).
750
751 \membersection{wxString::IsNumber}\label{wxstringisnumber}
752
753 \constfunc{bool}{IsNumber}{\void}
754
755 Returns true if the string is an integer (with possible sign).
756
757 \membersection{wxString::IsSameAs}\label{wxstringissameas}
758
759 \constfunc{bool}{IsSameAs}{\param{const char*}{ psz}, \param{bool}{ caseSensitive = true}}
760
761 Test for string equality, case-sensitive (default) or not.
762
763 caseSensitive is true by default (case matters).
764
765 Returns true if strings are equal, false otherwise.
766
767 See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}
768
769 \constfunc{bool}{IsSameAs}{\param{char}{ c}, \param{bool}{ caseSensitive = true}}
770
771 Test whether the string is equal to the single character {\it c}. The test is
772 case-sensitive if {\it caseSensitive} is true (default) or not if it is false.
773
774 Returns true if the string is equal to the character, false otherwise.
775
776 See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}
777
778 \membersection{wxString::IsWord}\label{wxstringisword}
779
780 \constfunc{bool}{IsWord}{\void}
781
782 Returns true if the string is a word. TODO: what's the definition of a word?
783
784 \membersection{wxString::Last}\label{wxstringlast}
785
786 \constfunc{char}{Last}{\void}
787
788 Returns the last character.
789
790 \func{char\&}{Last}{\void}
791
792 Returns a reference to the last character (writable).
793
794 \membersection{wxString::Left}\label{wxstringleft}
795
796 \constfunc{wxString}{Left}{\param{size\_t}{ count}}
797
798 Returns the first {\it count} characters of the string.
799
800 \membersection{wxString::Len}\label{wxstringlen}
801
802 \constfunc{size\_t}{Len}{\void}
803
804 Returns the length of the string.
805
806 \membersection{wxString::Length}\label{wxstringlength}
807
808 \constfunc{size\_t}{Length}{\void}
809
810 Returns the length of the string (same as Len).
811
812 \membersection{wxString::Lower}\label{wxstringlower}
813
814 \constfunc{wxString}{Lower}{\void}
815
816 Returns this string converted to the lower case.
817
818 \membersection{wxString::LowerCase}\label{wxstringlowercase}
819
820 \func{void}{LowerCase}{\void}
821
822 Same as MakeLower.
823
824 \membersection{wxString::MakeLower}\label{wxstringmakelower}
825
826 \func{wxString\&}{MakeLower}{\void}
827
828 Converts all characters to lower case and returns the result.
829
830 \membersection{wxString::MakeUpper}\label{wxstringmakeupper}
831
832 \func{wxString\&}{MakeUpper}{\void}
833
834 Converts all characters to upper case and returns the result.
835
836 \membersection{wxString::Matches}\label{wxstringmatches}
837
838 \constfunc{bool}{Matches}{\param{const char*}{ szMask}}
839
840 Returns true if the string contents matches a mask containing '*' and '?'.
841
842 \membersection{wxString::mb\_str}\label{wxstringmbstr}
843
844 \constfunc{const char*}{mb\_str}{\param{wxMBConv\&}{ conv}}
845
846 \constfunc{const wxCharBuffer}{mb\_str}{\param{wxMBConv\&}{ conv}}
847
848 Returns multibyte (C string) representation of the string.
849 In Unicode build, converts using \arg{conv}'s \helpref{cWC2MB}{wxmbconvcwc2mb}
850 method and returns wxCharBuffer. In ANSI build, this function is same
851 as \helpref{c\_str}{wxstringcstr}.
852 The macro wxWX2MBbuf is defined as the correct return type (without const).
853
854 \wxheading{See also}
855
856 \helpref{wxMBConv}{wxmbconv},
857 \helpref{c\_str}{wxstringcstr}, \helpref{wc\_str}{wxstringwcstr},
858 \helpref{fn\_str}{wxstringfnstr}
859
860 \membersection{wxString::Mid}\label{wxstringmid}
861
862 \constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}}
863
864 Returns a substring starting at {\it first}, with length {\it count}, or the rest of
865 the string if {\it count} is the default value.
866
867 \membersection{wxString::Pad}\label{wxstringpad}
868
869 \func{wxString\&}{Pad}{\param{size\_t}{ count}, \param{char}{ pad = ' '}, \param{bool}{ fromRight = true}}
870
871 Adds {\it count} copies of {\it pad} to the beginning, or to the end of the string (the default).
872
873 Removes spaces from the left or from the right (default).
874
875 \membersection{wxString::Prepend}\label{wxstringprepend}
876
877 \func{wxString\&}{Prepend}{\param{const wxString\&}{ str}}
878
879 Prepends {\it str} to this string, returning a reference to this string.
880
881 \membersection{wxString::Printf}\label{wxstringprintf}
882
883 \func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}}
884
885 Similar to the standard function {\it sprintf()}. Returns the number of
886 characters written, or an integer less than zero on error.
887
888 {\bf NB:} This function will use a safe version of {\it vsprintf()} (usually called
889 {\it vsnprintf()}) whenever available to always allocate the buffer of correct
890 size. Unfortunately, this function is not available on all platforms and the
891 dangerous {\it vsprintf()} will be used then which may lead to buffer overflows.
892
893 \membersection{wxString::PrintfV}\label{wxstringprintfv}
894
895 \func{int}{PrintfV}{\param{const char* }{pszFormat}, \param{va\_list}{ argPtr}}
896
897 Similar to vprintf. Returns the number of characters written, or an integer less than zero
898 on error.
899
900 \membersection{wxString::Remove}\label{wxstringremove}
901
902 \func{wxString\&}{Remove}{\param{size\_t}{ pos}}
903
904 Same as Truncate. Removes the portion from {\it pos} to the end of the string.
905
906 \func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
907
908 Removes the {\it len} characters from the string, starting at {\it pos}.
909
910 \membersection{wxString::RemoveLast}\label{wxstringremovelast}
911
912 \func{wxString\&}{RemoveLast}{\void}
913
914 Removes the last character.
915
916 \membersection{wxString::Replace}\label{wxstringreplace}
917
918 \func{size\_t}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll = true}}
919
920 Replace first (or all) occurrences of substring with another one.
921
922 {\it replaceAll}: global replace (default), or only the first occurrence.
923
924 Returns the number of replacements made.
925
926 \membersection{wxString::Right}\label{wxstringright}
927
928 \constfunc{wxString}{Right}{\param{size\_t}{ count}}
929
930 Returns the last {\it count} characters.
931
932 \membersection{wxString::SetChar}\label{wxstringsetchar}
933
934 \func{void}{SetChar}{\param{size\_t}{ n}, \param{char}{ch}}
935
936 Sets the character at position {\it n}.
937
938 \membersection{wxString::Shrink}\label{wxstringshrink}
939
940 \func{void}{Shrink}{\void}
941
942 Minimizes the string's memory. This can be useful after a call to
943 \helpref{Alloc()}{wxstringalloc} if too much memory were preallocated.
944
945 \membersection{wxString::sprintf}\label{wxstringsprintf}
946
947 \func{void}{sprintf}{\param{const char* }{ fmt}}
948
949 The same as Printf.
950
951 \membersection{wxString::StartsWith}\label{wxstringstartswith}
952
953 \constfunc{bool}{StartsWith}{\param{const wxChar }{*prefix}, \param{wxString }{*rest = NULL}}
954
955 This function can be used to test if the string starts with the specified
956 {\it prefix}. If it does, the function will return {\tt true} and put the rest
957 of the string (i.e. after the prefix) into {\it rest} string if it is not
958 {\tt NULL}. Otherwise, the function returns {\tt false} and doesn't modify the
959 {\it rest}.
960
961 \membersection{wxString::Strip}\label{wxstringstrip}
962
963 \begin{verbatim}
964 enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
965 \end{verbatim}
966
967 \constfunc{wxString}{Strip}{\param{stripType}{ s = trailing}}
968
969 Strip characters at the front and/or end. The same as Trim except that it
970 doesn't change this string.
971
972 \membersection{wxString::SubString}\label{wxstringsubstring}
973
974 \constfunc{wxString}{SubString}{\param{size\_t}{ from}, \param{size\_t}{ to}}
975
976 Deprecated, use \helpref{Mid}{wxstringmid} instead (but note that parameters
977 have different meaning).
978
979 Returns the part of the string between the indices {\it from} and {\it to}
980 inclusive.
981
982 \membersection{wxString::ToAscii}\label{wxstringtoascii}
983
984 \constfunc{const char*}{ToAscii}{\void}
985
986 Converts the string to an ASCII, 7-bit string (ANSI builds only).
987
988 \constfunc{const wxCharBuffer}{ToAscii}{\void}
989
990 Converts the string to an ASCII, 7-bit string in the form of
991 a wxCharBuffer (Unicode builds only).
992
993 Note that this conversion only works if the string contains only ASCII
994 characters. The \helpref{mb\_str}{wxstringmbstr} method provides more
995 powerful means of converting wxString to C string.
996
997 \membersection{wxString::ToDouble}\label{wxstringtodouble}
998
999 \constfunc{bool}{ToDouble}{\param{double}{ *val}}
1000
1001 Attempts to convert the string to a floating point number. Returns true on
1002 success (the number is stored in the location pointed to by {\it val}) or false
1003 if the string does not represent such number.
1004
1005 \wxheading{See also}
1006
1007 \helpref{wxString::ToLong}{wxstringtolong},\\
1008 \helpref{wxString::ToULong}{wxstringtoulong}
1009
1010 \membersection{wxString::ToLong}\label{wxstringtolong}
1011
1012 \constfunc{bool}{ToLong}{\param{long}{ *val}, \param{int }{base = $10$}}
1013
1014 Attempts to convert the string to a signed integer in base {\it base}. Returns
1015 {\tt true} on success in which case the number is stored in the location
1016 pointed to by {\it val} or {\tt false} if the string does not represent a
1017 valid number in the given base.
1018
1019 The value of {\it base} must be comprised between $2$ and $36$, inclusive, or
1020 be a special value $0$ which means that the usual rules of {\tt C} numbers are
1021 applied: if the number starts with {\tt 0x} it is considered to be in base
1022 $16$, if it starts with {\tt 0} - in base $8$ and in base $10$ otherwise. Note
1023 that you may not want to specify the base $0$ if you are parsing the numbers
1024 which may have leading zeroes as they can yield unexpected (to the user not
1025 familiar with C) results.
1026
1027 \wxheading{See also}
1028
1029 \helpref{wxString::ToDouble}{wxstringtodouble},\\
1030 \helpref{wxString::ToULong}{wxstringtoulong}
1031
1032 \membersection{wxString::ToULong}\label{wxstringtoulong}
1033
1034 \constfunc{bool}{ToULong}{\param{unsigned long}{ *val}, \param{int }{base = $10$}}
1035
1036 Attempts to convert the string to a unsigned integer in base {\it base}.
1037 Returns {\tt true} on success in which case the number is stored in the
1038 location pointed to by {\it val} or {\tt false} if the string does not
1039 represent a valid number in the given base.
1040
1041 See \helpref{wxString::ToLong}{wxstringtolong} for the more detailed
1042 description of the {\it base} parameter.
1043
1044 \wxheading{See also}
1045
1046 \helpref{wxString::ToDouble}{wxstringtodouble},\\
1047 \helpref{wxString::ToLong}{wxstringtolong}
1048
1049 \membersection{wxString::Trim}\label{wxstringtrim}
1050
1051 \func{wxString\&}{Trim}{\param{bool}{ fromRight = true}}
1052
1053 Removes spaces from the left or from the right (default).
1054
1055 \membersection{wxString::Truncate}\label{wxstringtruncate}
1056
1057 \func{wxString\&}{Truncate}{\param{size\_t}{ len}}
1058
1059 Truncate the string to the given length.
1060
1061 \membersection{wxString::UngetWriteBuf}\label{wxstringungetwritebuf}
1062
1063 \func{void}{UngetWriteBuf}{\void}
1064
1065 \func{void}{UngetWriteBuf}{\param{size\_t }{len}}
1066
1067 Puts the string back into a reasonable state (in which it can be used
1068 normally), after
1069 \rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called.
1070
1071 The version of the function without the {\it len} parameter will calculate the
1072 new string length itself assuming that the string is terminated by the first
1073 {\tt NUL} character in it while the second one will use the specified length
1074 and thus is the only version which should be used with the strings with
1075 embedded {\tt NUL}s (it is also slightly more efficient as {\tt strlen()}
1076 doesn't have to be called).
1077
1078 \membersection{wxString::Upper}\label{wxstringupper}
1079
1080 \constfunc{wxString}{Upper}{\void}
1081
1082 Returns this string converted to upper case.
1083
1084 \membersection{wxString::UpperCase}\label{wxstringuppercase}
1085
1086 \func{void}{UpperCase}{\void}
1087
1088 The same as MakeUpper.
1089
1090 \membersection{wxString::wc\_str}\label{wxstringwcstr}
1091
1092 \constfunc{const wchar\_t*}{wc\_str}{\param{wxMBConv\&}{ conv}}
1093
1094 \constfunc{const wxWCharBuffer}{wc\_str}{\param{wxMBConv\&}{ conv}}
1095
1096 Returns wide character representation of the string.
1097 In ANSI build, converts using \arg{conv}'s \helpref{cMB2WC}{wxmbconvcmb2wc}
1098 method and returns wxWCharBuffer. In Unicode build, this function is same
1099 as \helpref{c\_str}{wxstringcstr}.
1100 The macro wxWX2WCbuf is defined as the correct return type (without const).
1101
1102 \wxheading{See also}
1103
1104 \helpref{wxMBConv}{wxmbconv},
1105 \helpref{c\_str}{wxstringcstr}, \helpref{mb\_str}{wxstringwcstr},
1106 \helpref{fn\_str}{wxstringfnstr}
1107
1108 \membersection{wxString::operator!}\label{wxstringoperatornot}
1109
1110 \constfunc{bool}{operator!}{\void}
1111
1112 Empty string is false, so !string will only return true if the string is empty.
1113 This allows the tests for NULLness of a {\it const char *} pointer and emptiness
1114 of the string to look the same in the code and makes it easier to port old code
1115 to wxString.
1116
1117 See also \helpref{IsEmpty()}{wxstringisempty}.
1118
1119 \membersection{wxString::operator $=$}\label{wxstringoperatorassign}
1120
1121 \func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}}
1122
1123 \func{wxString\&}{operator $=$}{\param{const char*}{ psz}}
1124
1125 \func{wxString\&}{operator $=$}{\param{char}{ c}}
1126
1127 \func{wxString\&}{operator $=$}{\param{const unsigned char*}{ psz}}
1128
1129 \func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}}
1130
1131 Assignment: the effect of each operation is the same as for the corresponding
1132 constructor (see \helpref{wxString constructors}{wxstringconstruct}).
1133
1134 \membersection{wxString::operator $+$}\label{wxstringoperatorplus}
1135
1136 Concatenation: all these operators return a new string equal to the
1137 concatenation of the operands.
1138
1139 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1140
1141 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const char*}{ y}}
1142
1143 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{char}{ y}}
1144
1145 \func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}}
1146
1147 \membersection{wxString::operator $+=$}\label{wxstringplusequal}
1148
1149 \func{void}{operator $+=$}{\param{const wxString\&}{ str}}
1150
1151 \func{void}{operator $+=$}{\param{const char*}{ psz}}
1152
1153 \func{void}{operator $+=$}{\param{char}{ c}}
1154
1155 Concatenation in place: the argument is appended to the string.
1156
1157 \membersection{wxString::operator []}\label{wxstringoperatorbracket}
1158
1159 \func{char\&}{operator []}{\param{size\_t}{ i}}
1160
1161 \func{char}{operator []}{\param{size\_t}{ i}}
1162
1163 \func{char}{operator []}{\param{int}{ i}}
1164
1165 Element extraction.
1166
1167 \membersection{wxString::operator ()}\label{wxstringoperatorparenth}
1168
1169 \func{wxString}{operator ()}{\param{size\_t}{ start}, \param{size\_t}{ len}}
1170
1171 Same as Mid (substring extraction).
1172
1173 \membersection{wxString::operator \cinsert}\label{wxstringoperatorout}
1174
1175 \func{wxString\&}{operator \cinsert}{\param{const wxString\&}{ str}}
1176
1177 \func{wxString\&}{operator \cinsert}{\param{const char*}{ psz}}
1178
1179 \func{wxString\&}{operator \cinsert}{\param{char }{ch}}
1180
1181 Same as $+=$.
1182
1183 \func{wxString\&}{operator \cinsert}{\param{int}{ i}}
1184
1185 \func{wxString\&}{operator \cinsert}{\param{float}{ f}}
1186
1187 \func{wxString\&}{operator \cinsert}{\param{double}{ d}}
1188
1189 These functions work as C++ stream insertion operators: they insert the given
1190 value into the string. Precision or format cannot be set using them, you can use
1191 \helpref{Printf}{wxstringprintf} for this.
1192
1193 \membersection{wxString::operator \cextract}\label{wxstringoperatorin}
1194
1195 \func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}}
1196
1197 Extraction from a stream.
1198
1199 \membersection{wxString::operator const char*}\label{wxstringoperatorconstcharpt}
1200
1201 \constfunc{}{operator const char*}{\void}
1202
1203 Implicit conversion to a C string.
1204
1205 \membersection{Comparison operators}\label{wxstringcomparison}
1206
1207 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1208
1209 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1210
1211 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1212
1213 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1214
1215 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1216
1217 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1218
1219 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1220
1221 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1222
1223 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1224
1225 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1226
1227 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1228
1229 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
1230
1231 \wxheading{Remarks}
1232
1233 These comparisons are case-sensitive.
1234
1235
1236 \section{\class{wxStringBuffer}}\label{wxstringbuffer}
1237
1238 This tiny class allows to conveniently access the \helpref{wxString}{wxstring}
1239 internal buffer as a writable pointer without any risk of forgetting to restore
1240 the string to the usable state later.
1241
1242 For example, assuming you have a low-level OS function called
1243 {\tt GetMeaningOfLifeAsString(char *)} returning the value in the provided
1244 buffer (which must be writable, of course) you might call it like this:
1245
1246 \begin{verbatim}
1247 wxString theAnswer;
1248 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
1249 if ( theAnswer != "42" )
1250 {
1251 wxLogError("Something is very wrong!");
1252 }
1253 \end{verbatim}
1254
1255 Note that the exact usage of this depends on whether on not wxUSE\_STL is enabled. If
1256 wxUSE\_STL is enabled, wxStringBuffer creates a seperate empty character buffer, and
1257 if wxUSE\_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same buffer
1258 wxString uses intact. In other words, relying on wxStringBuffer containing the old
1259 wxString data is probably not a good idea if you want to build your program in both
1260 with and without wxUSE\_STL.
1261
1262 \wxheading{Derived from}
1263
1264 None
1265
1266 \wxheading{Include files}
1267
1268 <wx/string.h>
1269
1270 \latexignore{\rtfignore{\wxheading{Members}}}
1271
1272 \membersection{wxStringBuffer::wxStringBuffer}\label{wxstringbufferctor}
1273
1274 \func{}{wxStringBuffer}{\param{const wxString\& }{str}, \param{size\_t }{len}}
1275
1276 Constructs a writable string buffer object associated with the given string
1277 and containing enough space for at least {\it len} characters. Basically, this
1278 is equivalent to calling \helpref{GetWriteBuf}{wxstringgetwritebuf} and
1279 saving the result.
1280
1281 \membersection{wxStringBuffer::\destruct{wxStringBuffer}}\label{wxstringbufferdtor}
1282
1283 \func{}{\destruct{wxStringBuffer}}{\void}
1284
1285 Restores the string passed to the constructor to the usable state by calling
1286 \helpref{UngetWriteBuf}{wxstringungetwritebuf} on it.
1287
1288 \membersection{wxStringBuffer::operator wxChar *}\label{wxstringbufferwxchar}
1289
1290 \func{wxChar *}{operator wxChar *}{\void}
1291
1292 Returns the writable pointer to a buffer of the size at least equal to the
1293 length specified in the constructor.
1294
1295
1296
1297 \section{\class{wxStringBufferLength}}\label{wxstringbufferlength}
1298
1299 This tiny class allows to conveniently access the \helpref{wxString}{wxstring}
1300 internal buffer as a writable pointer without any risk of forgetting to restore
1301 the string to the usable state later, and allows the user to set the internal
1302 length of the string.
1303
1304 For example, assuming you have a low-level OS function called
1305 {\tt int GetMeaningOfLifeAsString(char *)} copying the value in the provided
1306 buffer (which must be writable, of course), and returning the actual length
1307 of the string, you might call it like this:
1308
1309 \begin{verbatim}
1310 wxString theAnswer;
1311 wxStringBuffer theAnswerBuffer(theAnswer, 1024);
1312 int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
1313 theAnswerBuffer.SetLength(nLength);
1314 if ( theAnswer != "42" )
1315 {
1316 wxLogError("Something is very wrong!");
1317 }
1318 \end{verbatim}
1319
1320 Note that the exact usage of this depends on whether on not wxUSE\_STL is enabled. If
1321 wxUSE\_STL is enabled, wxStringBuffer creates a seperate empty character buffer, and
1322 if wxUSE\_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same buffer
1323 wxString uses intact. In other words, relying on wxStringBuffer containing the old
1324 wxString data is probably not a good idea if you want to build your program in both
1325 with and without wxUSE\_STL.
1326
1327 Note that SetLength {\tt must} be called before wxStringBufferLength destructs.
1328
1329 \wxheading{Derived from}
1330
1331 None
1332
1333 \wxheading{Include files}
1334
1335 <wx/string.h>
1336
1337 \latexignore{\rtfignore{\wxheading{Members}}}
1338
1339 \membersection{wxStringBufferLength::wxStringBufferLength}\label{wxstringbufferlengthctor}
1340
1341 \func{}{wxStringBuffer}{\param{const wxString\& }{str}, \param{size\_t }{len}}
1342
1343 Constructs a writable string buffer object associated with the given string
1344 and containing enough space for at least {\it len} characters. Basically, this
1345 is equivalent to calling \helpref{GetWriteBuf}{wxstringgetwritebuf} and
1346 saving the result.
1347
1348 \membersection{wxStringBufferLength::\destruct{wxStringBufferLength}}\label{wxstringbufferlengthdtor}
1349
1350 \func{}{\destruct{wxStringBufferLength}}{\void}
1351
1352 Restores the string passed to the constructor to the usable state by calling
1353 \helpref{UngetWriteBuf}{wxstringungetwritebuf} on it.
1354
1355 \membersection{wxStringBufferLength::SetLength}\label{wxstringbufferlengthsetlength}
1356
1357 \func{void}{SetLength}{\param{size\_t }{nLength}}
1358
1359 Sets the internal length of the string referred to by wxStringBufferLength to
1360 {\it nLength} characters.
1361
1362 Must be called before wxStringBufferLength destructs.
1363
1364 \membersection{wxStringBufferLength::operator wxChar *}\label{wxstringbufferlengthwxchar}
1365
1366 \func{wxChar *}{operator wxChar *}{\void}
1367
1368 Returns the writable pointer to a buffer of the size at least equal to the
1369 length specified in the constructor.
1370
1371