docs/latex/wx/wxstring.tex

   1 \section{\class{wxString}}\label{wxstring}
   2
   3 \wxheading{Derived from}
   4
   5 None
   6
   7 \wxheading{See also}
   8
   9 \overview{Overview}{wxstringoverview}
  10
  11 \latexignore{\rtfignore{\wxheading{Members}}}
  12
  13 \membersection{wxString::wxString}\label{wxstringconstruct}
  14
  15 \func{}{wxString}{\void}
  16
  17 Default constructor.
  18
  19 \func{}{wxString}{\param{const wxString\&}{ x}}
  20
  21 Copy constructor.
  22
  23 \func{}{wxString}{\param{char}{ ch}, \param{size\_t}{ n = 1}}
  24
  25 Constructs a string of {\it n} copies of character {\it ch}.
  26
  27 \func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = STRING\_MAXLEN}}
  28
  29 Takes first {\it nLength} characters from the C string {\it psz}.
  30 The default value of STRING\_MAXLEN means take all the string.
  31
  32 \func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = STRING\_MAXLEN}}
  33
  34 For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
  35 The default value of STRING\_MAXLEN means take all the string.
  36
  37 \func{}{wxString}{\param{const wchar\_t*}{ psz}}
  38
  39 Constructs a string from the wide (UNICODE) string.
  40
  41 \membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
  42
  43 \func{}{\destruct{wxString}}{\void}
  44
  45 String destructor. Note that this is not virtual, so wxString must not be inherited from.
  46
  47 \membersection{wxString::Alloc}\label{wxstringAlloc}
  48
  49 \func{void}{Alloc}{\param{uint}{ newsize}}
  50
  51 Preallocate some space for wxString. Only works if the data of this string is not shared.
  52
  53 \membersection{wxString::Append}\label{wxstringAppend}
  54
  55 \func{wxString\&}{Append}{\param{const char*}{ psz}}
  56
  57 Concatenates {\it psz} to this string, returning a reference to it.
  58
  59 \func{wxString\&}{Append}{\param{char}{ ch}, \param{int}{ count = 1}}
  60
  61 Concatenates character {\it ch} to this string, {\it count} times, returning a reference
  62 to it.
  63
  64 \membersection{wxString::After}\label{wxstringAfter}
  65
  66 \constfunc{wxString}{After}{\param{char}{ ch}}
  67
  68 Gets all the characters after the first occurence of {\it ch}.
  69 Returns the empty string if {\it ch} is not found.
  70
  71 \membersection{wxString::Before}\label{wxstringBefore}
  72
  73 \constfunc{wxString}{Before}{\param{char}{ ch}}
  74
  75 Gets all characters before the last occurence of {\it ch}.
  76 Returns empty string if {\it ch} is not found.
  77
  78 \membersection{wxString::Cmp}\label{wxstringcmp}
  79
  80 \constfunc{int}{Cmp}{\param{const char*}{ psz}}
  81
  82 Case-sensitive comparison.
  83
  84 Returns 0 if equal, +1 if greater or -1 if less.
  85
  86 See also CmpNoCase, IsSameAs.
  87
  88 \membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
  89
  90 \constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
  91
  92 Case-insensitive comparison.
  93
  94 Returns 0 if equal, +1 if greater or -1 if less.
  95
  96 See also Cmp, IsSameAs.
  97
  98 \membersection{wxString::CompareTo}\label{wxstringCompareTo}
  99
 100 \begin{verbatim}
 101 #define NO_POS ((int)(-1)) // undefined position
 102 enum caseCompare {exact, ignoreCase};
 103 \end{verbatim}
 104
 105 \constfunc{int}{CompareTo}{\param{const char*}{ psz}, \param{caseCompare}{ cmp = exact}}
 106
 107 Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
 108
 109 \membersection{wxString::Contains}\label{wxstringContains}
 110
 111 \func{bool}{Contains}{\param{const wxString\&}{ str}}
 112
 113 Returns 1 if target appears anyhere in wxString; else 0.
 114
 115 \membersection{wxString::Empty}\label{wxstringempty}
 116
 117 \func{void}{Empty}{\void}
 118
 119 Reinitializes the string and frees the data.
 120
 121 \membersection{wxString::Find}\label{wxstringfind}
 122
 123 \constfunc{int}{Find}{\param{char}{ ch}, \param{bool}{ fromEnd = FALSE}}
 124
 125 Searches for the given character. Returns the starting index, or -1 if not found.
 126
 127 \constfunc{int}{Find}{\param{const char*}{ sz}}
 128
 129 Searches for the given string. Returns the starting index, or -1 if not found.
 130
 131 \membersection{wxString::First}\label{wxstringfirst}
 132
 133 \func{size\_t}{First}{\param{char}{ c}}
 134
 135 \constfunc{size\_t}{First}{\param{const char*}{ psz}}
 136
 137 \constfunc{size\_t}{First}{\param{const wxString\&}{ str}}
 138
 139 \constfunc{size\_t}{First}{\param{const char}{ ch}}
 140
 141 Returns the first occurrence of the item.
 142
 143 \membersection{wxString::GetChar}\label{wxstringgetchar}
 144
 145 \constfunc{char}{GetChar}{\param{size\_t}{ n}}
 146
 147 Returns the character at position {\it n} (read-only).
 148
 149 \membersection{wxString::GetData}\label{wxstringGetData}
 150
 151 \constfunc{const char*}{GetData}{\void}
 152
 153 wxWindows compatibility conversion. Returns a constant pointer to the data in the string.
 154
 155 \membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
 156
 157 \func{char\&}{GetWritableChar}{\param{size\_t}{ n}}
 158
 159 Returns a reference to the character at position {\it n}.
 160
 161 \membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
 162
 163 \func{char*}{GetWriteBuf}{\param{uint}{ len}}
 164
 165 Returns a writable buffer of at least {\it len} bytes.
 166
 167 Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
 168 to put the string back into a reasonable state.
 169
 170 \membersection{wxString::Index}\label{wxstringIndex}
 171
 172 \constfunc{size\_t}{Index}{\param{char}{ ch}, \param{int}{ startpos = 0}}
 173
 174 Same as \helpref{wxString::Find}{wxstringfind}.
 175
 176 \constfunc{size\_t}{Index}{\param{const char*}{ sz}}
 177
 178 Same as \helpref{wxString::Find}{wxstringfind}.
 179
 180 \constfunc{size\_t}{Index}{\param{const char*}{ sz}, \param{bool}{ caseSensitive = TRUE}, \param{bool}{ fromEnd = FALSE}}
 181
 182 Search the element in the array, starting from either side.
 183
 184 If {\it fromEnd} is TRUE, reverse search direction.
 185
 186 If {\bf caseSensitive}, comparison is case sensitive (the default).
 187
 188 Returns the index of the first item matched, or NOT\_FOUND.
 189
 190 % TODO
 191 %\membersection{wxString::insert}\label{wxstringinsert}
 192 % Wrong!
 193 %\func{void}{insert}{\param{const wxString\&}{ str}, \param{uint}{ index}}
 194 %
 195 %Add new element at the given position.
 196 %
 197 \membersection{wxString::IsAscii}\label{wxstringIsAscii}
 198
 199 \constfunc{bool}{IsAscii}{\void}
 200
 201 Returns TRUE if the string is ASCII.
 202
 203 \membersection{wxString::IsEmpty}\label{wxstringisempty}
 204
 205 \constfunc{bool}{IsEmpty}{\void}
 206
 207 Returns TRUE if the string is NULL.
 208
 209 \membersection{wxString::IsNull}\label{wxstringIsNull}
 210
 211 \constfunc{bool}{IsNull}{\void}
 212
 213 Returns TRUE if the string is NULL (same as IsEmpty).
 214
 215 \membersection{wxString::IsNumber}\label{wxstringIsNumber}
 216
 217 \constfunc{bool}{IsNumber}{\void}
 218
 219 Returns TRUE if the string is a number.
 220
 221 \membersection{wxString::IsSameAs}\label{wxstringissameas}
 222
 223 \constfunc{bool}{IsSameAs}{\param{const char*}{ psz}, \param{bool}{ caseSensitive = TRUE}}
 224
 225 Test for string equality, case-sensitive (default) or not.
 226
 227 caseSensitive is TRUE by default (case matters).
 228
 229 Returns TRUE if strings are equal, FALSE otherwise.
 230
 231 See also Cmp, CmpNoCase.
 232
 233 \membersection{wxString::IsWord}\label{wxstringIsWord}
 234
 235 \constfunc{bool}{IsWord}{\void}
 236
 237 Returns TRUE if the string is a word. TODO: what's the definition of a word?
 238
 239 \membersection{wxString::Last}\label{wxstringLast}
 240
 241 \constfunc{char}{Last}{\void}
 242
 243 Returns the last character.
 244
 245 \func{char\&}{Last}{\void}
 246
 247 Returns a reference to the last character (writable).
 248
 249 \membersection{wxString::Left}\label{wxstringleft}
 250
 251 \constfunc{wxString}{Left}{\param{size\_t}{ count}}
 252
 253 Returns the first {\it count} characters.
 254
 255 \constfunc{wxString}{Left}{\param{char}{ ch}}
 256
 257 Returns all characters before the first occurence of {\it ch}.
 258 Returns the whole string if {\it ch} is not found.
 259
 260 \membersection{wxString::Len}\label{wxstringlen}
 261
 262 \constfunc{size\_t}{Len}{\void}
 263
 264 Returns the length of the string.
 265
 266 \membersection{wxString::Length}\label{wxstringlength}
 267
 268 \constfunc{size\_t}{Length}{\void}
 269
 270 Returns the length of the string (same as Len).
 271
 272 \membersection{wxString::LowerCase}\label{wxstringLowerCase}
 273
 274 \func{void}{LowerCase}{\void}
 275
 276 Same as MakeLower.
 277
 278 \membersection{wxString::MakeLower}\label{wxstringmakelower}
 279
 280 \func{void}{MakeLower}{\void}
 281
 282 Converts all characters to lower case.
 283
 284 \membersection{wxString::MakeUpper}\label{wxstringmakeupper}
 285
 286 \func{void}{MakeUpper}{\void}
 287
 288 Converts all characters to upper case.
 289
 290 \membersection{wxString::Matches}\label{wxstringMatches}
 291
 292 \constfunc{bool}{Matches}{\param{const char*}{ szMask}}
 293
 294 Returns TRUE if the string contents matches a mask containing '*' and '?'.
 295
 296 \membersection{wxString::Mid}\label{wxstringmid}
 297
 298 \constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = STRING\_MAXLEN}}
 299
 300 Returns a substring starting at {\it first}, with length {\it count}, or the rest of
 301 the string if {\it count} is the default value.
 302
 303 \membersection{wxString::Pad}\label{wxstringpad}
 304
 305 \func{wxString\&}{Pad}{\param{size\_t}{ count}, \param{char}{ pad = ' '}, \param{bool}{ fromRight = TRUE}}
 306
 307 Adds {\it count} copies of {\it pad} to the beginning, or to the end of the string (the default).
 308
 309 Removes spaces from the left or from the right (default).
 310
 311 \membersection{wxString::Prepend}\label{wxstringPrepend}
 312
 313 \func{wxString\&}{Prepend}{\param{const wxString\&}{ str}}
 314
 315 Prepends {\it str} to this string, returning a reference to this string.
 316
 317 \membersection{wxString::Printf}\label{wxstringprintf}
 318
 319 \func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}}
 320
 321 Similar to sprintf. Returns the number of characters written, or an integer less than zero
 322 on error.
 323
 324 \membersection{wxString::PrintfV}\label{wxstringprintfv}
 325
 326 \func{int}{PrintfV}{\param{const char* }{pszFormat}, \param{va\_list}{ argPtr}}
 327
 328 Similar to vprintf. Returns the number of characters written, or an integer less than zero
 329 on error.
 330
 331 \membersection{wxString::Remove}\label{wxstringRemove}
 332
 333 \func{wxString\&}{Remove}{\param{size\_t}{ pos}}
 334
 335 Same as Truncate. Removes the portion from {\it pos} to the end of the string.
 336
 337 \func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
 338
 339 Removes the last {\it len} characters from the string, starting at {\it pos}.
 340
 341 \membersection{wxString::RemoveLast}\label{wxstringremovelast}
 342
 343 \func{wxString\&}{RemoveLast}{\void}
 344
 345 Removes the last character.
 346
 347 \membersection{wxString::Replace}\label{wxstringReplace}
 348
 349 \func{uint}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll}}
 350
 351 Replace first (or all) occurences of substring with another one.
 352
 353 {\it replaceAll}: global replace (default), or only the first occurence.
 354
 355 Returns the number of replacements made.
 356
 357 \membersection{wxString::Right}\label{wxstringright}
 358
 359 \constfunc{wxString}{Right}{\param{size\_t}{ count}}
 360
 361 Returns the last {\it count} characters.
 362
 363 \constfunc{wxString}{Right}{\param{char}{ ch}}
 364
 365 Returns all characters after the last occurence of {\it ch}.
 366 Returns the whole string if {\it ch} is not found.
 367
 368 \membersection{wxString::SetChar}\label{wxstringsetchar}
 369
 370 \func{void}{SetChar}{\param{size\_t}{ n}, \param{char}{ch}}
 371
 372 Sets the character at position {\it n}.
 373
 374 \membersection{wxString::Shrink}\label{wxstringshrink}
 375
 376 \func{void}{Shrink}{\void}
 377
 378 Minimizes the string's memory. Only works if the data of this string is not shared.
 379
 380 \membersection{wxString::sprintf}\label{wxstringsprintf}
 381
 382 \func{void}{sprintf}{\param{const char* }{ fmt}}
 383
 384 The same as Printf.
 385
 386 \membersection{wxString::Strip}\label{wxstringStrip}
 387
 388 \begin{verbatim}
 389 enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
 390 \end{verbatim}
 391
 392 \constfunc{wxString}{Strip}{\param{stripType}{ s = trailing}}
 393
 394 Strip characters at the front and/or end. The same as Trim except that it
 395 doesn't change this string.
 396
 397 \membersection{wxString::Trim}\label{wxstringtrim}
 398
 399 \func{wxString\&}{Trim}{\param{bool}{ fromRight = TRUE}}
 400
 401 Removes spaces from the left or from the right (default).
 402
 403 \membersection{wxString::Truncate}\label{wxstringtruncate}
 404
 405 \func{wxString\&}{Truncate}{\param{size\_t}{ len}}
 406
 407 Truncate the string to the given length.
 408
 409 \membersection{wxString::UngetWriteBuf}\label{wxstringungetwritebuf}
 410
 411 \func{void}{UngetWriteBuf}{\void}
 412
 413 Puts the string back into a reasonable state, after
 414 \rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called.
 415
 416 \membersection{wxString::UpperCase}\label{wxstringUpperCase}
 417
 418 \func{void}{UpperCase}{\void}
 419
 420 The same as MakeUpper.
 421
 422 \membersection{wxString::operator $=$}\label{wxstringoperatorassign}
 423
 424 \func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}}
 425
 426 \func{wxString\&}{operator $=$}{\param{const char*}{ psz}}
 427
 428 \func{wxString\&}{operator $=$}{\param{char}{ c}}
 429
 430 \func{wxString\&}{operator $=$}{\param{const unsigned char*}{ psz}}
 431
 432 \func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}}
 433
 434 Assignment.
 435
 436 \membersection{operator wxString::$+$}\label{wxstringoperatorplus}
 437
 438 Concatenation.
 439
 440 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 441
 442 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const char*}{ y}}
 443
 444 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{char}{ y}}
 445
 446 \func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}}
 447
 448 \membersection{wxString::operator $+=$}\label{wxstringPlusEqual}
 449
 450 \func{void}{operator $+=$}{\param{const wxString\&}{ str}}
 451
 452 \func{void}{operator $+=$}{\param{const char*}{ psz}}
 453
 454 \func{void}{operator $+=$}{\param{char}{ c}}
 455
 456 Concatenation.
 457
 458 \membersection{wxString::operator []}\label{wxstringoperatorbracket}
 459
 460 \func{char\&}{operator []}{\param{size\_t}{ i}}
 461
 462 \func{char}{operator []}{\param{size\_t}{ i}}
 463
 464 \func{char}{operator []}{\param{int}{ i}}
 465
 466 Element extraction.
 467
 468 \membersection{wxString::operator ()}\label{wxstringoperatorparenth}
 469
 470 \func{wxString}{operator ()}{\param{size\_t}{ start}, \param{size\_t}{ len}}
 471
 472 Same as Mid (substring extraction).
 473
 474 \membersection{wxString::operator \cinsert}\label{wxstringoperatorout}
 475
 476 \func{wxString\&}{operator \cinsert}{\\param{const wxString\&}{ str}}
 477
 478 \func{wxString\&}{operator \cinsert}{\\param{const char*}{ psz}}
 479
 480 \func{wxString\&}{operator \cinsert}{\\param{char }{ch}}
 481
 482 Same as $+=$.
 483
 484 \membersection{wxString::operator \cextract}\label{wxstringoperatorin}
 485
 486 \func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}}
 487
 488 Extraction from a stream.
 489
 490 \membersection{wxString::operator const char*}\label{wxstringoperatorconstcharpt}
 491
 492 \constfunc{}{operator const char*}{\void}
 493
 494 Implicit conversion to a C string.
 495
 496 \membersection{Comparison operators}\label{wxstringComparison}
 497
 498 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 499
 500 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 501
 502 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 503
 504 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 505
 506 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 507
 508 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 509
 510 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 511
 512 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 513
 514 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 515
 516 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 517
 518 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 519
 520 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 521
 522 \wxheading{Remarks}
 523
 524 These comparisons are case-sensitive.
 525
 526