/*

**********************************************************************

*   Copyright (C) 1998-2005, International Business Machines

*   Corporation and others.  All Rights Reserved.

**********************************************************************

*

* File unistr.h

*

* Modification History:

*

*   Date        Name        Description

*   09/25/98    stephen     Creation.

*   11/11/98    stephen     Changed per 11/9 code review.

*   04/20/99    stephen     Overhauled per 4/16 code review.

*   11/18/99    aliu        Made to inherit from Replaceable.  Added method

*                           handleReplaceBetween(); other methods unchanged.

*   06/25/01    grhoten     Remove dependency on iostream.

******************************************************************************

*/

#ifndef UNISTR_H

#define UNISTR_H

/**

 * \file 

 * \brief C++ API: Unicode String 

 */

#include "unicode/rep.h"

struct UConverter;          // unicode/ucnv.h

class  StringThreadTest;

#ifndef U_COMPARE_CODE_POINT_ORDER

/* see also ustring.h and unorm.h */

/**

 * Option bit for u_strCaseCompare, u_strcasecmp, unorm_compare, etc:

 * Compare strings in code point order instead of code unit order.

 * @stable ICU 2.2

 */

#define U_COMPARE_CODE_POINT_ORDER  0x8000

#endif

#ifndef USTRING_H

/* see ustring.h */

U_STABLE int32_t U_EXPORT2

u_strlen(const UChar *s);

#endif

U_NAMESPACE_BEGIN

class Locale;               // unicode/locid.h

class StringCharacterIterator;

class BreakIterator;        // unicode/brkiter.h

/* The <iostream> include has been moved to unicode/ustream.h */

/**

 * Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor

 * which constructs a Unicode string from an invariant-character char * string.

 * About invariant characters see utypes.h.

 * This constructor has no runtime dependency on conversion code and is

 * therefore recommended over ones taking a charset name string

 * (where the empty string "" indicates invariant-character conversion).

 *

 * @draft ICU 3.2

 */

#define US_INV UnicodeString::kInvariant

/**

 * Unicode String literals in C++.

 * Dependent on the platform properties, different UnicodeString

 * constructors should be used to create a UnicodeString object from

 * a string literal.

 * The macros are defined for maximum performance.

 * They work only for strings that contain "invariant characters", i.e.,

 * only latin letters, digits, and some punctuation.

 * See utypes.h for details.

 *

 * The string parameter must be a C string literal.

 * The length of the string, not including the terminating

 * <code>NUL</code>, must be specified as a constant.

 * The U_STRING_DECL macro should be invoked exactly once for one

 * such string variable before it is used.

 * @stable ICU 2.0

 */

#if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16)))

#   define UNICODE_STRING(cs, _length) UnicodeString(TRUE, (const UChar *)L ## cs, _length)

#elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY

#   define UNICODE_STRING(cs, _length) UnicodeString(TRUE, (const UChar *)cs, _length)

#else

#   define UNICODE_STRING(cs, _length) UnicodeString(cs, _length, US_INV)

#endif

/**

 * Unicode String literals in C++.

 * Dependent on the platform properties, different UnicodeString

 * constructors should be used to create a UnicodeString object from

 * a string literal.

 * The macros are defined for improved performance.

 * They work only for strings that contain "invariant characters", i.e.,

 * only latin letters, digits, and some punctuation.

 * See utypes.h for details.

 *

 * The string parameter must be a C string literal.

 * @stable ICU 2.0

 */

#if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && (U_CHARSET_FAMILY==U_ASCII_FAMILY || (U_SIZEOF_UCHAR == 2 && defined(U_WCHAR_IS_UTF16)))

#   define UNICODE_STRING_SIMPLE(cs) UnicodeString(TRUE, (const UChar *)L ## cs, -1)

#elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY

#   define UNICODE_STRING_SIMPLE(cs) UnicodeString(TRUE, (const UChar *)cs, -1)

#else

#   define UNICODE_STRING_SIMPLE(cs) UnicodeString(cs, -1, US_INV)

#endif

