docs/latex/wx/wxstring.tex

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