Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/unistr.h @ 69:33d812a61356

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