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