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 \membersection{wxString::Insert}\label{wxstringInsert}
 191
 192 \func{void}{Insert}{\param{const wxString\&}{ str}, \param{uint}{ index}}
 193
 194 Add new element at the given position.
 195
 196 \membersection{wxString::IsAscii}\label{wxstringIsAscii}
 197
 198 \constfunc{bool}{IsAscii}{\void}
 199
 200 Returns TRUE if the string is ASCII.
 201
 202 \membersection{wxString::IsEmpty}\label{wxstringisempty}
 203
 204 \constfunc{bool}{IsEmpty}{\void}
 205
 206 Returns TRUE if the string is NULL.
 207
 208 \membersection{wxString::IsNull}\label{wxstringIsNull}
 209
 210 \constfunc{bool}{IsNull}{\void}
 211
 212 Returns TRUE if the string is NULL (same as IsEmpty).
 213
 214 \membersection{wxString::IsNumber}\label{wxstringIsNumber}
 215
 216 \constfunc{bool}{IsNumber}{\void}
 217
 218 Returns TRUE if the string is a number.
 219
 220 \membersection{wxString::IsSameAs}\label{wxstringissameas}
 221
 222 \constfunc{bool}{IsSameAs}{\param{const char*}{ psz}, \param{bool}{ caseSensitive = TRUE}}
 223
 224 Test for string equality, case-sensitive (default) or not.
 225
 226 caseSensitive is TRUE by default (case matters).
 227
 228 Returns TRUE if strings are equal, FALSE otherwise.
 229
 230 See also Cmp, CmpNoCase.
 231
 232 \membersection{wxString::IsWord}\label{wxstringIsWord}
 233
 234 \constfunc{bool}{IsWord}{\void}
 235
 236 Returns TRUE if the string is a word. TODO: what's the definition of a word?
 237
 238 \membersection{wxString::Last}\label{wxstringLast}
 239
 240 \constfunc{char}{Last}{\void}
 241
 242 Returns the last character.
 243
 244 \func{char\&}{Last}{\void}
 245
 246 Returns a reference to the last character (writable).
 247
 248 \membersection{wxString::Left}\label{wxstringleft}
 249
 250 \constfunc{wxString}{Left}{\param{size\_t}{ count}}
 251
 252 Returns the first {\it count} characters.
 253
 254 \constfunc{wxString}{Left}{\param{char}{ ch}}
 255
 256 Returns all characters before the first occurence of {\it ch}.
 257 Returns the whole string if {\it ch} is not found.
 258
 259 \membersection{wxString::Len}\label{wxstringlen}
 260
 261 \constfunc{size\_t}{Len}{\void}
 262
 263 Returns the length of the string.
 264
 265 \membersection{wxString::Length}\label{wxstringlength}
 266
 267 \constfunc{size\_t}{Length}{\void}
 268
 269 Returns the length of the string (same as Len).
 270
 271 \membersection{wxString::LowerCase}\label{wxstringLowerCase}
 272
 273 \func{void}{LowerCase}{\void}
 274
 275 Same as MakeLower.
 276
 277 \membersection{wxString::MakeLower}\label{wxstringmakelower}
 278
 279 \func{void}{MakeLower}{\void}
 280
 281 Converts all characters to lower case.
 282
 283 \membersection{wxString::MakeUpper}\label{wxstringmakeupper}
 284
 285 \func{void}{MakeUpper}{\void}
 286
 287 Converts all characters to upper case.
 288
 289 \membersection{wxString::Matches}\label{wxstringMatches}
 290
 291 \constfunc{bool}{Matches}{\param{const char*}{ szMask}}
 292
 293 Returns TRUE if the string contents matches a mask containing '*' and '?'.
 294
 295 \membersection{wxString::Mid}\label{wxstringmid}
 296
 297 \constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = STRING\_MAXLEN}}
 298
 299 Returns a substring starting at {\it first}, with length {\it count}, or the rest of
 300 the string if {\it count} is the default value.
 301
 302 \membersection{wxString::Pad}\label{wxstringpad}
 303
 304 \func{wxString\&}{Pad}{\param{size\_t}{ count}, \param{char}{ pad = ' '}, \param{bool}{ fromRight = TRUE}}
 305
 306 Adds {\it count} copies of {\it pad} to the beginning, or to the end of the string (the default).
 307
 308 Removes spaces from the left or from the right (default).
 309
 310 \membersection{wxString::Prepend}\label{wxstringPrepend}
 311
 312 \func{wxString\&}{Prepend}{\param{const wxString\&}{ str}}
 313
 314 Prepends {\it str} to this string, returning a reference to this string.
 315
 316 \membersection{wxString::Printf}\label{wxstringprintf}
 317
 318 \func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}}
 319
 320 Similar to sprintf. Returns the number of characters written, or an integer less than zero
 321 on error.
 322
 323 \membersection{wxString::PrintfV}\label{wxstringprintfv}
 324
 325 \func{int}{PrintfV}{\param{const char* }{pszFormat}, \param{va\_list}{ argPtr}}
 326
 327 Similar to vprintf. Returns the number of characters written, or an integer less than zero
 328 on error.
 329
 330 \membersection{wxString::Remove}\label{wxstringRemove}
 331
 332 \func{wxString\&}{Remove}{\param{size\_t}{ pos}}
 333
 334 Same as Truncate. Removes the portion from {\it pos} to the end of the string.
 335
 336 \func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
 337
 338 Removes the last {\it len} characters from the string, starting at {\it pos}.
 339
 340 \membersection{wxString::RemoveLast}\label{wxstringremovelast}
 341
 342 \func{wxString\&}{RemoveLast}{\void}
 343
 344 Removes the last character.
 345
 346 \membersection{wxString::Replace}\label{wxstringReplace}
 347
 348 \func{uint}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll}}
 349
 350 Replace first (or all) occurences of substring with another one.
 351
 352 {\it replaceAll}: global replace (default), or only the first occurence.
 353
 354 Returns the number of replacements made.
 355
 356 \membersection{wxString::Right}\label{wxstringright}
 357
 358 \constfunc{wxString}{Right}{\param{size\_t}{ count}}
 359
 360 Returns the last {\it count} characters.
 361
 362 \constfunc{wxString}{Right}{\param{char}{ ch}}
 363
 364 Returns all characters after the last occurence of {\it ch}.
 365 Returns the whole string if {\it ch} is not found.
 366
 367 \membersection{wxString::SetChar}\label{wxstringsetchar}
 368
 369 \func{void}{SetChar}{\param{size\_t}{ n}, \param{char}{ch}}
 370
 371 Sets the character at position {\it n}.
 372
 373 \membersection{wxString::Shrink}\label{wxstringshrink}
 374
 375 \func{void}{Shrink}{\void}
 376
 377 Minimizes the string's memory. Only works if the data of this string is not shared.
 378
 379 \membersection{wxString::sprintf}\label{wxstringsprintf}
 380
 381 \func{void}{sprintf}{\param{const char* }{ fmt}}
 382
 383 The same as Printf.
 384
 385 \membersection{wxString::Strip}\label{wxstringStrip}
 386
 387 \begin{verbatim}
 388 enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
 389 \end{verbatim}
 390
 391 \constfunc{wxString}{Strip}{\param{stripType}{ s = trailing}}
 392
 393 Strip characters at the front and/or end. The same as Trim except that it
 394 doesn't change this string.
 395
 396 \membersection{wxString::Trim}\label{wxstringtrim}
 397
 398 \func{wxString\&}{Trim}{\param{bool}{ fromRight = TRUE}}
 399
 400 Removes spaces from the left or from the right (default).
 401
 402 \membersection{wxString::Truncate}\label{wxstringtruncate}
 403
 404 \func{wxString\&}{Truncate}{\param{size\_t}{ len}}
 405
 406 Truncate the string to the given length.
 407
 408 \membersection{wxString::UngetWriteBuf}\label{wxstringungetwritebuf}
 409
 410 \func{void}{UngetWriteBuf}{\void}
 411
 412 Puts the string back into a reasonable state, after
 413 \rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called.
 414
 415 \membersection{wxString::UpperCase}\label{wxstringUpperCase}
 416
 417 \func{void}{UpperCase}{\void}
 418
 419 The same as MakeUpper.
 420
 421 \membersection{wxString::operator $=$}\label{wxstringoperatorassign}
 422
 423 \func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}}
 424
 425 \func{wxString\&}{operator $=$}{\param{const char*}{ psz}}
 426
 427 \func{wxString\&}{operator $=$}{\param{char}{ c}}
 428
 429 \func{wxString\&}{operator $=$}{\param{const unsigned char*}{ psz}}
 430
 431 \func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}}
 432
 433 Assignment.
 434
 435 \membersection{wxString::operator $+=$}\label{wxstringPlusEqual}
 436
 437 \func{void}{operator $+=$}{\param{const wxString\&}{ str}}
 438
 439 \func{void}{operator $+=$}{\param{const char*}{ psz}}
 440
 441 \func{void}{operator $+=$}{\param{char}{ c}}
 442
 443 Concatenation.
 444
 445 \membersection{wxString::operator []}\label{wxstringoperatorbracket}
 446
 447 \func{char\&}{operator []}{\param{size\_t}{ i}}
 448
 449 \func{char}{operator []}{\param{size\_t}{ i}}
 450
 451 \func{char}{operator []}{\param{int}{ i}}
 452
 453 Element extraction.
 454
 455 \membersection{wxString::operator ()}\label{wxstringoperatorparenth}
 456
 457 \func{wxString}{operator ()}{\param{size\_t}{ start}, \param{size\_t}{ len}}
 458
 459 Same as Mid (substring extraction).
 460
 461 \membersection{wxString::operator \cinsert}\label{wxstringoperatorout}
 462
 463 \func{wxString\&}{operator \cinsert}{\\param{const wxString\&}{ str}}
 464
 465 \func{wxString\&}{operator \cinsert}{\\param{const char*}{ psz}}
 466
 467 \func{wxString\&}{operator \cinsert}{\\param{char }{ch}}
 468
 469 Same as $+=$.
 470
 471 \membersection{wxString::operator \cextract}\label{wxstringoperatorin}
 472
 473 \func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}}
 474
 475 Extraction from a stream.
 476
 477 \membersection{wxString::operator const char*}\label{wxstringoperatorconstcharpt}
 478
 479 \constfunc{}{operator const char*}{\void}
 480
 481 Implicit conversion to a C string.
 482
 483 \membersection{Comparison operators}\label{wxstringComparison}
 484
 485 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 486
 487 \func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 488
 489 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 490
 491 \func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 492
 493 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 494
 495 \func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 496
 497 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 498
 499 \func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 500
 501 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 502
 503 \func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 504
 505 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 506
 507 \func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
 508
 509 \wxheading{Remarks}
 510
 511 These comparisons are case-sensitive.
 512
 513 \membersection{operator $+$}\label{wxstringoperatorplus}
 514
 515 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 516
 517 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const char*}{ y}}
 518
 519 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{char}{ y}}
 520
 521 \func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}}
 522
 523