1 : /*
2 : **********************************************************************
3 : * Copyright (C) 1998-2006, 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/rep.h"
30 :
31 : struct UConverter; // unicode/ucnv.h
32 : class StringThreadTest;
33 :
34 : #ifndef U_COMPARE_CODE_POINT_ORDER
35 : /* see also ustring.h and unorm.h */
36 : /**
37 : * Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc:
38 : * Compare strings in code point order instead of code unit order.
39 : * @stable ICU 2.2
40 : */
41 : #define U_COMPARE_CODE_POINT_ORDER 0x8000
42 : #endif
43 :
44 : #ifndef USTRING_H
45 : /**
46 : * \ingroup ustring_ustrlen
47 : */
48 : U_STABLE int32_t U_EXPORT2
49 : u_strlen(const UChar *s);
50 : #endif
51 :
52 : U_NAMESPACE_BEGIN
53 :
54 : class Locale; // unicode/locid.h
55 : class StringCharacterIterator;
56 : class BreakIterator; // unicode/brkiter.h
57 :
58 : /* The <iostream> include has been moved to unicode/ustream.h */
59 :
60 : /**
61 : * Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor
62 : * which constructs a Unicode string from an invariant-character char * string.
63 : * About invariant characters see utypes.h.
64 : * This constructor has no runtime dependency on conversion code and is
65 : * therefore recommended over ones taking a charset name string
66 : * (where the empty string "" indicates invariant-character conversion).
67 : *
68 : * @stable ICU 3.2
69 : */
70 : #define US_INV UnicodeString::kInvariant
71 :
72 : /**
73 : * Unicode String literals in C++.
74 : * Dependent on the platform properties, different UnicodeString
75 : * constructors should be used to create a UnicodeString object from
76 : * a string literal.
77 : * The macros are defined for maximum performance.
78 : * They work only for strings that contain "invariant characters", i.e.,
79 : * only latin letters, digits, and some punctuation.
80 : * See utypes.h for details.
81 : *
82 : * The string parameter must be a C string literal.
83 : * The length of the string, not including the terminating
84 : * <code>NUL</code>, must be specified as a constant.
85 : * The U_STRING_DECL macro should be invoked exactly once for one
86 : * such string variable before it is used.
87 : * @stable ICU 2.0
88 : */
89 : #if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16)))
90 : # define UNICODE_STRING(cs, _length) UnicodeString(TRUE, (const UChar *)L ## cs, _length)
91 : #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
92 : # define UNICODE_STRING(cs, _length) UnicodeString(TRUE, (const UChar *)cs, _length)
93 : #else
94 : # define UNICODE_STRING(cs, _length) UnicodeString(cs, _length, US_INV)
95 : #endif
96 :
97 : /**
98 : * Unicode String literals in C++.
99 : * Dependent on the platform properties, different UnicodeString
100 : * constructors should be used to create a UnicodeString object from
101 : * a string literal.
102 : * The macros are defined for improved performance.
103 : * They work only for strings that contain "invariant characters", i.e.,
104 : * only latin letters, digits, and some punctuation.
105 : * See utypes.h for details.
106 : *
107 : * The string parameter must be a C string literal.
108 : * @stable ICU 2.0
109 : */
110 : #if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16)))
111 : # define UNICODE_STRING_SIMPLE(cs) UnicodeString(TRUE, (const UChar *)L ## cs, -1)
112 : #elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
113 : # define UNICODE_STRING_SIMPLE(cs) UnicodeString(TRUE, (const UChar *)cs, -1)
114 : #else
115 : # define UNICODE_STRING_SIMPLE(cs) UnicodeString(cs, -1, US_INV)
116 : #endif
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.sourceforge.net/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.sourceforge.net/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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 : * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work
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 !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 a specified codepage.
1457 : * The output string is NUL-terminated.
1458 : *
1459 : * Recommendation: For invariant-character strings use
1460 : * extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const
1461 : * because it avoids object code dependencies of UnicodeString on
1462 : * the conversion code.
1463 : *
1464 : * @param start offset of first character which will be copied
1465 : * @param startLength the number of characters to extract
1466 : * @param target the target buffer for extraction
1467 : * @param codepage the desired codepage for the characters. 0 has
1468 : * the special meaning of the default codepage
1469 : * If <code>codepage</code> is an empty string (<code>""</code>),
1470 : * then a simple conversion is performed on the codepage-invariant
1471 : * subset ("invariant characters") of the platform encoding. See utypes.h.
1472 : * If <TT>target</TT> is NULL, then the number of bytes required for
1473 : * <TT>target</TT> is returned. It is assumed that the target is big enough
1474 : * to fit all of the characters.
1475 : * @return the output string length, not including the terminating NUL
1476 : * @stable ICU 2.0
1477 : */
1478 : inline int32_t extract(int32_t start,
1479 : int32_t startLength,
1480 : char *target,
1481 : const char *codepage = 0) const;
1482 :
1483 : /**
1484 : * Copy the characters in the range
1485 : * [<tt>start</TT>, <tt>start + length</TT>) into an array of characters
1486 : * in a specified codepage.
1487 : * This function does not write any more than <code>targetLength</code>
1488 : * characters but returns the length of the entire output string
1489 : * so that one can allocate a larger buffer and call the function again
1490 : * if necessary.
1491 : * The output string is NUL-terminated if possible.
1492 : *
1493 : * Recommendation: For invariant-character strings use
1494 : * extract(int32_t start, int32_t length, char *target, int32_t targetCapacity, enum EInvariant inv) const
1495 : * because it avoids object code dependencies of UnicodeString on
1496 : * the conversion code.
1497 : *
1498 : * @param start offset of first character which will be copied
1499 : * @param startLength the number of characters to extract
1500 : * @param target the target buffer for extraction
1501 : * @param targetLength the length of the target buffer
1502 : * @param codepage the desired codepage for the characters. 0 has
1503 : * the special meaning of the default codepage
1504 : * If <code>codepage</code> is an empty string (<code>""</code>),
1505 : * then a simple conversion is performed on the codepage-invariant
1506 : * subset ("invariant characters") of the platform encoding. See utypes.h.
1507 : * If <TT>target</TT> is NULL, then the number of bytes required for
1508 : * <TT>target</TT> is returned.
1509 : * @return the output string length, not including the terminating NUL
1510 : * @stable ICU 2.0
1511 : */
1512 : int32_t extract(int32_t start,
1513 : int32_t startLength,
1514 : char *target,
1515 : uint32_t targetLength,
1516 : const char *codepage = 0) const;
1517 :
1518 : /**
1519 : * Convert the UnicodeString into a codepage string using an existing UConverter.
1520 : * The output string is NUL-terminated if possible.
1521 : *
1522 : * This function avoids the overhead of opening and closing a converter if
1523 : * multiple strings are extracted.
1524 : *
1525 : * @param dest destination string buffer, can be NULL if destCapacity==0
1526 : * @param destCapacity the number of chars available at dest
1527 : * @param cnv the converter object to be used (ucnv_resetFromUnicode() will be called),
1528 : * or NULL for the default converter
1529 : * @param errorCode normal ICU error code
1530 : * @return the length of the output string, not counting the terminating NUL;
1531 : * if the length is greater than destCapacity, then the string will not fit
1532 : * and a buffer of the indicated length would need to be passed in
1533 : * @stable ICU 2.0
1534 : */
1535 : int32_t extract(char *dest, int32_t destCapacity,
1536 : UConverter *cnv,
1537 : UErrorCode &errorCode) const;
1538 :
1539 : #endif
1540 :
1541 : /* Length operations */
1542 :
1543 : /**
1544 : * Return the length of the UnicodeString object.
1545 : * The length is the number of UChar code units are in the UnicodeString.
1546 : * If you want the number of code points, please use countChar32().
1547 : * @return the length of the UnicodeString object
1548 : * @see countChar32
1549 : * @stable ICU 2.0
1550 : */
1551 : inline int32_t length(void) const;
1552 :
1553 : /**
1554 : * Count Unicode code points in the length UChar code units of the string.
1555 : * A code point may occupy either one or two UChar code units.
1556 : * Counting code points involves reading all code units.
1557 : *
1558 : * This functions is basically the inverse of moveIndex32().
1559 : *
1560 : * @param start the index of the first code unit to check
1561 : * @param length the number of UChar code units to check
1562 : * @return the number of code points in the specified code units
1563 : * @see length
1564 : * @stable ICU 2.0
1565 : */
1566 : int32_t
1567 : countChar32(int32_t start=0, int32_t length=INT32_MAX) const;
1568 :
1569 : /**
1570 : * Check if the length UChar code units of the string
1571 : * contain more Unicode code points than a certain number.
1572 : * This is more efficient than counting all code points in this part of the string
1573 : * and comparing that number with a threshold.
1574 : * This function may not need to scan the string at all if the length
1575 : * falls within a certain range, and
1576 : * never needs to count more than 'number+1' code points.
1577 : * Logically equivalent to (countChar32(start, length)>number).
1578 : * A Unicode code point may occupy either one or two UChar code units.
1579 : *
1580 : * @param start the index of the first code unit to check (0 for the entire string)
1581 : * @param length the number of UChar code units to check
1582 : * (use INT32_MAX for the entire string; remember that start/length
1583 : * values are pinned)
1584 : * @param number The number of code points in the (sub)string is compared against
1585 : * the 'number' parameter.
1586 : * @return Boolean value for whether the string contains more Unicode code points
1587 : * than 'number'. Same as (u_countChar32(s, length)>number).
1588 : * @see countChar32
1589 : * @see u_strHasMoreChar32Than
1590 : * @stable ICU 2.4
1591 : */
1592 : UBool
1593 : hasMoreChar32Than(int32_t start, int32_t length, int32_t number) const;
1594 :
1595 : /**
1596 : * Determine if this string is empty.
1597 : * @return TRUE if this string contains 0 characters, FALSE otherwise.
1598 : * @stable ICU 2.0
1599 : */
1600 : inline UBool isEmpty(void) const;
1601 :
1602 : /**
1603 : * Return the capacity of the internal buffer of the UnicodeString object.
1604 : * This is useful together with the getBuffer functions.
1605 : * See there for details.
1606 : *
1607 : * @return the number of UChars available in the internal buffer
1608 : * @see getBuffer
1609 : * @stable ICU 2.0
1610 : */
1611 : inline int32_t getCapacity(void) const;
1612 :
1613 : /* Other operations */
1614 :
1615 : /**
1616 : * Generate a hash code for this object.
1617 : * @return The hash code of this UnicodeString.
1618 : * @stable ICU 2.0
1619 : */
1620 : inline int32_t hashCode(void) const;
1621 :
1622 : /**
1623 : * Determine if this object contains a valid string.
1624 : * A bogus string has no value. It is different from an empty string.
1625 : * It can be used to indicate that no string value is available.
1626 : * getBuffer() and getTerminatedBuffer() return NULL, and
1627 : * length() returns 0.
1628 : *
1629 : * @return TRUE if the string is valid, FALSE otherwise
1630 : * @see setToBogus()
1631 : * @stable ICU 2.0
1632 : */
1633 : inline UBool isBogus(void) const;
1634 :
1635 :
1636 : //========================================
1637 : // Write operations
1638 : //========================================
1639 :
1640 : /* Assignment operations */
1641 :
1642 : /**
1643 : * Assignment operator. Replace the characters in this UnicodeString
1644 : * with the characters from <TT>srcText</TT>.
1645 : * @param srcText The text containing the characters to replace
1646 : * @return a reference to this
1647 : * @stable ICU 2.0
1648 : */
1649 : UnicodeString &operator=(const UnicodeString &srcText);
1650 :
1651 : /**
1652 : * Almost the same as the assignment operator.
1653 : * Replace the characters in this UnicodeString
1654 : * with the characters from <code>srcText</code>.
1655 : *
1656 : * This function works the same for all strings except for ones that
1657 : * are readonly aliases.
1658 : * Starting with ICU 2.4, the assignment operator and the copy constructor
1659 : * allocate a new buffer and copy the buffer contents even for readonly aliases.
1660 : * This function implements the old, more efficient but less safe behavior
1661 : * of making this string also a readonly alias to the same buffer.
1662 : * The fastCopyFrom function must be used only if it is known that the lifetime of
1663 : * this UnicodeString is at least as long as the lifetime of the aliased buffer
1664 : * including its contents, for example for strings from resource bundles
1665 : * or aliases to string contents.
1666 : *
1667 : * @param src The text containing the characters to replace.
1668 : * @return a reference to this
1669 : * @stable ICU 2.4
1670 : */
1671 : UnicodeString &fastCopyFrom(const UnicodeString &src);
1672 :
1673 : /**
1674 : * Assignment operator. Replace the characters in this UnicodeString
1675 : * with the code unit <TT>ch</TT>.
1676 : * @param ch the code unit to replace
1677 : * @return a reference to this
1678 : * @stable ICU 2.0
1679 : */
1680 : inline UnicodeString& operator= (UChar ch);
1681 :
1682 : /**
1683 : * Assignment operator. Replace the characters in this UnicodeString
1684 : * with the code point <TT>ch</TT>.
1685 : * @param ch the code point to replace
1686 : * @return a reference to this
1687 : * @stable ICU 2.0
1688 : */
1689 : inline UnicodeString& operator= (UChar32 ch);
1690 :
1691 : /**
1692 : * Set the text in the UnicodeString object to the characters
1693 : * in <TT>srcText</TT> in the range
1694 : * [<TT>srcStart</TT>, <TT>srcText.length()</TT>).
1695 : * <TT>srcText</TT> is not modified.
1696 : * @param srcText the source for the new characters
1697 : * @param srcStart the offset into <TT>srcText</TT> where new characters
1698 : * will be obtained
1699 : * @return a reference to this
1700 : * @stable ICU 2.2
1701 : */
1702 : inline UnicodeString& setTo(const UnicodeString& srcText,
1703 : int32_t srcStart);
1704 :
1705 : /**
1706 : * Set the text in the UnicodeString object to the characters
1707 : * in <TT>srcText</TT> in the range
1708 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>).
1709 : * <TT>srcText</TT> is not modified.
1710 : * @param srcText the source for the new characters
1711 : * @param srcStart the offset into <TT>srcText</TT> where new characters
1712 : * will be obtained
1713 : * @param srcLength the number of characters in <TT>srcText</TT> in the
1714 : * replace string.
1715 : * @return a reference to this
1716 : * @stable ICU 2.0
1717 : */
1718 : inline UnicodeString& setTo(const UnicodeString& srcText,
1719 : int32_t srcStart,
1720 : int32_t srcLength);
1721 :
1722 : /**
1723 : * Set the text in the UnicodeString object to the characters in
1724 : * <TT>srcText</TT>.
1725 : * <TT>srcText</TT> is not modified.
1726 : * @param srcText the source for the new characters
1727 : * @return a reference to this
1728 : * @stable ICU 2.0
1729 : */
1730 : inline UnicodeString& setTo(const UnicodeString& srcText);
1731 :
1732 : /**
1733 : * Set the characters in the UnicodeString object to the characters
1734 : * in <TT>srcChars</TT>. <TT>srcChars</TT> is not modified.
1735 : * @param srcChars the source for the new characters
1736 : * @param srcLength the number of Unicode characters in srcChars.
1737 : * @return a reference to this
1738 : * @stable ICU 2.0
1739 : */
1740 : inline UnicodeString& setTo(const UChar *srcChars,
1741 : int32_t srcLength);
1742 :
1743 : /**
1744 : * Set the characters in the UnicodeString object to the code unit
1745 : * <TT>srcChar</TT>.
1746 : * @param srcChar the code unit which becomes the UnicodeString's character
1747 : * content
1748 : * @return a reference to this
1749 : * @stable ICU 2.0
1750 : */
1751 : UnicodeString& setTo(UChar srcChar);
1752 :
1753 : /**
1754 : * Set the characters in the UnicodeString object to the code point
1755 : * <TT>srcChar</TT>.
1756 : * @param srcChar the code point which becomes the UnicodeString's character
1757 : * content
1758 : * @return a reference to this
1759 : * @stable ICU 2.0
1760 : */
1761 : UnicodeString& setTo(UChar32 srcChar);
1762 :
1763 : /**
1764 : * Aliasing setTo() function, analogous to the readonly-aliasing UChar* constructor.
1765 : * The text will be used for the UnicodeString object, but
1766 : * it will not be released when the UnicodeString is destroyed.
1767 : * This has copy-on-write semantics:
1768 : * When the string is modified, then the buffer is first copied into
1769 : * newly allocated memory.
1770 : * The aliased buffer is never modified.
1771 : * In an assignment to another UnicodeString, the text will be aliased again,
1772 : * so that both strings then alias the same readonly-text.
1773 : *
1774 : * @param isTerminated specifies if <code>text</code> is <code>NUL</code>-terminated.
1775 : * This must be true if <code>textLength==-1</code>.
1776 : * @param text The characters to alias for the UnicodeString.
1777 : * @param textLength The number of Unicode characters in <code>text</code> to alias.
1778 : * If -1, then this constructor will determine the length
1779 : * by calling <code>u_strlen()</code>.
1780 : * @return a reference to this
1781 : * @stable ICU 2.0
1782 : */
1783 : UnicodeString &setTo(UBool isTerminated,
1784 : const UChar *text,
1785 : int32_t textLength);
1786 :
1787 : /**
1788 : * Aliasing setTo() function, analogous to the writable-aliasing UChar* constructor.
1789 : * The text will be used for the UnicodeString object, but
1790 : * it will not be released when the UnicodeString is destroyed.
1791 : * This has write-through semantics:
1792 : * For as long as the capacity of the buffer is sufficient, write operations
1793 : * will directly affect the buffer. When more capacity is necessary, then
1794 : * a new buffer will be allocated and the contents copied as with regularly
1795 : * constructed strings.
1796 : * In an assignment to another UnicodeString, the buffer will be copied.
1797 : * The extract(UChar *dst) function detects whether the dst pointer is the same
1798 : * as the string buffer itself and will in this case not copy the contents.
1799 : *
1800 : * @param buffer The characters to alias for the UnicodeString.
1801 : * @param buffLength The number of Unicode characters in <code>buffer</code> to alias.
1802 : * @param buffCapacity The size of <code>buffer</code> in UChars.
1803 : * @return a reference to this
1804 : * @stable ICU 2.0
1805 : */
1806 : UnicodeString &setTo(UChar *buffer,
1807 : int32_t buffLength,
1808 : int32_t buffCapacity);
1809 :
1810 : /**
1811 : * Make this UnicodeString object invalid.
1812 : * The string will test TRUE with isBogus().
1813 : *
1814 : * A bogus string has no value. It is different from an empty string.
1815 : * It can be used to indicate that no string value is available.
1816 : * getBuffer() and getTerminatedBuffer() return NULL, and
1817 : * length() returns 0.
1818 : *
1819 : * This utility function is used throughout the UnicodeString
1820 : * implementation to indicate that a UnicodeString operation failed,
1821 : * and may be used in other functions,
1822 : * especially but not exclusively when such functions do not
1823 : * take a UErrorCode for simplicity.
1824 : *
1825 : * The following methods, and no others, will clear a string object's bogus flag:
1826 : * - remove()
1827 : * - remove(0, INT32_MAX)
1828 : * - truncate(0)
1829 : * - operator=() (assignment operator)
1830 : * - setTo(...)
1831 : *
1832 : * The simplest ways to turn a bogus string into an empty one
1833 : * is to use the remove() function.
1834 : * Examples for other functions that are equivalent to "set to empty string":
1835 : * \code
1836 : * if(s.isBogus()) {
1837 : * s.remove(); // set to an empty string (remove all), or
1838 : * s.remove(0, INT32_MAX); // set to an empty string (remove all), or
1839 : * s.truncate(0); // set to an empty string (complete truncation), or
1840 : * s=UnicodeString(); // assign an empty string, or
1841 : * s.setTo((UChar32)-1); // set to a pseudo code point that is out of range, or
1842 : * static const UChar nul=0;
1843 : * s.setTo(&nul, 0); // set to an empty C Unicode string
1844 : * }
1845 : * \endcode
1846 : *
1847 : * @see isBogus()
1848 : * @stable ICU 2.0
1849 : */
1850 : void setToBogus();
1851 :
1852 : /**
1853 : * Set the character at the specified offset to the specified character.
1854 : * @param offset A valid offset into the text of the character to set
1855 : * @param ch The new character
1856 : * @return A reference to this
1857 : * @stable ICU 2.0
1858 : */
1859 : UnicodeString& setCharAt(int32_t offset,
1860 : UChar ch);
1861 :
1862 :
1863 : /* Append operations */
1864 :
1865 : /**
1866 : * Append operator. Append the code unit <TT>ch</TT> to the UnicodeString
1867 : * object.
1868 : * @param ch the code unit to be appended
1869 : * @return a reference to this
1870 : * @stable ICU 2.0
1871 : */
1872 : inline UnicodeString& operator+= (UChar ch);
1873 :
1874 : /**
1875 : * Append operator. Append the code point <TT>ch</TT> to the UnicodeString
1876 : * object.
1877 : * @param ch the code point to be appended
1878 : * @return a reference to this
1879 : * @stable ICU 2.0
1880 : */
1881 : inline UnicodeString& operator+= (UChar32 ch);
1882 :
1883 : /**
1884 : * Append operator. Append the characters in <TT>srcText</TT> to the
1885 : * UnicodeString object at offset <TT>start</TT>. <TT>srcText</TT> is
1886 : * not modified.
1887 : * @param srcText the source for the new characters
1888 : * @return a reference to this
1889 : * @stable ICU 2.0
1890 : */
1891 : inline UnicodeString& operator+= (const UnicodeString& srcText);
1892 :
1893 : /**
1894 : * Append the characters
1895 : * in <TT>srcText</TT> in the range
1896 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) to the
1897 : * UnicodeString object at offset <TT>start</TT>. <TT>srcText</TT>
1898 : * is not modified.
1899 : * @param srcText the source for the new characters
1900 : * @param srcStart the offset into <TT>srcText</TT> where new characters
1901 : * will be obtained
1902 : * @param srcLength the number of characters in <TT>srcText</TT> in
1903 : * the append string
1904 : * @return a reference to this
1905 : * @stable ICU 2.0
1906 : */
1907 : inline UnicodeString& append(const UnicodeString& srcText,
1908 : int32_t srcStart,
1909 : int32_t srcLength);
1910 :
1911 : /**
1912 : * Append the characters in <TT>srcText</TT> to the UnicodeString object at
1913 : * offset <TT>start</TT>. <TT>srcText</TT> is not modified.
1914 : * @param srcText the source for the new characters
1915 : * @return a reference to this
1916 : * @stable ICU 2.0
1917 : */
1918 : inline UnicodeString& append(const UnicodeString& srcText);
1919 :
1920 : /**
1921 : * Append the characters in <TT>srcChars</TT> in the range
1922 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) to the UnicodeString
1923 : * object at offset
1924 : * <TT>start</TT>. <TT>srcChars</TT> is not modified.
1925 : * @param srcChars the source for the new characters
1926 : * @param srcStart the offset into <TT>srcChars</TT> where new characters
1927 : * will be obtained
1928 : * @param srcLength the number of characters in <TT>srcChars</TT> in
1929 : * the append string
1930 : * @return a reference to this
1931 : * @stable ICU 2.0
1932 : */
1933 : inline UnicodeString& append(const UChar *srcChars,
1934 : int32_t srcStart,
1935 : int32_t srcLength);
1936 :
1937 : /**
1938 : * Append the characters in <TT>srcChars</TT> to the UnicodeString object
1939 : * at offset <TT>start</TT>. <TT>srcChars</TT> is not modified.
1940 : * @param srcChars the source for the new characters
1941 : * @param srcLength the number of Unicode characters in <TT>srcChars</TT>
1942 : * @return a reference to this
1943 : * @stable ICU 2.0
1944 : */
1945 : inline UnicodeString& append(const UChar *srcChars,
1946 : int32_t srcLength);
1947 :
1948 : /**
1949 : * Append the code unit <TT>srcChar</TT> to the UnicodeString object.
1950 : * @param srcChar the code unit to append
1951 : * @return a reference to this
1952 : * @stable ICU 2.0
1953 : */
1954 : inline UnicodeString& append(UChar srcChar);
1955 :
1956 : /**
1957 : * Append the code point <TT>srcChar</TT> to the UnicodeString object.
1958 : * @param srcChar the code point to append
1959 : * @return a reference to this
1960 : * @stable ICU 2.0
1961 : */
1962 : inline UnicodeString& append(UChar32 srcChar);
1963 :
1964 :
1965 : /* Insert operations */
1966 :
1967 : /**
1968 : * Insert the characters in <TT>srcText</TT> in the range
1969 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) into the UnicodeString
1970 : * object at offset <TT>start</TT>. <TT>srcText</TT> is not modified.
1971 : * @param start the offset where the insertion begins
1972 : * @param srcText the source for the new characters
1973 : * @param srcStart the offset into <TT>srcText</TT> where new characters
1974 : * will be obtained
1975 : * @param srcLength the number of characters in <TT>srcText</TT> in
1976 : * the insert string
1977 : * @return a reference to this
1978 : * @stable ICU 2.0
1979 : */
1980 : inline UnicodeString& insert(int32_t start,
1981 : const UnicodeString& srcText,
1982 : int32_t srcStart,
1983 : int32_t srcLength);
1984 :
1985 : /**
1986 : * Insert the characters in <TT>srcText</TT> into the UnicodeString object
1987 : * at offset <TT>start</TT>. <TT>srcText</TT> is not modified.
1988 : * @param start the offset where the insertion begins
1989 : * @param srcText the source for the new characters
1990 : * @return a reference to this
1991 : * @stable ICU 2.0
1992 : */
1993 : inline UnicodeString& insert(int32_t start,
1994 : const UnicodeString& srcText);
1995 :
1996 : /**
1997 : * Insert the characters in <TT>srcChars</TT> in the range
1998 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>) into the UnicodeString
1999 : * object at offset <TT>start</TT>. <TT>srcChars</TT> is not modified.
2000 : * @param start the offset at which the insertion begins
2001 : * @param srcChars the source for the new characters
2002 : * @param srcStart the offset into <TT>srcChars</TT> where new characters
2003 : * will be obtained
2004 : * @param srcLength the number of characters in <TT>srcChars</TT>
2005 : * in the insert string
2006 : * @return a reference to this
2007 : * @stable ICU 2.0
2008 : */
2009 : inline UnicodeString& insert(int32_t start,
2010 : const UChar *srcChars,
2011 : int32_t srcStart,
2012 : int32_t srcLength);
2013 :
2014 : /**
2015 : * Insert the characters in <TT>srcChars</TT> into the UnicodeString object
2016 : * at offset <TT>start</TT>. <TT>srcChars</TT> is not modified.
2017 : * @param start the offset where the insertion begins
2018 : * @param srcChars the source for the new characters
2019 : * @param srcLength the number of Unicode characters in srcChars.
2020 : * @return a reference to this
2021 : * @stable ICU 2.0
2022 : */
2023 : inline UnicodeString& insert(int32_t start,
2024 : const UChar *srcChars,
2025 : int32_t srcLength);
2026 :
2027 : /**
2028 : * Insert the code unit <TT>srcChar</TT> into the UnicodeString object at
2029 : * offset <TT>start</TT>.
2030 : * @param start the offset at which the insertion occurs
2031 : * @param srcChar the code unit to insert
2032 : * @return a reference to this
2033 : * @stable ICU 2.0
2034 : */
2035 : inline UnicodeString& insert(int32_t start,
2036 : UChar srcChar);
2037 :
2038 : /**
2039 : * Insert the code point <TT>srcChar</TT> into the UnicodeString object at
2040 : * offset <TT>start</TT>.
2041 : * @param start the offset at which the insertion occurs
2042 : * @param srcChar the code point to insert
2043 : * @return a reference to this
2044 : * @stable ICU 2.0
2045 : */
2046 : inline UnicodeString& insert(int32_t start,
2047 : UChar32 srcChar);
2048 :
2049 :
2050 : /* Replace operations */
2051 :
2052 : /**
2053 : * Replace the characters in the range
2054 : * [<TT>start</TT>, <TT>start + length</TT>) with the characters in
2055 : * <TT>srcText</TT> in the range
2056 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>).
2057 : * <TT>srcText</TT> is not modified.
2058 : * @param start the offset at which the replace operation begins
2059 : * @param length the number of characters to replace. The character at
2060 : * <TT>start + length</TT> is not modified.
2061 : * @param srcText the source for the new characters
2062 : * @param srcStart the offset into <TT>srcText</TT> where new characters
2063 : * will be obtained
2064 : * @param srcLength the number of characters in <TT>srcText</TT> in
2065 : * the replace string
2066 : * @return a reference to this
2067 : * @stable ICU 2.0
2068 : */
2069 : UnicodeString& replace(int32_t start,
2070 : int32_t length,
2071 : const UnicodeString& srcText,
2072 : int32_t srcStart,
2073 : int32_t srcLength);
2074 :
2075 : /**
2076 : * Replace the characters in the range
2077 : * [<TT>start</TT>, <TT>start + length</TT>)
2078 : * with the characters in <TT>srcText</TT>. <TT>srcText</TT> is
2079 : * not modified.
2080 : * @param start the offset at which the replace operation begins
2081 : * @param length the number of characters to replace. The character at
2082 : * <TT>start + length</TT> is not modified.
2083 : * @param srcText the source for the new characters
2084 : * @return a reference to this
2085 : * @stable ICU 2.0
2086 : */
2087 : UnicodeString& replace(int32_t start,
2088 : int32_t length,
2089 : const UnicodeString& srcText);
2090 :
2091 : /**
2092 : * Replace the characters in the range
2093 : * [<TT>start</TT>, <TT>start + length</TT>) with the characters in
2094 : * <TT>srcChars</TT> in the range
2095 : * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>). <TT>srcChars</TT>
2096 : * is not modified.
2097 : * @param start the offset at which the replace operation begins
2098 : * @param length the number of characters to replace. The character at
2099 : * <TT>start + length</TT> is not modified.
2100 : * @param srcChars the source for the new characters
2101 : * @param srcStart the offset into <TT>srcChars</TT> where new characters
2102 : * will be obtained
2103 : * @param srcLength the number of characters in <TT>srcChars</TT>
2104 : * in the replace string
2105 : * @return a reference to this
2106 : * @stable ICU 2.0
2107 : */
2108 : UnicodeString& replace(int32_t start,
2109 : int32_t length,
2110 : const UChar *srcChars,
2111 : int32_t srcStart,
2112 : int32_t srcLength);
2113 :
2114 : /**
2115 : * Replace the characters in the range
2116 : * [<TT>start</TT>, <TT>start + length</TT>) with the characters in
2117 : * <TT>srcChars</TT>. <TT>srcChars</TT> is not modified.
2118 : * @param start the offset at which the replace operation begins
2119 : * @param length number of characters to replace. The character at
2120 : * <TT>start + length</TT> is not modified.
2121 : * @param srcChars the source for the new characters
2122 : * @param srcLength the number of Unicode characters in srcChars
2123 : * @return a reference to this
2124 : * @stable ICU 2.0
2125 : */
2126 : inline UnicodeString& replace(int32_t start,
2127 : int32_t length,
2128 : const UChar *srcChars,
2129 : int32_t srcLength);
2130 :
2131 : /**
2132 : * Replace the characters in the range
2133 : * [<TT>start</TT>, <TT>start + length</TT>) with the code unit
2134 : * <TT>srcChar</TT>.
2135 : * @param start the offset at which the replace operation begins
2136 : * @param length the number of characters to replace. The character at
2137 : * <TT>start + length</TT> is not modified.
2138 : * @param srcChar the new code unit
2139 : * @return a reference to this
2140 : * @stable ICU 2.0
2141 : */
2142 : inline UnicodeString& replace(int32_t start,
2143 : int32_t length,
2144 : UChar srcChar);
2145 :
2146 : /**
2147 : * Replace the characters in the range
2148 : * [<TT>start</TT>, <TT>start + length</TT>) with the code point
2149 : * <TT>srcChar</TT>.
2150 : * @param start the offset at which the replace operation begins
2151 : * @param length the number of characters to replace. The character at
2152 : * <TT>start + length</TT> is not modified.
2153 : * @param srcChar the new code point
2154 : * @return a reference to this
2155 : * @stable ICU 2.0
2156 : */
2157 : inline UnicodeString& replace(int32_t start,
2158 : int32_t length,
2159 : UChar32 srcChar);
2160 :
2161 : /**
2162 : * Replace the characters in the range [<TT>start</TT>, <TT>limit</TT>)
2163 : * with the characters in <TT>srcText</TT>. <TT>srcText</TT> is not modified.
2164 : * @param start the offset at which the replace operation begins
2165 : * @param limit the offset immediately following the replace range
2166 : * @param srcText the source for the new characters
2167 : * @return a reference to this
2168 : * @stable ICU 2.0
2169 : */
2170 : inline UnicodeString& replaceBetween(int32_t start,
2171 : int32_t limit,
2172 : const UnicodeString& srcText);
2173 :
2174 : /**
2175 : * Replace the characters in the range [<TT>start</TT>, <TT>limit</TT>)
2176 : * with the characters in <TT>srcText</TT> in the range
2177 : * [<TT>srcStart</TT>, <TT>srcLimit</TT>). <TT>srcText</TT> is not modified.
2178 : * @param start the offset at which the replace operation begins
2179 : * @param limit the offset immediately following the replace range
2180 : * @param srcText the source for the new characters
2181 : * @param srcStart the offset into <TT>srcChars</TT> where new characters
2182 : * will be obtained
2183 : * @param srcLimit the offset immediately following the range to copy
2184 : * in <TT>srcText</TT>
2185 : * @return a reference to this
2186 : * @stable ICU 2.0
2187 : */
2188 : inline UnicodeString& replaceBetween(int32_t start,
2189 : int32_t limit,
2190 : const UnicodeString& srcText,
2191 : int32_t srcStart,
2192 : int32_t srcLimit);
2193 :
2194 : /**
2195 : * Replace a substring of this object with the given text.
2196 : * @param start the beginning index, inclusive; <code>0 <= start
2197 : * <= limit</code>.
2198 : * @param limit the ending index, exclusive; <code>start <= limit
2199 : * <= length()</code>.
2200 : * @param text the text to replace characters <code>start</code>
2201 : * to <code>limit - 1</code>
2202 : * @stable ICU 2.0
2203 : */
2204 : virtual void handleReplaceBetween(int32_t start,
2205 : int32_t limit,
2206 : const UnicodeString& text);
2207 :
2208 : /**
2209 : * Replaceable API
2210 : * @return TRUE if it has MetaData
2211 : * @stable ICU 2.4
2212 : */
2213 : virtual UBool hasMetaData() const;
2214 :
2215 : /**
2216 : * Copy a substring of this object, retaining attribute (out-of-band)
2217 : * information. This method is used to duplicate or reorder substrings.
2218 : * The destination index must not overlap the source range.
2219 : *
2220 : * @param start the beginning index, inclusive; <code>0 <= start <=
2221 : * limit</code>.
2222 : * @param limit the ending index, exclusive; <code>start <= limit <=
2223 : * length()</code>.
2224 : * @param dest the destination index. The characters from
2225 : * <code>start..limit-1</code> will be copied to <code>dest</code>.
2226 : * Implementations of this method may assume that <code>dest <= start ||
2227 : * dest >= limit</code>.
2228 : * @stable ICU 2.0
2229 : */
2230 : virtual void copy(int32_t start, int32_t limit, int32_t dest);
2231 :
2232 : /* Search and replace operations */
2233 :
2234 : /**
2235 : * Replace all occurrences of characters in oldText with the characters
2236 : * in newText
2237 : * @param oldText the text containing the search text
2238 : * @param newText the text containing the replacement text
2239 : * @return a reference to this
2240 : * @stable ICU 2.0
2241 : */
2242 : inline UnicodeString& findAndReplace(const UnicodeString& oldText,
2243 : const UnicodeString& newText);
2244 :
2245 : /**
2246 : * Replace all occurrences of characters in oldText with characters
2247 : * in newText
2248 : * in the range [<TT>start</TT>, <TT>start + length</TT>).
2249 : * @param start the start of the range in which replace will performed
2250 : * @param length the length of the range in which replace will be performed
2251 : * @param oldText the text containing the search text
2252 : * @param newText the text containing the replacement text
2253 : * @return a reference to this
2254 : * @stable ICU 2.0
2255 : */
2256 : inline UnicodeString& findAndReplace(int32_t start,
2257 : int32_t length,
2258 : const UnicodeString& oldText,
2259 : const UnicodeString& newText);
2260 :
2261 : /**
2262 : * Replace all occurrences of characters in oldText in the range
2263 : * [<TT>oldStart</TT>, <TT>oldStart + oldLength</TT>) with the characters
2264 : * in newText in the range
2265 : * [<TT>newStart</TT>, <TT>newStart + newLength</TT>)
2266 : * in the range [<TT>start</TT>, <TT>start + length</TT>).
2267 : * @param start the start of the range in which replace will performed
2268 : * @param length the length of the range in which replace will be performed
2269 : * @param oldText the text containing the search text
2270 : * @param oldStart the start of the search range in <TT>oldText</TT>
2271 : * @param oldLength the length of the search range in <TT>oldText</TT>
2272 : * @param newText the text containing the replacement text
2273 : * @param newStart the start of the replacement range in <TT>newText</TT>
2274 : * @param newLength the length of the replacement range in <TT>newText</TT>
2275 : * @return a reference to this
2276 : * @stable ICU 2.0
2277 : */
2278 : UnicodeString& findAndReplace(int32_t start,
2279 : int32_t length,
2280 : const UnicodeString& oldText,
2281 : int32_t oldStart,
2282 : int32_t oldLength,
2283 : const UnicodeString& newText,
2284 : int32_t newStart,
2285 : int32_t newLength);
2286 :
2287 :
2288 : /* Remove operations */
2289 :
2290 : /**
2291 : * Remove all characters from the UnicodeString object.
2292 : * @return a reference to this
2293 : * @stable ICU 2.0
2294 : */
2295 : inline UnicodeString& remove(void);
2296 :
2297 : /**
2298 : * Remove the characters in the range
2299 : * [<TT>start</TT>, <TT>start + length</TT>) from the UnicodeString object.
2300 : * @param start the offset of the first character to remove
2301 : * @param length the number of characters to remove
2302 : * @return a reference to this
2303 : * @stable ICU 2.0
2304 : */
2305 : inline UnicodeString& remove(int32_t start,
2306 : int32_t length = (int32_t)INT32_MAX);
2307 :
2308 : /**
2309 : * Remove the characters in the range
2310 : * [<TT>start</TT>, <TT>limit</TT>) from the UnicodeString object.
2311 : * @param start the offset of the first character to remove
2312 : * @param limit the offset immediately following the range to remove
2313 : * @return a reference to this
2314 : * @stable ICU 2.0
2315 : */
2316 : inline UnicodeString& removeBetween(int32_t start,
2317 : int32_t limit = (int32_t)INT32_MAX);
2318 :
2319 :
2320 : /* Length operations */
2321 :
2322 : /**
2323 : * Pad the start of this UnicodeString with the character <TT>padChar</TT>.
2324 : * If the length of this UnicodeString is less than targetLength,
2325 : * length() - targetLength copies of padChar will be added to the
2326 : * beginning of this UnicodeString.
2327 : * @param targetLength the desired length of the string
2328 : * @param padChar the character to use for padding. Defaults to
2329 : * space (U+0020)
2330 : * @return TRUE if the text was padded, FALSE otherwise.
2331 : * @stable ICU 2.0
2332 : */
2333 : UBool padLeading(int32_t targetLength,
2334 : UChar padChar = 0x0020);
2335 :
2336 : /**
2337 : * Pad the end of this UnicodeString with the character <TT>padChar</TT>.
2338 : * If the length of this UnicodeString is less than targetLength,
2339 : * length() - targetLength copies of padChar will be added to the
2340 : * end of this UnicodeString.
2341 : * @param targetLength the desired length of the string
2342 : * @param padChar the character to use for padding. Defaults to
2343 : * space (U+0020)
2344 : * @return TRUE if the text was padded, FALSE otherwise.
2345 : * @stable ICU 2.0
2346 : */
2347 : UBool padTrailing(int32_t targetLength,
2348 : UChar padChar = 0x0020);
2349 :
2350 : /**
2351 : * Truncate this UnicodeString to the <TT>targetLength</TT>.
2352 : * @param targetLength the desired length of this UnicodeString.
2353 : * @return TRUE if the text was truncated, FALSE otherwise
2354 : * @stable ICU 2.0
2355 : */
2356 : inline UBool truncate(int32_t targetLength);
2357 :
2358 : /**
2359 : * Trims leading and trailing whitespace from this UnicodeString.
2360 : * @return a reference to this
2361 : * @stable ICU 2.0
2362 : */
2363 : UnicodeString& trim(void);
2364 :
2365 :
2366 : /* Miscellaneous operations */
2367 :
2368 : /**
2369 : * Reverse this UnicodeString in place.
2370 : * @return a reference to this
2371 : * @stable ICU 2.0
2372 : */
2373 : inline UnicodeString& reverse(void);
2374 :
2375 : /**
2376 : * Reverse the range [<TT>start</TT>, <TT>start + length</TT>) in
2377 : * this UnicodeString.
2378 : * @param start the start of the range to reverse
2379 : * @param length the number of characters to to reverse
2380 : * @return a reference to this
2381 : * @stable ICU 2.0
2382 : */
2383 : inline UnicodeString& reverse(int32_t start,
2384 : int32_t length);
2385 :
2386 : /**
2387 : * Convert the characters in this to UPPER CASE following the conventions of
2388 : * the default locale.
2389 : * @return A reference to this.
2390 : * @stable ICU 2.0
2391 : */
2392 : UnicodeString& toUpper(void);
2393 :
2394 : /**
2395 : * Convert the characters in this to UPPER CASE following the conventions of
2396 : * a specific locale.
2397 : * @param locale The locale containing the conventions to use.
2398 : * @return A reference to this.
2399 : * @stable ICU 2.0
2400 : */
2401 : UnicodeString& toUpper(const Locale& locale);
2402 :
2403 : /**
2404 : * Convert the characters in this to lower case following the conventions of
2405 : * the default locale.
2406 : * @return A reference to this.
2407 : * @stable ICU 2.0
2408 : */
2409 : UnicodeString& toLower(void);
2410 :
2411 : /**
2412 : * Convert the characters in this to lower case following the conventions of
2413 : * a specific locale.
2414 : * @param locale The locale containing the conventions to use.
2415 : * @return A reference to this.
2416 : * @stable ICU 2.0
2417 : */
2418 : UnicodeString& toLower(const Locale& locale);
2419 :
2420 : #if !UCONFIG_NO_BREAK_ITERATION
2421 :
2422 : /**
2423 : * Titlecase this string, convenience function using the default locale.
2424 : *
2425 : * Casing is locale-dependent and context-sensitive.
2426 : * Titlecasing uses a break iterator to find the first characters of words
2427 : * that are to be titlecased. It titlecases those characters and lowercases
2428 : * all others.
2429 : *
2430 : * The titlecase break iterator can be provided to customize for arbitrary
2431 : * styles, using rules and dictionaries beyond the standard iterators.
2432 : * It may be more efficient to always provide an iterator to avoid
2433 : * opening and closing one for each string.
2434 : * The standard titlecase iterator for the root locale implements the
2435 : * algorithm of Unicode TR 21.
2436 : *
2437 : * This function uses only the first() and next() methods of the
2438 : * provided break iterator.
2439 : *
2440 : * @param titleIter A break iterator to find the first characters of words
2441 : * that are to be titlecased.
2442 : * If none is provided (0), then a standard titlecase
2443 : * break iterator is opened.
2444 : * Otherwise the provided iterator is set to the string's text.
2445 : * @return A reference to this.
2446 : * @stable ICU 2.1
2447 : */
2448 : UnicodeString &toTitle(BreakIterator *titleIter);
2449 :
2450 : /**
2451 : * Titlecase this string.
2452 : *
2453 : * Casing is locale-dependent and context-sensitive.
2454 : * Titlecasing uses a break iterator to find the first characters of words
2455 : * that are to be titlecased. It titlecases those characters and lowercases
2456 : * all others.
2457 : *
2458 : * The titlecase break iterator can be provided to customize for arbitrary
2459 : * styles, using rules and dictionaries beyond the standard iterators.
2460 : * It may be more efficient to always provide an iterator to avoid
2461 : * opening and closing one for each string.
2462 : * The standard titlecase iterator for the root locale implements the
2463 : * algorithm of Unicode TR 21.
2464 : *
2465 : * This function uses only the first() and next() methods of the
2466 : * provided break iterator.
2467 : *
2468 : * @param titleIter A break iterator to find the first characters of words
2469 : * that are to be titlecased.
2470 : * If none is provided (0), then a standard titlecase
2471 : * break iterator is opened.
2472 : * Otherwise the provided iterator is set to the string's text.
2473 : * @param locale The locale to consider.
2474 : * @return A reference to this.
2475 : * @stable ICU 2.1
2476 : */
2477 : UnicodeString &toTitle(BreakIterator *titleIter, const Locale &locale);
2478 :
2479 : #endif
2480 :
2481 : /**
2482 : * Case-fold the characters in this string.
2483 : * Case-folding is locale-independent and not context-sensitive,
2484 : * but there is an option for whether to include or exclude mappings for dotted I
2485 : * and dotless i that are marked with 'I' in CaseFolding.txt.
2486 : * The result may be longer or shorter than the original.
2487 : *
2488 : * @param options Either U_FOLD_CASE_DEFAULT or U_FOLD_CASE_EXCLUDE_SPECIAL_I
2489 : * @return A reference to this.
2490 : * @stable ICU 2.0
2491 : */
2492 : UnicodeString &foldCase(uint32_t options=0 /*U_FOLD_CASE_DEFAULT*/);
2493 :
2494 : //========================================
2495 : // Access to the internal buffer
2496 : //========================================
2497 :
2498 : /**
2499 : * Get a read/write pointer to the internal buffer.
2500 : * The buffer is guaranteed to be large enough for at least minCapacity UChars,
2501 : * writable, and is still owned by the UnicodeString object.
2502 : * Calls to getBuffer(minCapacity) must not be nested, and
2503 : * must be matched with calls to releaseBuffer(newLength).
2504 : * If the string buffer was read-only or shared,
2505 : * then it will be reallocated and copied.
2506 : *
2507 : * An attempted nested call will return 0, and will not further modify the
2508 : * state of the UnicodeString object.
2509 : * It also returns 0 if the string is bogus.
2510 : *
2511 : * The actual capacity of the string buffer may be larger than minCapacity.
2512 : * getCapacity() returns the actual capacity.
2513 : * For many operations, the full capacity should be used to avoid reallocations.
2514 : *
2515 : * While the buffer is "open" between getBuffer(minCapacity)
2516 : * and releaseBuffer(newLength), the following applies:
2517 : * - The string length is set to 0.
2518 : * - Any read API call on the UnicodeString object will behave like on a 0-length string.
2519 : * - Any write API call on the UnicodeString object is disallowed and will have no effect.
2520 : * - You can read from and write to the returned buffer.
2521 : * - The previous string contents will still be in the buffer;
2522 : * if you want to use it, then you need to call length() before getBuffer(minCapacity).
2523 : * If the length() was greater than minCapacity, then any contents after minCapacity
2524 : * may be lost.
2525 : * The buffer contents is not NUL-terminated by getBuffer().
2526 : * If length()<getCapacity() then you can terminate it by writing a NUL
2527 : * at index length().
2528 : * - You must call releaseBuffer(newLength) before and in order to
2529 : * return to normal UnicodeString operation.
2530 : *
2531 : * @param minCapacity the minimum number of UChars that are to be available
2532 : * in the buffer, starting at the returned pointer;
2533 : * default to the current string capacity if minCapacity==-1
2534 : * @return a writable pointer to the internal string buffer,
2535 : * or 0 if an error occurs (nested calls, out of memory)
2536 : *
2537 : * @see releaseBuffer
2538 : * @see getTerminatedBuffer()
2539 : * @stable ICU 2.0
2540 : */
2541 : UChar *getBuffer(int32_t minCapacity);
2542 :
2543 : /**
2544 : * Release a read/write buffer on a UnicodeString object with an
2545 : * "open" getBuffer(minCapacity).
2546 : * This function must be called in a matched pair with getBuffer(minCapacity).
2547 : * releaseBuffer(newLength) must be called if and only if a getBuffer(minCapacity) is "open".
2548 : *
2549 : * It will set the string length to newLength, at most to the current capacity.
2550 : * If newLength==-1 then it will set the length according to the
2551 : * first NUL in the buffer, or to the capacity if there is no NUL.
2552 : *
2553 : * After calling releaseBuffer(newLength) the UnicodeString is back to normal operation.
2554 : *
2555 : * @param newLength the new length of the UnicodeString object;
2556 : * defaults to the current capacity if newLength is greater than that;
2557 : * if newLength==-1, it defaults to u_strlen(buffer) but not more than
2558 : * the current capacity of the string
2559 : *
2560 : * @see getBuffer(int32_t minCapacity)
2561 : * @stable ICU 2.0
2562 : */
2563 : void releaseBuffer(int32_t newLength=-1);
2564 :
2565 : /**
2566 : * Get a read-only pointer to the internal buffer.
2567 : * This can be called at any time on a valid UnicodeString.
2568 : *
2569 : * It returns 0 if the string is bogus, or
2570 : * during an "open" getBuffer(minCapacity).
2571 : *
2572 : * It can be called as many times as desired.
2573 : * The pointer that it returns will remain valid until the UnicodeString object is modified,
2574 : * at which time the pointer is semantically invalidated and must not be used any more.
2575 : *
2576 : * The capacity of the buffer can be determined with getCapacity().
2577 : * The part after length() may or may not be initialized and valid,
2578 : * depending on the history of the UnicodeString object.
2579 : *
2580 : * The buffer contents is (probably) not NUL-terminated.
2581 : * You can check if it is with
2582 : * <code>(s.length()<s.getCapacity() && buffer[s.length()]==0)</code>.
2583 : * (See getTerminatedBuffer().)
2584 : *
2585 : * The buffer may reside in read-only memory. Its contents must not
2586 : * be modified.
2587 : *
2588 : * @return a read-only pointer to the internal string buffer,
2589 : * or 0 if the string is empty or bogus
2590 : *
2591 : * @see getBuffer(int32_t minCapacity)
2592 : * @see getTerminatedBuffer()
2593 : * @stable ICU 2.0
2594 : */
2595 : inline const UChar *getBuffer() const;
2596 :
2597 : /**
2598 : * Get a read-only pointer to the internal buffer,
2599 : * making sure that it is NUL-terminated.
2600 : * This can be called at any time on a valid UnicodeString.
2601 : *
2602 : * It returns 0 if the string is bogus, or
2603 : * during an "open" getBuffer(minCapacity), or if the buffer cannot
2604 : * be NUL-terminated (because memory allocation failed).
2605 : *
2606 : * It can be called as many times as desired.
2607 : * The pointer that it returns will remain valid until the UnicodeString object is modified,
2608 : * at which time the pointer is semantically invalidated and must not be used any more.
2609 : *
2610 : * The capacity of the buffer can be determined with getCapacity().
2611 : * The part after length()+1 may or may not be initialized and valid,
2612 : * depending on the history of the UnicodeString object.
2613 : *
2614 : * The buffer contents is guaranteed to be NUL-terminated.
2615 : * getTerminatedBuffer() may reallocate the buffer if a terminating NUL
2616 : * is written.
2617 : * For this reason, this function is not const, unlike getBuffer().
2618 : * Note that a UnicodeString may also contain NUL characters as part of its contents.
2619 : *
2620 : * The buffer may reside in read-only memory. Its contents must not
2621 : * be modified.
2622 : *
2623 : * @return a read-only pointer to the internal string buffer,
2624 : * or 0 if the string is empty or bogus
2625 : *
2626 : * @see getBuffer(int32_t minCapacity)
2627 : * @see getBuffer()
2628 : * @stable ICU 2.2
2629 : */
2630 : inline const UChar *getTerminatedBuffer();
2631 :
2632 : //========================================
2633 : // Constructors
2634 : //========================================
2635 :
2636 : /** Construct an empty UnicodeString.
2637 : * @stable ICU 2.0
2638 : */
2639 : UnicodeString();
2640 :
2641 : /**
2642 : * Construct a UnicodeString with capacity to hold <TT>capacity</TT> UChars
2643 : * @param capacity the number of UChars this UnicodeString should hold
2644 : * before a resize is necessary; if count is greater than 0 and count
2645 : * code points c take up more space than capacity, then capacity is adjusted
2646 : * accordingly.
2647 : * @param c is used to initially fill the string
2648 : * @param count specifies how many code points c are to be written in the
2649 : * string
2650 : * @stable ICU 2.0
2651 : */
2652 : UnicodeString(int32_t capacity, UChar32 c, int32_t count);
2653 :
2654 : /**
2655 : * Single UChar (code unit) constructor.
2656 : * @param ch the character to place in the UnicodeString
2657 : * @stable ICU 2.0
2658 : */
2659 : UnicodeString(UChar ch);
2660 :
2661 : /**
2662 : * Single UChar32 (code point) constructor.
2663 : * @param ch the character to place in the UnicodeString
2664 : * @stable ICU 2.0
2665 : */
2666 : UnicodeString(UChar32 ch);
2667 :
2668 : /**
2669 : * UChar* constructor.
2670 : * @param text The characters to place in the UnicodeString. <TT>text</TT>
2671 : * must be NULL (U+0000) terminated.
2672 : * @stable ICU 2.0
2673 : */
2674 : UnicodeString(const UChar *text);
2675 :
2676 : /**
2677 : * UChar* constructor.
2678 : * @param text The characters to place in the UnicodeString.
2679 : * @param textLength The number of Unicode characters in <TT>text</TT>
2680 : * to copy.
2681 : * @stable ICU 2.0
2682 : */
2683 : UnicodeString(const UChar *text,
2684 : int32_t textLength);
2685 :
2686 : /**
2687 : * Readonly-aliasing UChar* constructor.
2688 : * The text will be used for the UnicodeString object, but
2689 : * it will not be released when the UnicodeString is destroyed.
2690 : * This has copy-on-write semantics:
2691 : * When the string is modified, then the buffer is first copied into
2692 : * newly allocated memory.
2693 : * The aliased buffer is never modified.
2694 : * In an assignment to another UnicodeString, the text will be aliased again,
2695 : * so that both strings then alias the same readonly-text.
2696 : *
2697 : * @param isTerminated specifies if <code>text</code> is <code>NUL</code>-terminated.
2698 : * This must be true if <code>textLength==-1</code>.
2699 : * @param text The characters to alias for the UnicodeString.
2700 : * @param textLength The number of Unicode characters in <code>text</code> to alias.
2701 : * If -1, then this constructor will determine the length
2702 : * by calling <code>u_strlen()</code>.
2703 : * @stable ICU 2.0
2704 : */
2705 : UnicodeString(UBool isTerminated,
2706 : const UChar *text,
2707 : int32_t textLength);
2708 :
2709 : /**
2710 : * Writable-aliasing UChar* constructor.
2711 : * The text will be used for the UnicodeString object, but
2712 : * it will not be released when the UnicodeString is destroyed.
2713 : * This has write-through semantics:
2714 : * For as long as the capacity of the buffer is sufficient, write operations
2715 : * will directly affect the buffer. When more capacity is necessary, then
2716 : * a new buffer will be allocated and the contents copied as with regularly
2717 : * constructed strings.
2718 : * In an assignment to another UnicodeString, the buffer will be copied.
2719 : * The extract(UChar *dst) function detects whether the dst pointer is the same
2720 : * as the string buffer itself and will in this case not copy the contents.
2721 : *
2722 : * @param buffer The characters to alias for the UnicodeString.
2723 : * @param buffLength The number of Unicode characters in <code>buffer</code> to alias.
2724 : * @param buffCapacity The size of <code>buffer</code> in UChars.
2725 : * @stable ICU 2.0
2726 : */
2727 : UnicodeString(UChar *buffer, int32_t buffLength, int32_t buffCapacity);
2728 :
2729 : #if !UCONFIG_NO_CONVERSION
2730 :
2731 : /**
2732 : * char* constructor.
2733 : * @param codepageData an array of bytes, null-terminated
2734 : * @param codepage the encoding of <TT>codepageData</TT>. The special
2735 : * value 0 for <TT>codepage</TT> indicates that the text is in the
2736 : * platform's default codepage.
2737 : *
2738 : * If <code>codepage</code> is an empty string (<code>""</code>),
2739 : * then a simple conversion is performed on the codepage-invariant
2740 : * subset ("invariant characters") of the platform encoding. See utypes.h.
2741 : * Recommendation: For invariant-character strings use the constructor
2742 : * UnicodeString(const char *src, int32_t length, enum EInvariant inv)
2743 : * because it avoids object code dependencies of UnicodeString on
2744 : * the conversion code.
2745 : *
2746 : * @stable ICU 2.0
2747 : */
2748 : UnicodeString(const char *codepageData,
2749 : const char *codepage = 0);
2750 :
2751 : /**
2752 : * char* constructor.
2753 : * @param codepageData an array of bytes.
2754 : * @param dataLength The number of bytes in <TT>codepageData</TT>.
2755 : * @param codepage the encoding of <TT>codepageData</TT>. The special
2756 : * value 0 for <TT>codepage</TT> indicates that the text is in the
2757 : * platform's default codepage.
2758 : * If <code>codepage</code> is an empty string (<code>""</code>),
2759 : * then a simple conversion is performed on the codepage-invariant
2760 : * subset ("invariant characters") of the platform encoding. See utypes.h.
2761 : * Recommendation: For invariant-character strings use the constructor
2762 : * UnicodeString(const char *src, int32_t length, enum EInvariant inv)
2763 : * because it avoids object code dependencies of UnicodeString on
2764 : * the conversion code.
2765 : *
2766 : * @stable ICU 2.0
2767 : */
2768 : UnicodeString(const char *codepageData,
2769 : int32_t dataLength,
2770 : const char *codepage = 0);
2771 :
2772 : /**
2773 : * char * / UConverter constructor.
2774 : * This constructor uses an existing UConverter object to
2775 : * convert the codepage string to Unicode and construct a UnicodeString
2776 : * from that.
2777 : *
2778 : * The converter is reset at first.
2779 : * If the error code indicates a failure before this constructor is called,
2780 : * or if an error occurs during conversion or construction,
2781 : * then the string will be bogus.
2782 : *
2783 : * This function avoids the overhead of opening and closing a converter if
2784 : * multiple strings are constructed.
2785 : *
2786 : * @param src input codepage string
2787 : * @param srcLength length of the input string, can be -1 for NUL-terminated strings
2788 : * @param cnv converter object (ucnv_resetToUnicode() will be called),
2789 : * can be NULL for the default converter
2790 : * @param errorCode normal ICU error code
2791 : * @stable ICU 2.0
2792 : */
2793 : UnicodeString(
2794 : const char *src, int32_t srcLength,
2795 : UConverter *cnv,
2796 : UErrorCode &errorCode);
2797 :
2798 : #endif
2799 :
2800 : /**
2801 : * Constructs a Unicode string from an invariant-character char * string.
2802 : * About invariant characters see utypes.h.
2803 : * This constructor has no runtime dependency on conversion code and is
2804 : * therefore recommended over ones taking a charset name string
2805 : * (where the empty string "" indicates invariant-character conversion).
2806 : *
2807 : * Use the macro US_INV as the third, signature-distinguishing parameter.
2808 : *
2809 : * For example:
2810 : * \code
2811 : * void fn(const char *s) {
2812 : * UnicodeString ustr(s, -1, US_INV);
2813 : * // use ustr ...
2814 : * }
2815 : * \endcode
2816 : *
2817 : * @param src String using only invariant characters.
2818 : * @param length Length of src, or -1 if NUL-terminated.
2819 : * @param inv Signature-distinguishing paramater, use US_INV.
2820 : *
2821 : * @see US_INV
2822 : * @stable ICU 3.2
2823 : */
2824 : UnicodeString(const char *src, int32_t length, enum EInvariant inv);
2825 :
2826 :
2827 : /**
2828 : * Copy constructor.
2829 : * @param that The UnicodeString object to copy.
2830 : * @stable ICU 2.0
2831 : */
2832 : UnicodeString(const UnicodeString& that);
2833 :
2834 : /**
2835 : * 'Substring' constructor from tail of source string.
2836 : * @param src The UnicodeString object to copy.
2837 : * @param srcStart The offset into <tt>src</tt> at which to start copying.
2838 : * @stable ICU 2.2
2839 : */
2840 : UnicodeString(const UnicodeString& src, int32_t srcStart);
2841 :
2842 : /**
2843 : * 'Substring' constructor from subrange of source string.
2844 : * @param src The UnicodeString object to copy.
2845 : * @param srcStart The offset into <tt>src</tt> at which to start copying.
2846 : * @param srcLength The number of characters from <tt>src</tt> to copy.
2847 : * @stable ICU 2.2
2848 : */
2849 : UnicodeString(const UnicodeString& src, int32_t srcStart, int32_t srcLength);
2850 :
2851 : /**
2852 : * Clone this object, an instance of a subclass of Replaceable.
2853 : * Clones can be used concurrently in multiple threads.
2854 : * If a subclass does not implement clone(), or if an error occurs,
2855 : * then NULL is returned.
2856 : * The clone functions in all subclasses return a pointer to a Replaceable
2857 : * because some compilers do not support covariant (same-as-this)
2858 : * return types; cast to the appropriate subclass if necessary.
2859 : * The caller must delete the clone.
2860 : *
2861 : * @return a clone of this object
2862 : *
2863 : * @see Replaceable::clone
2864 : * @see getDynamicClassID
2865 : * @stable ICU 2.6
2866 : */
2867 : virtual Replaceable *clone() const;
2868 :
2869 : /** Destructor.
2870 : * @stable ICU 2.0
2871 : */
2872 : virtual ~UnicodeString();
2873 :
2874 :
2875 : /* Miscellaneous operations */
2876 :
2877 : /**
2878 : * Unescape a string of characters and return a string containing
2879 : * the result. The following escape sequences are recognized:
2880 : *
2881 : * \\uhhhh 4 hex digits; h in [0-9A-Fa-f]
2882 : * \\Uhhhhhhhh 8 hex digits
2883 : * \\xhh 1-2 hex digits
2884 : * \\ooo 1-3 octal digits; o in [0-7]
2885 : * \\cX control-X; X is masked with 0x1F
2886 : *
2887 : * as well as the standard ANSI C escapes:
2888 : *
2889 : * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A,
2890 : * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B,
2891 : * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C
2892 : *
2893 : * Anything else following a backslash is generically escaped. For
2894 : * example, "[a\\-z]" returns "[a-z]".
2895 : *
2896 : * If an escape sequence is ill-formed, this method returns an empty
2897 : * string. An example of an ill-formed sequence is "\\u" followed by
2898 : * fewer than 4 hex digits.
2899 : *
2900 : * This function is similar to u_unescape() but not identical to it.
2901 : * The latter takes a source char*, so it does escape recognition
2902 : * and also invariant conversion.
2903 : *
2904 : * @return a string with backslash escapes interpreted, or an
2905 : * empty string on error.
2906 : * @see UnicodeString#unescapeAt()
2907 : * @see u_unescape()
2908 : * @see u_unescapeAt()
2909 : * @stable ICU 2.0
2910 : */
2911 : UnicodeString unescape() const;
2912 :
2913 : /**
2914 : * Unescape a single escape sequence and return the represented
2915 : * character. See unescape() for a listing of the recognized escape
2916 : * sequences. The character at offset-1 is assumed (without
2917 : * checking) to be a backslash. If the escape sequence is
2918 : * ill-formed, or the offset is out of range, (UChar32)0xFFFFFFFF is
2919 : * returned.
2920 : *
2921 : * @param offset an input output parameter. On input, it is the
2922 : * offset into this string where the escape sequence is located,
2923 : * after the initial backslash. On output, it is advanced after the
2924 : * last character parsed. On error, it is not advanced at all.
2925 : * @return the character represented by the escape sequence at
2926 : * offset, or (UChar32)0xFFFFFFFF on error.
2927 : * @see UnicodeString#unescape()
2928 : * @see u_unescape()
2929 : * @see u_unescapeAt()
2930 : * @stable ICU 2.0
2931 : */
2932 : UChar32 unescapeAt(int32_t &offset) const;
2933 :
2934 : /**
2935 : * ICU "poor man's RTTI", returns a UClassID for this class.
2936 : *
2937 : * @stable ICU 2.2
2938 : */
2939 : static UClassID U_EXPORT2 getStaticClassID();
2940 :
2941 : /**
2942 : * ICU "poor man's RTTI", returns a UClassID for the actual class.
2943 : *
2944 : * @stable ICU 2.2
2945 : */
2946 : virtual UClassID getDynamicClassID() const;
2947 :
2948 : //========================================
2949 : // Implementation methods
2950 : //========================================
2951 :
2952 : protected:
2953 : /**
2954 : * Implement Replaceable::getLength() (see jitterbug 1027).
2955 : * @stable ICU 2.4
2956 : */
2957 : virtual int32_t getLength() const;
2958 :
2959 : /**
2960 : * The change in Replaceable to use virtual getCharAt() allows
2961 : * UnicodeString::charAt() to be inline again (see jitterbug 709).
2962 : * @stable ICU 2.4
2963 : */
2964 : virtual UChar getCharAt(int32_t offset) const;
2965 :
2966 : /**
2967 : * The change in Replaceable to use virtual getChar32At() allows
2968 : * UnicodeString::char32At() to be inline again (see jitterbug 709).
2969 : * @stable ICU 2.4
2970 : */
2971 : virtual UChar32 getChar32At(int32_t offset) const;
2972 :
2973 : private:
2974 :
2975 : inline int8_t
2976 : doCompare(int32_t start,
2977 : int32_t length,
2978 : const UnicodeString& srcText,
2979 : int32_t srcStart,
2980 : int32_t srcLength) const;
2981 :
2982 : int8_t doCompare(int32_t start,
2983 : int32_t length,
2984 : const UChar *srcChars,
2985 : int32_t srcStart,
2986 : int32_t srcLength) const;
2987 :
2988 : inline int8_t
2989 : doCompareCodePointOrder(int32_t start,
2990 : int32_t length,
2991 : const UnicodeString& srcText,
2992 : int32_t srcStart,
2993 : int32_t srcLength) const;
2994 :
2995 : int8_t doCompareCodePointOrder(int32_t start,
2996 : int32_t length,
2997 : const UChar *srcChars,
2998 : int32_t srcStart,
2999 : int32_t srcLength) const;
3000 :
3001 : inline int8_t
3002 : doCaseCompare(int32_t start,
3003 : int32_t length,
3004 : const UnicodeString &srcText,
3005 : int32_t srcStart,
3006 : int32_t srcLength,
3007 : uint32_t options) const;
3008 :
3009 : int8_t
3010 : doCaseCompare(int32_t start,
3011 : int32_t length,
3012 : const UChar *srcChars,
3013 : int32_t srcStart,
3014 : int32_t srcLength,
3015 : uint32_t options) const;
3016 :
3017 : int32_t doIndexOf(UChar c,
3018 : int32_t start,
3019 : int32_t length) const;
3020 :
3021 : int32_t doIndexOf(UChar32 c,
3022 : int32_t start,
3023 : int32_t length) const;
3024 :
3025 : int32_t doLastIndexOf(UChar c,
3026 : int32_t start,
3027 : int32_t length) const;
3028 :
3029 : int32_t doLastIndexOf(UChar32 c,
3030 : int32_t start,
3031 : int32_t length) const;
3032 :
3033 : void doExtract(int32_t start,
3034 : int32_t length,
3035 : UChar *dst,
3036 : int32_t dstStart) const;
3037 :
3038 : inline void doExtract(int32_t start,
3039 : int32_t length,
3040 : UnicodeString& target) const;
3041 :
3042 : inline UChar doCharAt(int32_t offset) const;
3043 :
3044 : UnicodeString& doReplace(int32_t start,
3045 : int32_t length,
3046 : const UnicodeString& srcText,
3047 : int32_t srcStart,
3048 : int32_t srcLength);
3049 :
3050 : UnicodeString& doReplace(int32_t start,
3051 : int32_t length,
3052 : const UChar *srcChars,
3053 : int32_t srcStart,
3054 : int32_t srcLength);
3055 :
3056 : UnicodeString& doReverse(int32_t start,
3057 : int32_t length);
3058 :
3059 : // calculate hash code
3060 : int32_t doHashCode(void) const;
3061 :
3062 : // get pointer to start of array
3063 : inline UChar* getArrayStart(void);
3064 : inline const UChar* getArrayStart(void) const;
3065 :
3066 : // allocate the array; result may be fStackBuffer
3067 : // sets refCount to 1 if appropriate
3068 : // sets fArray, fCapacity, and fFlags
3069 : // returns boolean for success or failure
3070 : UBool allocate(int32_t capacity);
3071 :
3072 : // release the array if owned
3073 : void releaseArray(void);
3074 :
3075 : // turn a bogus string into an empty one
3076 : void unBogus();
3077 :
3078 : // implements assigment operator, copy constructor, and fastCopyFrom()
3079 : UnicodeString ©From(const UnicodeString &src, UBool fastCopy=FALSE);
3080 :
3081 : // Pin start and limit to acceptable values.
3082 : inline void pinIndex(int32_t& start) const;
3083 : inline void pinIndices(int32_t& start,
3084 : int32_t& length) const;
3085 :
3086 : #if !UCONFIG_NO_CONVERSION
3087 :
3088 : /* Internal extract() using UConverter. */
3089 : int32_t doExtract(int32_t start, int32_t length,
3090 : char *dest, int32_t destCapacity,
3091 : UConverter *cnv,
3092 : UErrorCode &errorCode) const;
3093 :
3094 : /*
3095 : * Real constructor for converting from codepage data.
3096 : * It assumes that it is called with !fRefCounted.
3097 : *
3098 : * If <code>codepage==0</code>, then the default converter
3099 : * is used for the platform encoding.
3100 : * If <code>codepage</code> is an empty string (<code>""</code>),
3101 : * then a simple conversion is performed on the codepage-invariant
3102 : * subset ("invariant characters") of the platform encoding. See utypes.h.
3103 : */
3104 : void doCodepageCreate(const char *codepageData,
3105 : int32_t dataLength,
3106 : const char *codepage);
3107 :
3108 : /*
3109 : * Worker function for creating a UnicodeString from
3110 : * a codepage string using a UConverter.
3111 : */
3112 : void
3113 : doCodepageCreate(const char *codepageData,
3114 : int32_t dataLength,
3115 : UConverter *converter,
3116 : UErrorCode &status);
3117 :
3118 : #endif
3119 :
3120 : /*
3121 : * This function is called when write access to the array
3122 : * is necessary.
3123 : *
3124 : * We need to make a copy of the array if
3125 : * the buffer is read-only, or
3126 : * the buffer is refCounted (shared), and refCount>1, or
3127 : * the buffer is too small.
3128 : *
3129 : * Return FALSE if memory could not be allocated.
3130 : */
3131 : UBool cloneArrayIfNeeded(int32_t newCapacity = -1,
3132 : int32_t growCapacity = -1,
3133 : UBool doCopyArray = TRUE,
3134 : int32_t **pBufferToDelete = 0,
3135 : UBool forceClone = FALSE);
3136 :
3137 : // common function for case mappings
3138 : UnicodeString &
3139 : caseMap(BreakIterator *titleIter,
3140 : const char *locale,
3141 : uint32_t options,
3142 : int32_t toWhichCase);
3143 :
3144 : // ref counting
3145 : void addRef(void);
3146 : int32_t removeRef(void);
3147 : int32_t refCount(void) const;
3148 :
3149 : // constants
3150 : enum {
3151 : US_STACKBUF_SIZE=7, // Size of stack buffer for small strings
3152 : kInvalidUChar=0xffff, // invalid UChar index
3153 : kGrowSize=128, // grow size for this buffer
3154 : kInvalidHashCode=0, // invalid hash code
3155 : kEmptyHashCode=1, // hash code for empty string
3156 :
3157 : // bit flag values for fFlags
3158 : kIsBogus=1, // this string is bogus, i.e., not valid or NULL
3159 : kUsingStackBuffer=2,// fArray==fStackBuffer
3160 : kRefCounted=4, // there is a refCount field before the characters in fArray
3161 : kBufferIsReadonly=8,// do not write to this buffer
3162 : kOpenGetBuffer=16, // getBuffer(minCapacity) was called (is "open"),
3163 : // and releaseBuffer(newLength) must be called
3164 :
3165 : // combined values for convenience
3166 : kShortString=kUsingStackBuffer,
3167 : kLongString=kRefCounted,
3168 : kReadonlyAlias=kBufferIsReadonly,
3169 : kWritableAlias=0
3170 : };
3171 :
3172 : friend class StringCharacterIterator;
3173 : friend class StringThreadTest;
3174 :
3175 : /*
3176 : * The following are all the class fields that are stored
3177 : * in each UnicodeString object.
3178 : * Note that UnicodeString has virtual functions,
3179 : * therefore there is an implicit vtable pointer
3180 : * as the first real field.
3181 : * The fields should be aligned such that no padding is
3182 : * necessary, mostly by having larger types first.
3183 : * On 32-bit machines, the size should be 32 bytes,
3184 : * on 64-bit machines (8-byte pointers), it should be 40 bytes.
3185 : */
3186 : // (implicit) *vtable;
3187 : int32_t fLength; // number of characters in fArray
3188 : int32_t fCapacity; // sizeof fArray
3189 : UChar *fArray; // the Unicode data
3190 : uint16_t fFlags; // bit flags: see constants above
3191 : UChar fStackBuffer [ US_STACKBUF_SIZE ]; // buffer for small strings
3192 :
3193 : };
3194 :
3195 : /**
3196 : * Create a new UnicodeString with the concatenation of two others.
3197 : *
3198 : * @param s1 The first string to be copied to the new one.
3199 : * @param s2 The second string to be copied to the new one, after s1.
3200 : * @return UnicodeString(s1).append(s2)
3201 : * @stable ICU 2.8
3202 : */
3203 : U_COMMON_API UnicodeString U_EXPORT2
3204 : operator+ (const UnicodeString &s1, const UnicodeString &s2);
3205 :
3206 : //========================================
3207 : // Inline members
3208 : //========================================
3209 :
3210 : //========================================
3211 : // Privates
3212 : //========================================
3213 :
3214 : inline void
3215 : UnicodeString::pinIndex(int32_t& start) const
3216 : {
3217 : // pin index
3218 : if(start < 0) {
3219 : start = 0;
3220 : } else if(start > fLength) {
3221 : start = fLength;
3222 : }
3223 : }
3224 :
3225 : inline void
3226 : UnicodeString::pinIndices(int32_t& start,
3227 : int32_t& _length) const
3228 : {
3229 : // pin indices
3230 : if(start < 0) {
3231 : start = 0;
3232 : } else if(start > fLength) {
3233 : start = fLength;
3234 : }
3235 : if(_length < 0) {
3236 : _length = 0;
3237 : } else if(_length > (fLength - start)) {
3238 : _length = (fLength - start);
3239 : }
3240 : }
3241 :
3242 : inline UChar*
3243 : UnicodeString::getArrayStart()
3244 : { return fArray; }
3245 :
3246 : inline const UChar*
3247 : UnicodeString::getArrayStart() const
3248 : { return fArray; }
3249 :
3250 : //========================================
3251 : // Read-only implementation methods
3252 : //========================================
3253 : inline int32_t
3254 26 : UnicodeString::length() const
3255 26 : { return fLength; }
3256 :
3257 : inline int32_t
3258 : UnicodeString::getCapacity() const
3259 : { return fCapacity; }
3260 :
3261 : inline int32_t
3262 : UnicodeString::hashCode() const
3263 : { return doHashCode(); }
3264 :
3265 : inline UBool
3266 : UnicodeString::isBogus() const
3267 : { return (UBool)(fFlags & kIsBogus); }
3268 :
3269 : inline const UChar *
3270 0 : UnicodeString::getBuffer() const {
3271 0 : if(!(fFlags&(kIsBogus|kOpenGetBuffer))) {
3272 0 : return fArray;
3273 : } else {
3274 0 : return 0;
3275 : }
3276 : }
3277 :
3278 : //========================================
3279 : // Read-only alias methods
3280 : //========================================
3281 : inline int8_t
3282 : UnicodeString::doCompare(int32_t start,
3283 : int32_t length,
3284 : const UnicodeString& srcText,
3285 : int32_t srcStart,
3286 : int32_t srcLength) const
3287 : {
3288 : if(srcText.isBogus()) {
3289 : return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise
3290 : } else {
3291 : srcText.pinIndices(srcStart, srcLength);
3292 : return doCompare(start, length, srcText.fArray, srcStart, srcLength);
3293 : }
3294 : }
3295 :
3296 : inline UBool
3297 : UnicodeString::operator== (const UnicodeString& text) const
3298 : {
3299 : if(isBogus()) {
3300 : return text.isBogus();
3301 : } else {
3302 : return
3303 : !text.isBogus() &&
3304 : fLength == text.fLength &&
3305 : doCompare(0, fLength, text, 0, text.fLength) == 0;
3306 : }
3307 : }
3308 :
3309 : inline UBool
3310 : UnicodeString::operator!= (const UnicodeString& text) const
3311 : { return (! operator==(text)); }
3312 :
3313 : inline UBool
3314 : UnicodeString::operator> (const UnicodeString& text) const
3315 : { return doCompare(0, fLength, text, 0, text.fLength) == 1; }
3316 :
3317 : inline UBool
3318 : UnicodeString::operator< (const UnicodeString& text) const
3319 : { return doCompare(0, fLength, text, 0, text.fLength) == -1; }
3320 :
3321 : inline UBool
3322 : UnicodeString::operator>= (const UnicodeString& text) const
3323 : { return doCompare(0, fLength, text, 0, text.fLength) != -1; }
3324 :
3325 : inline UBool
3326 : UnicodeString::operator<= (const UnicodeString& text) const
3327 : { return doCompare(0, fLength, text, 0, text.fLength) != 1; }
3328 :
3329 : inline int8_t
3330 : UnicodeString::compare(const UnicodeString& text) const
3331 : { return doCompare(0, fLength, text, 0, text.fLength); }
3332 :
3333 : inline int8_t
3334 : UnicodeString::compare(int32_t start,
3335 : int32_t _length,
3336 : const UnicodeString& srcText) const
3337 : { return doCompare(start, _length, srcText, 0, srcText.fLength); }
3338 :
3339 : inline int8_t
3340 : UnicodeString::compare(const UChar *srcChars,
3341 : int32_t srcLength) const
3342 : { return doCompare(0, fLength, srcChars, 0, srcLength); }
3343 :
3344 : inline int8_t
3345 : UnicodeString::compare(int32_t start,
3346 : int32_t _length,
3347 : const UnicodeString& srcText,
3348 : int32_t srcStart,
3349 : int32_t srcLength) const
3350 : { return doCompare(start, _length, srcText, srcStart, srcLength); }
3351 :
3352 : inline int8_t
3353 : UnicodeString::compare(int32_t start,
3354 : int32_t _length,
3355 : const UChar *srcChars) const
3356 : { return doCompare(start, _length, srcChars, 0, _length); }
3357 :
3358 : inline int8_t
3359 : UnicodeString::compare(int32_t start,
3360 : int32_t _length,
3361 : const UChar *srcChars,
3362 : int32_t srcStart,
3363 : int32_t srcLength) const
3364 : { return doCompare(start, _length, srcChars, srcStart, srcLength); }
3365 :
3366 : inline int8_t
3367 : UnicodeString::compareBetween(int32_t start,
3368 : int32_t limit,
3369 : const UnicodeString& srcText,
3370 : int32_t srcStart,
3371 : int32_t srcLimit) const
3372 : { return doCompare(start, limit - start,
3373 : srcText, srcStart, srcLimit - srcStart); }
3374 :
3375 : inline int8_t
3376 : UnicodeString::doCompareCodePointOrder(int32_t start,
3377 : int32_t length,
3378 : const UnicodeString& srcText,
3379 : int32_t srcStart,
3380 : int32_t srcLength) const
3381 : {
3382 : if(srcText.isBogus()) {
3383 : return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise
3384 : } else {
3385 : srcText.pinIndices(srcStart, srcLength);
3386 : return doCompareCodePointOrder(start, length, srcText.fArray, srcStart, srcLength);
3387 : }
3388 : }
3389 :
3390 : inline int8_t
3391 : UnicodeString::compareCodePointOrder(const UnicodeString& text) const
3392 : { return doCompareCodePointOrder(0, fLength, text, 0, text.fLength); }
3393 :
3394 : inline int8_t
3395 : UnicodeString::compareCodePointOrder(int32_t start,
3396 : int32_t _length,
3397 : const UnicodeString& srcText) const
3398 : { return doCompareCodePointOrder(start, _length, srcText, 0, srcText.fLength); }
3399 :
3400 : inline int8_t
3401 : UnicodeString::compareCodePointOrder(const UChar *srcChars,
3402 : int32_t srcLength) const
3403 : { return doCompareCodePointOrder(0, fLength, srcChars, 0, srcLength); }
3404 :
3405 : inline int8_t
3406 : UnicodeString::compareCodePointOrder(int32_t start,
3407 : int32_t _length,
3408 : const UnicodeString& srcText,
3409 : int32_t srcStart,
3410 : int32_t srcLength) const
3411 : { return doCompareCodePointOrder(start, _length, srcText, srcStart, srcLength); }
3412 :
3413 : inline int8_t
3414 : UnicodeString::compareCodePointOrder(int32_t start,
3415 : int32_t _length,
3416 : const UChar *srcChars) const
3417 : { return doCompareCodePointOrder(start, _length, srcChars, 0, _length); }
3418 :
3419 : inline int8_t
3420 : UnicodeString::compareCodePointOrder(int32_t start,
3421 : int32_t _length,
3422 : const UChar *srcChars,
3423 : int32_t srcStart,
3424 : int32_t srcLength) const
3425 : { return doCompareCodePointOrder(start, _length, srcChars, srcStart, srcLength); }
3426 :
3427 : inline int8_t
3428 : UnicodeString::compareCodePointOrderBetween(int32_t start,
3429 : int32_t limit,
3430 : const UnicodeString& srcText,
3431 : int32_t srcStart,
3432 : int32_t srcLimit) const
3433 : { return doCompareCodePointOrder(start, limit - start,
3434 : srcText, srcStart, srcLimit - srcStart); }
3435 :
3436 : inline int8_t
3437 : UnicodeString::doCaseCompare(int32_t start,
3438 : int32_t length,
3439 : const UnicodeString &srcText,
3440 : int32_t srcStart,
3441 : int32_t srcLength,
3442 : uint32_t options) const
3443 : {
3444 : if(srcText.isBogus()) {
3445 : return (int8_t)!isBogus(); // 0 if both are bogus, 1 otherwise
3446 : } else {
3447 : srcText.pinIndices(srcStart, srcLength);
3448 : return doCaseCompare(start, length, srcText.fArray, srcStart, srcLength, options);
3449 : }
3450 : }
3451 :
3452 : inline int8_t
3453 : UnicodeString::caseCompare(const UnicodeString &text, uint32_t options) const {
3454 : return doCaseCompare(0, fLength, text, 0, text.fLength, options);
3455 : }
3456 :
3457 : inline int8_t
3458 : UnicodeString::caseCompare(int32_t start,
3459 : int32_t _length,
3460 : const UnicodeString &srcText,
3461 : uint32_t options) const {
3462 : return doCaseCompare(start, _length, srcText, 0, srcText.fLength, options);
3463 : }
3464 :
3465 : inline int8_t
3466 : UnicodeString::caseCompare(const UChar *srcChars,
3467 : int32_t srcLength,
3468 : uint32_t options) const {
3469 : return doCaseCompare(0, fLength, srcChars, 0, srcLength, options);
3470 : }
3471 :
3472 : inline int8_t
3473 : UnicodeString::caseCompare(int32_t start,
3474 : int32_t _length,
3475 : const UnicodeString &srcText,
3476 : int32_t srcStart,
3477 : int32_t srcLength,
3478 : uint32_t options) const {
3479 : return doCaseCompare(start, _length, srcText, srcStart, srcLength, options);
3480 : }
3481 :
3482 : inline int8_t
3483 : UnicodeString::caseCompare(int32_t start,
3484 : int32_t _length,
3485 : const UChar *srcChars,
3486 : uint32_t options) const {
3487 : return doCaseCompare(start, _length, srcChars, 0, _length, options);
3488 : }
3489 :
3490 : inline int8_t
3491 : UnicodeString::caseCompare(int32_t start,
3492 : int32_t _length,
3493 : const UChar *srcChars,
3494 : int32_t srcStart,
3495 : int32_t srcLength,
3496 : uint32_t options) const {
3497 : return doCaseCompare(start, _length, srcChars, srcStart, srcLength, options);
3498 : }
3499 :
3500 : inline int8_t
3501 : UnicodeString::caseCompareBetween(int32_t start,
3502 : int32_t limit,
3503 : const UnicodeString &srcText,
3504 : int32_t srcStart,
3505 : int32_t srcLimit,
3506 : uint32_t options) const {
3507 : return doCaseCompare(start, limit - start, srcText, srcStart, srcLimit - srcStart, options);
3508 : }
3509 :
3510 : inline int32_t
3511 : UnicodeString::indexOf(const UnicodeString& srcText,
3512 : int32_t srcStart,
3513 : int32_t srcLength,
3514 : int32_t start,
3515 : int32_t _length) const
3516 : {
3517 : if(!srcText.isBogus()) {
3518 : srcText.pinIndices(srcStart, srcLength);
3519 : if(srcLength > 0) {
3520 : return indexOf(srcText.getArrayStart(), srcStart, srcLength, start, _length);
3521 : }
3522 : }
3523 : return -1;
3524 : }
3525 :
3526 : inline int32_t
3527 : UnicodeString::indexOf(const UnicodeString& text) const
3528 : { return indexOf(text, 0, text.fLength, 0, fLength); }
3529 :
3530 : inline int32_t
3531 : UnicodeString::indexOf(const UnicodeString& text,
3532 : int32_t start) const {
3533 : pinIndex(start);
3534 : return indexOf(text, 0, text.fLength, start, fLength - start);
3535 : }
3536 :
3537 : inline int32_t
3538 : UnicodeString::indexOf(const UnicodeString& text,
3539 : int32_t start,
3540 : int32_t _length) const
3541 : { return indexOf(text, 0, text.fLength, start, _length); }
3542 :
3543 : inline int32_t
3544 : UnicodeString::indexOf(const UChar *srcChars,
3545 : int32_t srcLength,
3546 : int32_t start) const {
3547 : pinIndex(start);
3548 : return indexOf(srcChars, 0, srcLength, start, fLength - start);
3549 : }
3550 :
3551 : inline int32_t
3552 : UnicodeString::indexOf(const UChar *srcChars,
3553 : int32_t srcLength,
3554 : int32_t start,
3555 : int32_t _length) const
3556 : { return indexOf(srcChars, 0, srcLength, start, _length); }
3557 :
3558 : inline int32_t
3559 : UnicodeString::indexOf(UChar c,
3560 : int32_t start,
3561 : int32_t _length) const
3562 : { return doIndexOf(c, start, _length); }
3563 :
3564 : inline int32_t
3565 : UnicodeString::indexOf(UChar32 c,
3566 : int32_t start,
3567 : int32_t _length) const
3568 : { return doIndexOf(c, start, _length); }
3569 :
3570 : inline int32_t
3571 : UnicodeString::indexOf(UChar c) const
3572 : { return doIndexOf(c, 0, fLength); }
3573 :
3574 : inline int32_t
3575 : UnicodeString::indexOf(UChar32 c) const
3576 : { return indexOf(c, 0, fLength); }
3577 :
3578 : inline int32_t
3579 : UnicodeString::indexOf(UChar c,
3580 : int32_t start) const {
3581 : pinIndex(start);
3582 : return doIndexOf(c, start, fLength - start);
3583 : }
3584 :
3585 : inline int32_t
3586 : UnicodeString::indexOf(UChar32 c,
3587 : int32_t start) const {
3588 : pinIndex(start);
3589 : return indexOf(c, start, fLength - start);
3590 : }
3591 :
3592 : inline int32_t
3593 : UnicodeString::lastIndexOf(const UChar *srcChars,
3594 : int32_t srcLength,
3595 : int32_t start,
3596 : int32_t _length) const
3597 : { return lastIndexOf(srcChars, 0, srcLength, start, _length); }
3598 :
3599 : inline int32_t
3600 : UnicodeString::lastIndexOf(const UChar *srcChars,
3601 : int32_t srcLength,
3602 : int32_t start) const {
3603 : pinIndex(start);
3604 : return lastIndexOf(srcChars, 0, srcLength, start, fLength - start);
3605 : }
3606 :
3607 : inline int32_t
3608 : UnicodeString::lastIndexOf(const UnicodeString& srcText,
3609 : int32_t srcStart,
3610 : int32_t srcLength,
3611 : int32_t start,
3612 : int32_t _length) const
3613 : {
3614 : if(!srcText.isBogus()) {
3615 : srcText.pinIndices(srcStart, srcLength);
3616 : if(srcLength > 0) {
3617 : return lastIndexOf(srcText.getArrayStart(), srcStart, srcLength, start, _length);
3618 : }
3619 : }
3620 : return -1;
3621 : }
3622 :
3623 : inline int32_t
3624 : UnicodeString::lastIndexOf(const UnicodeString& text,
3625 : int32_t start,
3626 : int32_t _length) const
3627 : { return lastIndexOf(text, 0, text.fLength, start, _length); }
3628 :
3629 : inline int32_t
3630 : UnicodeString::lastIndexOf(const UnicodeString& text,
3631 : int32_t start) const {
3632 : pinIndex(start);
3633 : return lastIndexOf(text, 0, text.fLength, start, fLength - start);
3634 : }
3635 :
3636 : inline int32_t
3637 : UnicodeString::lastIndexOf(const UnicodeString& text) const
3638 : { return lastIndexOf(text, 0, text.fLength, 0, fLength); }
3639 :
3640 : inline int32_t
3641 : UnicodeString::lastIndexOf(UChar c,
3642 : int32_t start,
3643 : int32_t _length) const
3644 : { return doLastIndexOf(c, start, _length); }
3645 :
3646 : inline int32_t
3647 : UnicodeString::lastIndexOf(UChar32 c,
3648 : int32_t start,
3649 : int32_t _length) const {
3650 : return doLastIndexOf(c, start, _length);
3651 : }
3652 :
3653 : inline int32_t
3654 : UnicodeString::lastIndexOf(UChar c) const
3655 : { return doLastIndexOf(c, 0, fLength); }
3656 :
3657 : inline int32_t
3658 : UnicodeString::lastIndexOf(UChar32 c) const {
3659 : return lastIndexOf(c, 0, fLength);
3660 : }
3661 :
3662 : inline int32_t
3663 : UnicodeString::lastIndexOf(UChar c,
3664 : int32_t start) const {
3665 : pinIndex(start);
3666 : return doLastIndexOf(c, start, fLength - start);
3667 : }
3668 :
3669 : inline int32_t
3670 : UnicodeString::lastIndexOf(UChar32 c,
3671 : int32_t start) const {
3672 : pinIndex(start);
3673 : return lastIndexOf(c, start, fLength - start);
3674 : }
3675 :
3676 : inline UBool
3677 : UnicodeString::startsWith(const UnicodeString& text) const
3678 : { return compare(0, text.fLength, text, 0, text.fLength) == 0; }
3679 :
3680 : inline UBool
3681 : UnicodeString::startsWith(const UnicodeString& srcText,
3682 : int32_t srcStart,
3683 : int32_t srcLength) const
3684 : { return doCompare(0, srcLength, srcText, srcStart, srcLength) == 0; }
3685 :
3686 : inline UBool
3687 : UnicodeString::startsWith(const UChar *srcChars,
3688 : int32_t srcLength) const
3689 : { return doCompare(0, srcLength, srcChars, 0, srcLength) == 0; }
3690 :
3691 : inline UBool
3692 : UnicodeString::startsWith(const UChar *srcChars,
3693 : int32_t srcStart,
3694 : int32_t srcLength) const
3695 : { return doCompare(0, srcLength, srcChars, srcStart, srcLength) == 0;}
3696 :
3697 : inline UBool
3698 : UnicodeString::endsWith(const UnicodeString& text) const
3699 : { return doCompare(fLength - text.fLength, text.fLength,
3700 : text, 0, text.fLength) == 0; }
3701 :
3702 : inline UBool
3703 : UnicodeString::endsWith(const UnicodeString& srcText,
3704 : int32_t srcStart,
3705 : int32_t srcLength) const {
3706 : srcText.pinIndices(srcStart, srcLength);
3707 : return doCompare(fLength - srcLength, srcLength,
3708 : srcText, srcStart, srcLength) == 0;
3709 : }
3710 :
3711 : inline UBool
3712 : UnicodeString::endsWith(const UChar *srcChars,
3713 : int32_t srcLength) const {
3714 : if(srcLength < 0) {
3715 : srcLength = u_strlen(srcChars);
3716 : }
3717 : return doCompare(fLength - srcLength, srcLength,
3718 : srcChars, 0, srcLength) == 0;
3719 : }
3720 :
3721 : inline UBool
3722 : UnicodeString::endsWith(const UChar *srcChars,
3723 : int32_t srcStart,
3724 : int32_t srcLength) const {
3725 : if(srcLength < 0) {
3726 : srcLength = u_strlen(srcChars + srcStart);
3727 : }
3728 : return doCompare(fLength - srcLength, srcLength,
3729 : srcChars, srcStart, srcLength) == 0;
3730 : }
3731 :
3732 : //========================================
3733 : // replace
3734 : //========================================
3735 : inline UnicodeString&
3736 : UnicodeString::replace(int32_t start,
3737 : int32_t _length,
3738 : const UnicodeString& srcText)
3739 : { return doReplace(start, _length, srcText, 0, srcText.fLength); }
3740 :
3741 : inline UnicodeString&
3742 : UnicodeString::replace(int32_t start,
3743 : int32_t _length,
3744 : const UnicodeString& srcText,
3745 : int32_t srcStart,
3746 : int32_t srcLength)
3747 : { return doReplace(start, _length, srcText, srcStart, srcLength); }
3748 :
3749 : inline UnicodeString&
3750 : UnicodeString::replace(int32_t start,
3751 : int32_t _length,
3752 : const UChar *srcChars,
3753 : int32_t srcLength)
3754 : { return doReplace(start, _length, srcChars, 0, srcLength); }
3755 :
3756 : inline UnicodeString&
3757 : UnicodeString::replace(int32_t start,
3758 : int32_t _length,
3759 : const UChar *srcChars,
3760 : int32_t srcStart,
3761 : int32_t srcLength)
3762 : { return doReplace(start, _length, srcChars, srcStart, srcLength); }
3763 :
3764 : inline UnicodeString&
3765 : UnicodeString::replace(int32_t start,
3766 : int32_t _length,
3767 : UChar srcChar)
3768 : { return doReplace(start, _length, &srcChar, 0, 1); }
3769 :
3770 : inline UnicodeString&
3771 : UnicodeString::replace(int32_t start,
3772 : int32_t _length,
3773 : UChar32 srcChar) {
3774 : UChar buffer[U16_MAX_LENGTH];
3775 : int32_t count = 0;
3776 : UBool isError = FALSE;
3777 : U16_APPEND(buffer, count, U16_MAX_LENGTH, srcChar, isError);
3778 : return doReplace(start, _length, buffer, 0, count);
3779 : }
3780 :
3781 : inline UnicodeString&
3782 : UnicodeString::replaceBetween(int32_t start,
3783 : int32_t limit,
3784 : const UnicodeString& srcText)
3785 : { return doReplace(start, limit - start, srcText, 0, srcText.fLength); }
3786 :
3787 : inline UnicodeString&
3788 : UnicodeString::replaceBetween(int32_t start,
3789 : int32_t limit,
3790 : const UnicodeString& srcText,
3791 : int32_t srcStart,
3792 : int32_t srcLimit)
3793 : { return doReplace(start, limit - start, srcText, srcStart, srcLimit - srcStart); }
3794 :
3795 : inline UnicodeString&
3796 : UnicodeString::findAndReplace(const UnicodeString& oldText,
3797 : const UnicodeString& newText)
3798 : { return findAndReplace(0, fLength, oldText, 0, oldText.fLength,
3799 : newText, 0, newText.fLength); }
3800 :
3801 : inline UnicodeString&
3802 : UnicodeString::findAndReplace(int32_t start,
3803 : int32_t _length,
3804 : const UnicodeString& oldText,
3805 : const UnicodeString& newText)
3806 : { return findAndReplace(start, _length, oldText, 0, oldText.fLength,
3807 : newText, 0, newText.fLength); }
3808 :
3809 : // ============================
3810 : // extract
3811 : // ============================
3812 : inline void
3813 : UnicodeString::doExtract(int32_t start,
3814 : int32_t _length,
3815 : UnicodeString& target) const
3816 : { target.replace(0, target.fLength, *this, start, _length); }
3817 :
3818 : inline void
3819 : UnicodeString::extract(int32_t start,
3820 : int32_t _length,
3821 : UChar *target,
3822 : int32_t targetStart) const
3823 : { doExtract(start, _length, target, targetStart); }
3824 :
3825 : inline void
3826 : UnicodeString::extract(int32_t start,
3827 : int32_t _length,
3828 : UnicodeString& target) const
3829 : { doExtract(start, _length, target); }
3830 :
3831 : #if !UCONFIG_NO_CONVERSION
3832 :
3833 : inline int32_t
3834 : UnicodeString::extract(int32_t start,
3835 : int32_t _length,
3836 : char *dst,
3837 : const char *codepage) const
3838 :
3839 : {
3840 : // This dstSize value will be checked explicitly
3841 : return extract(start, _length, dst, dst!=0 ? 0xffffffff : 0, codepage);
3842 : }
3843 :
3844 : #endif
3845 :
3846 : inline void
3847 : UnicodeString::extractBetween(int32_t start,
3848 : int32_t limit,
3849 : UChar *dst,
3850 : int32_t dstStart) const {
3851 : pinIndex(start);
3852 : pinIndex(limit);
3853 : doExtract(start, limit - start, dst, dstStart);
3854 : }
3855 :
3856 : inline UChar
3857 : UnicodeString::doCharAt(int32_t offset) const
3858 : {
3859 : if((uint32_t)offset < (uint32_t)fLength) {
3860 : return fArray[offset];
3861 : } else {
3862 : return kInvalidUChar;
3863 : }
3864 : }
3865 :
3866 : inline UChar
3867 : UnicodeString::charAt(int32_t offset) const
3868 : { return doCharAt(offset); }
3869 :
3870 : inline UChar
3871 : UnicodeString::operator[] (int32_t offset) const
3872 : { return doCharAt(offset); }
3873 :
3874 : inline UChar32
3875 : UnicodeString::char32At(int32_t offset) const
3876 : {
3877 : if((uint32_t)offset < (uint32_t)fLength) {
3878 : UChar32 c;
3879 : U16_GET(fArray, 0, offset, fLength, c);
3880 : return c;
3881 : } else {
3882 : return kInvalidUChar;
3883 : }
3884 : }
3885 :
3886 : inline int32_t
3887 : UnicodeString::getChar32Start(int32_t offset) const {
3888 : if((uint32_t)offset < (uint32_t)fLength) {
3889 : U16_SET_CP_START(fArray, 0, offset);
3890 : return offset;
3891 : } else {
3892 : return 0;
3893 : }
3894 : }
3895 :
3896 : inline int32_t
3897 : UnicodeString::getChar32Limit(int32_t offset) const {
3898 : if((uint32_t)offset < (uint32_t)fLength) {
3899 : U16_SET_CP_LIMIT(fArray, 0, offset, fLength);
3900 : return offset;
3901 : } else {
3902 : return fLength;
3903 : }
3904 : }
3905 :
3906 : inline UBool
3907 : UnicodeString::isEmpty() const {
3908 : return fLength == 0;
3909 : }
3910 :
3911 : //========================================
3912 : // Write implementation methods
3913 : //========================================
3914 : inline const UChar *
3915 : UnicodeString::getTerminatedBuffer() {
3916 : if(fFlags&(kIsBogus|kOpenGetBuffer)) {
3917 : return 0;
3918 : } else if(fLength<fCapacity && fArray[fLength]==0) {
3919 : return fArray;
3920 : } else if(cloneArrayIfNeeded(fLength+1)) {
3921 : fArray[fLength]=0;
3922 : return fArray;
3923 : } else {
3924 : return 0;
3925 : }
3926 : }
3927 :
3928 : inline UnicodeString&
3929 : UnicodeString::operator= (UChar ch)
3930 : { return doReplace(0, fLength, &ch, 0, 1); }
3931 :
3932 : inline UnicodeString&
3933 : UnicodeString::operator= (UChar32 ch)
3934 : { return replace(0, fLength, ch); }
3935 :
3936 : inline UnicodeString&
3937 : UnicodeString::setTo(const UnicodeString& srcText,
3938 : int32_t srcStart,
3939 : int32_t srcLength)
3940 : {
3941 : unBogus();
3942 : return doReplace(0, fLength, srcText, srcStart, srcLength);
3943 : }
3944 :
3945 : inline UnicodeString&
3946 : UnicodeString::setTo(const UnicodeString& srcText,
3947 : int32_t srcStart)
3948 : {
3949 : unBogus();
3950 : srcText.pinIndex(srcStart);
3951 : return doReplace(0, fLength, srcText, srcStart, srcText.fLength - srcStart);
3952 : }
3953 :
3954 : inline UnicodeString&
3955 : UnicodeString::setTo(const UnicodeString& srcText)
3956 : {
3957 : unBogus();
3958 : return doReplace(0, fLength, srcText, 0, srcText.fLength);
3959 : }
3960 :
3961 : inline UnicodeString&
3962 : UnicodeString::setTo(const UChar *srcChars,
3963 : int32_t srcLength)
3964 : {
3965 : unBogus();
3966 : return doReplace(0, fLength, srcChars, 0, srcLength);
3967 : }
3968 :
3969 : inline UnicodeString&
3970 : UnicodeString::setTo(UChar srcChar)
3971 : {
3972 : unBogus();
3973 : return doReplace(0, fLength, &srcChar, 0, 1);
3974 : }
3975 :
3976 : inline UnicodeString&
3977 : UnicodeString::setTo(UChar32 srcChar)
3978 : {
3979 : unBogus();
3980 : return replace(0, fLength, srcChar);
3981 : }
3982 :
3983 : inline UnicodeString&
3984 : UnicodeString::append(const UnicodeString& srcText,
3985 : int32_t srcStart,
3986 : int32_t srcLength)
3987 : { return doReplace(fLength, 0, srcText, srcStart, srcLength); }
3988 :
3989 : inline UnicodeString&
3990 : UnicodeString::append(const UnicodeString& srcText)
3991 : { return doReplace(fLength, 0, srcText, 0, srcText.fLength); }
3992 :
3993 : inline UnicodeString&
3994 : UnicodeString::append(const UChar *srcChars,
3995 : int32_t srcStart,
3996 : int32_t srcLength)
3997 : { return doReplace(fLength, 0, srcChars, srcStart, srcLength); }
3998 :
3999 : inline UnicodeString&
4000 : UnicodeString::append(const UChar *srcChars,
4001 : int32_t srcLength)
4002 : { return doReplace(fLength, 0, srcChars, 0, srcLength); }
4003 :
4004 : inline UnicodeString&
4005 : UnicodeString::append(UChar srcChar)
4006 : { return doReplace(fLength, 0, &srcChar, 0, 1); }
4007 :
4008 : inline UnicodeString&
4009 : UnicodeString::append(UChar32 srcChar) {
4010 : UChar buffer[U16_MAX_LENGTH];
4011 : int32_t _length = 0;
4012 : UBool isError = FALSE;
4013 : U16_APPEND(buffer, _length, U16_MAX_LENGTH, srcChar, isError);
4014 : return doReplace(fLength, 0, buffer, 0, _length);
4015 : }
4016 :
4017 : inline UnicodeString&
4018 : UnicodeString::operator+= (UChar ch)
4019 : { return doReplace(fLength, 0, &ch, 0, 1); }
4020 :
4021 : inline UnicodeString&
4022 : UnicodeString::operator+= (UChar32 ch) {
4023 : return append(ch);
4024 : }
4025 :
4026 : inline UnicodeString&
4027 : UnicodeString::operator+= (const UnicodeString& srcText)
4028 : { return doReplace(fLength, 0, srcText, 0, srcText.fLength); }
4029 :
4030 : inline UnicodeString&
4031 : UnicodeString::insert(int32_t start,
4032 : const UnicodeString& srcText,
4033 : int32_t srcStart,
4034 : int32_t srcLength)
4035 : { return doReplace(start, 0, srcText, srcStart, srcLength); }
4036 :
4037 : inline UnicodeString&
4038 : UnicodeString::insert(int32_t start,
4039 : const UnicodeString& srcText)
4040 : { return doReplace(start, 0, srcText, 0, srcText.fLength); }
4041 :
4042 : inline UnicodeString&
4043 : UnicodeString::insert(int32_t start,
4044 : const UChar *srcChars,
4045 : int32_t srcStart,
4046 : int32_t srcLength)
4047 : { return doReplace(start, 0, srcChars, srcStart, srcLength); }
4048 :
4049 : inline UnicodeString&
4050 : UnicodeString::insert(int32_t start,
4051 : const UChar *srcChars,
4052 : int32_t srcLength)
4053 : { return doReplace(start, 0, srcChars, 0, srcLength); }
4054 :
4055 : inline UnicodeString&
4056 : UnicodeString::insert(int32_t start,
4057 : UChar srcChar)
4058 : { return doReplace(start, 0, &srcChar, 0, 1); }
4059 :
4060 : inline UnicodeString&
4061 : UnicodeString::insert(int32_t start,
4062 : UChar32 srcChar)
4063 : { return replace(start, 0, srcChar); }
4064 :
4065 :
4066 : inline UnicodeString&
4067 : UnicodeString::remove()
4068 : {
4069 : // remove() of a bogus string makes the string empty and non-bogus
4070 : if(isBogus()) {
4071 : unBogus();
4072 : } else {
4073 : fLength = 0;
4074 : }
4075 : return *this;
4076 : }
4077 :
4078 : inline UnicodeString&
4079 : UnicodeString::remove(int32_t start,
4080 : int32_t _length)
4081 : {
4082 : if(start <= 0 && _length == INT32_MAX) {
4083 : // remove(guaranteed everything) of a bogus string makes the string empty and non-bogus
4084 : return remove();
4085 : }
4086 : return doReplace(start, _length, NULL, 0, 0);
4087 : }
4088 :
4089 : inline UnicodeString&
4090 : UnicodeString::removeBetween(int32_t start,
4091 : int32_t limit)
4092 : { return doReplace(start, limit - start, NULL, 0, 0); }
4093 :
4094 : inline UBool
4095 : UnicodeString::truncate(int32_t targetLength)
4096 : {
4097 : if(isBogus() && targetLength == 0) {
4098 : // truncate(0) of a bogus string makes the string empty and non-bogus
4099 : unBogus();
4100 : return FALSE;
4101 : } else if((uint32_t)targetLength < (uint32_t)fLength) {
4102 : fLength = targetLength;
4103 : return TRUE;
4104 : } else {
4105 : return FALSE;
4106 : }
4107 : }
4108 :
4109 : inline UnicodeString&
4110 : UnicodeString::reverse()
4111 : { return doReverse(0, fLength); }
4112 :
4113 : inline UnicodeString&
4114 : UnicodeString::reverse(int32_t start,
4115 : int32_t _length)
4116 : { return doReverse(start, _length); }
4117 :
4118 : U_NAMESPACE_END
4119 :
4120 : #endif
|
