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