]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/wxstring.tex
Fixed wxTextCtrl::SetMaxLength for rich edit controls
[wxWidgets.git] / docs / latex / wx / wxstring.tex
CommitLineData
a660d684
KB
1\section{\class{wxString}}\label{wxstring}
2
40b480c3
JS
3wxString is a class representing a character string. Please see the
4\helpref{wxString overview}{wxstringoverview} for more information about it. As explained
5there, wxString implements about 90\% of methods of the std::string class (iterators
6are not supported, nor all methods which use them).
7These standard functions are not documented in this manual so please see the STL documentation.
99f09bc1 8The behaviour of all these functions is identical to the behaviour described
e2101186 9there (except that wxString is sensitive to null character).
99f09bc1 10
0aa35d19
VZ
11You may notice that wxString sometimes has many functions which do the same
12thing like, for example, \helpref{Length()}{wxstringlength},
13\helpref{Len()}{wxstringlen} and {\tt length()} which all return the string
14length. In all cases of such duplication the {\tt std::string}-compatible
15method ({\tt length()} in this case, always the lowercase version) should be
fc2171bd 16used as it will ensure smoother transition to {\tt std::string} when wxWidgets
0aa35d19
VZ
17starts using it instead of wxString.
18
b3324be2
JS
19\wxheading{Derived from}
20
21None
a660d684 22
954b8ae6
JS
23\wxheading{Include files}
24
25<wx/string.h>
26
20e85460
JS
27\wxheading{Predefined objects}
28
29Objects:
30
31{\bf wxEmptyString}
32
b3324be2
JS
33\wxheading{See also}
34
35\overview{Overview}{wxstringoverview}
a660d684 36
99f09bc1
VZ
37\latexignore{\rtfignore{\wxheading{Function groups}}}
38
39\membersection{Constructors and assignment operators}
40
2edb0bde 41A string may be constructed either from a C string, (some number of copies of)
99f09bc1
VZ
42a single character or a wide (UNICODE) string. For all constructors (except the
43default which creates an empty string) there is also a corresponding assignment
44operator.
45
46\helpref{wxString}{wxstringconstruct}\\
47\helpref{operator $=$}{wxstringoperatorassign}\\
48\helpref{\destruct{wxString}}{wxstringdestruct}
49
50\membersection{String length}
51
52These functions return the string length and check whether the string is empty
53or 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}
62
63Many functions in this section take a character index in the string. As with C
64strings and/or arrays, the indices start from $0$, so the first character of a
65string is string[$0$]. Attempt to access a character beyond the end of the
2edb0bde 66string (which may be even $0$ if the string is empty) will provoke an assert
99f09bc1
VZ
67failure in \helpref{debug build}{debuggingoverview}, but no checks are done in
68release builds.
69
70This section also contains both implicit and explicit conversions to C style
71strings. Although implicit conversion is quite convenient, it is advised to use
72explicit \helpref{c\_str()}{wxstringcstr} method for the sake of clarity. Also
fd34e3a5 73see \helpref{overview}{wxstringadvices} for the cases where it is necessary to
99f09bc1
VZ
74use 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}\\
bd8465ff
VS
82\helpref{mb\_str}{wxstringmbstr}\\
83\helpref{wc\_str}{wxstringwcstr}\\
84\helpref{fn\_str}{wxstringfnstr}\\
99f09bc1
VZ
85\helpref{operator const char*}{wxstringoperatorconstcharpt}
86
87\membersection{Concatenation}
88
89Anything may be concatenated (appended to) with a string. However, you can't
90append something to a C string (including literal constants), so to do this it
91should 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}
100
101The default comparison function \helpref{Cmp}{wxstringcmp} is case-sensitive and
102so is the default version of \helpref{IsSameAs}{wxstringissameas}. For case
103insensitive comparisons you should use \helpref{CmpNoCase}{wxstringcmpnocase} or
104give a second parameter to IsSameAs. This last function is may be more
105convenient if only equality of the strings matters because it returns a boolean
cc81d32f 106true value if the strings are the same and not 0 (which is usually false in C)
f6bcfd97 107as {\tt Cmp()} does.
99f09bc1
VZ
108
109\helpref{Matches}{wxstringmatches} is a poor man's regular expression matcher:
110it only understands '*' and '?' metacharacters in the sense of DOS command line
111interpreter.
112
f6bcfd97
BP
113\helpref{StartsWith}{wxstringstartswith} is helpful when parsing a line of
114text which should start with some predefined prefix and is more efficient than
2edb0bde 115doing direct string comparison as you would also have to precalculate the
f6bcfd97
BP
116length of the prefix then.
117
99f09bc1
VZ
118\helpref{Cmp}{wxstringcmp}\\
119\helpref{CmpNoCase}{wxstringcmpnocase}\\
120\helpref{IsSameAs}{wxstringissameas}\\
f6bcfd97
BP
121\helpref{Matches}{wxstringmatches}\\
122\helpref{StartsWith}{wxstringstartswith}
99f09bc1
VZ
123
124\membersection{Substring extraction}
125
126These functions allow to extract substring from this string. All of them don't
127modify the original string and return a new string containing the extracted
128substring.
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}\\
f6bcfd97
BP
137\helpref{AfterLast}{wxstringafterlast}\\
138\helpref{StartsWith}{wxstringstartswith}
99f09bc1
VZ
139
140\membersection{Case conversion}
141
142The MakeXXX() variants modify the string in place, while the other functions
2edb0bde 143return a new string which contains the original text converted to the upper or
99f09bc1
VZ
144lower 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}
152
40b480c3 153These functions replace the standard {\it strchr()} and {\it strstr()}
99f09bc1
VZ
154functions.
155
156\helpref{Find}{wxstringfind}\\
157\helpref{Replace}{wxstringreplace}
158
cd0b1709
VZ
159\membersection{Conversion to numbers}
160
161The string provides functions for conversion to signed and unsigned integer and
162floating point numbers. All three functions take a pointer to the variable to
cc81d32f 163put the numeric value in and return true if the {\bf entire} string could be
cd0b1709
VZ
164converted to a number.
165
166\helpref{ToLong}{wxstringtolong}\\
167\helpref{ToULong}{wxstringtoulong}\\
168\helpref{ToDouble}{wxstringtodouble}
169
99f09bc1
VZ
170\membersection{Writing values into the string}
171
172Both formatted versions (\helpref{Printf}{wxstringprintf}) and stream-like
341e7d28
VZ
173insertion operators exist (for basic types only). Additionally, the
174\helpref{Format}{wxstringformat} function allows to use simply append
175formatted value to a string:
99f09bc1 176
341e7d28
VZ
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}\\
99f09bc1
VZ
189\helpref{Printf}{wxstringprintf}\\
190\helpref{PrintfV}{wxstringprintfv}\\
40b480c3 191\helpref{operator \cinsert}{wxstringoperatorout}
99f09bc1
VZ
192
193\membersection{Memory management}
194
2edb0bde 195These are "advanced" functions and they will be needed quite rarely.
99f09bc1
VZ
196\helpref{Alloc}{wxstringalloc} and \helpref{Shrink}{wxstringshrink} are only
197interesting for optimization purposes.
198\helpref{GetWriteBuf}{wxstringgetwritebuf} may be very useful when working with
199some external API which requires the caller to provide a writable buffer, but
200extreme care should be taken when using it: before performing any other
201operation on the string \helpref{UngetWriteBuf}{wxstringungetwritebuf} {\bf
202must} be called!
203
204\helpref{Alloc}{wxstringalloc}\\
205\helpref{Shrink}{wxstringshrink}\\
206\helpref{GetWriteBuf}{wxstringgetwritebuf}\\
207\helpref{UngetWriteBuf}{wxstringungetwritebuf}
208
209\membersection{Miscellaneous}
210
211Other string functions.
212
213\helpref{Trim}{wxstringtrim}\\
214\helpref{Pad}{wxstringpad}\\
215\helpref{Truncate}{wxstringtruncate}
216
fc2171bd 217\membersection{wxWidgets 1.xx compatibility functions}
99f09bc1 218
fc2171bd 219These functions are deprecated, please consider using new wxWidgets 2.0
99f09bc1
VZ
220functions 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
ed93168b 240\membersection{std::string compatibility functions}\label{wxstringat}
99f09bc1
VZ
241
242The supported functions are only listed here, please see any STL reference for
243their 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
7335902d 328 // find the first occurrence of character ch after nStart
99f09bc1
VZ
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
7335902d 342 // find first/last occurrence of any character in the set
99f09bc1
VZ
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
7335902d 357 // find first/last occurrence of any character not in the set
99f09bc1
VZ
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}}
a660d684
KB
398
399\membersection{wxString::wxString}\label{wxstringconstruct}
400
b3324be2 401\func{}{wxString}{\void}
a660d684 402
bd8465ff 403Default constructor. Initializes the string to {\tt ""} (empty string).
a660d684 404
b3324be2 405\func{}{wxString}{\param{const wxString\&}{ x}}
a660d684 406
b3324be2 407Copy constructor.
a660d684 408
b3324be2 409\func{}{wxString}{\param{char}{ ch}, \param{size\_t}{ n = 1}}
a660d684 410
b3324be2 411Constructs a string of {\it n} copies of character {\it ch}.
a660d684 412
99f09bc1 413\func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
a660d684 414
b3324be2 415Takes first {\it nLength} characters from the C string {\it psz}.
bd8465ff 416The default value of {\tt wxSTRING\_MAXLEN} means to take all the string.
f6bcfd97
BP
417
418Note that this constructor may be used even if {\it psz} points to a buffer
419with binary data (i.e. containing {\tt NUL} characters) as long as you provide
420the correct value for {\it nLength}. However, the default form of it works
421only with strings without intermediate {\tt NUL}s because it uses
422{\tt strlen()} to calculate the effective length and it would not give correct
423results otherwise.
a660d684 424
99f09bc1 425\func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
a660d684 426
b3324be2 427For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
bd8465ff 428The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
a660d684 429
bd8465ff
VS
430{\bf Note:} In Unicode build, all of the above constructors take
431{\tt wchar\_t} arguments instead of {\tt char}.
a660d684 432
bd8465ff
VS
433\wxheading{Constructors with conversion}
434
435The following constructors allow you to construct wxString from wide string
436in 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
440Initializes the string from first \arg{nLength} characters of wide string.
441The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
442In ANSI build, \arg{conv}'s
443\helpref{WC2MB}{wxmbconvwc2mb} method is called to
444convert \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
448Initializes the string from first \arg{nLength} characters of C string.
449The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
450In Unicode build, \arg{conv}'s
451\helpref{MB2WC}{wxmbconvmb2wc} method is called to
452convert \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}
a660d684 458
b3324be2 459\membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
a660d684 460
b3324be2 461\func{}{\destruct{wxString}}{\void}
a660d684 462
b3324be2 463String destructor. Note that this is not virtual, so wxString must not be inherited from.
a660d684 464
99f09bc1
VZ
465\membersection{wxString::Alloc}\label{wxstringalloc}
466
467\func{void}{Alloc}{\param{size\_t}{ nLen}}
468
469Preallocate enough space for wxString to store {\it nLen} characters. This function
470may be used to increase speed when the string is constructed by repeated
471concatenation as in
472
473\begin{verbatim}
a660d684 474
99f09bc1
VZ
475// delete all vowels from the string
476wxString DeleteAllVowels(const wxString& original)
477{
478 wxString result;
a660d684 479
99f09bc1 480 size_t len = original.length();
a660d684 481
99f09bc1
VZ
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
495because it will avoid the need of reallocating string memory many times (in case
496of long strings). Note that it does not set the maximal length of a string - it
497will still expand if more than {\it nLen} characters are stored in it. Also, it
498does not truncate the existing string (use
499\helpref{Truncate()}{wxstringtruncate} for this) even if its current length is
500greater than {\it nLen}
501
502\membersection{wxString::Append}\label{wxstringappend}
b3324be2
JS
503
504\func{wxString\&}{Append}{\param{const char*}{ psz}}
a660d684 505
b3324be2 506Concatenates {\it psz} to this string, returning a reference to it.
a660d684 507
b3324be2 508\func{wxString\&}{Append}{\param{char}{ ch}, \param{int}{ count = 1}}
a660d684 509
b3324be2
JS
510Concatenates character {\it ch} to this string, {\it count} times, returning a reference
511to it.
512
99f09bc1 513\membersection{wxString::AfterFirst}\label{wxstringafterfirst}
b3324be2 514
99f09bc1 515\constfunc{wxString}{AfterFirst}{\param{char}{ ch}}
b3324be2 516
7335902d 517Gets all the characters after the first occurrence of {\it ch}.
b3324be2 518Returns the empty string if {\it ch} is not found.
a660d684 519
99f09bc1 520\membersection{wxString::AfterLast}\label{wxstringafterlast}
a660d684 521
99f09bc1
VZ
522\constfunc{wxString}{AfterLast}{\param{char}{ ch}}
523
7335902d 524Gets all the characters after the last occurrence of {\it ch}.
99f09bc1
VZ
525Returns 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
7335902d 531Gets all characters before the first occurrence of {\it ch}.
99f09bc1
VZ
532Returns the whole string if {\it ch} is not found.
533
534\membersection{wxString::BeforeLast}\label{wxstringbeforelast}
535
536\constfunc{wxString}{BeforeLast}{\param{char}{ ch}}
b3324be2 537
7335902d 538Gets all characters before the last occurrence of {\it ch}.
99f09bc1 539Returns the empty string if {\it ch} is not found.
a660d684 540
ed93168b
VZ
541\membersection{wxString::c\_str}\label{wxstringcstr}
542
543\constfunc{const char *}{c\_str}{\void}
544
bd8465ff
VS
545Returns 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}
ed93168b
VZ
552
553\membersection{wxString::Clear}\label{wxstringclear}
554
555\func{void}{Clear}{\void}
556
557Empties the string and frees memory occupied by it.
558
559See also: \helpref{Empty}{wxstringempty}
560
f7bd2698
JS
561\membersection{wxString::Cmp}\label{wxstringcmp}
562
563\constfunc{int}{Cmp}{\param{const char*}{ psz}}
564
565Case-sensitive comparison.
566
99f09bc1 567Returns a positive value if the string is greater than the argument, zero if
f6bcfd97 568it is equal to it or a negative value if it is less than the argument (same semantics
99f09bc1 569as the standard {\it strcmp()} function).
f7bd2698 570
99f09bc1 571See also \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}.
f7bd2698
JS
572
573\membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
574
575\constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
576
577Case-insensitive comparison.
578
99f09bc1 579Returns a positive value if the string is greater than the argument, zero if
f6bcfd97 580it is equal to it or a negative value if it is less than the argument (same semantics
99f09bc1 581as the standard {\it strcmp()} function).
f7bd2698 582
99f09bc1 583See also \helpref{Cmp}{wxstringcmp}, \helpref{IsSameAs}{wxstringissameas}.
f7bd2698 584
99f09bc1 585\membersection{wxString::CompareTo}\label{wxstringcompareto}
a660d684
KB
586
587\begin{verbatim}
588#define NO_POS ((int)(-1)) // undefined position
b3324be2 589enum caseCompare {exact, ignoreCase};
a660d684 590\end{verbatim}
ed93168b 591
b3324be2 592\constfunc{int}{CompareTo}{\param{const char*}{ psz}, \param{caseCompare}{ cmp = exact}}
a660d684 593
b3324be2 594Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
a660d684 595
99f09bc1 596\membersection{wxString::Contains}\label{wxstringcontains}
a660d684 597
99f09bc1 598\constfunc{bool}{Contains}{\param{const wxString\&}{ str}}
a660d684 599
b3324be2 600Returns 1 if target appears anyhere in wxString; else 0.
a660d684 601
f7bd2698 602\membersection{wxString::Empty}\label{wxstringempty}
a660d684 603
f7bd2698
JS
604\func{void}{Empty}{\void}
605
ed93168b
VZ
606Makes the string empty, but doesn't free memory occupied by the string.
607
608See also: \helpref{Clear()}{wxstringclear}.
f7bd2698
JS
609
610\membersection{wxString::Find}\label{wxstringfind}
611
cc81d32f 612\constfunc{int}{Find}{\param{char}{ ch}, \param{bool}{ fromEnd = false}}
f7bd2698
JS
613
614Searches for the given character. Returns the starting index, or -1 if not found.
615
616\constfunc{int}{Find}{\param{const char*}{ sz}}
617
618Searches for the given string. Returns the starting index, or -1 if not found.
a660d684 619
b3324be2 620\membersection{wxString::First}\label{wxstringfirst}
a660d684 621
0aa35d19 622\func{int}{First}{\param{char}{ c}}
a660d684 623
0aa35d19 624\constfunc{int}{First}{\param{const char*}{ psz}}
a660d684 625
0aa35d19 626\constfunc{int}{First}{\param{const wxString\&}{ str}}
a660d684 627
0aa35d19 628Same as \helpref{Find}{wxstringfind}.
a660d684 629
bd8465ff
VS
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
638Returns string representation suitable for passing to OS' functions for
639file handling. In ANSI build, this is same as \helpref{c\_str}{wxstringcstr}.
640In Unicode build, returned value can be either wide character string
641or C string in charset matching the {\tt wxConvFile} object, depending on
642the OS.
643
644\wxheading{See also}
645
646\helpref{wxMBConv}{wxmbconv},
647\helpref{wc\_str}{wxstringwcstr}, \helpref{mb\_str}{wxstringwcstr}
648
341e7d28
VZ
649\membersection{wxString::Format}\label{wxstringformat}
650
651\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{}{...}}
652
653This 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
664This 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
99f09bc1
VZ
671\membersection{wxString::Freq}\label{wxstringfreq}
672
f6bcfd97 673\constfunc{int}{Freq}{\param{char }{ch}}
99f09bc1 674
f6bcfd97 675Returns the number of occurrences of {\it ch} in the string.
99f09bc1 676
6d9d6350
JS
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
683Converts the string or character from an ASCII, 7-bit form
684to the native wxString representation. Most useful when using
fc2171bd 685a Unicode build of wxWidgets.
bd8465ff
VS
686Use \helpref{wxString constructors}{wxstringconstruct} if you
687need to convert from another charset.
6d9d6350 688
f7bd2698 689\membersection{wxString::GetChar}\label{wxstringgetchar}
a660d684 690
f7bd2698 691\constfunc{char}{GetChar}{\param{size\_t}{ n}}
a660d684 692
f7bd2698 693Returns the character at position {\it n} (read-only).
a660d684 694
99f09bc1 695\membersection{wxString::GetData}\label{wxstringgetdata}
a660d684 696
f7bd2698 697\constfunc{const char*}{GetData}{\void}
a660d684 698
fc2171bd 699wxWidgets compatibility conversion. Returns a constant pointer to the data in the string.
a660d684 700
f7bd2698 701\membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
a660d684 702
f7bd2698 703\func{char\&}{GetWritableChar}{\param{size\_t}{ n}}
a660d684 704
f7bd2698 705Returns a reference to the character at position {\it n}.
a660d684 706
f7bd2698 707\membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
a660d684 708
9a55c2ee 709\func{wxChar*}{GetWriteBuf}{\param{size\_t}{ len}}
a660d684 710
f7bd2698 711Returns a writable buffer of at least {\it len} bytes.
8161ba08
JS
712It returns a pointer to a new memory block, and the
713existing data will not be copied.
a660d684 714
f7bd2698
JS
715Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
716to put the string back into a reasonable state.
a660d684 717
99f09bc1 718\membersection{wxString::Index}\label{wxstringindex}
a660d684 719
5ef056a3 720\constfunc{size\_t}{Index}{\param{char}{ ch}}
a660d684 721
f7bd2698 722\constfunc{size\_t}{Index}{\param{const char*}{ sz}}
a660d684 723
f7bd2698 724Same as \helpref{wxString::Find}{wxstringfind}.
a660d684 725
cc81d32f 726\constfunc{size\_t}{Index}{\param{const char*}{ sz}, \param{bool}{ caseSensitive = true}, \param{bool}{ fromEnd = false}}
a660d684 727
f7bd2698 728Search the element in the array, starting from either side.
a660d684 729
cc81d32f 730If {\it fromEnd} is true, reverse search direction.
a660d684 731
f7bd2698 732If {\bf caseSensitive}, comparison is case sensitive (the default).
a660d684 733
2b5f62a0 734Returns the index of the first item matched, or wxNOT\_FOUND.
a660d684 735
8a2c6ef8
JS
736% TODO
737%\membersection{wxString::insert}\label{wxstringinsert}
738% Wrong!
99f09bc1 739%\func{void}{insert}{\param{const wxString\&}{ str}, \param{size\_t}{ index}}
8a2c6ef8
JS
740%
741%Add new element at the given position.
742%
99f09bc1 743\membersection{wxString::IsAscii}\label{wxstringisascii}
a660d684 744
f7bd2698 745\constfunc{bool}{IsAscii}{\void}
a660d684 746
cc81d32f 747Returns true if the string contains only ASCII characters.
a660d684 748
f7bd2698 749\membersection{wxString::IsEmpty}\label{wxstringisempty}
a660d684 750
f7bd2698 751\constfunc{bool}{IsEmpty}{\void}
a660d684 752
cc81d32f 753Returns true if the string is empty.
a660d684 754
99f09bc1 755\membersection{wxString::IsNull}\label{wxstringisnull}
a660d684 756
f7bd2698 757\constfunc{bool}{IsNull}{\void}
a660d684 758
cc81d32f 759Returns true if the string is empty (same as \helpref{IsEmpty}{wxstringisempty}).
a660d684 760
99f09bc1 761\membersection{wxString::IsNumber}\label{wxstringisnumber}
a660d684 762
f7bd2698
JS
763\constfunc{bool}{IsNumber}{\void}
764
cc81d32f 765Returns true if the string is an integer (with possible sign).
f7bd2698
JS
766
767\membersection{wxString::IsSameAs}\label{wxstringissameas}
768
cc81d32f 769\constfunc{bool}{IsSameAs}{\param{const char*}{ psz}, \param{bool}{ caseSensitive = true}}
f7bd2698
JS
770
771Test for string equality, case-sensitive (default) or not.
772
cc81d32f 773caseSensitive is true by default (case matters).
a660d684 774
cc81d32f 775Returns true if strings are equal, false otherwise.
f7bd2698 776
f33fee2a
VZ
777See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas2}
778
779\membersection{wxString::IsSameAs}\label{wxstringissameas2}
780
cc81d32f 781\constfunc{bool}{IsSameAs}{\param{char}{ c}, \param{bool}{ caseSensitive = true}}
f33fee2a
VZ
782
783Test whether the string is equal to the single character {\it c}. The test is
cc81d32f 784case-sensitive if {\it caseSensitive} is true (default) or not if it is false.
f33fee2a 785
cc81d32f 786Returns true if the string is equal to the character, false otherwise.
f33fee2a
VZ
787
788See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}
a660d684 789
99f09bc1 790\membersection{wxString::IsWord}\label{wxstringisword}
a660d684 791
f7bd2698 792\constfunc{bool}{IsWord}{\void}
a660d684 793
cc81d32f 794Returns true if the string is a word. TODO: what's the definition of a word?
a660d684 795
99f09bc1 796\membersection{wxString::Last}\label{wxstringlast}
a660d684 797
f7bd2698 798\constfunc{char}{Last}{\void}
a660d684 799
f7bd2698 800Returns the last character.
a660d684 801
f7bd2698 802\func{char\&}{Last}{\void}
a660d684 803
f7bd2698 804Returns a reference to the last character (writable).
a660d684 805
f7bd2698
JS
806\membersection{wxString::Left}\label{wxstringleft}
807
808\constfunc{wxString}{Left}{\param{size\_t}{ count}}
809
fefc4f15 810Returns the first {\it count} characters of the string.
a660d684 811
f7bd2698 812\membersection{wxString::Len}\label{wxstringlen}
a660d684 813
f7bd2698
JS
814\constfunc{size\_t}{Len}{\void}
815
816Returns the length of the string.
817
818\membersection{wxString::Length}\label{wxstringlength}
819
820\constfunc{size\_t}{Length}{\void}
821
822Returns the length of the string (same as Len).
a660d684 823
99f09bc1
VZ
824\membersection{wxString::Lower}\label{wxstringlower}
825
826\constfunc{wxString}{Lower}{\void}
827
828Returns this string converted to the lower case.
829
830\membersection{wxString::LowerCase}\label{wxstringlowercase}
a660d684 831
f7bd2698
JS
832\func{void}{LowerCase}{\void}
833
834Same as MakeLower.
835
836\membersection{wxString::MakeLower}\label{wxstringmakelower}
837
e16f8973 838\func{wxString\&}{MakeLower}{\void}
f7bd2698 839
e16f8973 840Converts all characters to lower case and returns the result.
f7bd2698
JS
841
842\membersection{wxString::MakeUpper}\label{wxstringmakeupper}
843
e16f8973 844\func{wxString\&}{MakeUpper}{\void}
f7bd2698 845
e16f8973 846Converts all characters to upper case and returns the result.
a660d684 847
99f09bc1 848\membersection{wxString::Matches}\label{wxstringmatches}
a660d684 849
f7bd2698
JS
850\constfunc{bool}{Matches}{\param{const char*}{ szMask}}
851
cc81d32f 852Returns true if the string contents matches a mask containing '*' and '?'.
a660d684 853
bd8465ff
VS
854\membersection{wxString::mb\_str}\label{wxstringmbstr}
855
856\constfunc{const char*}{mb\_str}{\param{wxMBConv\&}{ conv}}
857
858\constfunc{const wxCharBuffer}{mb\_str}{\param{wxMBConv\&}{ conv}}
859
860Returns multibyte (C string) representation of the string.
861In Unicode build, converts using \arg{conv}'s \helpref{cWC2MB}{wxmbconvcwc2mb}
862method and returns wxCharBuffer. In ANSI build, this function is same
863as \helpref{c\_str}{wxstringcstr}.
864The macro wxWX2MBbuf is defined as the correct return type (without const).
865
866\wxheading{See also}
867
868\helpref{wxMBConv}{wxmbconv},
869\helpref{c\_str}{wxstringcstr}, \helpref{wc\_str}{wxstringwcstr},
870\helpref{fn\_str}{wxstringfnstr}
871
f7bd2698 872\membersection{wxString::Mid}\label{wxstringmid}
a660d684 873
99f09bc1 874\constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}}
a660d684 875
f7bd2698
JS
876Returns a substring starting at {\it first}, with length {\it count}, or the rest of
877the string if {\it count} is the default value.
878
879\membersection{wxString::Pad}\label{wxstringpad}
880
cc81d32f 881\func{wxString\&}{Pad}{\param{size\_t}{ count}, \param{char}{ pad = ' '}, \param{bool}{ fromRight = true}}
f7bd2698
JS
882
883Adds {\it count} copies of {\it pad} to the beginning, or to the end of the string (the default).
884
885Removes spaces from the left or from the right (default).
a660d684 886
99f09bc1 887\membersection{wxString::Prepend}\label{wxstringprepend}
a660d684 888
f7bd2698 889\func{wxString\&}{Prepend}{\param{const wxString\&}{ str}}
a660d684 890
f7bd2698 891Prepends {\it str} to this string, returning a reference to this string.
a660d684 892
f7bd2698 893\membersection{wxString::Printf}\label{wxstringprintf}
a660d684 894
f7bd2698
JS
895\func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}}
896
99f09bc1
VZ
897Similar to the standard function {\it sprintf()}. Returns the number of
898characters written, or an integer less than zero on error.
899
900{\bf NB:} This function will use a safe version of {\it vsprintf()} (usually called
901{\it vsnprintf()}) whenever available to always allocate the buffer of correct
902size. Unfortunately, this function is not available on all platforms and the
903dangerous {\it vsprintf()} will be used then which may lead to buffer overflows.
a660d684 904
f7bd2698
JS
905\membersection{wxString::PrintfV}\label{wxstringprintfv}
906
907\func{int}{PrintfV}{\param{const char* }{pszFormat}, \param{va\_list}{ argPtr}}
908
909Similar to vprintf. Returns the number of characters written, or an integer less than zero
910on error.
a660d684 911
99f09bc1 912\membersection{wxString::Remove}\label{wxstringremove}
a660d684 913
f7bd2698
JS
914\func{wxString\&}{Remove}{\param{size\_t}{ pos}}
915
916Same as Truncate. Removes the portion from {\it pos} to the end of the string.
917
918\func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
919
42d14d4e 920Removes the {\it len} characters from the string, starting at {\it pos}.
f7bd2698
JS
921
922\membersection{wxString::RemoveLast}\label{wxstringremovelast}
a660d684 923
f7bd2698
JS
924\func{wxString\&}{RemoveLast}{\void}
925
926Removes the last character.
a660d684 927
99f09bc1 928\membersection{wxString::Replace}\label{wxstringreplace}
a660d684 929
cc81d32f 930\func{size\_t}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll = true}}
f7bd2698 931
7335902d 932Replace first (or all) occurrences of substring with another one.
f7bd2698 933
7335902d 934{\it replaceAll}: global replace (default), or only the first occurrence.
f7bd2698
JS
935
936Returns the number of replacements made.
937
938\membersection{wxString::Right}\label{wxstringright}
939
940\constfunc{wxString}{Right}{\param{size\_t}{ count}}
a660d684 941
f7bd2698 942Returns the last {\it count} characters.
a660d684 943
f7bd2698 944\membersection{wxString::SetChar}\label{wxstringsetchar}
a660d684 945
f7bd2698
JS
946\func{void}{SetChar}{\param{size\_t}{ n}, \param{char}{ch}}
947
948Sets the character at position {\it n}.
949
950\membersection{wxString::Shrink}\label{wxstringshrink}
951
952\func{void}{Shrink}{\void}
953
99f09bc1
VZ
954Minimizes the string's memory. This can be useful after a call to
955\helpref{Alloc()}{wxstringalloc} if too much memory were preallocated.
a660d684
KB
956
957\membersection{wxString::sprintf}\label{wxstringsprintf}
a660d684 958
f7bd2698 959\func{void}{sprintf}{\param{const char* }{ fmt}}
a660d684 960
f7bd2698 961The same as Printf.
a660d684 962
f6bcfd97
BP
963\membersection{wxString::StartsWith}\label{wxstringstartswith}
964
965\constfunc{bool}{StartsWith}{\param{const wxChar }{*prefix}, \param{wxString }{*rest = NULL}}
966
967This function can be used to test if the string starts with the specified
cc81d32f 968{\it prefix}. If it does, the function will return {\tt true} and put the rest
f6bcfd97 969of the string (i.e. after the prefix) into {\it rest} string if it is not
cc81d32f 970{\tt NULL}. Otherwise, the function returns {\tt false} and doesn't modify the
f6bcfd97
BP
971{\it rest}.
972
99f09bc1 973\membersection{wxString::Strip}\label{wxstringstrip}
a660d684
KB
974
975\begin{verbatim}
f7bd2698 976enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
a660d684
KB
977\end{verbatim}
978
f7bd2698 979\constfunc{wxString}{Strip}{\param{stripType}{ s = trailing}}
a660d684 980
f7bd2698
JS
981Strip characters at the front and/or end. The same as Trim except that it
982doesn't change this string.
a660d684 983
99f09bc1
VZ
984\membersection{wxString::SubString}\label{wxstringsubstring}
985
f6bcfd97 986\constfunc{wxString}{SubString}{\param{size\_t}{ from}, \param{size\_t}{ to}}
99f09bc1 987
b855ef77
VZ
988Deprecated, use \helpref{Mid}{wxstringmid} instead (but note that parameters
989have different meaning).
990
991Returns the part of the string between the indices {\it from} and {\it to}
992inclusive.
99f09bc1 993
6d9d6350
JS
994\membersection{wxString::ToAscii}\label{wxstringtoascii}
995
996\constfunc{const char*}{ToAscii}{\void}
997
998Converts the string to an ASCII, 7-bit string (ANSI builds only).
999
1000\constfunc{const wxCharBuffer}{ToAscii}{\void}
1001
1002Converts the string to an ASCII, 7-bit string in the form of
1003a wxCharBuffer (Unicode builds only).
1004
bd8465ff
VS
1005Note that this conversion only works if the string contains only ASCII
1006characters. The \helpref{mb\_str}{wxstringmbstr} method provides more
1007powerful means of converting wxString to C string.
1008
cd0b1709
VZ
1009\membersection{wxString::ToDouble}\label{wxstringtodouble}
1010
f6bcfd97 1011\constfunc{bool}{ToDouble}{\param{double}{ *val}}
cd0b1709 1012
cc81d32f
VS
1013Attempts to convert the string to a floating point number. Returns true on
1014success (the number is stored in the location pointed to by {\it val}) or false
cd0b1709
VZ
1015if the string does not represent such number.
1016
f6bcfd97
BP
1017\wxheading{See also}
1018
1019\helpref{wxString::ToLong}{wxstringtolong},\\
1020\helpref{wxString::ToULong}{wxstringtoulong}
1021
cd0b1709
VZ
1022\membersection{wxString::ToLong}\label{wxstringtolong}
1023
538f35cc 1024\constfunc{bool}{ToLong}{\param{long}{ *val}, \param{int }{base = $10$}}
cd0b1709 1025
4eb438cf 1026Attempts to convert the string to a signed integer in base {\it base}. Returns
cc81d32f
VS
1027{\tt true} on success in which case the number is stored in the location
1028pointed to by {\it val} or {\tt false} if the string does not represent a
4eb438cf
VZ
1029valid number in the given base.
1030
538f35cc
VZ
1031The value of {\it base} must be comprised between $2$ and $36$, inclusive, or
1032be a special value $0$ which means that the usual rules of {\tt C} numbers are
1033applied: if the number starts with {\tt 0x} it is considered to be in base
1034$16$, if it starts with {\tt 0} - in base $8$ and in base $10$ otherwise. Note
1035that you may not want to specify the base $0$ if you are parsing the numbers
1036which may have leading zeroes as they can yield unexpected (to the user not
1037familiar with C) results.
cd0b1709 1038
f6bcfd97
BP
1039\wxheading{See also}
1040
1041\helpref{wxString::ToDouble}{wxstringtodouble},\\
1042\helpref{wxString::ToULong}{wxstringtoulong}
1043
cd0b1709
VZ
1044\membersection{wxString::ToULong}\label{wxstringtoulong}
1045
538f35cc 1046\constfunc{bool}{ToULong}{\param{unsigned long}{ *val}, \param{int }{base = $10$}}
4eb438cf
VZ
1047
1048Attempts to convert the string to a ansigned integer in base {\it base}.
cc81d32f
VS
1049Returns {\tt true} on success in which case the number is stored in the
1050location pointed to by {\it val} or {\tt false} if the string does not
4eb438cf 1051represent a valid number in the given base.
cd0b1709 1052
ec64d632
VZ
1053See \helpref{wxString::ToLong}{wxstringtolong} for the more detailed
1054description of the {\it base} parameter.
cd0b1709 1055
f6bcfd97
BP
1056\wxheading{See also}
1057
1058\helpref{wxString::ToDouble}{wxstringtodouble},\\
1059\helpref{wxString::ToLong}{wxstringtolong}
1060
f7bd2698 1061\membersection{wxString::Trim}\label{wxstringtrim}
a660d684 1062
cc81d32f 1063\func{wxString\&}{Trim}{\param{bool}{ fromRight = true}}
a660d684 1064
f7bd2698 1065Removes spaces from the left or from the right (default).
a660d684 1066
f7bd2698 1067\membersection{wxString::Truncate}\label{wxstringtruncate}
a660d684 1068
f7bd2698 1069\func{wxString\&}{Truncate}{\param{size\_t}{ len}}
a660d684 1070
f7bd2698 1071Truncate the string to the given length.
a660d684 1072
f7bd2698
JS
1073\membersection{wxString::UngetWriteBuf}\label{wxstringungetwritebuf}
1074
1075\func{void}{UngetWriteBuf}{\void}
1076
448025b0
VZ
1077\func{void}{UngetWriteBuf}{\param{size\_t }{len}}
1078
1079Puts the string back into a reasonable state (in which it can be used
1080normally), after
f7bd2698 1081\rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called.
a660d684 1082
448025b0
VZ
1083The version of the function without the {\it len} parameter will calculate the
1084new string length itself assuming that the string is terminated by the first
1085{\tt NUL} character in it while the second one will use the specified length
1086and thus is the only version which should be used with the strings with
1087embedded {\tt NUL}s (it is also slightly more efficient as {\tt strlen()}
1088doesn't have to be called).
1089
99f09bc1
VZ
1090\membersection{wxString::Upper}\label{wxstringupper}
1091
1092\constfunc{wxString}{Upper}{\void}
1093
1094Returns this string converted to upper case.
1095
1096\membersection{wxString::UpperCase}\label{wxstringuppercase}
a660d684 1097
f7bd2698
JS
1098\func{void}{UpperCase}{\void}
1099
1100The same as MakeUpper.
a660d684 1101
bd8465ff
VS
1102\membersection{wxString::wc\_str}\label{wxstringwcstr}
1103
1104\constfunc{const wchar\_t*}{wc\_str}{\param{wxMBConv\&}{ conv}}
1105
1106\constfunc{const wxWCharBuffer}{wc\_str}{\param{wxMBConv\&}{ conv}}
1107
1108Returns wide character representation of the string.
1109In ANSI build, converts using \arg{conv}'s \helpref{cMB2WC}{wxmbconvcmb2wc}
1110method and returns wxWCharBuffer. In Unicode build, this function is same
1111as \helpref{c\_str}{wxstringcstr}.
1112The macro wxWX2WCbuf is defined as the correct return type (without const).
1113
1114\wxheading{See also}
1115
1116\helpref{wxMBConv}{wxmbconv},
1117\helpref{c\_str}{wxstringcstr}, \helpref{mb\_str}{wxstringwcstr},
1118\helpref{fn\_str}{wxstringfnstr}
1119
99f09bc1
VZ
1120\membersection{wxString::operator!}\label{wxstringoperatornot}
1121
1122\constfunc{bool}{operator!}{\void}
1123
cc81d32f 1124Empty string is false, so !string will only return true if the string is empty.
99f09bc1
VZ
1125This allows the tests for NULLness of a {\it const char *} pointer and emptyness
1126of the string to look the same in the code and makes it easier to port old code
1127to wxString.
1128
1129See also \helpref{IsEmpty()}{wxstringisempty}.
1130
a660d684
KB
1131\membersection{wxString::operator $=$}\label{wxstringoperatorassign}
1132
f7bd2698
JS
1133\func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}}
1134
1135\func{wxString\&}{operator $=$}{\param{const char*}{ psz}}
1136
1137\func{wxString\&}{operator $=$}{\param{char}{ c}}
1138
1139\func{wxString\&}{operator $=$}{\param{const unsigned char*}{ psz}}
1140
1141\func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}}
a660d684 1142
99f09bc1
VZ
1143Assignment: the effect of each operation is the same as for the corresponding
1144constructor (see \helpref{wxString constructors}{wxstringconstruct}).
5de76427 1145
f6bcfd97 1146\membersection{wxString::operator $+$}\label{wxstringoperatorplus}
5de76427 1147
99f09bc1
VZ
1148Concatenation: all these operators return a new strign equal to the sum of the
1149operands.
5de76427
JS
1150
1151\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
1152
1153\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const char*}{ y}}
1154
1155\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{char}{ y}}
1156
1157\func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}}
1158
99f09bc1 1159\membersection{wxString::operator $+=$}\label{wxstringplusequal}
a660d684 1160
f7bd2698
JS
1161\func{void}{operator $+=$}{\param{const wxString\&}{ str}}
1162
1163\func{void}{operator $+=$}{\param{const char*}{ psz}}
1164
1165\func{void}{operator $+=$}{\param{char}{ c}}
a660d684 1166
99f09bc1 1167Concatenation in place: the argument is appended to the string.
a660d684
KB
1168
1169\membersection{wxString::operator []}\label{wxstringoperatorbracket}
1170
f7bd2698
JS
1171\func{char\&}{operator []}{\param{size\_t}{ i}}
1172
1173\func{char}{operator []}{\param{size\_t}{ i}}
1174
1175\func{char}{operator []}{\param{int}{ i}}
a660d684
KB
1176
1177Element extraction.
1178
1179\membersection{wxString::operator ()}\label{wxstringoperatorparenth}
1180
f7bd2698
JS
1181\func{wxString}{operator ()}{\param{size\_t}{ start}, \param{size\_t}{ len}}
1182
1183Same as Mid (substring extraction).
a660d684
KB
1184
1185\membersection{wxString::operator \cinsert}\label{wxstringoperatorout}
f7bd2698 1186
037267e1 1187\func{wxString\&}{operator \cinsert}{\param{const wxString\&}{ str}}
f7bd2698 1188
037267e1 1189\func{wxString\&}{operator \cinsert}{\param{const char*}{ psz}}
f7bd2698 1190
037267e1 1191\func{wxString\&}{operator \cinsert}{\param{char }{ch}}
f7bd2698
JS
1192
1193Same as $+=$.
a660d684 1194
99f09bc1
VZ
1195\func{wxString\&}{operator \cinsert}{\param{int}{ i}}
1196
1197\func{wxString\&}{operator \cinsert}{\param{float}{ f}}
1198
1199\func{wxString\&}{operator \cinsert}{\param{double}{ d}}
1200
1201These functions work as C++ stream insertion operators: they insert the given
1202value into the string. Precision or format cannot be set using them, you can use
1203\helpref{Printf}{wxstringprintf} for this.
1204
a660d684 1205\membersection{wxString::operator \cextract}\label{wxstringoperatorin}
a660d684 1206
f7bd2698 1207\func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}}
a660d684 1208
f7bd2698 1209Extraction from a stream.
a660d684 1210
f7bd2698 1211\membersection{wxString::operator const char*}\label{wxstringoperatorconstcharpt}
a660d684 1212
f7bd2698 1213\constfunc{}{operator const char*}{\void}
a660d684 1214
f7bd2698 1215Implicit conversion to a C string.
a660d684 1216
99f09bc1 1217\membersection{Comparison operators}\label{wxstringcomparison}
a660d684 1218
f7bd2698 1219\func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1220
f7bd2698 1221\func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1222
f7bd2698 1223\func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1224
f7bd2698 1225\func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1226
f7bd2698 1227\func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1228
f7bd2698 1229\func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1230
f7bd2698 1231\func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1232
f7bd2698 1233\func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1234
f7bd2698 1235\func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1236
f7bd2698 1237\func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1238
f7bd2698 1239\func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
a660d684 1240
f7bd2698 1241\func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
a660d684 1242
f7bd2698 1243\wxheading{Remarks}
a660d684 1244
f7bd2698 1245These comparisons are case-sensitive.
a660d684 1246
1d218550
VZ
1247
1248\section{\class{wxStringBuffer}}\label{wxstringbuffer}
1249
1250This tiny class allows to conveniently access the \helpref{wxString}{wxstring}
1251internal buffer as a writable pointer without any risk to forget to restore
1252the string to the usable state later.
1253
1254For example, assuming you have a low-level OS function called
1255{\tt GetMeaningOfLifeAsString(char *)} returning the value in the provided
1256buffer (which must be writable, of course) you might call it like this:
1257
1258\begin{verbatim}
1259 wxString theAnswer;
1260 GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
1261 if ( theAnswer != "42" )
1262 {
1263 wxLogError("Something is very wrong!");
1264 }
1265\end{verbatim}
1266
1267\wxheading{Derived from}
1268
1269None
1270
1271\wxheading{Include files}
1272
1273<wx/string.h>
1274
1275\latexignore{\rtfignore{\wxheading{Members}}}
1276
1277\membersection{wxStringBuffer::wxStringBuffer}
1278
1279\func{}{wxStringBuffer}{\param{const wxString\& }{str}, \param{size\_t }{len}}
1280
1281Constructs a writable string buffer object associated with the given string
2edb0bde 1282and containing enough space for at least {\it len} characters. Basically, this
1d218550
VZ
1283is equivalent to calling \helpref{GetWriteBuf}{wxstringgetwritebuf} and
1284saving the result.
1285
1286\membersection{wxStringBuffer::\destruct{wxStringBuffer}}
1287
1288\func{}{\destruct{wxStringBuffer}}{\void}
1289
1290Restores the string passed to the constructor to the usable state by calling
1291\helpref{UngetWriteBuf}{wxstringungetwritebuf} on it.
1292
1293\membersection{wxStringBuffer::operator wxChar *}
1294
1295\constfunc{wxChar *}{operator wxChar *}{\void}
1296
1297Returns the writable pointer to a buffer of the size at least equal to the
1298length specified in the constructor.
1299
1300