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