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