/**

 * UnicodeString is a string class that stores Unicode characters directly and provides

 * similar functionality as the Java String and StringBuffer classes.

 * It is a concrete implementation of the abstract class Replaceable (for transliteration).

 *

 * The UnicodeString class is not suitable for subclassing.

 *

 * <p>For an overview of Unicode strings in C and C++ see the

 * <a href="http://icu.sourceforge.net/userguide/strings.html">User Guide Strings chapter</a>.</p>

 *

 * <p>In ICU, a Unicode string consists of 16-bit Unicode <em>code units</em>.

 * A Unicode character may be stored with either one code unit

 * (the most common case) or with a matched pair of special code units

 * ("surrogates"). The data type for code units is UChar. 

 * For single-character handling, a Unicode character code <em>point</em> is a value

 * in the range 0..0x10ffff. ICU uses the UChar32 type for code points.</p>

 *

 * <p>Indexes and offsets into and lengths of strings always count code units, not code points.

 * This is the same as with multi-byte char* strings in traditional string handling.

 * Operations on partial strings typically do not test for code point boundaries.

 * If necessary, the user needs to take care of such boundaries by testing for the code unit

 * values or by using functions like

 * UnicodeString::getChar32Start() and UnicodeString::getChar32Limit()

 * (or, in C, the equivalent macros U16_SET_CP_START() and U16_SET_CP_LIMIT(), see utf.h).</p>

 *

 * UnicodeString methods are more lenient with regard to input parameter values

 * than other ICU APIs. In particular:

 * - If indexes are out of bounds for a UnicodeString object

 *   (<0 or >length()) then they are "pinned" to the nearest boundary.

 * - If primitive string pointer values (e.g., const UChar * or char *)

 *   for input strings are NULL, then those input string parameters are treated

 *   as if they pointed to an empty string.

 *   However, this is <em>not</em> the case for char * parameters for charset names

 *   or other IDs.

 * - Most UnicodeString methods do not take a UErrorCode parameter because

 *   there are usually very few opportunities for failure other than a shortage

 *   of memory, error codes in low-level C++ string methods would be inconvenient,

 *   and the error code as the last parameter (ICU convention) would prevent

 *   the use of default parameter values.

 *   Instead, such methods set the UnicodeString into a "bogus" state

 *   (see isBogus()) if an error occurs.

 *

 * In string comparisons, two UnicodeString objects that are both "bogus"

 * compare equal (to be transitive and prevent endless loops in sorting),

 * and a "bogus" string compares less than any non-"bogus" one.

 *

 * Const UnicodeString methods are thread-safe. Multiple threads can use

 * const methods on the same UnicodeString object simultaneously,

 * but non-const methods must not be called concurrently (in multiple threads)

 * with any other (const or non-const) methods.

 *

 * Similarly, const UnicodeString & parameters are thread-safe.

 * One object may be passed in as such a parameter concurrently in multiple threads.

 * This includes the const UnicodeString & parameters for

 * copy construction, assignment, and cloning.

 *

 * <p>UnicodeString uses several storage methods.

 * String contents can be stored inside the UnicodeString object itself,

 * in an allocated and shared buffer, or in an outside buffer that is "aliased".

 * Most of this is done transparently, but careful aliasing in particular provides

 * significant performance improvements.

 * Also, the internal buffer is accessible via special functions.

 * For details see the

 * <a href="http://icu.sourceforge.net/userguide/strings.html">User Guide Strings chapter</a>.</p>

 *

 * @see utf.h

 * @see CharacterIterator

 * @stable ICU 2.0

 */

class U_COMMON_API UnicodeString : public Replaceable

{

public:

  /**

   * Constant to be used in the UnicodeString(char *, int32_t, EInvariant) constructor

   * which constructs a Unicode string from an invariant-character char * string.

   * Use the macro US_INV instead of the full qualification for this value.

   *

   * @see US_INV

   * @draft ICU 3.2

   */

  enum EInvariant {

    /**

     * @see EInvariant

     * @draft ICU 3.2

     */

    kInvariant

  };

  //========================================

  // Read-only operations

  //========================================

  /* Comparison - bitwise only - for international comparison use collation */

  /**

   * Equality operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return TRUE if <TT>text</TT> contains the same characters as this one,

   * FALSE otherwise.

   * @stable ICU 2.0

   */

