1 /* 2 ********************************************************************** 3 * Copyright (C) 1998-2010, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 * 7 * File unistr.h 8 * 9 * Modification History: 10 * 11 * Date Name Description 12 * 09/25/98 stephen Creation. 13 * 11/11/98 stephen Changed per 11/9 code review. 14 * 04/20/99 stephen Overhauled per 4/16 code review. 15 * 11/18/99 aliu Made to inherit from Replaceable. Added method 16 * handleReplaceBetween(); other methods unchanged. 17 * 06/25/01 grhoten Remove dependency on iostream. 18 ****************************************************************************** 19 */ 20 21 #ifndef UNISTR_H 22 #define UNISTR_H 23 24 /** 25 * \file 26 * \brief C++ API: Unicode String 27 */ 28 29 #include "unicode/utypes.h" 30 #include "unicode/rep.h" 31 #include "unicode/std_string.h" 32 #include "unicode/stringpiece.h" 33 #include "unicode/bytestream.h" 34 35 struct UConverter; // unicode/ucnv.h 36 class StringThreadTest; 37 38 #ifndef U_COMPARE_CODE_POINT_ORDER 39 /* see also ustring.h and unorm.h */ 40 /** 41 * Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc: 42 * Compare strings in code point order instead of code unit order. 43 * @stable ICU 2.2 44 */ 45 #define U_COMPARE_CODE_POINT_ORDER 0x8000 46 #endif 47 48 #ifndef USTRING_H 49 /** 50 * \ingroup ustring_ustrlen 51 */ 52 U_STABLE int32_t U_EXPORT2 53 u_strlen(const UChar *s); 54 #endif 55 56 U_NAMESPACE_BEGIN 57 58 class Locale; // unicode/locid.h 59 class StringCharacterIterator; 60 class BreakIterator; // unicode/brkiter.h 61 62 /* The <iostream> include has been moved to unicode/ustream.h */ 63 64 /** 65 * Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor 66 * which constructs a Unicode string from an invariant-character char * string. 67 * About invariant characters see utypes.h. 68 * This constructor has no runtime dependency on conversion code and is 69 * therefore recommended over ones taking a charset name string 70 * (where the empty string "" indicates invariant-character conversion). 71 * 72 * @stable ICU 3.2 73 */ 74 #define US_INV U_NAMESPACE_QUALIFIER UnicodeString::kInvariant 75 76 /** 77 * Unicode String literals in C++. 78 * Dependent on the platform properties, different UnicodeString 79 * constructors should be used to create a UnicodeString object from 80 * a string literal. 81 * The macros are defined for maximum performance. 82 * They work only for strings that contain "invariant characters", i.e., 83 * only latin letters, digits, and some punctuation. 84 * See utypes.h for details. 85 * 86 * The string parameter must be a C string literal. 87 * The length of the string, not including the terminating 88 * <code>NUL</code>, must be specified as a constant. 89 * The U_STRING_DECL macro should be invoked exactly once for one 90 * such string variable before it is used. 91 * @stable ICU 2.0 92 */ 93 #if defined(U_DECLARE_UTF16) 94 # define UNICODE_STRING(cs, _length) U_NAMESPACE_QUALIFIER UnicodeString(TRUE, (const UChar *)U_DECLARE_UTF16(cs), _length) 95 #elif U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16))) 96 # define UNICODE_STRING(cs, _length) U_NAMESPACE_QUALIFIER UnicodeString(TRUE, (const UChar *)L ## cs, _length) 97 #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY 98 # define UNICODE_STRING(cs, _length) U_NAMESPACE_QUALIFIER UnicodeString(TRUE, (const UChar *)cs, _length) 99 #else 100 # define UNICODE_STRING(cs, _length) U_NAMESPACE_QUALIFIER UnicodeString(cs, _length, US_INV) 101 #endif 102 103 /** 104 * Unicode String literals in C++. 105 * Dependent on the platform properties, different UnicodeString 106 * constructors should be used to create a UnicodeString object from 107 * a string literal. 108 * The macros are defined for improved performance. 109 * They work only for strings that contain "invariant characters", i.e., 110 * only latin letters, digits, and some punctuation. 111 * See utypes.h for details. 112 * 113 * The string parameter must be a C string literal. 114 * @stable ICU 2.0 115 */ 116 #define UNICODE_STRING_SIMPLE(cs) UNICODE_STRING(cs, -1) 117 118 /** 119 * UnicodeString is a string class that stores Unicode characters directly and provides 120 * similar functionality as the Java String and StringBuffer classes. 121 * It is a concrete implementation of the abstract class Replaceable (for transliteration). 122 * 123 * The UnicodeString class is not suitable for subclassing. 124 * 125 * <p>For an overview of Unicode strings in C and C++ see the 126 * <a href="http://icu-project.org/userguide/strings.html">User Guide Strings chapter</a>.</p> 127 * 128 * <p>In ICU, a Unicode string consists of 16-bit Unicode <em>code units</em>. 129 * A Unicode character may be stored with either one code unit 130 * (the most common case) or with a matched pair of special code units 131 * ("surrogates"). The data type for code units is UChar. 132 * For single-character handling, a Unicode character code <em>point</em> is a value 133 * in the range 0..0x10ffff. ICU uses the UChar32 type for code points.</p> 134 * 135 * <p>Indexes and offsets into and lengths of strings always count code units, not code points. 136 * This is the same as with multi-byte char* strings in traditional string handling. 137 * Operations on partial strings typically do not test for code point boundaries. 138 * If necessary, the user needs to take care of such boundaries by testing for the code unit 139 * values or by using functions like 140 * UnicodeString::getChar32Start() and UnicodeString::getChar32Limit() 141 * (or, in C, the equivalent macros U16_SET_CP_START() and U16_SET_CP_LIMIT(), see utf.h).</p> 142 * 143 * UnicodeString methods are more lenient with regard to input parameter values 144 * than other ICU APIs. In particular: 145 * - If indexes are out of bounds for a UnicodeString object 146 * (<0 or >length()) then they are "pinned" to the nearest boundary. 147 * - If primitive string pointer values (e.g., const UChar * or char *) 148 * for input strings are NULL, then those input string parameters are treated 149 * as if they pointed to an empty string. 150 * However, this is <em>not</em> the case for char * parameters for charset names 151 * or other IDs. 152 * - Most UnicodeString methods do not take a UErrorCode parameter because 153 * there are usually very few opportunities for failure other than a shortage 154 * of memory, error codes in low-level C++ string methods would be inconvenient, 155 * and the error code as the last parameter (ICU convention) would prevent 156 * the use of default parameter values. 157 * Instead, such methods set the UnicodeString into a "bogus" state 158 * (see isBogus()) if an error occurs. 159 * 160 * In string comparisons, two UnicodeString objects that are both "bogus" 161 * compare equal (to be transitive and prevent endless loops in sorting), 162 * and a "bogus" string compares less than any non-"bogus" one. 163 * 164 * Const UnicodeString methods are thread-safe. Multiple threads can use 165 * const methods on the same UnicodeString object simultaneously, 166 * but non-const methods must not be called concurrently (in multiple threads) 167 * with any other (const or non-const) methods. 168 * 169 * Similarly, const UnicodeString & parameters are thread-safe. 170 * One object may be passed in as such a parameter concurrently in multiple threads. 171 * This includes the const UnicodeString & parameters for 172 * copy construction, assignment, and cloning. 173 * 174 * <p>UnicodeString uses several storage methods. 175 * String contents can be stored inside the UnicodeString object itself, 176 * in an allocated and shared buffer, or in an outside buffer that is "aliased". 177 * Most of this is done transparently, but careful aliasing in particular provides 178 * significant performance improvements. 179 * Also, the internal buffer is accessible via special functions. 180 * For details see the 181 * <a href="http://icu-project.org/userguide/strings.html">User Guide Strings chapter</a>.</p> 182 * 183 * @see utf.h 184 * @see CharacterIterator 185 * @stable ICU 2.0 186 */ 187 class U_COMMON_API UnicodeString : public Replaceable 188 { 189 public: 190 191 /** 192 * Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor 193 * which constructs a Unicode string from an invariant-character char * string. 194 * Use the macro US_INV instead of the full qualification for this value. 195 * 196 * @see US_INV 197 * @stable ICU 3.2 198 */ 199 enum EInvariant { 200 /** 201 * @see EInvariant 202 * @stable ICU 3.2 203 */ 204 kInvariant 205 }; 206 207 //======================================== 208 // Read-only operations 209 //======================================== 210 211 /* Comparison - bitwise only - for international comparison use collation */ 212 213 /** 214 * Equality operator. Performs only bitwise comparison. 215 * @param text The UnicodeString to compare to this one. 216 * @return TRUE if <TT>text</TT> contains the same characters as this one, 217 * FALSE otherwise. 218 * @stable ICU 2.0 219 */ 220 inline UBool operator== (const UnicodeString& text) const; 221 222 /** 223 * Inequality operator. Performs only bitwise comparison. 224 * @param text The UnicodeString to compare to this one. 225 * @return FALSE if <TT>text</TT> contains the same characters as this one, 226 * TRUE otherwise. 227 * @stable ICU 2.0 228 */ 229 inline UBool operator!= (const UnicodeString& text) const; 230 231 /** 232 * Greater than operator. Performs only bitwise comparison. 233 * @param text The UnicodeString to compare to this one. 234 * @return TRUE if the characters in this are bitwise 235 * greater than the characters in <code>text</code>, FALSE otherwise 236 * @stable ICU 2.0 237 */ 238 inline UBool operator> (const UnicodeString& text) const; 239 240 /** 241 * Less than operator. Performs only bitwise comparison. 242 * @param text The UnicodeString to compare to this one. 243 * @return TRUE if the characters in this are bitwise 244 * less than the characters in <code>text</code>, FALSE otherwise 245 * @stable ICU 2.0 246 */ 247 inline UBool operator< (const UnicodeString& text) const; 248 249 /** 250 * Greater than or equal operator. Performs only bitwise comparison. 251 * @param text The UnicodeString to compare to this one. 252 * @return TRUE if the characters in this are bitwise 253 * greater than or equal to the characters in <code>text</code>, FALSE otherwise 254 * @stable ICU 2.0 255 */ 256 inline UBool operator>= (const UnicodeString& text) const; 257 258 /** 259 * Less than or equal operator. Performs only bitwise comparison. 260 * @param text The UnicodeString to compare to this one. 261 * @return TRUE if the characters in this are bitwise 262 * less than or equal to the characters in <code>text</code>, FALSE otherwise 263 * @stable ICU 2.0 264 */ 265 inline UBool operator<= (const UnicodeString& text) const; 266 267 /** 268 * Compare the characters bitwise in this UnicodeString to 269 * the characters in <code>text</code>. 270 * @param text The UnicodeString to compare to this one. 271 * @return The result of bitwise character comparison: 0 if this 272 * contains the same characters as <code>text</code>, -1 if the characters in 273 * this are bitwise less than the characters in <code>text</code>, +1 if the 274 * characters in this are bitwise greater than the characters 275 * in <code>text</code>. 276 * @stable ICU 2.0 277 */ 278 inline int8_t compare(const UnicodeString& text) const; 279 280 /** 281 * Compare the characters bitwise in the range 282 * [<TT>start</TT>, <TT>start + length</TT>) with the characters 283 * in <TT>text</TT> 284 * @param start the offset at which the compare operation begins 285 * @param length the number of characters of text to compare. 286 * @param text the other text to be compared against this string. 287 * @return The result of bitwise character comparison: 0 if this 288 * contains the same characters as <code>text</code>, -1 if the characters in 289 * this are bitwise less than the characters in <code>text</code>, +1 if the 290 * characters in this are bitwise greater than the characters 291 * in <code>text</code>. 292 * @stable ICU 2.0 293 */ 294 inline int8_t compare(int32_t start, 295 int32_t length, 296 const UnicodeString& text) const; 297 298 /** 299 * Compare the characters bitwise in the range 300 * [<TT>start</TT>, <TT>start + length</TT>) with the characters 301 * in <TT>srcText</TT> in the range 302 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 303 * @param start the offset at which the compare operation begins 304 * @param length the number of characters in this to compare. 305 * @param srcText the text to be compared 306 * @param srcStart the offset into <TT>srcText</TT> to start comparison 307 * @param srcLength the number of characters in <TT>src</TT> to compare 308 * @return The result of bitwise character comparison: 0 if this 309 * contains the same characters as <code>srcText</code>, -1 if the characters in 310 * this are bitwise less than the characters in <code>srcText</code>, +1 if the 311 * characters in this are bitwise greater than the characters 312 * in <code>srcText</code>. 313 * @stable ICU 2.0 314 */ 315 inline int8_t compare(int32_t start, 316 int32_t length, 317 const UnicodeString& srcText, 318 int32_t srcStart, 319 int32_t srcLength) const; 320 321 /** 322 * Compare the characters bitwise in this UnicodeString with the first 323 * <TT>srcLength</TT> characters in <TT>srcChars</TT>. 324 * @param srcChars The characters to compare to this UnicodeString. 325 * @param srcLength the number of characters in <TT>srcChars</TT> to compare 326 * @return The result of bitwise character comparison: 0 if this 327 * contains the same characters as <code>srcChars</code>, -1 if the characters in 328 * this are bitwise less than the characters in <code>srcChars</code>, +1 if the 329 * characters in this are bitwise greater than the characters 330 * in <code>srcChars</code>. 331 * @stable ICU 2.0 332 */ 333 inline int8_t compare(const UChar *srcChars, 334 int32_t srcLength) const; 335 336 /** 337 * Compare the characters bitwise in the range 338 * [<TT>start</TT>, <TT>start + length</TT>) with the first 339 * <TT>length</TT> characters in <TT>srcChars</TT> 340 * @param start the offset at which the compare operation begins 341 * @param length the number of characters to compare. 342 * @param srcChars the characters to be compared 343 * @return The result of bitwise character comparison: 0 if this 344 * contains the same characters as <code>srcChars</code>, -1 if the characters in 345 * this are bitwise less than the characters in <code>srcChars</code>, +1 if the 346 * characters in this are bitwise greater than the characters 347 * in <code>srcChars</code>. 348 * @stable ICU 2.0 349 */ 350 inline int8_t compare(int32_t start, 351 int32_t length, 352 const UChar *srcChars) const; 353 354 /** 355 * Compare the characters bitwise in the range 356 * [<TT>start</TT>, <TT>start + length</TT>) with the characters 357 * in <TT>srcChars</TT> in the range 358 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 359 * @param start the offset at which the compare operation begins 360 * @param length the number of characters in this to compare 361 * @param srcChars the characters to be compared 362 * @param srcStart the offset into <TT>srcChars</TT> to start comparison 363 * @param srcLength the number of characters in <TT>srcChars</TT> to compare 364 * @return The result of bitwise character comparison: 0 if this 365 * contains the same characters as <code>srcChars</code>, -1 if the characters in 366 * this are bitwise less than the characters in <code>srcChars</code>, +1 if the 367 * characters in this are bitwise greater than the characters 368 * in <code>srcChars</code>. 369 * @stable ICU 2.0 370 */ 371 inline int8_t compare(int32_t start, 372 int32_t length, 373 const UChar *srcChars, 374 int32_t srcStart, 375 int32_t srcLength) const; 376 377 /** 378 * Compare the characters bitwise in the range 379 * [<TT>start</TT>, <TT>limit</TT>) with the characters 380 * in <TT>srcText</TT> in the range 381 * [<TT>srcStart</TT>, <TT>srcLimit</TT>). 382 * @param start the offset at which the compare operation begins 383 * @param limit the offset immediately following the compare operation 384 * @param srcText the text to be compared 385 * @param srcStart the offset into <TT>srcText</TT> to start comparison 386 * @param srcLimit the offset into <TT>srcText</TT> to limit comparison 387 * @return The result of bitwise character comparison: 0 if this 388 * contains the same characters as <code>srcText</code>, -1 if the characters in 389 * this are bitwise less than the characters in <code>srcText</code>, +1 if the 390 * characters in this are bitwise greater than the characters 391 * in <code>srcText</code>. 392 * @stable ICU 2.0 393 */ 394 inline int8_t compareBetween(int32_t start, 395 int32_t limit, 396 const UnicodeString& srcText, 397 int32_t srcStart, 398 int32_t srcLimit) const; 399 400 /** 401 * Compare two Unicode strings in code point order. 402 * The result may be different from the results of compare(), operator<, etc. 403 * if supplementary characters are present: 404 * 405 * In UTF-16, supplementary characters (with code points U+10000 and above) are 406 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 407 * which means that they compare as less than some other BMP characters like U+feff. 408 * This function compares Unicode strings in code point order. 409 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 410 * 411 * @param text Another string to compare this one to. 412 * @return a negative/zero/positive integer corresponding to whether 413 * this string is less than/equal to/greater than the second one 414 * in code point order 415 * @stable ICU 2.0 416 */ 417 inline int8_t compareCodePointOrder(const UnicodeString& text) const; 418 419 /** 420 * Compare two Unicode strings in code point order. 421 * The result may be different from the results of compare(), operator<, etc. 422 * if supplementary characters are present: 423 * 424 * In UTF-16, supplementary characters (with code points U+10000 and above) are 425 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 426 * which means that they compare as less than some other BMP characters like U+feff. 427 * This function compares Unicode strings in code point order. 428 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 429 * 430 * @param start The start offset in this string at which the compare operation begins. 431 * @param length The number of code units from this string to compare. 432 * @param srcText Another string to compare this one to. 433 * @return a negative/zero/positive integer corresponding to whether 434 * this string is less than/equal to/greater than the second one 435 * in code point order 436 * @stable ICU 2.0 437 */ 438 inline int8_t compareCodePointOrder(int32_t start, 439 int32_t length, 440 const UnicodeString& srcText) const; 441 442 /** 443 * Compare two Unicode strings in code point order. 444 * The result may be different from the results of compare(), operator<, etc. 445 * if supplementary characters are present: 446 * 447 * In UTF-16, supplementary characters (with code points U+10000 and above) are 448 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 449 * which means that they compare as less than some other BMP characters like U+feff. 450 * This function compares Unicode strings in code point order. 451 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 452 * 453 * @param start The start offset in this string at which the compare operation begins. 454 * @param length The number of code units from this string to compare. 455 * @param srcText Another string to compare this one to. 456 * @param srcStart The start offset in that string at which the compare operation begins. 457 * @param srcLength The number of code units from that string to compare. 458 * @return a negative/zero/positive integer corresponding to whether 459 * this string is less than/equal to/greater than the second one 460 * in code point order 461 * @stable ICU 2.0 462 */ 463 inline int8_t compareCodePointOrder(int32_t start, 464 int32_t length, 465 const UnicodeString& srcText, 466 int32_t srcStart, 467 int32_t srcLength) const; 468 469 /** 470 * Compare two Unicode strings in code point order. 471 * The result may be different from the results of compare(), operator<, etc. 472 * if supplementary characters are present: 473 * 474 * In UTF-16, supplementary characters (with code points U+10000 and above) are 475 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 476 * which means that they compare as less than some other BMP characters like U+feff. 477 * This function compares Unicode strings in code point order. 478 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 479 * 480 * @param srcChars A pointer to another string to compare this one to. 481 * @param srcLength The number of code units from that string to compare. 482 * @return a negative/zero/positive integer corresponding to whether 483 * this string is less than/equal to/greater than the second one 484 * in code point order 485 * @stable ICU 2.0 486 */ 487 inline int8_t compareCodePointOrder(const UChar *srcChars, 488 int32_t srcLength) const; 489 490 /** 491 * Compare two Unicode strings in code point order. 492 * The result may be different from the results of compare(), operator<, etc. 493 * if supplementary characters are present: 494 * 495 * In UTF-16, supplementary characters (with code points U+10000 and above) are 496 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 497 * which means that they compare as less than some other BMP characters like U+feff. 498 * This function compares Unicode strings in code point order. 499 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 500 * 501 * @param start The start offset in this string at which the compare operation begins. 502 * @param length The number of code units from this string to compare. 503 * @param srcChars A pointer to another string to compare this one to. 504 * @return a negative/zero/positive integer corresponding to whether 505 * this string is less than/equal to/greater than the second one 506 * in code point order 507 * @stable ICU 2.0 508 */ 509 inline int8_t compareCodePointOrder(int32_t start, 510 int32_t length, 511 const UChar *srcChars) const; 512 513 /** 514 * Compare two Unicode strings in code point order. 515 * The result may be different from the results of compare(), operator<, etc. 516 * if supplementary characters are present: 517 * 518 * In UTF-16, supplementary characters (with code points U+10000 and above) are 519 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 520 * which means that they compare as less than some other BMP characters like U+feff. 521 * This function compares Unicode strings in code point order. 522 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 523 * 524 * @param start The start offset in this string at which the compare operation begins. 525 * @param length The number of code units from this string to compare. 526 * @param srcChars A pointer to another string to compare this one to. 527 * @param srcStart The start offset in that string at which the compare operation begins. 528 * @param srcLength The number of code units from that string to compare. 529 * @return a negative/zero/positive integer corresponding to whether 530 * this string is less than/equal to/greater than the second one 531 * in code point order 532 * @stable ICU 2.0 533 */ 534 inline int8_t compareCodePointOrder(int32_t start, 535 int32_t length, 536 const UChar *srcChars, 537 int32_t srcStart, 538 int32_t srcLength) const; 539 540 /** 541 * Compare two Unicode strings in code point order. 542 * The result may be different from the results of compare(), operator<, etc. 543 * if supplementary characters are present: 544 * 545 * In UTF-16, supplementary characters (with code points U+10000 and above) are 546 * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff, 547 * which means that they compare as less than some other BMP characters like U+feff. 548 * This function compares Unicode strings in code point order. 549 * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined. 550 * 551 * @param start The start offset in this string at which the compare operation begins. 552 * @param limit The offset after the last code unit from this string to compare. 553 * @param srcText Another string to compare this one to. 554 * @param srcStart The start offset in that string at which the compare operation begins. 555 * @param srcLimit The offset after the last code unit from that string to compare. 556 * @return a negative/zero/positive integer corresponding to whether 557 * this string is less than/equal to/greater than the second one 558 * in code point order 559 * @stable ICU 2.0 560 */ 561 inline int8_t compareCodePointOrderBetween(int32_t start, 562 int32_t limit, 563 const UnicodeString& srcText, 564 int32_t srcStart, 565 int32_t srcLimit) const; 566 567 /** 568 * Compare two strings case-insensitively using full case folding. 569 * This is equivalent to this->foldCase(options).compare(text.foldCase(options)). 570 * 571 * @param text Another string to compare this one to. 572 * @param options A bit set of options: 573 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 574 * Comparison in code unit order with default case folding. 575 * 576 * - U_COMPARE_CODE_POINT_ORDER 577 * Set to choose code point order instead of code unit order 578 * (see u_strCompare for details). 579 * 580 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 581 * 582 * @return A negative, zero, or positive integer indicating the comparison result. 583 * @stable ICU 2.0 584 */ 585 inline int8_t caseCompare(const UnicodeString& text, uint32_t options) const; 586 587 /** 588 * Compare two strings case-insensitively using full case folding. 589 * This is equivalent to this->foldCase(options).compare(srcText.foldCase(options)). 590 * 591 * @param start The start offset in this string at which the compare operation begins. 592 * @param length The number of code units from this string to compare. 593 * @param srcText Another string to compare this one to. 594 * @param options A bit set of options: 595 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 596 * Comparison in code unit order with default case folding. 597 * 598 * - U_COMPARE_CODE_POINT_ORDER 599 * Set to choose code point order instead of code unit order 600 * (see u_strCompare for details). 601 * 602 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 603 * 604 * @return A negative, zero, or positive integer indicating the comparison result. 605 * @stable ICU 2.0 606 */ 607 inline int8_t caseCompare(int32_t start, 608 int32_t length, 609 const UnicodeString& srcText, 610 uint32_t options) const; 611 612 /** 613 * Compare two strings case-insensitively using full case folding. 614 * This is equivalent to this->foldCase(options).compare(srcText.foldCase(options)). 615 * 616 * @param start The start offset in this string at which the compare operation begins. 617 * @param length The number of code units from this string to compare. 618 * @param srcText Another string to compare this one to. 619 * @param srcStart The start offset in that string at which the compare operation begins. 620 * @param srcLength The number of code units from that string to compare. 621 * @param options A bit set of options: 622 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 623 * Comparison in code unit order with default case folding. 624 * 625 * - U_COMPARE_CODE_POINT_ORDER 626 * Set to choose code point order instead of code unit order 627 * (see u_strCompare for details). 628 * 629 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 630 * 631 * @return A negative, zero, or positive integer indicating the comparison result. 632 * @stable ICU 2.0 633 */ 634 inline int8_t caseCompare(int32_t start, 635 int32_t length, 636 const UnicodeString& srcText, 637 int32_t srcStart, 638 int32_t srcLength, 639 uint32_t options) const; 640 641 /** 642 * Compare two strings case-insensitively using full case folding. 643 * This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)). 644 * 645 * @param srcChars A pointer to another string to compare this one to. 646 * @param srcLength The number of code units from that string to compare. 647 * @param options A bit set of options: 648 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 649 * Comparison in code unit order with default case folding. 650 * 651 * - U_COMPARE_CODE_POINT_ORDER 652 * Set to choose code point order instead of code unit order 653 * (see u_strCompare for details). 654 * 655 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 656 * 657 * @return A negative, zero, or positive integer indicating the comparison result. 658 * @stable ICU 2.0 659 */ 660 inline int8_t caseCompare(const UChar *srcChars, 661 int32_t srcLength, 662 uint32_t options) const; 663 664 /** 665 * Compare two strings case-insensitively using full case folding. 666 * This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)). 667 * 668 * @param start The start offset in this string at which the compare operation begins. 669 * @param length The number of code units from this string to compare. 670 * @param srcChars A pointer to another string to compare this one to. 671 * @param options A bit set of options: 672 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 673 * Comparison in code unit order with default case folding. 674 * 675 * - U_COMPARE_CODE_POINT_ORDER 676 * Set to choose code point order instead of code unit order 677 * (see u_strCompare for details). 678 * 679 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 680 * 681 * @return A negative, zero, or positive integer indicating the comparison result. 682 * @stable ICU 2.0 683 */ 684 inline int8_t caseCompare(int32_t start, 685 int32_t length, 686 const UChar *srcChars, 687 uint32_t options) const; 688 689 /** 690 * Compare two strings case-insensitively using full case folding. 691 * This is equivalent to this->foldCase(options).compare(srcChars.foldCase(options)). 692 * 693 * @param start The start offset in this string at which the compare operation begins. 694 * @param length The number of code units from this string to compare. 695 * @param srcChars A pointer to another string to compare this one to. 696 * @param srcStart The start offset in that string at which the compare operation begins. 697 * @param srcLength The number of code units from that string to compare. 698 * @param options A bit set of options: 699 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 700 * Comparison in code unit order with default case folding. 701 * 702 * - U_COMPARE_CODE_POINT_ORDER 703 * Set to choose code point order instead of code unit order 704 * (see u_strCompare for details). 705 * 706 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 707 * 708 * @return A negative, zero, or positive integer indicating the comparison result. 709 * @stable ICU 2.0 710 */ 711 inline int8_t caseCompare(int32_t start, 712 int32_t length, 713 const UChar *srcChars, 714 int32_t srcStart, 715 int32_t srcLength, 716 uint32_t options) const; 717 718 /** 719 * Compare two strings case-insensitively using full case folding. 720 * This is equivalent to this->foldCase(options).compareBetween(text.foldCase(options)). 721 * 722 * @param start The start offset in this string at which the compare operation begins. 723 * @param limit The offset after the last code unit from this string to compare. 724 * @param srcText Another string to compare this one to. 725 * @param srcStart The start offset in that string at which the compare operation begins. 726 * @param srcLimit The offset after the last code unit from that string to compare. 727 * @param options A bit set of options: 728 * - U_FOLD_CASE_DEFAULT or 0 is used for default options: 729 * Comparison in code unit order with default case folding. 730 * 731 * - U_COMPARE_CODE_POINT_ORDER 732 * Set to choose code point order instead of code unit order 733 * (see u_strCompare for details). 734 * 735 * - U_FOLD_CASE_EXCLUDE_SPECIAL_I 736 * 737 * @return A negative, zero, or positive integer indicating the comparison result. 738 * @stable ICU 2.0 739 */ 740 inline int8_t caseCompareBetween(int32_t start, 741 int32_t limit, 742 const UnicodeString& srcText, 743 int32_t srcStart, 744 int32_t srcLimit, 745 uint32_t options) const; 746 747 /** 748 * Determine if this starts with the characters in <TT>text</TT> 749 * @param text The text to match. 750 * @return TRUE if this starts with the characters in <TT>text</TT>, 751 * FALSE otherwise 752 * @stable ICU 2.0 753 */ 754 inline UBool startsWith(const UnicodeString& text) const; 755 756 /** 757 * Determine if this starts with the characters in <TT>srcText</TT> 758 * in the range [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 759 * @param srcText The text to match. 760 * @param srcStart the offset into <TT>srcText</TT> to start matching 761 * @param srcLength the number of characters in <TT>srcText</TT> to match 762 * @return TRUE if this starts with the characters in <TT>text</TT>, 763 * FALSE otherwise 764 * @stable ICU 2.0 765 */ 766 inline UBool startsWith(const UnicodeString& srcText, 767 int32_t srcStart, 768 int32_t srcLength) const; 769 770 /** 771 * Determine if this starts with the characters in <TT>srcChars</TT> 772 * @param srcChars The characters to match. 773 * @param srcLength the number of characters in <TT>srcChars</TT> 774 * @return TRUE if this starts with the characters in <TT>srcChars</TT>, 775 * FALSE otherwise 776 * @stable ICU 2.0 777 */ 778 inline UBool startsWith(const UChar *srcChars, 779 int32_t srcLength) const; 780 781 /** 782 * Determine if this ends with the characters in <TT>srcChars</TT> 783 * in the range [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 784 * @param srcChars The characters to match. 785 * @param srcStart the offset into <TT>srcText</TT> to start matching 786 * @param srcLength the number of characters in <TT>srcChars</TT> to match 787 * @return TRUE if this ends with the characters in <TT>srcChars</TT>, FALSE otherwise 788 * @stable ICU 2.0 789 */ 790 inline UBool startsWith(const UChar *srcChars, 791 int32_t srcStart, 792 int32_t srcLength) const; 793 794 /** 795 * Determine if this ends with the characters in <TT>text</TT> 796 * @param text The text to match. 797 * @return TRUE if this ends with the characters in <TT>text</TT>, 798 * FALSE otherwise 799 * @stable ICU 2.0 800 */ 801 inline UBool endsWith(const UnicodeString& text) const; 802 803 /** 804 * Determine if this ends with the characters in <TT>srcText</TT> 805 * in the range [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 806 * @param srcText The text to match. 807 * @param srcStart the offset into <TT>srcText</TT> to start matching 808 * @param srcLength the number of characters in <TT>srcText</TT> to match 809 * @return TRUE if this ends with the characters in <TT>text</TT>, 810 * FALSE otherwise 811 * @stable ICU 2.0 812 */ 813 inline UBool endsWith(const UnicodeString& srcText, 814 int32_t srcStart, 815 int32_t srcLength) const; 816 817 /** 818 * Determine if this ends with the characters in <TT>srcChars</TT> 819 * @param srcChars The characters to match. 820 * @param srcLength the number of characters in <TT>srcChars</TT> 821 * @return TRUE if this ends with the characters in <TT>srcChars</TT>, 822 * FALSE otherwise 823 * @stable ICU 2.0 824 */ 825 inline UBool endsWith(const UChar *srcChars, 826 int32_t srcLength) const; 827 828 /** 829 * Determine if this ends with the characters in <TT>srcChars</TT> 830 * in the range [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 831 * @param srcChars The characters to match. 832 * @param srcStart the offset into <TT>srcText</TT> to start matching 833 * @param srcLength the number of characters in <TT>srcChars</TT> to match 834 * @return TRUE if this ends with the characters in <TT>srcChars</TT>, 835 * FALSE otherwise 836 * @stable ICU 2.0 837 */ 838 inline UBool endsWith(const UChar *srcChars, 839 int32_t srcStart, 840 int32_t srcLength) const; 841 842 843 /* Searching - bitwise only */ 844 845 /** 846 * Locate in this the first occurrence of the characters in <TT>text</TT>, 847 * using bitwise comparison. 848 * @param text The text to search for. 849 * @return The offset into this of the start of <TT>text</TT>, 850 * or -1 if not found. 851 * @stable ICU 2.0 852 */ 853 inline int32_t indexOf(const UnicodeString& text) const; 854 855 /** 856 * Locate in this the first occurrence of the characters in <TT>text</TT> 857 * starting at offset <TT>start</TT>, using bitwise comparison. 858 * @param text The text to search for. 859 * @param start The offset at which searching will start. 860 * @return The offset into this of the start of <TT>text</TT>, 861 * or -1 if not found. 862 * @stable ICU 2.0 863 */ 864 inline int32_t indexOf(const UnicodeString& text, 865 int32_t start) const; 866 867 /** 868 * Locate in this the first occurrence in the range 869 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 870 * in <TT>text</TT>, using bitwise comparison. 871 * @param text The text to search for. 872 * @param start The offset at which searching will start. 873 * @param length The number of characters to search 874 * @return The offset into this of the start of <TT>text</TT>, 875 * or -1 if not found. 876 * @stable ICU 2.0 877 */ 878 inline int32_t indexOf(const UnicodeString& text, 879 int32_t start, 880 int32_t length) const; 881 882 /** 883 * Locate in this the first occurrence in the range 884 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 885 * in <TT>srcText</TT> in the range 886 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>), 887 * using bitwise comparison. 888 * @param srcText The text to search for. 889 * @param srcStart the offset into <TT>srcText</TT> at which 890 * to start matching 891 * @param srcLength the number of characters in <TT>srcText</TT> to match 892 * @param start the offset into this at which to start matching 893 * @param length the number of characters in this to search 894 * @return The offset into this of the start of <TT>text</TT>, 895 * or -1 if not found. 896 * @stable ICU 2.0 897 */ 898 inline int32_t indexOf(const UnicodeString& srcText, 899 int32_t srcStart, 900 int32_t srcLength, 901 int32_t start, 902 int32_t length) const; 903 904 /** 905 * Locate in this the first occurrence of the characters in 906 * <TT>srcChars</TT> 907 * starting at offset <TT>start</TT>, using bitwise comparison. 908 * @param srcChars The text to search for. 909 * @param srcLength the number of characters in <TT>srcChars</TT> to match 910 * @param start the offset into this at which to start matching 911 * @return The offset into this of the start of <TT>text</TT>, 912 * or -1 if not found. 913 * @stable ICU 2.0 914 */ 915 inline int32_t indexOf(const UChar *srcChars, 916 int32_t srcLength, 917 int32_t start) const; 918 919 /** 920 * Locate in this the first occurrence in the range 921 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 922 * in <TT>srcChars</TT>, using bitwise comparison. 923 * @param srcChars The text to search for. 924 * @param srcLength the number of characters in <TT>srcChars</TT> 925 * @param start The offset at which searching will start. 926 * @param length The number of characters to search 927 * @return The offset into this of the start of <TT>srcChars</TT>, 928 * or -1 if not found. 929 * @stable ICU 2.0 930 */ 931 inline int32_t indexOf(const UChar *srcChars, 932 int32_t srcLength, 933 int32_t start, 934 int32_t length) const; 935 936 /** 937 * Locate in this the first occurrence in the range 938 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 939 * in <TT>srcChars</TT> in the range 940 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>), 941 * using bitwise comparison. 942 * @param srcChars The text to search for. 943 * @param srcStart the offset into <TT>srcChars</TT> at which 944 * to start matching 945 * @param srcLength the number of characters in <TT>srcChars</TT> to match 946 * @param start the offset into this at which to start matching 947 * @param length the number of characters in this to search 948 * @return The offset into this of the start of <TT>text</TT>, 949 * or -1 if not found. 950 * @stable ICU 2.0 951 */ 952 int32_t indexOf(const UChar *srcChars, 953 int32_t srcStart, 954 int32_t srcLength, 955 int32_t start, 956 int32_t length) const; 957 958 /** 959 * Locate in this the first occurrence of the BMP code point <code>c</code>, 960 * using bitwise comparison. 961 * @param c The code unit to search for. 962 * @return The offset into this of <TT>c</TT>, or -1 if not found. 963 * @stable ICU 2.0 964 */ 965 inline int32_t indexOf(UChar c) const; 966 967 /** 968 * Locate in this the first occurrence of the code point <TT>c</TT>, 969 * using bitwise comparison. 970 * 971 * @param c The code point to search for. 972 * @return The offset into this of <TT>c</TT>, or -1 if not found. 973 * @stable ICU 2.0 974 */ 975 inline int32_t indexOf(UChar32 c) const; 976 977 /** 978 * Locate in this the first occurrence of the BMP code point <code>c</code>, 979 * starting at offset <TT>start</TT>, using bitwise comparison. 980 * @param c The code unit to search for. 981 * @param start The offset at which searching will start. 982 * @return The offset into this of <TT>c</TT>, or -1 if not found. 983 * @stable ICU 2.0 984 */ 985 inline int32_t indexOf(UChar c, 986 int32_t start) const; 987 988 /** 989 * Locate in this the first occurrence of the code point <TT>c</TT> 990 * starting at offset <TT>start</TT>, using bitwise comparison. 991 * 992 * @param c The code point to search for. 993 * @param start The offset at which searching will start. 994 * @return The offset into this of <TT>c</TT>, or -1 if not found. 995 * @stable ICU 2.0 996 */ 997 inline int32_t indexOf(UChar32 c, 998 int32_t start) const; 999 1000 /** 1001 * Locate in this the first occurrence of the BMP code point <code>c</code> 1002 * in the range [<TT>start</TT>, <TT>start + length</TT>), 1003 * using bitwise comparison. 1004 * @param c The code unit to search for. 1005 * @param start the offset into this at which to start matching 1006 * @param length the number of characters in this to search 1007 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1008 * @stable ICU 2.0 1009 */ 1010 inline int32_t indexOf(UChar c, 1011 int32_t start, 1012 int32_t length) const; 1013 1014 /** 1015 * Locate in this the first occurrence of the code point <TT>c</TT> 1016 * in the range [<TT>start</TT>, <TT>start + length</TT>), 1017 * using bitwise comparison. 1018 * 1019 * @param c The code point to search for. 1020 * @param start the offset into this at which to start matching 1021 * @param length the number of characters in this to search 1022 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1023 * @stable ICU 2.0 1024 */ 1025 inline int32_t indexOf(UChar32 c, 1026 int32_t start, 1027 int32_t length) const; 1028 1029 /** 1030 * Locate in this the last occurrence of the characters in <TT>text</TT>, 1031 * using bitwise comparison. 1032 * @param text The text to search for. 1033 * @return The offset into this of the start of <TT>text</TT>, 1034 * or -1 if not found. 1035 * @stable ICU 2.0 1036 */ 1037 inline int32_t lastIndexOf(const UnicodeString& text) const; 1038 1039 /** 1040 * Locate in this the last occurrence of the characters in <TT>text</TT> 1041 * starting at offset <TT>start</TT>, using bitwise comparison. 1042 * @param text The text to search for. 1043 * @param start The offset at which searching will start. 1044 * @return The offset into this of the start of <TT>text</TT>, 1045 * or -1 if not found. 1046 * @stable ICU 2.0 1047 */ 1048 inline int32_t lastIndexOf(const UnicodeString& text, 1049 int32_t start) const; 1050 1051 /** 1052 * Locate in this the last occurrence in the range 1053 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 1054 * in <TT>text</TT>, using bitwise comparison. 1055 * @param text The text to search for. 1056 * @param start The offset at which searching will start. 1057 * @param length The number of characters to search 1058 * @return The offset into this of the start of <TT>text</TT>, 1059 * or -1 if not found. 1060 * @stable ICU 2.0 1061 */ 1062 inline int32_t lastIndexOf(const UnicodeString& text, 1063 int32_t start, 1064 int32_t length) const; 1065 1066 /** 1067 * Locate in this the last occurrence in the range 1068 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 1069 * in <TT>srcText</TT> in the range 1070 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>), 1071 * using bitwise comparison. 1072 * @param srcText The text to search for. 1073 * @param srcStart the offset into <TT>srcText</TT> at which 1074 * to start matching 1075 * @param srcLength the number of characters in <TT>srcText</TT> to match 1076 * @param start the offset into this at which to start matching 1077 * @param length the number of characters in this to search 1078 * @return The offset into this of the start of <TT>text</TT>, 1079 * or -1 if not found. 1080 * @stable ICU 2.0 1081 */ 1082 inline int32_t lastIndexOf(const UnicodeString& srcText, 1083 int32_t srcStart, 1084 int32_t srcLength, 1085 int32_t start, 1086 int32_t length) const; 1087 1088 /** 1089 * Locate in this the last occurrence of the characters in <TT>srcChars</TT> 1090 * starting at offset <TT>start</TT>, using bitwise comparison. 1091 * @param srcChars The text to search for. 1092 * @param srcLength the number of characters in <TT>srcChars</TT> to match 1093 * @param start the offset into this at which to start matching 1094 * @return The offset into this of the start of <TT>text</TT>, 1095 * or -1 if not found. 1096 * @stable ICU 2.0 1097 */ 1098 inline int32_t lastIndexOf(const UChar *srcChars, 1099 int32_t srcLength, 1100 int32_t start) const; 1101 1102 /** 1103 * Locate in this the last occurrence in the range 1104 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 1105 * in <TT>srcChars</TT>, using bitwise comparison. 1106 * @param srcChars The text to search for. 1107 * @param srcLength the number of characters in <TT>srcChars</TT> 1108 * @param start The offset at which searching will start. 1109 * @param length The number of characters to search 1110 * @return The offset into this of the start of <TT>srcChars</TT>, 1111 * or -1 if not found. 1112 * @stable ICU 2.0 1113 */ 1114 inline int32_t lastIndexOf(const UChar *srcChars, 1115 int32_t srcLength, 1116 int32_t start, 1117 int32_t length) const; 1118 1119 /** 1120 * Locate in this the last occurrence in the range 1121 * [<TT>start</TT>, <TT>start + length</TT>) of the characters 1122 * in <TT>srcChars</TT> in the range 1123 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>), 1124 * using bitwise comparison. 1125 * @param srcChars The text to search for. 1126 * @param srcStart the offset into <TT>srcChars</TT> at which 1127 * to start matching 1128 * @param srcLength the number of characters in <TT>srcChars</TT> to match 1129 * @param start the offset into this at which to start matching 1130 * @param length the number of characters in this to search 1131 * @return The offset into this of the start of <TT>text</TT>, 1132 * or -1 if not found. 1133 * @stable ICU 2.0 1134 */ 1135 int32_t lastIndexOf(const UChar *srcChars, 1136 int32_t srcStart, 1137 int32_t srcLength, 1138 int32_t start, 1139 int32_t length) const; 1140 1141 /** 1142 * Locate in this the last occurrence of the BMP code point <code>c</code>, 1143 * using bitwise comparison. 1144 * @param c The code unit to search for. 1145 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1146 * @stable ICU 2.0 1147 */ 1148 inline int32_t lastIndexOf(UChar c) const; 1149 1150 /** 1151 * Locate in this the last occurrence of the code point <TT>c</TT>, 1152 * using bitwise comparison. 1153 * 1154 * @param c The code point to search for. 1155 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1156 * @stable ICU 2.0 1157 */ 1158 inline int32_t lastIndexOf(UChar32 c) const; 1159 1160 /** 1161 * Locate in this the last occurrence of the BMP code point <code>c</code> 1162 * starting at offset <TT>start</TT>, using bitwise comparison. 1163 * @param c The code unit to search for. 1164 * @param start The offset at which searching will start. 1165 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1166 * @stable ICU 2.0 1167 */ 1168 inline int32_t lastIndexOf(UChar c, 1169 int32_t start) const; 1170 1171 /** 1172 * Locate in this the last occurrence of the code point <TT>c</TT> 1173 * starting at offset <TT>start</TT>, using bitwise comparison. 1174 * 1175 * @param c The code point to search for. 1176 * @param start The offset at which searching will start. 1177 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1178 * @stable ICU 2.0 1179 */ 1180 inline int32_t lastIndexOf(UChar32 c, 1181 int32_t start) const; 1182 1183 /** 1184 * Locate in this the last occurrence of the BMP code point <code>c</code> 1185 * in the range [<TT>start</TT>, <TT>start + length</TT>), 1186 * using bitwise comparison. 1187 * @param c The code unit to search for. 1188 * @param start the offset into this at which to start matching 1189 * @param length the number of characters in this to search 1190 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1191 * @stable ICU 2.0 1192 */ 1193 inline int32_t lastIndexOf(UChar c, 1194 int32_t start, 1195 int32_t length) const; 1196 1197 /** 1198 * Locate in this the last occurrence of the code point <TT>c</TT> 1199 * in the range [<TT>start</TT>, <TT>start + length</TT>), 1200 * using bitwise comparison. 1201 * 1202 * @param c The code point to search for. 1203 * @param start the offset into this at which to start matching 1204 * @param length the number of characters in this to search 1205 * @return The offset into this of <TT>c</TT>, or -1 if not found. 1206 * @stable ICU 2.0 1207 */ 1208 inline int32_t lastIndexOf(UChar32 c, 1209 int32_t start, 1210 int32_t length) const; 1211 1212 1213 /* Character access */ 1214 1215 /** 1216 * Return the code unit at offset <tt>offset</tt>. 1217 * If the offset is not valid (0..length()-1) then U+ffff is returned. 1218 * @param offset a valid offset into the text 1219 * @return the code unit at offset <tt>offset</tt> 1220 * or 0xffff if the offset is not valid for this string 1221 * @stable ICU 2.0 1222 */ 1223 inline UChar charAt(int32_t offset) const; 1224 1225 /** 1226 * Return the code unit at offset <tt>offset</tt>. 1227 * If the offset is not valid (0..length()-1) then U+ffff is returned. 1228 * @param offset a valid offset into the text 1229 * @return the code unit at offset <tt>offset</tt> 1230 * @stable ICU 2.0 1231 */ 1232 inline UChar operator[] (int32_t offset) const; 1233 1234 /** 1235 * Return the code point that contains the code unit 1236 * at offset <tt>offset</tt>. 1237 * If the offset is not valid (0..length()-1) then U+ffff is returned. 1238 * @param offset a valid offset into the text 1239 * that indicates the text offset of any of the code units 1240 * that will be assembled into a code point (21-bit value) and returned 1241 * @return the code point of text at <tt>offset</tt> 1242 * or 0xffff if the offset is not valid for this string 1243 * @stable ICU 2.0 1244 */ 1245 inline UChar32 char32At(int32_t offset) const; 1246 1247 /** 1248 * Adjust a random-access offset so that 1249 * it points to the beginning of a Unicode character. 1250 * The offset that is passed in points to 1251 * any code unit of a code point, 1252 * while the returned offset will point to the first code unit 1253 * of the same code point. 1254 * In UTF-16, if the input offset points to a second surrogate 1255 * of a surrogate pair, then the returned offset will point 1256 * to the first surrogate. 1257 * @param offset a valid offset into one code point of the text 1258 * @return offset of the first code unit of the same code point 1259 * @see U16_SET_CP_START 1260 * @stable ICU 2.0 1261 */ 1262 inline int32_t getChar32Start(int32_t offset) const; 1263 1264 /** 1265 * Adjust a random-access offset so that 1266 * it points behind a Unicode character. 1267 * The offset that is passed in points behind 1268 * any code unit of a code point, 1269 * while the returned offset will point behind the last code unit 1270 * of the same code point. 1271 * In UTF-16, if the input offset points behind the first surrogate 1272 * (i.e., to the second surrogate) 1273 * of a surrogate pair, then the returned offset will point 1274 * behind the second surrogate (i.e., to the first surrogate). 1275 * @param offset a valid offset after any code unit of a code point of the text 1276 * @return offset of the first code unit after the same code point 1277 * @see U16_SET_CP_LIMIT 1278 * @stable ICU 2.0 1279 */ 1280 inline int32_t getChar32Limit(int32_t offset) const; 1281 1282 /** 1283 * Move the code unit index along the string by delta code points. 1284 * Interpret the input index as a code unit-based offset into the string, 1285 * move the index forward or backward by delta code points, and 1286 * return the resulting index. 1287 * The input index should point to the first code unit of a code point, 1288 * if there is more than one. 1289 * 1290 * Both input and output indexes are code unit-based as for all 1291 * string indexes/offsets in ICU (and other libraries, like MBCS char*). 1292 * If delta<0 then the index is moved backward (toward the start of the string). 1293 * If delta>0 then the index is moved forward (toward the end of the string). 1294 * 1295 * This behaves like CharacterIterator::move32(delta, kCurrent). 1296 * 1297 * Behavior for out-of-bounds indexes: 1298 * <code>moveIndex32</code> pins the input index to 0..length(), i.e., 1299 * if the input index<0 then it is pinned to 0; 1300 * if it is index>length() then it is pinned to length(). 1301 * Afterwards, the index is moved by <code>delta</code> code points 1302 * forward or backward, 1303 * but no further backward than to 0 and no further forward than to length(). 1304 * The resulting index return value will be in between 0 and length(), inclusively. 1305 * 1306 * Examples: 1307 * <pre> 1308 * // s has code points 'a' U+10000 'b' U+10ffff U+2029 1309 * UnicodeString s=UNICODE_STRING("a\\U00010000b\\U0010ffff\\u2029", 31).unescape(); 1310 * 1311 * // initial index: position of U+10000 1312 * int32_t index=1; 1313 * 1314 * // the following examples will all result in index==4, position of U+10ffff 1315 * 1316 * // skip 2 code points from some position in the string 1317 * index=s.moveIndex32(index, 2); // skips U+10000 and 'b' 1318 * 1319 * // go to the 3rd code point from the start of s (0-based) 1320 * index=s.moveIndex32(0, 3); // skips 'a', U+10000, and 'b' 1321 * 1322 * // go to the next-to-last code point of s 1323 * index=s.moveIndex32(s.length(), -2); // backward-skips U+2029 and U+10ffff 1324 * </pre> 1325 * 1326 * @param index input code unit index 1327 * @param delta (signed) code point count to move the index forward or backward 1328 * in the string 1329 * @return the resulting code unit index 1330 * @stable ICU 2.0 1331 */ 1332 int32_t moveIndex32(int32_t index, int32_t delta) const; 1333 1334 /* Substring extraction */ 1335 1336 /** 1337 * Copy the characters in the range 1338 * [<tt>start</tt>, <tt>start + length</tt>) into the array <tt>dst</tt>, 1339 * beginning at <tt>dstStart</tt>. 1340 * If the string aliases to <code>dst</code> itself as an external buffer, 1341 * then extract() will not copy the contents. 1342 * 1343 * @param start offset of first character which will be copied into the array 1344 * @param length the number of characters to extract 1345 * @param dst array in which to copy characters. The length of <tt>dst</tt> 1346 * must be at least (<tt>dstStart + length</tt>). 1347 * @param dstStart the offset in <TT>dst</TT> where the first character 1348 * will be extracted 1349 * @stable ICU 2.0 1350 */ 1351 inline void extract(int32_t start, 1352 int32_t length, 1353 UChar *dst, 1354 int32_t dstStart = 0) const; 1355 1356 /** 1357 * Copy the contents of the string into dest. 1358 * This is a convenience function that 1359 * checks if there is enough space in dest, 1360 * extracts the entire string if possible, 1361 * and NUL-terminates dest if possible. 1362 * 1363 * If the string fits into dest but cannot be NUL-terminated 1364 * (length()==destCapacity) then the error code is set to U_STRING_NOT_TERMINATED_WARNING. 1365 * If the string itself does not fit into dest 1366 * (length()>destCapacity) then the error code is set to U_BUFFER_OVERFLOW_ERROR. 1367 * 1368 * If the string aliases to <code>dest</code> itself as an external buffer, 1369 * then extract() will not copy the contents. 1370 * 1371 * @param dest Destination string buffer. 1372 * @param destCapacity Number of UChars available at dest. 1373 * @param errorCode ICU error code. 1374 * @return length() 1375 * @stable ICU 2.0 1376 */ 1377 int32_t 1378 extract(UChar *dest, int32_t destCapacity, 1379 UErrorCode &errorCode) const; 1380 1381 /** 1382 * Copy the characters in the range 1383 * [<tt>start</tt>, <tt>start + length</tt>) into the UnicodeString 1384 * <tt>target</tt>. 1385 * @param start offset of first character which will be copied 1386 * @param length the number of characters to extract 1387 * @param target UnicodeString into which to copy characters. 1388 * @return A reference to <TT>target</TT> 1389 * @stable ICU 2.0 1390 */ 1391 inline void extract(int32_t start, 1392 int32_t length, 1393 UnicodeString& target) const; 1394 1395 /** 1396 * Copy the characters in the range [<tt>start</tt>, <tt>limit</tt>) 1397 * into the array <tt>dst</tt>, beginning at <tt>dstStart</tt>. 1398 * @param start offset of first character which will be copied into the array 1399 * @param limit offset immediately following the last character to be copied 1400 * @param dst array in which to copy characters. The length of <tt>dst</tt> 1401 * must be at least (<tt>dstStart + (limit - start)</tt>). 1402 * @param dstStart the offset in <TT>dst</TT> where the first character 1403 * will be extracted 1404 * @stable ICU 2.0 1405 */ 1406 inline void extractBetween(int32_t start, 1407 int32_t limit, 1408 UChar *dst, 1409 int32_t dstStart = 0) const; 1410 1411 /** 1412 * Copy the characters in the range [<tt>start</tt>, <tt>limit</tt>) 1413 * into the UnicodeString <tt>target</tt>. Replaceable API. 1414 * @param start offset of first character which will be copied 1415 * @param limit offset immediately following the last character to be copied 1416 * @param target UnicodeString into which to copy characters. 1417 * @return A reference to <TT>target</TT> 1418 * @stable ICU 2.0 1419 */ 1420 virtual void extractBetween(int32_t start, 1421 int32_t limit, 1422 UnicodeString& target) const; 1423 1424 /** 1425 * Copy the characters in the range 1426 * [<tt>start</TT>, <tt>start + length</TT>) into an array of characters. 1427 * All characters must be invariant (see utypes.h). 1428 * Use US_INV as the last, signature-distinguishing parameter. 1429 * 1430 * This function does not write any more than <code>targetLength</code> 1431 * characters but returns the length of the entire output string 1432 * so that one can allocate a larger buffer and call the function again 1433 * if necessary. 1434 * The output string is NUL-terminated if possible. 1435 * 1436 * @param start offset of first character which will be copied 1437 * @param startLength the number of characters to extract 1438 * @param target the target buffer for extraction, can be NULL 1439 * if targetLength is 0 1440 * @param targetCapacity the length of the target buffer 1441 * @param inv Signature-distinguishing paramater, use US_INV. 1442 * @return the output string length, not including the terminating NUL 1443 * @stable ICU 3.2 1444 */ 1445 int32_t extract(int32_t start, 1446 int32_t startLength, 1447 char *target, 1448 int32_t targetCapacity, 1449 enum EInvariant inv) const; 1450 1451 #if U_CHARSET_IS_UTF8 || !UCONFIG_NO_CONVERSION 1452 1453 /** 1454 * Copy the characters in the range 1455 * [<tt>start</TT>, <tt>start + length</TT>) into an array of characters 1456 * in the platform's default codepage. 1457 * This function does not write any more than <code>targetLength</code> 1458 * characters but returns the length of the entire output string 1459 * so that one can allocate a larger buffer and call the function again 1460 * if necessary. 1461 * The output string is NUL-terminated if possible. 1462 * 1463 * @param start offset of first character which will be copied 1464 * @param startLength the number of characters to extract 1465 * @param target the target buffer for extraction 1466 * @param targetLength the length of the target buffer 1467 * If <TT>target</TT> is NULL, then the number of bytes required for 1468 * <TT>target</TT> is returned. 1469 * @return the output string length, not including the terminating NUL 1470 * @stable ICU 2.0 1471 */ 1472 int32_t extract(int32_t start, 1473 int32_t startLength, 1474 char *target, 1475 uint32_t targetLength) const; 1476 1477 #endif 1478 1479 #if !UCONFIG_NO_CONVERSION 1480 1481 /** 1482 * Copy the characters in the range 1483 * [<tt>start</TT>, <tt>start + length</TT>) into an array of characters 1484 * in a specified codepage. 1485 * The output string is NUL-terminated. 1486 * 1487 * Recommendation: For invariant-character strings use 1488 * extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const 1489 * because it avoids object code dependencies of UnicodeString on 1490 * the conversion code. 1491 * 1492 * @param start offset of first character which will be copied 1493 * @param startLength the number of characters to extract 1494 * @param target the target buffer for extraction 1495 * @param codepage the desired codepage for the characters. 0 has 1496 * the special meaning of the default codepage 1497 * If <code>codepage</code> is an empty string (<code>""</code>), 1498 * then a simple conversion is performed on the codepage-invariant 1499 * subset ("invariant characters") of the platform encoding. See utypes.h. 1500 * If <TT>target</TT> is NULL, then the number of bytes required for 1501 * <TT>target</TT> is returned. It is assumed that the target is big enough 1502 * to fit all of the characters. 1503 * @return the output string length, not including the terminating NUL 1504 * @stable ICU 2.0 1505 */ 1506 inline int32_t extract(int32_t start, 1507 int32_t startLength, 1508 char *target, 1509 const char *codepage = 0) const; 1510 1511 /** 1512 * Copy the characters in the range 1513 * [<tt>start</TT>, <tt>start + length</TT>) into an array of characters 1514 * in a specified codepage. 1515 * This function does not write any more than <code>targetLength</code> 1516 * characters but returns the length of the entire output string 1517 * so that one can allocate a larger buffer and call the function again 1518 * if necessary. 1519 * The output string is NUL-terminated if possible. 1520 * 1521 * Recommendation: For invariant-character strings use 1522 * extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const 1523 * because it avoids object code dependencies of UnicodeString on 1524 * the conversion code. 1525 * 1526 * @param start offset of first character which will be copied 1527 * @param startLength the number of characters to extract 1528 * @param target the target buffer for extraction 1529 * @param targetLength the length of the target buffer 1530 * @param codepage the desired codepage for the characters. 0 has 1531 * the special meaning of the default codepage 1532 * If <code>codepage</code> is an empty string (<code>""</code>), 1533 * then a simple conversion is performed on the codepage-invariant 1534 * subset ("invariant characters") of the platform encoding. See utypes.h. 1535 * If <TT>target</TT> is NULL, then the number of bytes required for 1536 * <TT>target</TT> is returned. 1537 * @return the output string length, not including the terminating NUL 1538 * @stable ICU 2.0 1539 */ 1540 int32_t extract(int32_t start, 1541 int32_t startLength, 1542 char *target, 1543 uint32_t targetLength, 1544 const char *codepage) const; 1545 1546 /** 1547 * Convert the UnicodeString into a codepage string using an existing UConverter. 1548 * The output string is NUL-terminated if possible. 1549 * 1550 * This function avoids the overhead of opening and closing a converter if 1551 * multiple strings are extracted. 1552 * 1553 * @param dest destination string buffer, can be NULL if destCapacity==0 1554 * @param destCapacity the number of chars available at dest 1555 * @param cnv the converter object to be used (ucnv_resetFromUnicode() will be called), 1556 * or NULL for the default converter 1557 * @param errorCode normal ICU error code 1558 * @return the length of the output string, not counting the terminating NUL; 1559 * if the length is greater than destCapacity, then the string will not fit 1560 * and a buffer of the indicated length would need to be passed in 1561 * @stable ICU 2.0 1562 */ 1563 int32_t extract(char *dest, int32_t destCapacity, 1564 UConverter *cnv, 1565 UErrorCode &errorCode) const; 1566 1567 #endif 1568 1569 /** 1570 * Create a temporary substring for the specified range. 1571 * Unlike the substring constructor and setTo() functions, 1572 * the object returned here will be a read-only alias (using getBuffer()) 1573 * rather than copying the text. 1574 * As a result, this substring operation is much faster but requires 1575 * that the original string not be modified or deleted during the lifetime 1576 * of the returned substring object. 1577 * @param start offset of the first character visible in the substring 1578 * @param length length of the substring 1579 * @return a read-only alias UnicodeString object for the substring 1580 * @draft ICU 4.4 1581 */ 1582 UnicodeString tempSubString(int32_t start=0, int32_t length=INT32_MAX) const; 1583 1584 /** 1585 * Create a temporary substring for the specified range. 1586 * Same as tempSubString(start, length) except that the substring range 1587 * is specified as a (start, limit) pair (with an exclusive limit index) 1588 * rather than a (start, length) pair. 1589 * @param start offset of the first character visible in the substring 1590 * @param limit offset immediately following the last character visible in the substring 1591 * @return a read-only alias UnicodeString object for the substring 1592 * @draft ICU 4.4 1593 */ 1594 inline UnicodeString tempSubStringBetween(int32_t start, int32_t limit=INT32_MAX) const; 1595 1596 /** 1597 * Convert the UnicodeString to UTF-8 and write the result 1598 * to a ByteSink. This is called by toUTF8String(). 1599 * Unpaired surrogates are replaced with U+FFFD. 1600 * Calls u_strToUTF8WithSub(). 1601 * 1602 * @param sink A ByteSink to which the UTF-8 version of the string is written. 1603 * @stable ICU 4.2 1604 * @see toUTF8String 1605 */ 1606 void toUTF8(ByteSink &sink) const; 1607 1608 #if U_HAVE_STD_STRING 1609 1610 /** 1611 * Convert the UnicodeString to UTF-8 and append the result 1612 * to a standard string. 1613 * Unpaired surrogates are replaced with U+FFFD. 1614 * Calls toUTF8(). 1615 * 1616 * @param result A standard string (or a compatible object) 1617 * to which the UTF-8 version of the string is appended. 1618 * @return The string object. 1619 * @stable ICU 4.2 1620 * @see toUTF8 1621 */ 1622 template<typename StringClass> 1623 StringClass &toUTF8String(StringClass &result) const { 1624 StringByteSink<StringClass> sbs(&result); 1625 toUTF8(sbs); 1626 return result; 1627 } 1628 1629 #endif 1630 1631 /** 1632 * Convert the UnicodeString to UTF-32. 1633 * Unpaired surrogates are replaced with U+FFFD. 1634 * Calls u_strToUTF32WithSub(). 1635 * 1636 * @param utf32 destination string buffer, can be NULL if capacity==0 1637 * @param capacity the number of UChar32s available at utf32 1638 * @param errorCode Standard ICU error code. Its input value must 1639 * pass the U_SUCCESS() test, or else the function returns 1640 * immediately. Check for U_FAILURE() on output or use with 1641 * function chaining. (See User Guide for details.) 1642 * @return The length of the UTF-32 string. 1643 * @see fromUTF32 1644 * @stable ICU 4.2 1645 */ 1646 int32_t toUTF32(UChar32 *utf32, int32_t capacity, UErrorCode &errorCode) const; 1647 1648 /* Length operations */ 1649 1650 /** 1651 * Return the length of the UnicodeString object. 1652 * The length is the number of UChar code units are in the UnicodeString. 1653 * If you want the number of code points, please use countChar32(). 1654 * @return the length of the UnicodeString object 1655 * @see countChar32 1656 * @stable ICU 2.0 1657 */ 1658 inline int32_t length(void) const; 1659 1660 /** 1661 * Count Unicode code points in the length UChar code units of the string. 1662 * A code point may occupy either one or two UChar code units. 1663 * Counting code points involves reading all code units. 1664 * 1665 * This functions is basically the inverse of moveIndex32(). 1666 * 1667 * @param start the index of the first code unit to check 1668 * @param length the number of UChar code units to check 1669 * @return the number of code points in the specified code units 1670 * @see length 1671 * @stable ICU 2.0 1672 */ 1673 int32_t 1674 countChar32(int32_t start=0, int32_t length=INT32_MAX) const; 1675 1676 /** 1677 * Check if the length UChar code units of the string 1678 * contain more Unicode code points than a certain number. 1679 * This is more efficient than counting all code points in this part of the string 1680 * and comparing that number with a threshold. 1681 * This function may not need to scan the string at all if the length 1682 * falls within a certain range, and 1683 * never needs to count more than 'number+1' code points. 1684 * Logically equivalent to (countChar32(start, length)>number). 1685 * A Unicode code point may occupy either one or two UChar code units. 1686 * 1687 * @param start the index of the first code unit to check (0 for the entire string) 1688 * @param length the number of UChar code units to check 1689 * (use INT32_MAX for the entire string; remember that start/length 1690 * values are pinned) 1691 * @param number The number of code points in the (sub)string is compared against 1692 * the 'number' parameter. 1693 * @return Boolean value for whether the string contains more Unicode code points 1694 * than 'number'. Same as (u_countChar32(s, length)>number). 1695 * @see countChar32 1696 * @see u_strHasMoreChar32Than 1697 * @stable ICU 2.4 1698 */ 1699 UBool 1700 hasMoreChar32Than(int32_t start, int32_t length, int32_t number) const; 1701 1702 /** 1703 * Determine if this string is empty. 1704 * @return TRUE if this string contains 0 characters, FALSE otherwise. 1705 * @stable ICU 2.0 1706 */ 1707 inline UBool isEmpty(void) const; 1708 1709 /** 1710 * Return the capacity of the internal buffer of the UnicodeString object. 1711 * This is useful together with the getBuffer functions. 1712 * See there for details. 1713 * 1714 * @return the number of UChars available in the internal buffer 1715 * @see getBuffer 1716 * @stable ICU 2.0 1717 */ 1718 inline int32_t getCapacity(void) const; 1719 1720 /* Other operations */ 1721 1722 /** 1723 * Generate a hash code for this object. 1724 * @return The hash code of this UnicodeString. 1725 * @stable ICU 2.0 1726 */ 1727 inline int32_t hashCode(void) const; 1728 1729 /** 1730 * Determine if this object contains a valid string. 1731 * A bogus string has no value. It is different from an empty string, 1732 * although in both cases isEmpty() returns TRUE and length() returns 0. 1733 * setToBogus() and isBogus() can be used to indicate that no string value is available. 1734 * For a bogus string, getBuffer() and getTerminatedBuffer() return NULL, and 1735 * length() returns 0. 1736 * 1737 * @return TRUE if the string is valid, FALSE otherwise 1738 * @see setToBogus() 1739 * @stable ICU 2.0 1740 */ 1741 inline UBool isBogus(void) const; 1742 1743 1744 //======================================== 1745 // Write operations 1746 //======================================== 1747 1748 /* Assignment operations */ 1749 1750 /** 1751 * Assignment operator. Replace the characters in this UnicodeString 1752 * with the characters from <TT>srcText</TT>. 1753 * @param srcText The text containing the characters to replace 1754 * @return a reference to this 1755 * @stable ICU 2.0 1756 */ 1757 UnicodeString &operator=(const UnicodeString &srcText); 1758 1759 /** 1760 * Almost the same as the assignment operator. 1761 * Replace the characters in this UnicodeString 1762 * with the characters from <code>srcText</code>. 1763 * 1764 * This function works the same for all strings except for ones that 1765 * are readonly aliases. 1766 * Starting with ICU 2.4, the assignment operator and the copy constructor 1767 * allocate a new buffer and copy the buffer contents even for readonly aliases. 1768 * This function implements the old, more efficient but less safe behavior 1769 * of making this string also a readonly alias to the same buffer. 1770 * The fastCopyFrom function must be used only if it is known that the lifetime of 1771 * this UnicodeString is at least as long as the lifetime of the aliased buffer 1772 * including its contents, for example for strings from resource bundles 1773 * or aliases to string contents. 1774 * 1775 * @param src The text containing the characters to replace. 1776 * @return a reference to this 1777 * @stable ICU 2.4 1778 */ 1779 UnicodeString &fastCopyFrom(const UnicodeString &src); 1780 1781 /** 1782 * Assignment operator. Replace the characters in this UnicodeString 1783 * with the code unit <TT>ch</TT>. 1784 * @param ch the code unit to replace 1785 * @return a reference to this 1786 * @stable ICU 2.0 1787 */ 1788 inline UnicodeString& operator= (UChar ch); 1789 1790 /** 1791 * Assignment operator. Replace the characters in this UnicodeString 1792 * with the code point <TT>ch</TT>. 1793 * @param ch the code point to replace 1794 * @return a reference to this 1795 * @stable ICU 2.0 1796 */ 1797 inline UnicodeString& operator= (UChar32 ch); 1798 1799 /** 1800 * Set the text in the UnicodeString object to the characters 1801 * in <TT>srcText</TT> in the range 1802 * [<TT>srcStart</TT>, <TT>srcText.length()</TT>). 1803 * <TT>srcText</TT> is not modified. 1804 * @param srcText the source for the new characters 1805 * @param srcStart the offset into <TT>srcText</TT> where new characters 1806 * will be obtained 1807 * @return a reference to this 1808 * @stable ICU 2.2 1809 */ 1810 inline UnicodeString& setTo(const UnicodeString& srcText, 1811 int32_t srcStart); 1812 1813 /** 1814 * Set the text in the UnicodeString object to the characters 1815 * in <TT>srcText</TT> in the range 1816 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 1817 * <TT>srcText</TT> is not modified. 1818 * @param srcText the source for the new characters 1819 * @param srcStart the offset into <TT>srcText</TT> where new characters 1820 * will be obtained 1821 * @param srcLength the number of characters in <TT>srcText</TT> in the 1822 * replace string. 1823 * @return a reference to this 1824 * @stable ICU 2.0 1825 */ 1826 inline UnicodeString& setTo(const UnicodeString& srcText, 1827 int32_t srcStart, 1828 int32_t srcLength); 1829 1830 /** 1831 * Set the text in the UnicodeString object to the characters in 1832 * <TT>srcText</TT>. 1833 * <TT>srcText</TT> is not modified. 1834 * @param srcText the source for the new characters 1835 * @return a reference to this 1836 * @stable ICU 2.0 1837 */ 1838 inline UnicodeString& setTo(const UnicodeString& srcText); 1839 1840 /** 1841 * Set the characters in the UnicodeString object to the characters 1842 * in <TT>srcChars</TT>. <TT>srcChars</TT> is not modified. 1843 * @param srcChars the source for the new characters 1844 * @param srcLength the number of Unicode characters in srcChars. 1845 * @return a reference to this 1846 * @stable ICU 2.0 1847 */ 1848 inline UnicodeString& setTo(const UChar *srcChars, 1849 int32_t srcLength); 1850 1851 /** 1852 * Set the characters in the UnicodeString object to the code unit 1853 * <TT>srcChar</TT>. 1854 * @param srcChar the code unit which becomes the UnicodeString's character 1855 * content 1856 * @return a reference to this 1857 * @stable ICU 2.0 1858 */ 1859 UnicodeString& setTo(UChar srcChar); 1860 1861 /** 1862 * Set the characters in the UnicodeString object to the code point 1863 * <TT>srcChar</TT>. 1864 * @param srcChar the code point which becomes the UnicodeString's character 1865 * content 1866 * @return a reference to this 1867 * @stable ICU 2.0 1868 */ 1869 UnicodeString& setTo(UChar32 srcChar); 1870 1871 /** 1872 * Aliasing setTo() function, analogous to the readonly-aliasing UChar* constructor. 1873 * The text will be used for the UnicodeString object, but 1874 * it will not be released when the UnicodeString is destroyed. 1875 * This has copy-on-write semantics: 1876 * When the string is modified, then the buffer is first copied into 1877 * newly allocated memory. 1878 * The aliased buffer is never modified. 1879 * In an assignment to another UnicodeString, the text will be aliased again, 1880 * so that both strings then alias the same readonly-text. 1881 * 1882 * @param isTerminated specifies if <code>text</code> is <code>NUL</code>-terminated. 1883 * This must be true if <code>textLength==-1</code>. 1884 * @param text The characters to alias for the UnicodeString. 1885 * @param textLength The number of Unicode characters in <code>text</code> to alias. 1886 * If -1, then this constructor will determine the length 1887 * by calling <code>u_strlen()</code>. 1888 * @return a reference to this 1889 * @stable ICU 2.0 1890 */ 1891 UnicodeString &setTo(UBool isTerminated, 1892 const UChar *text, 1893 int32_t textLength); 1894 1895 /** 1896 * Aliasing setTo() function, analogous to the writable-aliasing UChar* constructor. 1897 * The text will be used for the UnicodeString object, but 1898 * it will not be released when the UnicodeString is destroyed. 1899 * This has write-through semantics: 1900 * For as long as the capacity of the buffer is sufficient, write operations 1901 * will directly affect the buffer. When more capacity is necessary, then 1902 * a new buffer will be allocated and the contents copied as with regularly 1903 * constructed strings. 1904 * In an assignment to another UnicodeString, the buffer will be copied. 1905 * The extract(UChar *dst) function detects whether the dst pointer is the same 1906 * as the string buffer itself and will in this case not copy the contents. 1907 * 1908 * @param buffer The characters to alias for the UnicodeString. 1909 * @param buffLength The number of Unicode characters in <code>buffer</code> to alias. 1910 * @param buffCapacity The size of <code>buffer</code> in UChars. 1911 * @return a reference to this 1912 * @stable ICU 2.0 1913 */ 1914 UnicodeString &setTo(UChar *buffer, 1915 int32_t buffLength, 1916 int32_t buffCapacity); 1917 1918 /** 1919 * Make this UnicodeString object invalid. 1920 * The string will test TRUE with isBogus(). 1921 * 1922 * A bogus string has no value. It is different from an empty string. 1923 * It can be used to indicate that no string value is available. 1924 * getBuffer() and getTerminatedBuffer() return NULL, and 1925 * length() returns 0. 1926 * 1927 * This utility function is used throughout the UnicodeString 1928 * implementation to indicate that a UnicodeString operation failed, 1929 * and may be used in other functions, 1930 * especially but not exclusively when such functions do not 1931 * take a UErrorCode for simplicity. 1932 * 1933 * The following methods, and no others, will clear a string object's bogus flag: 1934 * - remove() 1935 * - remove(0, INT32_MAX) 1936 * - truncate(0) 1937 * - operator=() (assignment operator) 1938 * - setTo(...) 1939 * 1940 * The simplest ways to turn a bogus string into an empty one 1941 * is to use the remove() function. 1942 * Examples for other functions that are equivalent to "set to empty string": 1943 * \code 1944 * if(s.isBogus()) { 1945 * s.remove(); // set to an empty string (remove all), or 1946 * s.remove(0, INT32_MAX); // set to an empty string (remove all), or 1947 * s.truncate(0); // set to an empty string (complete truncation), or 1948 * s=UnicodeString(); // assign an empty string, or 1949 * s.setTo((UChar32)-1); // set to a pseudo code point that is out of range, or 1950 * static const UChar nul=0; 1951 * s.setTo(&nul, 0); // set to an empty C Unicode string 1952 * } 1953 * \endcode 1954 * 1955 * @see isBogus() 1956 * @stable ICU 2.0 1957 */ 1958 void setToBogus(); 1959 1960 /** 1961 * Set the character at the specified offset to the specified character. 1962 * @param offset A valid offset into the text of the character to set 1963 * @param ch The new character 1964 * @return A reference to this 1965 * @stable ICU 2.0 1966 */ 1967 UnicodeString& setCharAt(int32_t offset, 1968 UChar ch); 1969 1970 1971 /* Append operations */ 1972 1973 /** 1974 * Append operator. Append the code unit <TT>ch</TT> to the UnicodeString 1975 * object. 1976 * @param ch the code unit to be appended 1977 * @return a reference to this 1978 * @stable ICU 2.0 1979 */ 1980 inline UnicodeString& operator+= (UChar ch); 1981 1982 /** 1983 * Append operator. Append the code point <TT>ch</TT> to the UnicodeString 1984 * object. 1985 * @param ch the code point to be appended 1986 * @return a reference to this 1987 * @stable ICU 2.0 1988 */ 1989 inline UnicodeString& operator+= (UChar32 ch); 1990 1991 /** 1992 * Append operator. Append the characters in <TT>srcText</TT> to the 1993 * UnicodeString object at offset <TT>start</TT>. <TT>srcText</TT> is 1994 * not modified. 1995 * @param srcText the source for the new characters 1996 * @return a reference to this 1997 * @stable ICU 2.0 1998 */ 1999 inline UnicodeString& operator+= (const UnicodeString& srcText); 2000 2001 /** 2002 * Append the characters 2003 * in <TT>srcText</TT> in the range 2004 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) to the 2005 * UnicodeString object at offset <TT>start</TT>. <TT>srcText</TT> 2006 * is not modified. 2007 * @param srcText the source for the new characters 2008 * @param srcStart the offset into <TT>srcText</TT> where new characters 2009 * will be obtained 2010 * @param srcLength the number of characters in <TT>srcText</TT> in 2011 * the append string 2012 * @return a reference to this 2013 * @stable ICU 2.0 2014 */ 2015 inline UnicodeString& append(const UnicodeString& srcText, 2016 int32_t srcStart, 2017 int32_t srcLength); 2018 2019 /** 2020 * Append the characters in <TT>srcText</TT> to the UnicodeString object at 2021 * offset <TT>start</TT>. <TT>srcText</TT> is not modified. 2022 * @param srcText the source for the new characters 2023 * @return a reference to this 2024 * @stable ICU 2.0 2025 */ 2026 inline UnicodeString& append(const UnicodeString& srcText); 2027 2028 /** 2029 * Append the characters in <TT>srcChars</TT> in the range 2030 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) to the UnicodeString 2031 * object at offset 2032 * <TT>start</TT>. <TT>srcChars</TT> is not modified. 2033 * @param srcChars the source for the new characters 2034 * @param srcStart the offset into <TT>srcChars</TT> where new characters 2035 * will be obtained 2036 * @param srcLength the number of characters in <TT>srcChars</TT> in 2037 * the append string 2038 * @return a reference to this 2039 * @stable ICU 2.0 2040 */ 2041 inline UnicodeString& append(const UChar *srcChars, 2042 int32_t srcStart, 2043 int32_t srcLength); 2044 2045 /** 2046 * Append the characters in <TT>srcChars</TT> to the UnicodeString object 2047 * at offset <TT>start</TT>. <TT>srcChars</TT> is not modified. 2048 * @param srcChars the source for the new characters 2049 * @param srcLength the number of Unicode characters in <TT>srcChars</TT> 2050 * @return a reference to this 2051 * @stable ICU 2.0 2052 */ 2053 inline UnicodeString& append(const UChar *srcChars, 2054 int32_t srcLength); 2055 2056 /** 2057 * Append the code unit <TT>srcChar</TT> to the UnicodeString object. 2058 * @param srcChar the code unit to append 2059 * @return a reference to this 2060 * @stable ICU 2.0 2061 */ 2062 inline UnicodeString& append(UChar srcChar); 2063 2064 /** 2065 * Append the code point <TT>srcChar</TT> to the UnicodeString object. 2066 * @param srcChar the code point to append 2067 * @return a reference to this 2068 * @stable ICU 2.0 2069 */ 2070 inline UnicodeString& append(UChar32 srcChar); 2071 2072 2073 /* Insert operations */ 2074 2075 /** 2076 * Insert the characters in <TT>srcText</TT> in the range 2077 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) into the UnicodeString 2078 * object at offset <TT>start</TT>. <TT>srcText</TT> is not modified. 2079 * @param start the offset where the insertion begins 2080 * @param srcText the source for the new characters 2081 * @param srcStart the offset into <TT>srcText</TT> where new characters 2082 * will be obtained 2083 * @param srcLength the number of characters in <TT>srcText</TT> in 2084 * the insert string 2085 * @return a reference to this 2086 * @stable ICU 2.0 2087 */ 2088 inline UnicodeString& insert(int32_t start, 2089 const UnicodeString& srcText, 2090 int32_t srcStart, 2091 int32_t srcLength); 2092 2093 /** 2094 * Insert the characters in <TT>srcText</TT> into the UnicodeString object 2095 * at offset <TT>start</TT>. <TT>srcText</TT> is not modified. 2096 * @param start the offset where the insertion begins 2097 * @param srcText the source for the new characters 2098 * @return a reference to this 2099 * @stable ICU 2.0 2100 */ 2101 inline UnicodeString& insert(int32_t start, 2102 const UnicodeString& srcText); 2103 2104 /** 2105 * Insert the characters in <TT>srcChars</TT> in the range 2106 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) into the UnicodeString 2107 * object at offset <TT>start</TT>. <TT>srcChars</TT> is not modified. 2108 * @param start the offset at which the insertion begins 2109 * @param srcChars the source for the new characters 2110 * @param srcStart the offset into <TT>srcChars</TT> where new characters 2111 * will be obtained 2112 * @param srcLength the number of characters in <TT>srcChars</TT> 2113 * in the insert string 2114 * @return a reference to this 2115 * @stable ICU 2.0 2116 */ 2117 inline UnicodeString& insert(int32_t start, 2118 const UChar *srcChars, 2119 int32_t srcStart, 2120 int32_t srcLength); 2121 2122 /** 2123 * Insert the characters in <TT>srcChars</TT> into the UnicodeString object 2124 * at offset <TT>start</TT>. <TT>srcChars</TT> is not modified. 2125 * @param start the offset where the insertion begins 2126 * @param srcChars the source for the new characters 2127 * @param srcLength the number of Unicode characters in srcChars. 2128 * @return a reference to this 2129 * @stable ICU 2.0 2130 */ 2131 inline UnicodeString& insert(int32_t start, 2132 const UChar *srcChars, 2133 int32_t srcLength); 2134 2135 /** 2136 * Insert the code unit <TT>srcChar</TT> into the UnicodeString object at 2137 * offset <TT>start</TT>. 2138 * @param start the offset at which the insertion occurs 2139 * @param srcChar the code unit to insert 2140 * @return a reference to this 2141 * @stable ICU 2.0 2142 */ 2143 inline UnicodeString& insert(int32_t start, 2144 UChar srcChar); 2145 2146 /** 2147 * Insert the code point <TT>srcChar</TT> into the UnicodeString object at 2148 * offset <TT>start</TT>. 2149 * @param start the offset at which the insertion occurs 2150 * @param srcChar the code point to insert 2151 * @return a reference to this 2152 * @stable ICU 2.0 2153 */ 2154 inline UnicodeString& insert(int32_t start, 2155 UChar32 srcChar); 2156 2157 2158 /* Replace operations */ 2159 2160 /** 2161 * Replace the characters in the range 2162 * [<TT>start</TT>, <TT>start + length</TT>) with the characters in 2163 * <TT>srcText</TT> in the range 2164 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). 2165 * <TT>srcText</TT> is not modified. 2166 * @param start the offset at which the replace operation begins 2167 * @param length the number of characters to replace. The character at 2168 * <TT>start + length</TT> is not modified. 2169 * @param srcText the source for the new characters 2170 * @param srcStart the offset into <TT>srcText</TT> where new characters 2171 * will be obtained 2172 * @param srcLength the number of characters in <TT>srcText</TT> in 2173 * the replace string 2174 * @return a reference to this 2175 * @stable ICU 2.0 2176 */ 2177 UnicodeString& replace(int32_t start, 2178 int32_t length, 2179 const UnicodeString& srcText, 2180 int32_t srcStart, 2181 int32_t srcLength); 2182 2183 /** 2184 * Replace the characters in the range 2185 * [<TT>start</TT>, <TT>start + length</TT>) 2186 * with the characters in <TT>srcText</TT>. <TT>srcText</TT> is 2187 * not modified. 2188 * @param start the offset at which the replace operation begins 2189 * @param length the number of characters to replace. The character at 2190 * <TT>start + length</TT> is not modified. 2191 * @param srcText the source for the new characters 2192 * @return a reference to this 2193 * @stable ICU 2.0 2194 */ 2195 UnicodeString& replace(int32_t start, 2196 int32_t length, 2197 const UnicodeString& srcText); 2198 2199 /** 2200 * Replace the characters in the range 2201 * [<TT>start</TT>, <TT>start + length</TT>) with the characters in 2202 * <TT>srcChars</TT> in the range 2203 * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). <TT>srcChars</TT> 2204 * is not modified. 2205 * @param start the offset at which the replace operation begins 2206 * @param length the number of characters to replace. The character at 2207 * <TT>start + length</TT> is not modified. 2208 * @param srcChars the source for the new characters 2209 * @param srcStart the offset into <TT>srcChars</TT> where new characters 2210 * will be obtained 2211 * @param srcLength the number of characters in <TT>srcChars</TT> 2212 * in the replace string 2213 * @return a reference to this 2214 * @stable ICU 2.0 2215 */ 2216 UnicodeString& replace(int32_t start, 2217 int32_t length, 2218 const UChar *srcChars, 2219 int32_t srcStart, 2220 int32_t srcLength); 2221 2222 /** 2223 * Replace the characters in the range 2224 * [<TT>start</TT>, <TT>start + length</TT>) with the characters in 2225 * <TT>srcChars</TT>. <TT>srcChars</TT> is not modified. 2226 * @param start the offset at which the replace operation begins 2227 * @param length number of characters to replace. The character at 2228 * <TT>start + length</TT> is not modified. 2229 * @param srcChars the source for the new characters 2230 * @param srcLength the number of Unicode characters in srcChars 2231 * @return a reference to this 2232 * @stable ICU 2.0 2233 */ 2234 inline UnicodeString& replace(int32_t start, 2235 int32_t length, 2236 const UChar *srcChars, 2237 int32_t srcLength); 2238 2239 /** 2240 * Replace the characters in the range 2241 * [<TT>start</TT>, <TT>start + length</TT>) with the code unit 2242 * <TT>srcChar</TT>. 2243 * @param start the offset at which the replace operation begins 2244 * @param length the number of characters to replace. The character at 2245 * <TT>start + length</TT> is not modified. 2246 * @param srcChar the new code unit 2247 * @return a reference to this 2248 * @stable ICU 2.0 2249 */ 2250 inline UnicodeString& replace(int32_t start, 2251 int32_t length, 2252 UChar srcChar); 2253 2254 /** 2255 * Replace the characters in the range 2256 * [<TT>start</TT>, <TT>start + length</TT>) with the code point 2257 * <TT>srcChar</TT>. 2258 * @param start the offset at which the replace operation begins 2259 * @param length the number of characters to replace. The character at 2260 * <TT>start + length</TT> is not modified. 2261 * @param srcChar the new code point 2262 * @return a reference to this 2263 * @stable ICU 2.0 2264 */ 2265 inline UnicodeString& replace(int32_t start, 2266 int32_t length, 2267 UChar32 srcChar); 2268 2269 /** 2270 * Replace the characters in the range [<TT>start</TT>, <TT>limit</TT>) 2271 * with the characters in <TT>srcText</TT>. <TT>srcText</TT> is not modified. 2272 * @param start the offset at which the replace operation begins 2273 * @param limit the offset immediately following the replace range 2274 * @param srcText the source for the new characters 2275 * @return a reference to this 2276 * @stable ICU 2.0 2277 */ 2278 inline UnicodeString& replaceBetween(int32_t start, 2279 int32_t limit, 2280 const UnicodeString& srcText); 2281 2282 /** 2283 * Replace the characters in the range [<TT>start</TT>, <TT>limit</TT>) 2284 * with the characters in <TT>srcText</TT> in the range 2285 * [<TT>srcStart</TT>, <TT>srcLimit</TT>). <TT>srcText</TT> is not modified. 2286 * @param start the offset at which the replace operation begins 2287 * @param limit the offset immediately following the replace range 2288 * @param srcText the source for the new characters 2289 * @param srcStart the offset into <TT>srcChars</TT> where new characters 2290 * will be obtained 2291 * @param srcLimit the offset immediately following the range to copy 2292 * in <TT>srcText</TT> 2293 * @return a reference to this 2294 * @stable ICU 2.0 2295 */ 2296 inline UnicodeString& replaceBetween(int32_t start, 2297 int32_t limit, 2298 const UnicodeString& srcText, 2299 int32_t srcStart, 2300 int32_t srcLimit); 2301 2302 /** 2303 * Replace a substring of this object with the given text. 2304 * @param start the beginning index, inclusive; <code>0 <= start 2305 * <= limit</code>. 2306 * @param limit the ending index, exclusive; <code>start <= limit 2307 * <= length()</code>. 2308 * @param text the text to replace characters <code>start</code> 2309 * to <code>limit - 1</code> 2310 * @stable ICU 2.0 2311 */ 2312 virtual void handleReplaceBetween(int32_t start, 2313 int32_t limit, 2314 const UnicodeString& text); 2315 2316 /** 2317 * Replaceable API 2318 * @return TRUE if it has MetaData 2319 * @stable ICU 2.4 2320 */ 2321 virtual UBool hasMetaData() const; 2322 2323 /** 2324 * Copy a substring of this object, retaining attribute (out-of-band) 2325 * information. This method is used to duplicate or reorder substrings. 2326 * The destination index must not overlap the source range. 2327 * 2328 * @param start the beginning index, inclusive; <code>0 <= start <= 2329 * limit</code>. 2330 * @param limit the ending index, exclusive; <code>start <= limit <= 2331 * length()</code>. 2332 * @param dest the destination index. The characters from 2333 * <code>start..limit-1</code> will be copied to <code>dest</code>. 2334 * Implementations of this method may assume that <code>dest <= start || 2335 * dest >= limit</code>. 2336 * @stable ICU 2.0 2337 */ 2338 virtual void copy(int32_t start, int32_t limit, int32_t dest); 2339 2340 /* Search and replace operations */ 2341 2342 /** 2343 * Replace all occurrences of characters in oldText with the characters 2344 * in newText 2345 * @param oldText the text containing the search text 2346 * @param newText the text containing the replacement text 2347 * @return a reference to this 2348 * @stable ICU 2.0 2349 */ 2350 inline UnicodeString& findAndReplace(const UnicodeString& oldText, 2351 const UnicodeString& newText); 2352 2353 /** 2354 * Replace all occurrences of characters in oldText with characters 2355 * in newText 2356 * in the range [<TT>start</TT>, <TT>start + length</TT>). 2357 * @param start the start of the range in which replace will performed 2358 * @param length the length of the range in which replace will be performed 2359 * @param oldText the text containing the search text 2360 * @param newText the text containing the replacement text 2361 * @return a reference to this 2362 * @stable ICU 2.0 2363 */ 2364 inline UnicodeString& findAndReplace(int32_t start, 2365 int32_t length, 2366 const UnicodeString& oldText, 2367 const UnicodeString& newText); 2368 2369 /** 2370 * Replace all occurrences of characters in oldText in the range 2371 * [<TT>oldStart</TT>, <TT>oldStart + oldLength</TT>) with the characters 2372 * in newText in the range 2373 * [<TT>newStart</TT>, <TT>newStart + newLength</TT>) 2374 * in the range [<TT>start</TT>, <TT>start + length</TT>). 2375 * @param start the start of the range in which replace will performed 2376 * @param length the length of the range in which replace will be performed 2377 * @param oldText the text containing the search text 2378 * @param oldStart the start of the search range in <TT>oldText</TT> 2379 * @param oldLength the length of the search range in <TT>oldText</TT> 2380 * @param newText the text containing the replacement text 2381 * @param newStart the start of the replacement range in <TT>newText</TT> 2382 * @param newLength the length of the replacement range in <TT>newText</TT> 2383 * @return a reference to this 2384 * @stable ICU 2.0 2385 */ 2386 UnicodeString& findAndReplace(int32_t start, 2387 int32_t length, 2388 const UnicodeString& oldText, 2389 int32_t oldStart, 2390 int32_t oldLength, 2391 const UnicodeString& newText, 2392 int32_t newStart, 2393 int32_t newLength); 2394 2395 2396 /* Remove operations */ 2397 2398 /** 2399 * Remove all characters from the UnicodeString object. 2400 * @return a reference to this 2401 * @stable ICU 2.0 2402 */ 2403 inline UnicodeString& remove(void); 2404 2405 /** 2406 * Remove the characters in the range 2407 * [<TT>start</TT>, <TT>start + length</TT>) from the UnicodeString object. 2408 * @param start the offset of the first character to remove 2409 * @param length the number of characters to remove 2410 * @return a reference to this 2411 * @stable ICU 2.0 2412 */ 2413 inline UnicodeString& remove(int32_t start, 2414 int32_t length = (int32_t)INT32_MAX); 2415 2416 /** 2417 * Remove the characters in the range 2418 * [<TT>start</TT>, <TT>limit</TT>) from the UnicodeString object. 2419 * @param start the offset of the first character to remove 2420 * @param limit the offset immediately following the range to remove 2421 * @return a reference to this 2422 * @stable ICU 2.0 2423 */ 2424 inline UnicodeString& removeBetween(int32_t start, 2425 int32_t limit = (int32_t)INT32_MAX); 2426 2427 /** 2428 * Retain only the characters in the range 2429 * [<code>start</code>, <code>limit</code>) from the UnicodeString object. 2430 * Removes characters before <code>start</code> and at and after <code>limit</code>. 2431 * @param start the offset of the first character to retain 2432 * @param limit the offset immediately following the range to retain 2433 * @return a reference to this 2434 * @draft ICU 4.4 2435 */ 2436 inline UnicodeString &retainBetween(int32_t start, int32_t limit = INT32_MAX); 2437 2438 /* Length operations */ 2439 2440 /** 2441 * Pad the start of this UnicodeString with the character <TT>padChar</TT>. 2442 * If the length of this UnicodeString is less than targetLength, 2443 * length() - targetLength copies of padChar will be added to the 2444 * beginning of this UnicodeString. 2445 * @param targetLength the desired length of the string 2446 * @param padChar the character to use for padding. Defaults to 2447 * space (U+0020) 2448 * @return TRUE if the text was padded, FALSE otherwise. 2449 * @stable ICU 2.0 2450 */ 2451 UBool padLeading(int32_t targetLength, 2452 UChar padChar = 0x0020); 2453 2454 /** 2455 * Pad the end of this UnicodeString with the character <TT>padChar</TT>. 2456 * If the length of this UnicodeString is less than targetLength, 2457 * length() - targetLength copies of padChar will be added to the 2458 * end of this UnicodeString. 2459 * @param targetLength the desired length of the string 2460 * @param padChar the character to use for padding. Defaults to 2461 * space (U+0020) 2462 * @return TRUE if the text was padded, FALSE otherwise. 2463 * @stable ICU 2.0 2464 */ 2465 UBool padTrailing(int32_t targetLength, 2466 UChar padChar = 0x0020); 2467 2468 /** 2469 * Truncate this UnicodeString to the <TT>targetLength</TT>. 2470 * @param targetLength the desired length of this UnicodeString. 2471 * @return TRUE if the text was truncated, FALSE otherwise 2472 * @stable ICU 2.0 2473 */ 2474 inline UBool truncate(int32_t targetLength); 2475 2476 /** 2477 * Trims leading and trailing whitespace from this UnicodeString. 2478 * @return a reference to this 2479 * @stable ICU 2.0 2480 */ 2481 UnicodeString& trim(void); 2482 2483 2484 /* Miscellaneous operations */ 2485 2486 /** 2487 * Reverse this UnicodeString in place. 2488 * @return a reference to this 2489 * @stable ICU 2.0 2490 */ 2491 inline UnicodeString& reverse(void); 2492 2493 /** 2494 * Reverse the range [<TT>start</TT>, <TT>start + length</TT>) in 2495 * this UnicodeString. 2496 * @param start the start of the range to reverse 2497 * @param length the number of characters to to reverse 2498 * @return a reference to this 2499 * @stable ICU 2.0 2500 */ 2501 inline UnicodeString& reverse(int32_t start, 2502 int32_t length); 2503 2504 /** 2505 * Convert the characters in this to UPPER CASE following the conventions of 2506 * the default locale. 2507 * @return A reference to this. 2508 * @stable ICU 2.0 2509 */ 2510 UnicodeString& toUpper(void); 2511 2512 /** 2513 * Convert the characters in this to UPPER CASE following the conventions of 2514 * a specific locale. 2515 * @param locale The locale containing the conventions to use. 2516 * @return A reference to this. 2517 * @stable ICU 2.0 2518 */ 2519 UnicodeString& toUpper(const Locale& locale); 2520 2521 /** 2522 * Convert the characters in this to lower case following the conventions of 2523 * the default locale. 2524 * @return A reference to this. 2525 * @stable ICU 2.0 2526 */ 2527 UnicodeString& toLower(void); 2528 2529 /** 2530 * Convert the characters in this to lower case following the conventions of 2531 * a specific locale. 2532 * @param locale The locale containing the conventions to use. 2533 * @return A reference to this. 2534 * @stable ICU 2.0 2535 */ 2536 UnicodeString& toLower(const Locale& locale); 2537 2538 #if !UCONFIG_NO_BREAK_ITERATION 2539 2540 /** 2541 * Titlecase this string, convenience function using the default locale. 2542 * 2543 * Casing is locale-dependent and context-sensitive. 2544 * Titlecasing uses a break iterator to find the first characters of words 2545 * that are to be titlecased. It titlecases those characters and lowercases 2546 * all others. 2547 * 2548 * The titlecase break iterator can be provided to customize for arbitrary 2549 * styles, using rules and dictionaries beyond the standard iterators. 2550 * It may be more efficient to always provide an iterator to avoid 2551 * opening and closing one for each string. 2552 * The standard titlecase iterator for the root locale implements the 2553 * algorithm of Unicode TR 21. 2554 * 2555 * This function uses only the setText(), first() and next() methods of the 2556 * provided break iterator. 2557 * 2558 * @param titleIter A break iterator to find the first characters of words 2559 * that are to be titlecased. 2560 * If none is provided (0), then a standard titlecase 2561 * break iterator is opened. 2562 * Otherwise the provided iterator is set to the string's text. 2563 * @return A reference to this. 2564 * @stable ICU 2.1 2565 */ 2566 UnicodeString &toTitle(BreakIterator *titleIter); 2567 2568 /** 2569 * Titlecase this string. 2570 * 2571 * Casing is locale-dependent and context-sensitive. 2572 * Titlecasing uses a break iterator to find the first characters of words 2573 * that are to be titlecased. It titlecases those characters and lowercases 2574 * all others. 2575 * 2576 * The titlecase break iterator can be provided to customize for arbitrary 2577 * styles, using rules and dictionaries beyond the standard iterators. 2578 * It may be more efficient to always provide an iterator to avoid 2579 * opening and closing one for each string. 2580 * The standard titlecase iterator for the root locale implements the 2581 * algorithm of Unicode TR 21. 2582 * 2583 * This function uses only the setText(), first() and next() methods of the 2584 * provided break iterator. 2585 * 2586 * @param titleIter A break iterator to find the first characters of words 2587 * that are to be titlecased. 2588 * If none is provided (0), then a standard titlecase 2589 * break iterator is opened. 2590 * Otherwise the provided iterator is set to the string's text. 2591 * @param locale The locale to consider. 2592 * @return A reference to this. 2593 * @stable ICU 2.1 2594 */ 2595 UnicodeString &toTitle(BreakIterator *titleIter, const Locale &locale); 2596 2597 /** 2598 * Titlecase this string, with options. 2599 * 2600 * Casing is locale-dependent and context-sensitive. 2601 * Titlecasing uses a break iterator to find the first characters of words 2602 * that are to be titlecased. It titlecases those characters and lowercases 2603 * all others. (This can be modified with options.) 2604 * 2605 * The titlecase break iterator can be provided to customize for arbitrary 2606 * styles, using rules and dictionaries beyond the standard iterators. 2607 * It may be more efficient to always provide an iterator to avoid 2608 * opening and closing one for each string. 2609 * The standard titlecase iterator for the root locale implements the 2610 * algorithm of Unicode TR 21. 2611 * 2612 * This function uses only the setText(), first() and next() methods of the 2613 * provided break iterator. 2614 * 2615 * @param titleIter A break iterator to find the first characters of words 2616 * that are to be titlecased. 2617 * If none is provided (0), then a standard titlecase 2618 * break iterator is opened. 2619 * Otherwise the provided iterator is set to the string's text. 2620 * @param locale The locale to consider. 2621 * @param options Options bit set, see ucasemap_open(). 2622 * @return A reference to this. 2623 * @see U_TITLECASE_NO_LOWERCASE 2624 * @see U_TITLECASE_NO_BREAK_ADJUSTMENT 2625 * @see ucasemap_open 2626 * @stable ICU 3.8 2627 */ 2628 UnicodeString &toTitle(BreakIterator *titleIter, const Locale &locale, uint32_t options); 2629 2630 #endif 2631 2632 /** 2633 * Case-fold the characters in this string. 2634 * Case-folding is locale-independent and not context-sensitive, 2635 * but there is an option for whether to include or exclude mappings for dotted I 2636 * and dotless i that are marked with 'I' in CaseFolding.txt. 2637 * The result may be longer or shorter than the original. 2638 * 2639 * @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I 2640 * @return A reference to this. 2641 * @stable ICU 2.0 2642 */ 2643 UnicodeString &foldCase(uint32_t options=0 /*U_FOLD_CASE_DEFAULT*/); 2644 2645 //======================================== 2646 // Access to the internal buffer 2647 //======================================== 2648 2649 /** 2650 * Get a read/write pointer to the internal buffer. 2651 * The buffer is guaranteed to be large enough for at least minCapacity UChars, 2652 * writable, and is still owned by the UnicodeString object. 2653 * Calls to getBuffer(minCapacity) must not be nested, and 2654 * must be matched with calls to releaseBuffer(newLength). 2655 * If the string buffer was read-only or shared, 2656 * then it will be reallocated and copied. 2657 * 2658 * An attempted nested call will return 0, and will not further modify the 2659 * state of the UnicodeString object. 2660 * It also returns 0 if the string is bogus. 2661 * 2662 * The actual capacity of the string buffer may be larger than minCapacity. 2663 * getCapacity() returns the actual capacity. 2664 * For many operations, the full capacity should be used to avoid reallocations. 2665 * 2666 * While the buffer is "open" between getBuffer(minCapacity) 2667 * and releaseBuffer(newLength), the following applies: 2668 * - The string length is set to 0. 2669 * - Any read API call on the UnicodeString object will behave like on a 0-length string. 2670 * - Any write API call on the UnicodeString object is disallowed and will have no effect. 2671 * - You can read from and write to the returned buffer. 2672 * - The previous string contents will still be in the buffer; 2673 * if you want to use it, then you need to call length() before getBuffer(minCapacity). 2674 * If the length() was greater than minCapacity, then any contents after minCapacity 2675 * may be lost. 2676 * The buffer contents is not NUL-terminated by getBuffer(). 2677 * If length()<getCapacity() then you can terminate it by writing a NUL 2678 * at index length(). 2679 * - You must call releaseBuffer(newLength) before and in order to 2680 * return to normal UnicodeString operation. 2681 * 2682 * @param minCapacity the minimum number of UChars that are to be available 2683 * in the buffer, starting at the returned pointer; 2684 * default to the current string capacity if minCapacity==-1 2685 * @return a writable pointer to the internal string buffer, 2686 * or 0 if an error occurs (nested calls, out of memory) 2687 * 2688 * @see releaseBuffer 2689 * @see getTerminatedBuffer() 2690 * @stable ICU 2.0 2691 */ 2692 UChar *getBuffer(int32_t minCapacity); 2693 2694 /** 2695 * Release a read/write buffer on a UnicodeString object with an 2696 * "open" getBuffer(minCapacity). 2697 * This function must be called in a matched pair with getBuffer(minCapacity). 2698 * releaseBuffer(newLength) must be called if and only if a getBuffer(minCapacity) is "open". 2699 * 2700 * It will set the string length to newLength, at most to the current capacity. 2701 * If newLength==-1 then it will set the length according to the 2702 * first NUL in the buffer, or to the capacity if there is no NUL. 2703 * 2704 * After calling releaseBuffer(newLength) the UnicodeString is back to normal operation. 2705 * 2706 * @param newLength the new length of the UnicodeString object; 2707 * defaults to the current capacity if newLength is greater than that; 2708 * if newLength==-1, it defaults to u_strlen(buffer) but not more than 2709 * the current capacity of the string 2710 * 2711 * @see getBuffer(int32_t minCapacity) 2712 * @stable ICU 2.0 2713 */ 2714 void releaseBuffer(int32_t newLength=-1); 2715 2716 /** 2717 * Get a read-only pointer to the internal buffer. 2718 * This can be called at any time on a valid UnicodeString. 2719 * 2720 * It returns 0 if the string is bogus, or 2721 * during an "open" getBuffer(minCapacity). 2722 * 2723 * It can be called as many times as desired. 2724 * The pointer that it returns will remain valid until the UnicodeString object is modified, 2725 * at which time the pointer is semantically invalidated and must not be used any more. 2726 * 2727 * The capacity of the buffer can be determined with getCapacity(). 2728 * The part after length() may or may not be initialized and valid, 2729 * depending on the history of the UnicodeString object. 2730 * 2731 * The buffer contents is (probably) not NUL-terminated. 2732 * You can check if it is with 2733 * <code>(s.length()<s.getCapacity() && buffer[s.length()]==0)</code>. 2734 * (See getTerminatedBuffer().) 2735 * 2736 * The buffer may reside in read-only memory. Its contents must not 2737 * be modified. 2738 * 2739 * @return a read-only pointer to the internal string buffer, 2740 * or 0 if the string is empty or bogus 2741 * 2742 * @see getBuffer(int32_t minCapacity) 2743 * @see getTerminatedBuffer() 2744 * @stable ICU 2.0 2745 */ 2746 inline const UChar *getBuffer() const; 2747 2748 /** 2749 * Get a read-only pointer to the internal buffer, 2750 * making sure that it is NUL-terminated. 2751 * This can be called at any time on a valid UnicodeString. 2752 * 2753 * It returns 0 if the string is bogus, or 2754 * during an "open" getBuffer(minCapacity), or if the buffer cannot 2755 * be NUL-terminated (because memory allocation failed). 2756 * 2757 * It can be called as many times as desired. 2758 * The pointer that it returns will remain valid until the UnicodeString object is modified, 2759 * at which time the pointer is semantically invalidated and must not be used any more. 2760 * 2761 * The capacity of the buffer can be determined with getCapacity(). 2762 * The part after length()+1 may or may not be initialized and valid, 2763 * depending on the history of the UnicodeString object. 2764 * 2765 * The buffer contents is guaranteed to be NUL-terminated. 2766 * getTerminatedBuffer() may reallocate the buffer if a terminating NUL 2767 * is written. 2768 * For this reason, this function is not const, unlike getBuffer(). 2769 * Note that a UnicodeString may also contain NUL characters as part of its contents. 2770 * 2771 * The buffer may reside in read-only memory. Its contents must not 2772 * be modified. 2773 * 2774 * @return a read-only pointer to the internal string buffer, 2775 * or 0 if the string is empty or bogus 2776 * 2777 * @see getBuffer(int32_t minCapacity) 2778 * @see getBuffer() 2779 * @stable ICU 2.2 2780 */ 2781 inline const UChar *getTerminatedBuffer(); 2782 2783 //======================================== 2784 // Constructors 2785 //======================================== 2786 2787 /** Construct an empty UnicodeString. 2788 * @stable ICU 2.0 2789 */ 2790 UnicodeString(); 2791 2792 /** 2793 * Construct a UnicodeString with capacity to hold <TT>capacity</TT> UChars 2794 * @param capacity the number of UChars this UnicodeString should hold 2795 * before a resize is necessary; if count is greater than 0 and count 2796 * code points c take up more space than capacity, then capacity is adjusted 2797 * accordingly. 2798 * @param c is used to initially fill the string 2799 * @param count specifies how many code points c are to be written in the 2800 * string 2801 * @stable ICU 2.0 2802 */ 2803 UnicodeString(int32_t capacity, UChar32 c, int32_t count); 2804 2805 /** 2806 * Single UChar (code unit) constructor. 2807 * @param ch the character to place in the UnicodeString 2808 * @stable ICU 2.0 2809 */ 2810 UnicodeString(UChar ch); 2811 2812 /** 2813 * Single UChar32 (code point) constructor. 2814 * @param ch the character to place in the UnicodeString 2815 * @stable ICU 2.0 2816 */ 2817 UnicodeString(UChar32 ch); 2818 2819 /** 2820 * UChar* constructor. 2821 * @param text The characters to place in the UnicodeString. <TT>text</TT> 2822 * must be NULL (U+0000) terminated. 2823 * @stable ICU 2.0 2824 */ 2825 UnicodeString(const UChar *text); 2826 2827 /** 2828 * UChar* constructor. 2829 * @param text The characters to place in the UnicodeString. 2830 * @param textLength The number of Unicode characters in <TT>text</TT> 2831 * to copy. 2832 * @stable ICU 2.0 2833 */ 2834 UnicodeString(const UChar *text, 2835 int32_t textLength); 2836 2837 /** 2838 * Readonly-aliasing UChar* constructor. 2839 * The text will be used for the UnicodeString object, but 2840 * it will not be released when the UnicodeString is destroyed. 2841 * This has copy-on-write semantics: 2842 * When the string is modified, then the buffer is first copied into 2843 * newly allocated memory. 2844 * The aliased buffer is never modified. 2845 * In an assignment to another UnicodeString, the text will be aliased again, 2846 * so that both strings then alias the same readonly-text. 2847 * 2848 * @param isTerminated specifies if <code>text</code> is <code>NUL</code>-terminated. 2849 * This must be true if <code>textLength==-1</code>. 2850 * @param text The characters to alias for the UnicodeString. 2851 * @param textLength The number of Unicode characters in <code>text</code> to alias. 2852 * If -1, then this constructor will determine the length 2853 * by calling <code>u_strlen()</code>. 2854 * @stable ICU 2.0 2855 */ 2856 UnicodeString(UBool isTerminated, 2857 const UChar *text, 2858 int32_t textLength); 2859 2860 /** 2861 * Writable-aliasing UChar* constructor. 2862 * The text will be used for the UnicodeString object, but 2863 * it will not be released when the UnicodeString is destroyed. 2864 * This has write-through semantics: 2865 * For as long as the capacity of the buffer is sufficient, write operations 2866 * will directly affect the buffer. When more capacity is necessary, then 2867 * a new buffer will be allocated and the contents copied as with regularly 2868 * constructed strings. 2869 * In an assignment to another UnicodeString, the buffer will be copied. 2870 * The extract(UChar *dst) function detects whether the dst pointer is the same 2871 * as the string buffer itself and will in this case not copy the contents. 2872 * 2873 * @param buffer The characters to alias for the UnicodeString. 2874 * @param buffLength The number of Unicode characters in <code>buffer</code> to alias. 2875 * @param buffCapacity The size of <code>buffer</code> in UChars. 2876 * @stable ICU 2.0 2877 */ 2878 UnicodeString(UChar *buffer, int32_t buffLength, int32_t buffCapacity); 2879 2880 #if U_CHARSET_IS_UTF8 || !UCONFIG_NO_CONVERSION 2881 2882 /** 2883 * char* constructor. 2884 * @param codepageData an array of bytes, null-terminated, 2885 * in the platform's default codepage. 2886 * @stable ICU 2.0 2887 */ 2888 UnicodeString(const char *codepageData); 2889 2890 /** 2891 * char* constructor. 2892 * @param codepageData an array of bytes in the platform's default codepage. 2893 * @param dataLength The number of bytes in <TT>codepageData</TT>. 2894 * @stable ICU 2.0 2895 */ 2896 UnicodeString(const char *codepageData, int32_t dataLength); 2897 2898 #endif 2899 2900 #if !UCONFIG_NO_CONVERSION 2901 2902 /** 2903 * char* constructor. 2904 * @param codepageData an array of bytes, null-terminated 2905 * @param codepage the encoding of <TT>codepageData</TT>. The special 2906 * value 0 for <TT>codepage</TT> indicates that the text is in the 2907 * platform's default codepage. 2908 * 2909 * If <code>codepage</code> is an empty string (<code>""</code>), 2910 * then a simple conversion is performed on the codepage-invariant 2911 * subset ("invariant characters") of the platform encoding. See utypes.h. 2912 * Recommendation: For invariant-character strings use the constructor 2913 * UnicodeString(const char *src, int32_t length, enum EInvariant inv) 2914 * because it avoids object code dependencies of UnicodeString on 2915 * the conversion code. 2916 * 2917 * @stable ICU 2.0 2918 */ 2919 UnicodeString(const char *codepageData, const char *codepage); 2920 2921 /** 2922 * char* constructor. 2923 * @param codepageData an array of bytes. 2924 * @param dataLength The number of bytes in <TT>codepageData</TT>. 2925 * @param codepage the encoding of <TT>codepageData</TT>. The special 2926 * value 0 for <TT>codepage</TT> indicates that the text is in the 2927 * platform's default codepage. 2928 * If <code>codepage</code> is an empty string (<code>""</code>), 2929 * then a simple conversion is performed on the codepage-invariant 2930 * subset ("invariant characters") of the platform encoding. See utypes.h. 2931 * Recommendation: For invariant-character strings use the constructor 2932 * UnicodeString(const char *src, int32_t length, enum EInvariant inv) 2933 * because it avoids object code dependencies of UnicodeString on 2934 * the conversion code. 2935 * 2936 * @stable ICU 2.0 2937 */ 2938 UnicodeString(const char *codepageData, int32_t dataLength, const char *codepage); 2939 2940 /** 2941 * char * / UConverter constructor. 2942 * This constructor uses an existing UConverter object to 2943 * convert the codepage string to Unicode and construct a UnicodeString 2944 * from that. 2945 * 2946 * The converter is reset at first. 2947 * If the error code indicates a failure before this constructor is called, 2948 * or if an error occurs during conversion or construction, 2949 * then the string will be bogus. 2950 * 2951 * This function avoids the overhead of opening and closing a converter if 2952 * multiple strings are constructed. 2953 * 2954 * @param src input codepage string 2955 * @param srcLength length of the input string, can be -1 for NUL-terminated strings 2956 * @param cnv converter object (ucnv_resetToUnicode() will be called), 2957 * can be NULL for the default converter 2958 * @param errorCode normal ICU error code 2959 * @stable ICU 2.0 2960 */ 2961 UnicodeString( 2962 const char *src, int32_t srcLength, 2963 UConverter *cnv, 2964 UErrorCode &errorCode); 2965 2966 #endif 2967 2968 /** 2969 * Constructs a Unicode string from an invariant-character char * string. 2970 * About invariant characters see utypes.h. 2971 * This constructor has no runtime dependency on conversion code and is 2972 * therefore recommended over ones taking a charset name string 2973 * (where the empty string "" indicates invariant-character conversion). 2974 * 2975 * Use the macro US_INV as the third, signature-distinguishing parameter. 2976 * 2977 * For example: 2978 * \code 2979 * void fn(const char *s) { 2980 * UnicodeString ustr(s, -1, US_INV); 2981 * // use ustr ... 2982 * } 2983 * \endcode 2984 * 2985 * @param src String using only invariant characters. 2986 * @param length Length of src, or -1 if NUL-terminated. 2987 * @param inv Signature-distinguishing paramater, use US_INV. 2988 * 2989 * @see US_INV 2990 * @stable ICU 3.2 2991 */ 2992 UnicodeString(const char *src, int32_t length, enum EInvariant inv); 2993 2994 2995 /** 2996 * Copy constructor. 2997 * @param that The UnicodeString object to copy. 2998 * @stable ICU 2.0 2999 */ 3000 UnicodeString(const UnicodeString& that); 3001 3002 /** 3003 * 'Substring' constructor from tail of source string. 3004 * @param src The UnicodeString object to copy. 3005 * @param srcStart The offset into <tt>src</tt> at which to start copying. 3006 * @stable ICU 2.2 3007 */ 3008 UnicodeString(const UnicodeString& src, int32_t srcStart); 3009 3010 /** 3011 * 'Substring' constructor from subrange of source string. 3012 * @param src The UnicodeString object to copy. 3013 * @param srcStart The offset into <tt>src</tt> at which to start copying. 3014 * @param srcLength The number of characters from <tt>src</tt> to copy. 3015 * @stable ICU 2.2 3016 */ 3017 UnicodeString(const UnicodeString& src, int32_t srcStart, int32_t srcLength); 3018 3019 /** 3020 * Clone this object, an instance of a subclass of Replaceable. 3021 * Clones can be used concurrently in multiple threads. 3022 * If a subclass does not implement clone(), or if an error occurs, 3023 * then NULL is returned. 3024 * The clone functions in all subclasses return a pointer to a Replaceable 3025 * because some compilers do not support covariant (same-as-this) 3026 * return types; cast to the appropriate subclass if necessary. 3027 * The caller must delete the clone. 3028 * 3029 * @return a clone of this object 3030 * 3031 * @see Replaceable::clone 3032 * @see getDynamicClassID 3033 * @stable ICU 2.6 3034 */ 3035 virtual Replaceable *clone() const; 3036 3037 /** Destructor. 3038 * @stable ICU 2.0 3039 */ 3040 virtual ~UnicodeString(); 3041 3042 /** 3043 * Create a UnicodeString from a UTF-8 string. 3044 * Illegal input is replaced with U+FFFD. Otherwise, errors result in a bogus string. 3045 * Calls u_strFromUTF8WithSub(). 3046 * 3047 * @param utf8 UTF-8 input string. 3048 * Note that a StringPiece can be implicitly constructed 3049 * from a std::string or a NUL-terminated const char * string. 3050 * @return A UnicodeString with equivalent UTF-16 contents. 3051 * @see toUTF8 3052 * @see toUTF8String 3053 * @stable ICU 4.2 3054 */ 3055 static UnicodeString fromUTF8(const StringPiece &utf8); 3056 3057 /** 3058 * Create a UnicodeString from a UTF-32 string. 3059 * Illegal input is replaced with U+FFFD. Otherwise, errors result in a bogus string. 3060 * Calls u_strFromUTF32WithSub(). 3061 * 3062 * @param utf32 UTF-32 input string. Must not be NULL. 3063 * @param length Length of the input string, or -1 if NUL-terminated. 3064 * @return A UnicodeString with equivalent UTF-16 contents. 3065 * @see toUTF32 3066 * @stable ICU 4.2 3067 */ 3068 static UnicodeString fromUTF32(const UChar32 *utf32, int32_t length); 3069 3070 /* Miscellaneous operations */ 3071 3072 /** 3073 * Unescape a string of characters and return a string containing 3074 * the result. The following escape sequences are recognized: 3075 * 3076 * \\uhhhh 4 hex digits; h in [0-9A-Fa-f] 3077 * \\Uhhhhhhhh 8 hex digits 3078 * \\xhh 1-2 hex digits 3079 * \\ooo 1-3 octal digits; o in [0-7] 3080 * \\cX control-X; X is masked with 0x1F 3081 * 3082 * as well as the standard ANSI C escapes: 3083 * 3084 * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A, 3085 * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B, 3086 * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C 3087 * 3088 * Anything else following a backslash is generically escaped. For 3089 * example, "[a\\-z]" returns "[a-z]". 3090 * 3091 * If an escape sequence is ill-formed, this method returns an empty 3092 * string. An example of an ill-formed sequence is "\\u" followed by 3093 * fewer than 4 hex digits. 3094 * 3095 * This function is similar to u_unescape() but not identical to it. 3096 * The latter takes a source char*, so it does escape recognition 3097 * and also invariant conversion. 3098 * 3099 * @return a string with backslash escapes interpreted, or an 3100 * empty string on error. 3101 * @see UnicodeString#unescapeAt() 3102 * @see u_unescape() 3103 * @see u_unescapeAt() 3104 * @stable ICU 2.0 3105 */ 3106 UnicodeString unescape() const; 3107 3108 /** 3109 * Unescape a single escape sequence and return the represented 3110 * character. See unescape() for a listing of the recognized escape 3111 * sequences. The character at offset-1 is assumed (without 3112 * checking) to be a backslash. If the escape sequence is 3113 * ill-formed, or the offset is out of range, (UChar32)0xFFFFFFFF is 3114 * returned. 3115 * 3116 * @param offset an input output parameter. On input, it is the 3117 * offset into this string where the escape sequence is located, 3118 * after the initial backslash. On output, it is advanced after the 3119 * last character parsed. On error, it is not advanced at all. 3120 * @return the character represented by the escape sequence at 3121 * offset, or (UChar32)0xFFFFFFFF on error. 3122 * @see UnicodeString#unescape() 3123 * @see u_unescape() 3124 * @see u_unescapeAt() 3125 * @stable ICU 2.0 3126 */ 3127 UChar32 unescapeAt(int32_t &offset) const; 3128 3129 /** 3130 * ICU "poor man's RTTI", returns a UClassID for this class. 3131 * 3132 * @stable ICU 2.2 3133 */ 3134 static UClassID U_EXPORT2 getStaticClassID(); 3135 3136 /** 3137 * ICU "poor man's RTTI", returns a UClassID for the actual class. 3138 * 3139 * @stable ICU 2.2 3140 */ 3141 virtual UClassID getDynamicClassID() const; 3142 3143 //======================================== 3144 // Implementation methods 3145 //======================================== 3146 3147 protected: 3148 /** 3149 * Implement Replaceable::getLength() (see jitterbug 1027). 3150 * @stable ICU 2.4 3151 */ 3152 virtual int32_t getLength() const; 3153 3154 /** 3155 * The change in Replaceable to use virtual getCharAt() allows 3156 * UnicodeString::charAt() to be inline again (see jitterbug 709). 3157 * @stable ICU 2.4 3158 */ 3159 virtual UChar getCharAt(int32_t offset) const; 3160 3161 /** 3162 * The change in Replaceable to use virtual getChar32At() allows 3163 * UnicodeString::char32At() to be inline again (see jitterbug 709). 3164 * @stable ICU 2.4 3165 */ 3166 virtual UChar32 getChar32At(int32_t offset) const; 3167 3168 private: 3169 // For char* constructors. Could be made public. 3170 UnicodeString &setToUTF8(const StringPiece &utf8); 3171 // For extract(char*). 3172 // We could make a toUTF8(target, capacity, errorCode) public but not 3173 // this version: New API will be cleaner if we make callers create substrings 3174 // rather than having start+length on every method, 3175 // and it should take a UErrorCode&. 3176 int32_t 3177 toUTF8(int32_t start, int32_t len, 3178 char *target, int32_t capacity) const; 3179 3180 3181 inline int8_t 3182 doCompare(int32_t start, 3183 int32_t length, 3184 const UnicodeString& srcText, 3185 int32_t srcStart, 3186 int32_t srcLength) const; 3187 3188 int8_t doCompare(int32_t start, 3189 int32_t length, 3190 const UChar *srcChars, 3191 int32_t srcStart, 3192 int32_t srcLength) const; 3193 3194 inline int8_t 3195 doCompareCodePointOrder(int32_t start, 3196 int32_t length, 3197 const UnicodeString& srcText, 3198 int32_t srcStart, 3199 int32_t srcLength) const; 3200 3201 int8_t doCompareCodePointOrder(int32_t start, 3202 int32_t length, 3203 const UChar *srcChars, 3204 int32_t srcStart, 3205 int32_t srcLength) const; 3206 3207 inline int8_t 3208 doCaseCompare(int32_t start, 3209 int32_t length, 3210 const UnicodeString &srcText, 3211 int32_t srcStart, 3212 int32_t srcLength, 3213 uint32_t options) const; 3214 3215 int8_t 3216 doCaseCompare(int32_t start, 3217 int32_t length, 3218 const UChar *srcChars, 3219 int32_t srcStart, 3220 int32_t srcLength, 3221 uint32_t options) const; 3222 3223 int32_t doIndexOf(UChar c, 3224 int32_t start, 3225 int32_t length) const; 3226 3227 int32_t doIndexOf(UChar32 c, 3228 int32_t start, 3229 int32_t length) const; 3230 3231 int32_t doLastIndexOf(UChar c, 3232 int32_t start, 3233 int32_t length) const; 3234 3235 int32_t doLastIndexOf(UChar32 c, 3236 int32_t start, 3237 int32_t length) const; 3238 3239 void doExtract(int32_t start, 3240 int32_t length, 3241 UChar *dst, 3242 int32_t dstStart) const; 3243 3244 inline void doExtract(int32_t start, 3245 int32_t length, 3246 UnicodeString& target) const; 3247 3248 inline UChar doCharAt(int32_t offset) const; 3249 3250 UnicodeString& doReplace(int32_t start, 3251 int32_t length, 3252 const UnicodeString& srcText, 3253 int32_t srcStart, 3254 int32_t srcLength); 3255 3256 UnicodeString& doReplace(int32_t start, 3257 int32_t length, 3258 const UChar *srcChars, 3259 int32_t srcStart, 3260 int32_t srcLength); 3261 3262 UnicodeString& doReverse(int32_t start, 3263 int32_t length); 3264 3265 // calculate hash code 3266 int32_t doHashCode(void) const; 3267 3268 // get pointer to start of array 3269 // these do not check for kOpenGetBuffer, unlike the public getBuffer() function 3270 inline UChar* getArrayStart(void); 3271 inline const UChar* getArrayStart(void) const; 3272 3273 // A UnicodeString object (not necessarily its current buffer) 3274 // is writable unless it isBogus() or it has an "open" getBuffer(minCapacity). 3275 inline UBool isWritable() const; 3276 3277 // Is the current buffer writable? 3278 inline UBool isBufferWritable() const; 3279 3280 // None of the following does releaseArray(). 3281 inline void setLength(int32_t len); // sets only fShortLength and fLength 3282 inline void setToEmpty(); // sets fFlags=kShortString 3283 inline void setArray(UChar *array, int32_t len, int32_t capacity); // does not set fFlags 3284 3285 // allocate the array; result may be fStackBuffer 3286 // sets refCount to 1 if appropriate 3287 // sets fArray, fCapacity, and fFlags 3288 // returns boolean for success or failure 3289 UBool allocate(int32_t capacity); 3290 3291 // release the array if owned 3292 void releaseArray(void); 3293 3294 // turn a bogus string into an empty one 3295 void unBogus(); 3296 3297 // implements assigment operator, copy constructor, and fastCopyFrom() 3298 UnicodeString ©From(const UnicodeString &src, UBool fastCopy=FALSE); 3299 3300 // Pin start and limit to acceptable values. 3301 inline void pinIndex(int32_t& start) const; 3302 inline void pinIndices(int32_t& start, 3303 int32_t& length) const; 3304 3305 #if !UCONFIG_NO_CONVERSION 3306 3307 /* Internal extract() using UConverter. */ 3308 int32_t doExtract(int32_t start, int32_t length, 3309 char *dest, int32_t destCapacity, 3310 UConverter *cnv, 3311 UErrorCode &errorCode) const; 3312 3313 /* 3314 * Real constructor for converting from codepage data. 3315 * It assumes that it is called with !fRefCounted. 3316 * 3317 * If <code>codepage==0</code>, then the default converter 3318 * is used for the platform encoding. 3319 * If <code>codepage</code> is an empty string (<code>""</code>), 3320 * then a simple conversion is performed on the codepage-invariant 3321 * subset ("invariant characters") of the platform encoding. See utypes.h. 3322 */ 3323 void doCodepageCreate(const char *codepageData, 3324 int32_t dataLength, 3325 const char *codepage); 3326 3327 /* 3328 * Worker function for creating a UnicodeString from 3329 * a codepage string using a UConverter. 3330 */ 3331 void 3332 doCodepageCreate(const char *codepageData, 3333 int32_t dataLength, 3334 UConverter *converter, 3335 UErrorCode &status); 3336 3337 #endif 3338 3339 /* 3340 * This function is called when write access to the array 3341 * is necessary. 3342 * 3343 * We need to make a copy of the array if 3344 * the buffer is read-only, or 3345 * the buffer is refCounted (shared), and refCount>1, or 3346 * the buffer is too small. 3347 * 3348 * Return FALSE if memory could not be allocated. 3349 */ 3350 UBool cloneArrayIfNeeded(int32_t newCapacity = -1, 3351 int32_t growCapacity = -1, 3352 UBool doCopyArray = TRUE, 3353 int32_t **pBufferToDelete = 0, 3354 UBool forceClone = FALSE); 3355 3356 // common function for case mappings 3357 UnicodeString & 3358 caseMap(BreakIterator *titleIter, 3359 const char *locale, 3360 uint32_t options, 3361 int32_t toWhichCase); 3362 3363 // ref counting 3364 void addRef(void); 3365 int32_t removeRef(void); 3366 int32_t refCount(void) const; 3367 3368 // constants 3369 enum { 3370 // Set the stack buffer size so that sizeof(UnicodeString) is a multiple of sizeof(pointer): 3371 // 32-bit pointers: 4+1+1+13*2 = 32 bytes 3372 // 64-bit pointers: 8+1+1+15*2 = 40 bytes 3373 US_STACKBUF_SIZE= sizeof(void *)==4 ? 13 : 15, // Size of stack buffer for small strings 3374 kInvalidUChar=0xffff, // invalid UChar index 3375 kGrowSize=128, // grow size for this buffer 3376 kInvalidHashCode=0, // invalid hash code 3377 kEmptyHashCode=1, // hash code for empty string 3378 3379 // bit flag values for fFlags 3380 kIsBogus=1, // this string is bogus, i.e., not valid or NULL 3381 kUsingStackBuffer=2,// fArray==fStackBuffer 3382 kRefCounted=4, // there is a refCount field before the characters in fArray 3383 kBufferIsReadonly=8,// do not write to this buffer 3384 kOpenGetBuffer=16, // getBuffer(minCapacity) was called (is "open"), 3385 // and releaseBuffer(newLength) must be called 3386 3387 // combined values for convenience 3388 kShortString=kUsingStackBuffer, 3389 kLongString=kRefCounted, 3390 kReadonlyAlias=kBufferIsReadonly, 3391 kWritableAlias=0 3392 }; 3393 3394 friend class StringThreadTest; 3395 3396 union StackBufferOrFields; // forward declaration necessary before friend declaration 3397 friend union StackBufferOrFields; // make US_STACKBUF_SIZE visible inside fUnion 3398 3399 /* 3400 * The following are all the class fields that are stored 3401 * in each UnicodeString object. 3402 * Note that UnicodeString has virtual functions, 3403 * therefore there is an implicit vtable pointer 3404 * as the first real field. 3405 * The fields should be aligned such that no padding is 3406 * necessary, mostly by having larger types first. 3407 * On 32-bit machines, the size should be 32 bytes, 3408 * on 64-bit machines (8-byte pointers), it should be 40 bytes. 3409 */ 3410 // (implicit) *vtable; 3411 int8_t fShortLength; // 0..127: length <0: real length is in fUnion.fFields.fLength 3412 uint8_t fFlags; // bit flags: see constants above 3413 union StackBufferOrFields { 3414 // fStackBuffer is used iff (fFlags&kUsingStackBuffer) 3415 // else fFields is used 3416 UChar fStackBuffer [US_STACKBUF_SIZE]; // buffer for small strings 3417 struct { 3418 uint16_t fPadding; // align the following field at 8B (32b pointers) or 12B (64b) 3419 int32_t fLength; // number of characters in fArray if >127; else undefined 3420 UChar *fArray; // the Unicode data (aligned at 12B (32b pointers) or 16B (64b)) 3421 int32_t fCapacity; // sizeof fArray 3422 } fFields; 3423 } fUnion; 3424 }; 3425 3426 /** 3427 * Create a new UnicodeString with the concatenation of two others. 3428 * 3429 * @param s1 The first string to be copied to the new one. 3430 * @param s2 The second string to be copied to the new one, after s1. 3431 * @return UnicodeString(s1).append(s2) 3432 * @stable ICU 2.8 3433 */ 3434 U_COMMON_API UnicodeString U_EXPORT2 3435 operator+ (const UnicodeString &s1, const UnicodeString &s2); 3436 3437 //======================================== 3438 // Inline members 3439 //======================================== 3440 3441 //======================================== 3442 // Privates 3443 //======================================== 3444 3445 inline void 3446 UnicodeString::pinIndex(int32_t& start) const 3447 { 3448 // pin index 3449 if(start < 0) { 3450 start = 0; 3451 } else if(start > length()) { 3452 start = length(); 3453 } 3454 } 3455 3456 inline void 3457 UnicodeString::pinIndices(int32_t& start, 3458 int32_t& _length) const 3459 { 3460 // pin indices 3461 int32_t len = length(); 3462 if(start < 0) { 3463 start = 0; 3464 } else if(start > len) { 3465 start = len; 3466 } 3467 if(_length < 0) { 3468 _length = 0; 3469 } else if(_length > (len - start)) { 3470 _length = (len - start); 3471 } 3472 } 3473 3474 inline UChar* 3475 UnicodeString::getArrayStart() 3476 { return (fFlags&kUsingStackBuffer) ? fUnion.fStackBuffer : fUnion.fFields.fArray; } 3477 3478 inline const UChar* 3479 UnicodeString::getArrayStart() const 3480 { return (fFlags&kUsingStackBuffer) ? fUnion.fStackBuffer : fUnion.fFields.fArray; } 3481 3482 //======================================== 3483 // Read-only implementation methods 3484 //======================================== 3485 inline int32_t 3486 UnicodeString::length() const 3487 { return fShortLength>=0 ? fShortLength : fUnion.fFields.fLength; } 3488 3489 inline int32_t 3490 UnicodeString::getCapacity() const 3491 { return (fFlags&kUsingStackBuffer) ? US_STACKBUF_SIZE : fUnion.fFields.fCapacity; } 3492 3493 inline int32_t 3494 UnicodeString::hashCode() const 3495 { return doHashCode(); } 3496 3497 inline UBool 3498 UnicodeString::isBogus() const 3499 { return (UBool)(fFlags & kIsBogus); } 3500 3501 inline UBool 3502 UnicodeString::isWritable() const 3503 { return (UBool)!(fFlags&(kOpenGetBuffer|kIsBogus)); } 3504 3505 inline UBool 3506 UnicodeString::isBufferWritable() const 3507 { 3508 return (UBool)( 3509 !(fFlags&(kOpenGetBuffer|kIsBogus|kBufferIsReadonly)) && 3510 (!(fFlags&kRefCounted) || refCount()==1)); 3511 } 3512 3513 inline const UChar * 3514 UnicodeString::getBuffer() const { 3515 if(fFlags&(kIsBogus|kOpenGetBuffer)) { 3516 return 0; 3517 } else if(fFlags&kUsingStackBuffer) { 3518 return fUnion.fStackBuffer; 3519 } else { 3520 return fUnion.fFields.fArray; 3521 } 3522 } 3523 3524 //======================================== 3525 // Read-only alias methods 3526 //======================================== 3527 inline int8_t 3528 UnicodeString::doCompare(int32_t start, 3529 int32_t thisLength, 3530 const UnicodeString& srcText, 3531 int32_t srcStart, 3532 int32_t srcLength) const 3533 { 3534 if(srcText.isBogus()) { 3535 return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise 3536 } else { 3537 srcText.pinIndices(srcStart, srcLength); 3538 return doCompare(start, thisLength, srcText.getArrayStart(), srcStart, srcLength); 3539 } 3540 } 3541 3542 inline UBool 3543 UnicodeString::operator== (const UnicodeString& text) const 3544 { 3545 if(isBogus()) { 3546 return text.isBogus(); 3547 } else { 3548 int32_t len = length(), textLength = text.length(); 3549 return 3550 !text.isBogus() && 3551 len == textLength && 3552 doCompare(0, len, text, 0, textLength) == 0; 3553 } 3554 } 3555 3556 inline UBool 3557 UnicodeString::operator!= (const UnicodeString& text) const 3558 { return (! operator==(text)); } 3559 3560 inline UBool 3561 UnicodeString::operator> (const UnicodeString& text) const 3562 { return doCompare(0, length(), text, 0, text.length()) == 1; } 3563 3564 inline UBool 3565 UnicodeString::operator< (const UnicodeString& text) const 3566 { return doCompare(0, length(), text, 0, text.length()) == -1; } 3567 3568 inline UBool 3569 UnicodeString::operator>= (const UnicodeString& text) const 3570 { return doCompare(0, length(), text, 0, text.length()) != -1; } 3571 3572 inline UBool 3573 UnicodeString::operator<= (const UnicodeString& text) const 3574 { return doCompare(0, length(), text, 0, text.length()) != 1; } 3575 3576 inline int8_t 3577 UnicodeString::compare(const UnicodeString& text) const 3578 { return doCompare(0, length(), text, 0, text.length()); } 3579 3580 inline int8_t 3581 UnicodeString::compare(int32_t start, 3582 int32_t _length, 3583 const UnicodeString& srcText) const 3584 { return doCompare(start, _length, srcText, 0, srcText.length()); } 3585 3586 inline int8_t 3587 UnicodeString::compare(const UChar *srcChars, 3588 int32_t srcLength) const 3589 { return doCompare(0, length(), srcChars, 0, srcLength); } 3590 3591 inline int8_t 3592 UnicodeString::compare(int32_t start, 3593 int32_t _length, 3594 const UnicodeString& srcText, 3595 int32_t srcStart, 3596 int32_t srcLength) const 3597 { return doCompare(start, _length, srcText, srcStart, srcLength); } 3598 3599 inline int8_t 3600 UnicodeString::compare(int32_t start, 3601 int32_t _length, 3602 const UChar *srcChars) const 3603 { return doCompare(start, _length, srcChars, 0, _length); } 3604 3605 inline int8_t 3606 UnicodeString::compare(int32_t start, 3607 int32_t _length, 3608 const UChar *srcChars, 3609 int32_t srcStart, 3610 int32_t srcLength) const 3611 { return doCompare(start, _length, srcChars, srcStart, srcLength); } 3612 3613 inline int8_t 3614 UnicodeString::compareBetween(int32_t start, 3615 int32_t limit, 3616 const UnicodeString& srcText, 3617 int32_t srcStart, 3618 int32_t srcLimit) const 3619 { return doCompare(start, limit - start, 3620 srcText, srcStart, srcLimit - srcStart); } 3621 3622 inline int8_t 3623 UnicodeString::doCompareCodePointOrder(int32_t start, 3624 int32_t thisLength, 3625 const UnicodeString& srcText, 3626 int32_t srcStart, 3627 int32_t srcLength) const 3628 { 3629 if(srcText.isBogus()) { 3630 return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise 3631 } else { 3632 srcText.pinIndices(srcStart, srcLength); 3633 return doCompareCodePointOrder(start, thisLength, srcText.getArrayStart(), srcStart, srcLength); 3634 } 3635 } 3636 3637 inline int8_t 3638 UnicodeString::compareCodePointOrder(const UnicodeString& text) const 3639 { return doCompareCodePointOrder(0, length(), text, 0, text.length()); } 3640 3641 inline int8_t 3642 UnicodeString::compareCodePointOrder(int32_t start, 3643 int32_t _length, 3644 const UnicodeString& srcText) const 3645 { return doCompareCodePointOrder(start, _length, srcText, 0, srcText.length()); } 3646 3647 inline int8_t 3648 UnicodeString::compareCodePointOrder(const UChar *srcChars, 3649 int32_t srcLength) const 3650 { return doCompareCodePointOrder(0, length(), srcChars, 0, srcLength); } 3651 3652 inline int8_t 3653 UnicodeString::compareCodePointOrder(int32_t start, 3654 int32_t _length, 3655 const UnicodeString& srcText, 3656 int32_t srcStart, 3657 int32_t srcLength) const 3658 { return doCompareCodePointOrder(start, _length, srcText, srcStart, srcLength); } 3659 3660 inline int8_t 3661 UnicodeString::compareCodePointOrder(int32_t start, 3662 int32_t _length, 3663 const UChar *srcChars) const 3664 { return doCompareCodePointOrder(start, _length, srcChars, 0, _length); } 3665 3666 inline int8_t 3667 UnicodeString::compareCodePointOrder(int32_t start, 3668 int32_t _length, 3669 const UChar *srcChars, 3670 int32_t srcStart, 3671 int32_t srcLength) const 3672 { return doCompareCodePointOrder(start, _length, srcChars, srcStart, srcLength); } 3673 3674 inline int8_t 3675 UnicodeString::compareCodePointOrderBetween(int32_t start, 3676 int32_t limit, 3677 const UnicodeString& srcText, 3678 int32_t srcStart, 3679 int32_t srcLimit) const 3680 { return doCompareCodePointOrder(start, limit - start, 3681 srcText, srcStart, srcLimit - srcStart); } 3682 3683 inline int8_t 3684 UnicodeString::doCaseCompare(int32_t start, 3685 int32_t thisLength, 3686 const UnicodeString &srcText, 3687 int32_t srcStart, 3688 int32_t srcLength, 3689 uint32_t options) const 3690 { 3691 if(srcText.isBogus()) { 3692 return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise 3693 } else { 3694 srcText.pinIndices(srcStart, srcLength); 3695 return doCaseCompare(start, thisLength, srcText.getArrayStart(), srcStart, srcLength, options); 3696 } 3697 } 3698 3699 inline int8_t 3700 UnicodeString::caseCompare(const UnicodeString &text, uint32_t options) const { 3701 return doCaseCompare(0, length(), text, 0, text.length(), options); 3702 } 3703 3704 inline int8_t 3705 UnicodeString::caseCompare(int32_t start, 3706 int32_t _length, 3707 const UnicodeString &srcText, 3708 uint32_t options) const { 3709 return doCaseCompare(start, _length, srcText, 0, srcText.length(), options); 3710 } 3711 3712 inline int8_t 3713 UnicodeString::caseCompare(const UChar *srcChars, 3714 int32_t srcLength, 3715 uint32_t options) const { 3716 return doCaseCompare(0, length(), srcChars, 0, srcLength, options); 3717 } 3718 3719 inline int8_t 3720 UnicodeString::caseCompare(int32_t start, 3721 int32_t _length, 3722 const UnicodeString &srcText, 3723 int32_t srcStart, 3724 int32_t srcLength, 3725 uint32_t options) const { 3726 return doCaseCompare(start, _length, srcText, srcStart, srcLength, options); 3727 } 3728 3729 inline int8_t 3730 UnicodeString::caseCompare(int32_t start, 3731 int32_t _length, 3732 const UChar *srcChars, 3733 uint32_t options) const { 3734 return doCaseCompare(start, _length, srcChars, 0, _length, options); 3735 } 3736 3737 inline int8_t 3738 UnicodeString::caseCompare(int32_t start, 3739 int32_t _length, 3740 const UChar *srcChars, 3741 int32_t srcStart, 3742 int32_t srcLength, 3743 uint32_t options) const { 3744 return doCaseCompare(start, _length, srcChars, srcStart, srcLength, options); 3745 } 3746 3747 inline int8_t 3748 UnicodeString::caseCompareBetween(int32_t start, 3749 int32_t limit, 3750 const UnicodeString &srcText, 3751 int32_t srcStart, 3752 int32_t srcLimit, 3753 uint32_t options) const { 3754 return doCaseCompare(start, limit - start, srcText, srcStart, srcLimit - srcStart, options); 3755 } 3756 3757 inline int32_t 3758 UnicodeString::indexOf(const UnicodeString& srcText, 3759 int32_t srcStart, 3760 int32_t srcLength, 3761 int32_t start, 3762 int32_t _length) const 3763 { 3764 if(!srcText.isBogus()) { 3765 srcText.pinIndices(srcStart, srcLength); 3766 if(srcLength > 0) { 3767 return indexOf(srcText.getArrayStart(), srcStart, srcLength, start, _length); 3768 } 3769 } 3770 return -1; 3771 } 3772 3773 inline int32_t 3774 UnicodeString::indexOf(const UnicodeString& text) const 3775 { return indexOf(text, 0, text.length(), 0, length()); } 3776 3777 inline int32_t 3778 UnicodeString::indexOf(const UnicodeString& text, 3779 int32_t start) const { 3780 pinIndex(start); 3781 return indexOf(text, 0, text.length(), start, length() - start); 3782 } 3783 3784 inline int32_t 3785 UnicodeString::indexOf(const UnicodeString& text, 3786 int32_t start, 3787 int32_t _length) const 3788 { return indexOf(text, 0, text.length(), start, _length); } 3789 3790 inline int32_t 3791 UnicodeString::indexOf(const UChar *srcChars, 3792 int32_t srcLength, 3793 int32_t start) const { 3794 pinIndex(start); 3795 return indexOf(srcChars, 0, srcLength, start, length() - start); 3796 } 3797 3798 inline int32_t 3799 UnicodeString::indexOf(const UChar *srcChars, 3800 int32_t srcLength, 3801 int32_t start, 3802 int32_t _length) const 3803 { return indexOf(srcChars, 0, srcLength, start, _length); } 3804 3805 inline int32_t 3806 UnicodeString::indexOf(UChar c, 3807 int32_t start, 3808 int32_t _length) const 3809 { return doIndexOf(c, start, _length); } 3810 3811 inline int32_t 3812 UnicodeString::indexOf(UChar32 c, 3813 int32_t start, 3814 int32_t _length) const 3815 { return doIndexOf(c, start, _length); } 3816 3817 inline int32_t 3818 UnicodeString::indexOf(UChar c) const 3819 { return doIndexOf(c, 0, length()); } 3820 3821 inline int32_t 3822 UnicodeString::indexOf(UChar32 c) const 3823 { return indexOf(c, 0, length()); } 3824 3825 inline int32_t 3826 UnicodeString::indexOf(UChar c, 3827 int32_t start) const { 3828 pinIndex(start); 3829 return doIndexOf(c, start, length() - start); 3830 } 3831 3832 inline int32_t 3833 UnicodeString::indexOf(UChar32 c, 3834 int32_t start) const { 3835 pinIndex(start); 3836 return indexOf(c, start, length() - start); 3837 } 3838 3839 inline int32_t 3840 UnicodeString::lastIndexOf(const UChar *srcChars, 3841 int32_t srcLength, 3842 int32_t start, 3843 int32_t _length) const 3844 { return lastIndexOf(srcChars, 0, srcLength, start, _length); } 3845 3846 inline int32_t 3847 UnicodeString::lastIndexOf(const UChar *srcChars, 3848 int32_t srcLength, 3849 int32_t start) const { 3850 pinIndex(start); 3851 return lastIndexOf(srcChars, 0, srcLength, start, length() - start); 3852 } 3853 3854 inline int32_t 3855 UnicodeString::lastIndexOf(const UnicodeString& srcText, 3856 int32_t srcStart, 3857 int32_t srcLength, 3858 int32_t start, 3859 int32_t _length) const 3860 { 3861 if(!srcText.isBogus()) { 3862 srcText.pinIndices(srcStart, srcLength); 3863 if(srcLength > 0) { 3864 return lastIndexOf(srcText.getArrayStart(), srcStart, srcLength, start, _length); 3865 } 3866 } 3867 return -1; 3868 } 3869 3870 inline int32_t 3871 UnicodeString::lastIndexOf(const UnicodeString& text, 3872 int32_t start, 3873 int32_t _length) const 3874 { return lastIndexOf(text, 0, text.length(), start, _length); } 3875 3876 inline int32_t 3877 UnicodeString::lastIndexOf(const UnicodeString& text, 3878 int32_t start) const { 3879 pinIndex(start); 3880 return lastIndexOf(text, 0, text.length(), start, length() - start); 3881 } 3882 3883 inline int32_t 3884 UnicodeString::lastIndexOf(const UnicodeString& text) const 3885 { return lastIndexOf(text, 0, text.length(), 0, length()); } 3886 3887 inline int32_t 3888 UnicodeString::lastIndexOf(UChar c, 3889 int32_t start, 3890 int32_t _length) const 3891 { return doLastIndexOf(c, start, _length); } 3892 3893 inline int32_t 3894 UnicodeString::lastIndexOf(UChar32 c, 3895 int32_t start, 3896 int32_t _length) const { 3897 return doLastIndexOf(c, start, _length); 3898 } 3899 3900 inline int32_t 3901 UnicodeString::lastIndexOf(UChar c) const 3902 { return doLastIndexOf(c, 0, length()); } 3903 3904 inline int32_t 3905 UnicodeString::lastIndexOf(UChar32 c) const { 3906 return lastIndexOf(c, 0, length()); 3907 } 3908 3909 inline int32_t 3910 UnicodeString::lastIndexOf(UChar c, 3911 int32_t start) const { 3912 pinIndex(start); 3913 return doLastIndexOf(c, start, length() - start); 3914 } 3915 3916 inline int32_t 3917 UnicodeString::lastIndexOf(UChar32 c, 3918 int32_t start) const { 3919 pinIndex(start); 3920 return lastIndexOf(c, start, length() - start); 3921 } 3922 3923 inline UBool 3924 UnicodeString::startsWith(const UnicodeString& text) const 3925 { return compare(0, text.length(), text, 0, text.length()) == 0; } 3926 3927 inline UBool 3928 UnicodeString::startsWith(const UnicodeString& srcText, 3929 int32_t srcStart, 3930 int32_t srcLength) const 3931 { return doCompare(0, srcLength, srcText, srcStart, srcLength) == 0; } 3932 3933 inline UBool 3934 UnicodeString::startsWith(const UChar *srcChars, 3935 int32_t srcLength) const 3936 { return doCompare(0, srcLength, srcChars, 0, srcLength) == 0; } 3937 3938 inline UBool 3939 UnicodeString::startsWith(const UChar *srcChars, 3940 int32_t srcStart, 3941 int32_t srcLength) const 3942 { return doCompare(0, srcLength, srcChars, srcStart, srcLength) == 0;} 3943 3944 inline UBool 3945 UnicodeString::endsWith(const UnicodeString& text) const 3946 { return doCompare(length() - text.length(), text.length(), 3947 text, 0, text.length()) == 0; } 3948 3949 inline UBool 3950 UnicodeString::endsWith(const UnicodeString& srcText, 3951 int32_t srcStart, 3952 int32_t srcLength) const { 3953 srcText.pinIndices(srcStart, srcLength); 3954 return doCompare(length() - srcLength, srcLength, 3955 srcText, srcStart, srcLength) == 0; 3956 } 3957 3958 inline UBool 3959 UnicodeString::endsWith(const UChar *srcChars, 3960 int32_t srcLength) const { 3961 if(srcLength < 0) { 3962 srcLength = u_strlen(srcChars); 3963 } 3964 return doCompare(length() - srcLength, srcLength, 3965 srcChars, 0, srcLength) == 0; 3966 } 3967 3968 inline UBool 3969 UnicodeString::endsWith(const UChar *srcChars, 3970 int32_t srcStart, 3971 int32_t srcLength) const { 3972 if(srcLength < 0) { 3973 srcLength = u_strlen(srcChars + srcStart); 3974 } 3975 return doCompare(length() - srcLength, srcLength, 3976 srcChars, srcStart, srcLength) == 0; 3977 } 3978 3979 //======================================== 3980 // replace 3981 //======================================== 3982 inline UnicodeString& 3983 UnicodeString::replace(int32_t start, 3984 int32_t _length, 3985 const UnicodeString& srcText) 3986 { return doReplace(start, _length, srcText, 0, srcText.length()); } 3987 3988 inline UnicodeString& 3989 UnicodeString::replace(int32_t start, 3990 int32_t _length, 3991 const UnicodeString& srcText, 3992 int32_t srcStart, 3993 int32_t srcLength) 3994 { return doReplace(start, _length, srcText, srcStart, srcLength); } 3995 3996 inline UnicodeString& 3997 UnicodeString::replace(int32_t start, 3998 int32_t _length, 3999 const UChar *srcChars, 4000 int32_t srcLength) 4001 { return doReplace(start, _length, srcChars, 0, srcLength); } 4002 4003 inline UnicodeString& 4004 UnicodeString::replace(int32_t start, 4005 int32_t _length, 4006 const UChar *srcChars, 4007 int32_t srcStart, 4008 int32_t srcLength) 4009 { return doReplace(start, _length, srcChars, srcStart, srcLength); } 4010 4011 inline UnicodeString& 4012 UnicodeString::replace(int32_t start, 4013 int32_t _length, 4014 UChar srcChar) 4015 { return doReplace(start, _length, &srcChar, 0, 1); } 4016 4017 inline UnicodeString& 4018 UnicodeString::replace(int32_t start, 4019 int32_t _length, 4020 UChar32 srcChar) { 4021 UChar buffer[U16_MAX_LENGTH]; 4022 int32_t count = 0; 4023 UBool isError = FALSE; 4024 U16_APPEND(buffer, count, U16_MAX_LENGTH, srcChar, isError); 4025 return doReplace(start, _length, buffer, 0, count); 4026 } 4027 4028 inline UnicodeString& 4029 UnicodeString::replaceBetween(int32_t start, 4030 int32_t limit, 4031 const UnicodeString& srcText) 4032 { return doReplace(start, limit - start, srcText, 0, srcText.length()); } 4033 4034 inline UnicodeString& 4035 UnicodeString::replaceBetween(int32_t start, 4036 int32_t limit, 4037 const UnicodeString& srcText, 4038 int32_t srcStart, 4039 int32_t srcLimit) 4040 { return doReplace(start, limit - start, srcText, srcStart, srcLimit - srcStart); } 4041 4042 inline UnicodeString& 4043 UnicodeString::findAndReplace(const UnicodeString& oldText, 4044 const UnicodeString& newText) 4045 { return findAndReplace(0, length(), oldText, 0, oldText.length(), 4046 newText, 0, newText.length()); } 4047 4048 inline UnicodeString& 4049 UnicodeString::findAndReplace(int32_t start, 4050 int32_t _length, 4051 const UnicodeString& oldText, 4052 const UnicodeString& newText) 4053 { return findAndReplace(start, _length, oldText, 0, oldText.length(), 4054 newText, 0, newText.length()); } 4055 4056 // ============================ 4057 // extract 4058 // ============================ 4059 inline void 4060 UnicodeString::doExtract(int32_t start, 4061 int32_t _length, 4062 UnicodeString& target) const 4063 { target.replace(0, target.length(), *this, start, _length); } 4064 4065 inline void 4066 UnicodeString::extract(int32_t start, 4067 int32_t _length, 4068 UChar *target, 4069 int32_t targetStart) const 4070 { doExtract(start, _length, target, targetStart); } 4071 4072 inline void 4073 UnicodeString::extract(int32_t start, 4074 int32_t _length, 4075 UnicodeString& target) const 4076 { doExtract(start, _length, target); } 4077 4078 #if !UCONFIG_NO_CONVERSION 4079 4080 inline int32_t 4081 UnicodeString::extract(int32_t start, 4082 int32_t _length, 4083 char *dst, 4084 const char *codepage) const 4085 4086 { 4087 // This dstSize value will be checked explicitly 4088 #if defined(__GNUC__) 4089 // Ticket #7039: Clip length to the maximum valid length to the end of addressable memory given the starting address 4090 // This is only an issue when using GCC and certain optimizations are turned on. 4091 return extract(start, _length, dst, dst!=0 ? ((dst >= (char*)((size_t)-1) - UINT32_MAX) ? (((char*)UINT32_MAX) - dst) : UINT32_MAX) : 0, codepage); 4092 #else 4093 return extract(start, _length, dst, dst!=0 ? 0xffffffff : 0, codepage); 4094 #endif 4095 } 4096 4097 #endif 4098 4099 inline void 4100 UnicodeString::extractBetween(int32_t start, 4101 int32_t limit, 4102 UChar *dst, 4103 int32_t dstStart) const { 4104 pinIndex(start); 4105 pinIndex(limit); 4106 doExtract(start, limit - start, dst, dstStart); 4107 } 4108 4109 inline UnicodeString 4110 UnicodeString::tempSubStringBetween(int32_t start, int32_t limit) const { 4111 return tempSubString(start, limit - start); 4112 } 4113 4114 inline UChar 4115 UnicodeString::doCharAt(int32_t offset) const 4116 { 4117 if((uint32_t)offset < (uint32_t)length()) { 4118 return getArrayStart()[offset]; 4119 } else { 4120 return kInvalidUChar; 4121 } 4122 } 4123 4124 inline UChar 4125 UnicodeString::charAt(int32_t offset) const 4126 { return doCharAt(offset); } 4127 4128 inline UChar 4129 UnicodeString::operator[] (int32_t offset) const 4130 { return doCharAt(offset); } 4131 4132 inline UChar32 4133 UnicodeString::char32At(int32_t offset) const 4134 { 4135 int32_t len = length(); 4136 if((uint32_t)offset < (uint32_t)len) { 4137 const UChar *array = getArrayStart(); 4138 UChar32 c; 4139 U16_GET(array, 0, offset, len, c); 4140 return c; 4141 } else { 4142 return kInvalidUChar; 4143 } 4144 } 4145 4146 inline int32_t 4147 UnicodeString::getChar32Start(int32_t offset) const { 4148 if((uint32_t)offset < (uint32_t)length()) { 4149 const UChar *array = getArrayStart(); 4150 U16_SET_CP_START(array, 0, offset); 4151 return offset; 4152 } else { 4153 return 0; 4154 } 4155 } 4156 4157 inline int32_t 4158 UnicodeString::getChar32Limit(int32_t offset) const { 4159 int32_t len = length(); 4160 if((uint32_t)offset < (uint32_t)len) { 4161 const UChar *array = getArrayStart(); 4162 U16_SET_CP_LIMIT(array, 0, offset, len); 4163 return offset; 4164 } else { 4165 return len; 4166 } 4167 } 4168 4169 inline UBool 4170 UnicodeString::isEmpty() const { 4171 return fShortLength == 0; 4172 } 4173 4174 //======================================== 4175 // Write implementation methods 4176 //======================================== 4177 inline void 4178 UnicodeString::setLength(int32_t len) { 4179 if(len <= 127) { 4180 fShortLength = (int8_t)len; 4181 } else { 4182 fShortLength = (int8_t)-1; 4183 fUnion.fFields.fLength = len; 4184 } 4185 } 4186 4187 inline void 4188 UnicodeString::setToEmpty() { 4189 fShortLength = 0; 4190 fFlags = kShortString; 4191 } 4192 4193 inline void 4194 UnicodeString::setArray(UChar *array, int32_t len, int32_t capacity) { 4195 setLength(len); 4196 fUnion.fFields.fArray = array; 4197 fUnion.fFields.fCapacity = capacity; 4198 } 4199 4200 inline const UChar * 4201 UnicodeString::getTerminatedBuffer() { 4202 if(!isWritable()) { 4203 return 0; 4204 } else { 4205 UChar *array = getArrayStart(); 4206 int32_t len = length(); 4207 if(len < getCapacity() && ((fFlags&kRefCounted) == 0 || refCount() == 1)) { 4208 /* 4209 * kRefCounted: Do not write the NUL if the buffer is shared. 4210 * That is mostly safe, except when the length of one copy was modified 4211 * without copy-on-write, e.g., via truncate(newLength) or remove(void). 4212 * Then the NUL would be written into the middle of another copy's string. 4213 */ 4214 if(!(fFlags&kBufferIsReadonly)) { 4215 /* 4216 * We must not write to a readonly buffer, but it is known to be 4217 * NUL-terminated if len<capacity. 4218 * A shared, allocated buffer (refCount()>1) must not have its contents 4219 * modified, but the NUL at [len] is beyond the string contents, 4220 * and multiple string objects and threads writing the same NUL into the 4221 * same location is harmless. 4222 * In all other cases, the buffer is fully writable and it is anyway safe 4223 * to write the NUL. 4224 * 4225 * Note: An earlier version of this code tested whether there is a NUL 4226 * at [len] already, but, while safe, it generated lots of warnings from 4227 * tools like valgrind and Purify. 4228 */ 4229 array[len] = 0; 4230 } 4231 return array; 4232 } else if(cloneArrayIfNeeded(len+1)) { 4233 array = getArrayStart(); 4234 array[len] = 0; 4235 return array; 4236 } else { 4237 return 0; 4238 } 4239 } 4240 } 4241 4242 inline UnicodeString& 4243 UnicodeString::operator= (UChar ch) 4244 { return doReplace(0, length(), &ch, 0, 1); } 4245 4246 inline UnicodeString& 4247 UnicodeString::operator= (UChar32 ch) 4248 { return replace(0, length(), ch); } 4249 4250 inline UnicodeString& 4251 UnicodeString::setTo(const UnicodeString& srcText, 4252 int32_t srcStart, 4253 int32_t srcLength) 4254 { 4255 unBogus(); 4256 return doReplace(0, length(), srcText, srcStart, srcLength); 4257 } 4258 4259 inline UnicodeString& 4260 UnicodeString::setTo(const UnicodeString& srcText, 4261 int32_t srcStart) 4262 { 4263 unBogus(); 4264 srcText.pinIndex(srcStart); 4265 return doReplace(0, length(), srcText, srcStart, srcText.length() - srcStart); 4266 } 4267 4268 inline UnicodeString& 4269 UnicodeString::setTo(const UnicodeString& srcText) 4270 { 4271 unBogus(); 4272 return doReplace(0, length(), srcText, 0, srcText.length()); 4273 } 4274 4275 inline UnicodeString& 4276 UnicodeString::setTo(const UChar *srcChars, 4277 int32_t srcLength) 4278 { 4279 unBogus(); 4280 return doReplace(0, length(), srcChars, 0, srcLength); 4281 } 4282 4283 inline UnicodeString& 4284 UnicodeString::setTo(UChar srcChar) 4285 { 4286 unBogus(); 4287 return doReplace(0, length(), &srcChar, 0, 1); 4288 } 4289 4290 inline UnicodeString& 4291 UnicodeString::setTo(UChar32 srcChar) 4292 { 4293 unBogus(); 4294 return replace(0, length(), srcChar); 4295 } 4296 4297 inline UnicodeString& 4298 UnicodeString::append(const UnicodeString& srcText, 4299 int32_t srcStart, 4300 int32_t srcLength) 4301 { return doReplace(length(), 0, srcText, srcStart, srcLength); } 4302 4303 inline UnicodeString& 4304 UnicodeString::append(const UnicodeString& srcText) 4305 { return doReplace(length(), 0, srcText, 0, srcText.length()); } 4306 4307 inline UnicodeString& 4308 UnicodeString::append(const UChar *srcChars, 4309 int32_t srcStart, 4310 int32_t srcLength) 4311 { return doReplace(length(), 0, srcChars, srcStart, srcLength); } 4312 4313 inline UnicodeString& 4314 UnicodeString::append(const UChar *srcChars, 4315 int32_t srcLength) 4316 { return doReplace(length(), 0, srcChars, 0, srcLength); } 4317 4318 inline UnicodeString& 4319 UnicodeString::append(UChar srcChar) 4320 { return doReplace(length(), 0, &srcChar, 0, 1); } 4321 4322 inline UnicodeString& 4323 UnicodeString::append(UChar32 srcChar) { 4324 UChar buffer[U16_MAX_LENGTH]; 4325 int32_t _length = 0; 4326 UBool isError = FALSE; 4327 U16_APPEND(buffer, _length, U16_MAX_LENGTH, srcChar, isError); 4328 return doReplace(length(), 0, buffer, 0, _length); 4329 } 4330 4331 inline UnicodeString& 4332 UnicodeString::operator+= (UChar ch) 4333 { return doReplace(length(), 0, &ch, 0, 1); } 4334 4335 inline UnicodeString& 4336 UnicodeString::operator+= (UChar32 ch) { 4337 return append(ch); 4338 } 4339 4340 inline UnicodeString& 4341 UnicodeString::operator+= (const UnicodeString& srcText) 4342 { return doReplace(length(), 0, srcText, 0, srcText.length()); } 4343 4344 inline UnicodeString& 4345 UnicodeString::insert(int32_t start, 4346 const UnicodeString& srcText, 4347 int32_t srcStart, 4348 int32_t srcLength) 4349 { return doReplace(start, 0, srcText, srcStart, srcLength); } 4350 4351 inline UnicodeString& 4352 UnicodeString::insert(int32_t start, 4353 const UnicodeString& srcText) 4354 { return doReplace(start, 0, srcText, 0, srcText.length()); } 4355 4356 inline UnicodeString& 4357 UnicodeString::insert(int32_t start, 4358 const UChar *srcChars, 4359 int32_t srcStart, 4360 int32_t srcLength) 4361 { return doReplace(start, 0, srcChars, srcStart, srcLength); } 4362 4363 inline UnicodeString& 4364 UnicodeString::insert(int32_t start, 4365 const UChar *srcChars, 4366 int32_t srcLength) 4367 { return doReplace(start, 0, srcChars, 0, srcLength); } 4368 4369 inline UnicodeString& 4370 UnicodeString::insert(int32_t start, 4371 UChar srcChar) 4372 { return doReplace(start, 0, &srcChar, 0, 1); } 4373 4374 inline UnicodeString& 4375 UnicodeString::insert(int32_t start, 4376 UChar32 srcChar) 4377 { return replace(start, 0, srcChar); } 4378 4379 4380 inline UnicodeString& 4381 UnicodeString::remove() 4382 { 4383 // remove() of a bogus string makes the string empty and non-bogus 4384 // we also un-alias a read-only alias to deal with NUL-termination 4385 // issues with getTerminatedBuffer() 4386 if(fFlags & (kIsBogus|kBufferIsReadonly)) { 4387 setToEmpty(); 4388 } else { 4389 fShortLength = 0; 4390 } 4391 return *this; 4392 } 4393 4394 inline UnicodeString& 4395 UnicodeString::remove(int32_t start, 4396 int32_t _length) 4397 { 4398 if(start <= 0 && _length == INT32_MAX) { 4399 // remove(guaranteed everything) of a bogus string makes the string empty and non-bogus 4400 return remove(); 4401 } 4402 return doReplace(start, _length, NULL, 0, 0); 4403 } 4404 4405 inline UnicodeString& 4406 UnicodeString::removeBetween(int32_t start, 4407 int32_t limit) 4408 { return doReplace(start, limit - start, NULL, 0, 0); } 4409 4410 inline UnicodeString & 4411 UnicodeString::retainBetween(int32_t start, int32_t limit) { 4412 truncate(limit); 4413 return doReplace(0, start, NULL, 0, 0); 4414 } 4415 4416 inline UBool 4417 UnicodeString::truncate(int32_t targetLength) 4418 { 4419 if(isBogus() && targetLength == 0) { 4420 // truncate(0) of a bogus string makes the string empty and non-bogus 4421 unBogus(); 4422 return FALSE; 4423 } else if((uint32_t)targetLength < (uint32_t)length()) { 4424 setLength(targetLength); 4425 if(fFlags&kBufferIsReadonly) { 4426 fUnion.fFields.fCapacity = targetLength; // not NUL-terminated any more 4427 } 4428 return TRUE; 4429 } else { 4430 return FALSE; 4431 } 4432 } 4433 4434 inline UnicodeString& 4435 UnicodeString::reverse() 4436 { return doReverse(0, length()); } 4437 4438 inline UnicodeString& 4439 UnicodeString::reverse(int32_t start, 4440 int32_t _length) 4441 { return doReverse(start, _length); } 4442 4443 U_NAMESPACE_END 4444 4445 #endif 4446