  inline UBool operator== (const UnicodeString& text) const;

  /**

   * Inequality operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return FALSE if <TT>text</TT> contains the same characters as this one,

   * TRUE otherwise.

   * @stable ICU 2.0

   */

  inline UBool operator!= (const UnicodeString& text) const;

  /**

   * Greater than operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return TRUE if the characters in this are bitwise

   * greater than the characters in <code>text</code>, FALSE otherwise

   * @stable ICU 2.0

   */

  inline UBool operator> (const UnicodeString& text) const;

  /**

   * Less than operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return TRUE if the characters in this are bitwise

   * less than the characters in <code>text</code>, FALSE otherwise

   * @stable ICU 2.0

   */

  inline UBool operator< (const UnicodeString& text) const;

  /**

   * Greater than or equal operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return TRUE if the characters in this are bitwise

   * greater than or equal to the characters in <code>text</code>, FALSE otherwise

   * @stable ICU 2.0

   */

  inline UBool operator>= (const UnicodeString& text) const;

  /**

   * Less than or equal operator. Performs only bitwise comparison.

   * @param text The UnicodeString to compare to this one.

   * @return TRUE if the characters in this are bitwise

   * less than or equal to the characters in <code>text</code>, FALSE otherwise

   * @stable ICU 2.0

   */

  inline UBool operator<= (const UnicodeString& text) const;

  /**

   * Compare the characters bitwise in this UnicodeString to

   * the characters in <code>text</code>.

   * @param text The UnicodeString to compare to this one.

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>text</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>text</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>text</code>.

   * @stable ICU 2.0

   */

  inline int8_t compare(const UnicodeString& text) const;

  /**

   * Compare the characters bitwise in the range

   * [<TT>start</TT>, <TT>start + length</TT>) with the characters

   * in <TT>text</TT>

   * @param start the offset at which the compare operation begins

   * @param length the number of characters of text to compare.

   * @param text the other text to be compared against this string.

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>text</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>text</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>text</code>.

   * @stable ICU 2.0

   */

  inline int8_t compare(int32_t start,

         int32_t length,

         const UnicodeString& text) const;

  /**

   * Compare the characters bitwise in the range

   * [<TT>start</TT>, <TT>start + length</TT>) with the characters

   * in <TT>srcText</TT> in the range

   * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>).

   * @param start the offset at which the compare operation begins

   * @param length the number of characters in this to compare.

   * @param srcText the text to be compared

   * @param srcStart the offset into <TT>srcText</TT> to start comparison

   * @param srcLength the number of characters in <TT>src</TT> to compare

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>srcText</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>srcText</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>srcText</code>.

   * @stable ICU 2.0

   */

   inline int8_t compare(int32_t start,

         int32_t length,

         const UnicodeString& srcText,

         int32_t srcStart,

         int32_t srcLength) const;

  /**

   * Compare the characters bitwise in this UnicodeString with the first

   * <TT>srcLength</TT> characters in <TT>srcChars</TT>.

   * @param srcChars The characters to compare to this UnicodeString.

   * @param srcLength the number of characters in <TT>srcChars</TT> to compare

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>srcChars</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>srcChars</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>srcChars</code>.

   * @stable ICU 2.0

   */

  inline int8_t compare(const UChar *srcChars,

         int32_t srcLength) const;

  /**

   * Compare the characters bitwise in the range

   * [<TT>start</TT>, <TT>start + length</TT>) with the first

   * <TT>length</TT> characters in <TT>srcChars</TT>

   * @param start the offset at which the compare operation begins

   * @param length the number of characters to compare.

   * @param srcChars the characters to be compared

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>srcChars</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>srcChars</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>srcChars</code>.

   * @stable ICU 2.0

   */

  inline int8_t compare(int32_t start,

         int32_t length,

         const UChar *srcChars) const;

  /**

   * Compare the characters bitwise in the range

   * [<TT>start</TT>, <TT>start + length</TT>) with the characters

   * in <TT>srcChars</TT> in the range

   * [<TT>srcStart</TT>, <TT>srcStart + srcLength</TT>).

   * @param start the offset at which the compare operation begins

   * @param length the number of characters in this to compare

   * @param srcChars the characters to be compared

   * @param srcStart the offset into <TT>srcChars</TT> to start comparison

   * @param srcLength the number of characters in <TT>srcChars</TT> to compare

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>srcChars</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>srcChars</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>srcChars</code>.

   * @stable ICU 2.0

   */

  inline int8_t compare(int32_t start,

         int32_t length,

         const UChar *srcChars,

         int32_t srcStart,

         int32_t srcLength) const;

  /**

   * Compare the characters bitwise in the range

   * [<TT>start</TT>, <TT>limit</TT>) with the characters

   * in <TT>srcText</TT> in the range

   * [<TT>srcStart</TT>, <TT>srcLimit</TT>).

   * @param start the offset at which the compare operation begins

   * @param limit the offset immediately following the compare operation

   * @param srcText the text to be compared

   * @param srcStart the offset into <TT>srcText</TT> to start comparison

   * @param srcLimit the offset into <TT>srcText</TT> to limit comparison

   * @return The result of bitwise character comparison: 0 if this

   * contains the same characters as <code>srcText</code>, -1 if the characters in

   * this are bitwise less than the characters in <code>srcText</code>, +1 if the

   * characters in this are bitwise greater than the characters

   * in <code>srcText</code>.

   * @stable ICU 2.0

   */

  inline int8_t compareBetween(int32_t start,

            int32_t limit,

            const UnicodeString& srcText,

            int32_t srcStart,

            int32_t srcLimit) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param text Another string to compare this one to.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one

   * in code point order

   * @stable ICU 2.0

   */

  inline int8_t compareCodePointOrder(const UnicodeString& text) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param start The start offset in this string at which the compare operation begins.

   * @param length The number of code units from this string to compare.

   * @param srcText Another string to compare this one to.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one

   * in code point order

   * @stable ICU 2.0

   */

  inline int8_t compareCodePointOrder(int32_t start,

                                      int32_t length,

                                      const UnicodeString& srcText) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param start The start offset in this string at which the compare operation begins.

   * @param length The number of code units from this string to compare.

   * @param srcText Another string to compare this one to.

   * @param srcStart The start offset in that string at which the compare operation begins.

   * @param srcLength The number of code units from that string to compare.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one

   * in code point order

   * @stable ICU 2.0

   */

   inline int8_t compareCodePointOrder(int32_t start,

                                       int32_t length,

                                       const UnicodeString& srcText,

                                       int32_t srcStart,

                                       int32_t srcLength) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param srcChars A pointer to another string to compare this one to.

   * @param srcLength The number of code units from that string to compare.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one

   * in code point order

   * @stable ICU 2.0

   */

  inline int8_t compareCodePointOrder(const UChar *srcChars,

                                      int32_t srcLength) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param start The start offset in this string at which the compare operation begins.

   * @param length The number of code units from this string to compare.

   * @param srcChars A pointer to another string to compare this one to.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one

   * in code point order

   * @stable ICU 2.0

   */

  inline int8_t compareCodePointOrder(int32_t start,

                                      int32_t length,

                                      const UChar *srcChars) const;

  /**

   * Compare two Unicode strings in code point order.

   * This is different in UTF-16 from how compare(), operator==, startsWith() etc. work

   * if supplementary characters are present:

   *

   * In UTF-16, supplementary characters (with code points U+10000 and above) are

   * stored with pairs of surrogate code units. These have values from 0xd800 to 0xdfff,

   * which means that they compare as less than some other BMP characters like U+feff.

   * This function compares Unicode strings in code point order.

   * If either of the UTF-16 strings is malformed (i.e., it contains unpaired surrogates), then the result is not defined.

   *

   * @param start The start offset in this string at which the compare operation begins.

   * @param length The number of code units from this string to compare.

   * @param srcChars A pointer to another string to compare this one to.

   * @param srcStart The start offset in that string at which the compare operation begins.

   * @param srcLength The number of code units from that string to compare.

   * @return a negative/zero/positive integer corresponding to whether

   * this string is less than/equal to/greater than the second one