/*

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

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

*   Corporation and others.  All Rights Reserved.

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

*

* File ustring.h

*

* Modification History:

*

*   Date        Name        Description

*   12/07/98    bertrand    Creation.

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

*/

#ifndef USTRING_H

#define USTRING_H

#include "unicode/utypes.h"

#include "unicode/putil.h"

#include "unicode/uiter.h"

/** Simple declaration for u_strToTitle() to avoid including unicode/ubrk.h. @stable ICU 2.1*/

#ifndef UBRK_TYPEDEF_UBREAK_ITERATOR

#   define UBRK_TYPEDEF_UBREAK_ITERATOR

    typedef void UBreakIterator;

#endif

/**

 * \file

 * \brief C API: Unicode string handling functions

 *

 * These C API functions provide general Unicode string handling.

 *

 * Some functions are equivalent in name, signature, and behavior to the ANSI C <string.h>

 * functions. (For example, they do not check for bad arguments like NULL string pointers.)

 * In some cases, only the thread-safe variant of such a function is implemented here

 * (see u_strtok_r()).

 *

 * Other functions provide more Unicode-specific functionality like locale-specific

 * upper/lower-casing and string comparison in code point order.

 *

 * ICU uses 16-bit Unicode (UTF-16) in the form of arrays of UChar code units.

 * UTF-16 encodes each Unicode code point with either one or two UChar code units.

 * (This is the default form of Unicode, and a forward-compatible extension of the original,

 * fixed-width form that was known as UCS-2. UTF-16 superseded UCS-2 with Unicode 2.0

 * in 1996.)

 *

 * Some APIs accept a 32-bit UChar32 value for a single code point.

 *

 * ICU also handles 16-bit Unicode text with unpaired surrogates.

 * Such text is not well-formed UTF-16.

 * Code-point-related functions treat unpaired surrogates as surrogate code points,

 * i.e., as separate units.

 *

 * Although UTF-16 is a variable-width encoding form (like some legacy multi-byte encodings),

 * it is much more efficient even for random access because the code unit values

 * for single-unit characters vs. lead units vs. trail units are completely disjoint.

 * This means that it is easy to determine character (code point) boundaries from

 * random offsets in the string.

 *

 * Unicode (UTF-16) string processing is optimized for the single-unit case.

 * Although it is important to support supplementary characters

 * (which use pairs of lead/trail code units called "surrogates"),

 * their occurrence is rare. Almost all characters in modern use require only

 * a single UChar code unit (i.e., their code point values are <=0xffff).

 *

 * For more details see the User Guide Strings chapter (http://oss.software.ibm.com/icu/userguide/strings.html).

 * For a discussion of the handling of unpaired surrogates see also

 * Jitterbug 2145 and its icu mailing list proposal on 2002-sep-18.

 */

/**

 * Determine the length of an array of UChar.

 *

 * @param s The array of UChars, NULL (U+0000) terminated.

 * @return The number of UChars in <code>chars</code>, minus the terminator.

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2

u_strlen(const UChar *s);

/**

 * Count Unicode code points in the length UChar code units of the string.

 * A code point may occupy either one or two UChar code units.

 * Counting code points involves reading all code units.

 *

 * This functions is basically the inverse of the U16_FWD_N() macro (see utf.h).

 *

 * @param s The input string.

 * @param length The number of UChar code units to be checked, or -1 to count all

 *               code points before the first NUL (U+0000).

 * @return The number of code points in the specified code units.

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2

u_countChar32(const UChar *s, int32_t length);

/**

 * Check if the string contains more Unicode code points than a certain number.

 * This is more efficient than counting all code points in the entire string

 * and comparing that number with a threshold.

 * This function may not need to scan the string at all if the length is known

 * (not -1 for NUL-termination) and falls within a certain range, and

 * never needs to count more than 'number+1' code points.

 * Logically equivalent to (u_countChar32(s, length)>number).

 * A Unicode code point may occupy either one or two UChar code units.

 *

 * @param s The input string.

 * @param length The length of the string, or -1 if it is NUL-terminated.

 * @param number The number of code points in the string is compared against

 *               the 'number' parameter.

 * @return Boolean value for whether the string contains more Unicode code points

 *         than 'number'. Same as (u_countChar32(s, length)>number).

 * @stable ICU 2.4

 */

U_STABLE UBool U_EXPORT2

u_strHasMoreChar32Than(const UChar *s, int32_t length, int32_t number);

/**

 * Concatenate two ustrings.  Appends a copy of <code>src</code>,

 * including the null terminator, to <code>dst</code>. The initial copied

 * character from <code>src</code> overwrites the null terminator in <code>dst</code>.

 *

 * @param dst The destination string.

 * @param src The source string.

 * @return A pointer to <code>dst</code>.

 * @stable ICU 2.0

 */

U_STABLE UChar* U_EXPORT2

u_strcat(UChar     *dst, 

    const UChar     *src);

/**

 * Concatenate two ustrings.  

 * Appends at most <code>n</code> characters from <code>src</code> to <code>dst</code>.

 * Adds a terminating NUL.

 * If src is too long, then only <code>n-1</code> characters will be copied

 * before the terminating NUL.

 * If <code>n&lt;=0</code> then dst is not modified.

 *

 * @param dst The destination string.

 * @param src The source string.

 * @param n The maximum number of characters to compare.

 * @return A pointer to <code>dst</code>.

 * @stable ICU 2.0

 */

U_STABLE UChar* U_EXPORT2

u_strncat(UChar     *dst, 

     const UChar     *src, 

     int32_t     n);

/**

 * Find the first occurrence of a substring in a string.

 * The substring is found at code point boundaries.

 * That means that if the substring begins with

 * a trail surrogate or ends with a lead surrogate,

 * then it is found only if these surrogates stand alone in the text.

 * Otherwise, the substring edge units would be matched against

 * halves of surrogate pairs.

 *

 * @param s The string to search (NUL-terminated).

 * @param substring The substring to find (NUL-terminated).

 * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,

 *         or <code>s</code> itself if the <code>substring</code> is empty,

 *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.

 * @stable ICU 2.0

 *

 * @see u_strrstr

 * @see u_strFindFirst

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strstr(const UChar *s, const UChar *substring);

/**

 * Find the first occurrence of a substring in a string.

 * The substring is found at code point boundaries.

 * That means that if the substring begins with

 * a trail surrogate or ends with a lead surrogate,

 * then it is found only if these surrogates stand alone in the text.

 * Otherwise, the substring edge units would be matched against

 * halves of surrogate pairs.

 *

 * @param s The string to search.

 * @param length The length of s (number of UChars), or -1 if it is NUL-terminated.

 * @param substring The substring to find (NUL-terminated).

 * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.

 * @return A pointer to the first occurrence of <code>substring</code> in <code>s</code>,

 *         or <code>s</code> itself if the <code>substring</code> is empty,

 *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.

 * @stable ICU 2.4

 *

 * @see u_strstr

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strFindFirst(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);

/**

 * Find the first occurrence of a BMP code point in a string.

 * A surrogate code point is found only if its match in the text is not

 * part of a surrogate pair.

 * A NUL character is found at the string terminator.

 *

 * @param s The string to search (NUL-terminated).

 * @param c The BMP code point to find.

 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>

 *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.

 * @stable ICU 2.0

 *

 * @see u_strchr32

 * @see u_memchr

 * @see u_strstr

 * @see u_strFindFirst

 */

U_STABLE UChar * U_EXPORT2

u_strchr(const UChar *s, UChar c);

/**

 * Find the first occurrence of a code point in a string.

 * A surrogate code point is found only if its match in the text is not

 * part of a surrogate pair.

 * A NUL character is found at the string terminator.

 *

 * @param s The string to search (NUL-terminated).

 * @param c The code point to find.

 * @return A pointer to the first occurrence of <code>c</code> in <code>s</code>

 *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.

 * @stable ICU 2.0

 *

 * @see u_strchr

 * @see u_memchr32

 * @see u_strstr

 * @see u_strFindFirst

 */

U_STABLE UChar * U_EXPORT2

u_strchr32(const UChar *s, UChar32 c);

/**

 * Find the last occurrence of a substring in a string.

 * The substring is found at code point boundaries.

 * That means that if the substring begins with

 * a trail surrogate or ends with a lead surrogate,

 * then it is found only if these surrogates stand alone in the text.

 * Otherwise, the substring edge units would be matched against

 * halves of surrogate pairs.

 *

 * @param s The string to search (NUL-terminated).

 * @param substring The substring to find (NUL-terminated).

 * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,

 *         or <code>s</code> itself if the <code>substring</code> is empty,

 *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.

 * @stable ICU 2.4

 *

 * @see u_strstr

 * @see u_strFindFirst

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strrstr(const UChar *s, const UChar *substring);

/**

 * Find the last occurrence of a substring in a string.

 * The substring is found at code point boundaries.

 * That means that if the substring begins with

 * a trail surrogate or ends with a lead surrogate,

 * then it is found only if these surrogates stand alone in the text.

 * Otherwise, the substring edge units would be matched against

 * halves of surrogate pairs.

 *

 * @param s The string to search.

 * @param length The length of s (number of UChars), or -1 if it is NUL-terminated.

 * @param substring The substring to find (NUL-terminated).

 * @param subLength The length of substring (number of UChars), or -1 if it is NUL-terminated.

 * @return A pointer to the last occurrence of <code>substring</code> in <code>s</code>,

 *         or <code>s</code> itself if the <code>substring</code> is empty,

 *         or <code>NULL</code> if <code>substring</code> is not in <code>s</code>.

 * @stable ICU 2.4

 *

 * @see u_strstr

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strFindLast(const UChar *s, int32_t length, const UChar *substring, int32_t subLength);

/**

 * Find the last occurrence of a BMP code point in a string.

 * A surrogate code point is found only if its match in the text is not

 * part of a surrogate pair.

 * A NUL character is found at the string terminator.

 *

 * @param s The string to search (NUL-terminated).

 * @param c The BMP code point to find.

 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>

 *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.

 * @stable ICU 2.4

 *

 * @see u_strrchr32

 * @see u_memrchr

 * @see u_strrstr

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strrchr(const UChar *s, UChar c);

/**

 * Find the last occurrence of a code point in a string.

 * A surrogate code point is found only if its match in the text is not

 * part of a surrogate pair.

 * A NUL character is found at the string terminator.

 *

 * @param s The string to search (NUL-terminated).

 * @param c The code point to find.

 * @return A pointer to the last occurrence of <code>c</code> in <code>s</code>

 *         or <code>NULL</code> if <code>c</code> is not in <code>s</code>.

 * @stable ICU 2.4

 *

 * @see u_strrchr

 * @see u_memchr32

 * @see u_strrstr

 * @see u_strFindLast

 */

U_STABLE UChar * U_EXPORT2

u_strrchr32(const UChar *s, UChar32 c);

/**

 * Locates the first occurrence in the string <code>string</code> of any of the characters

 * in the string <code>matchSet</code>.

 * Works just like C's strpbrk but with Unicode.

 *

 * @param string The string in which to search, NUL-terminated.

 * @param matchSet A NUL-terminated string defining a set of code points

 *                 for which to search in the text string.

 * @return A pointer to the  character in <code>string</code> that matches one of the

 *         characters in <code>matchSet</code>, or NULL if no such character is found.

 * @stable ICU 2.0

 */

U_STABLE UChar * U_EXPORT2

u_strpbrk(const UChar *string, const UChar *matchSet);

/**

 * Returns the number of consecutive characters in <code>string</code>,

 * beginning with the first, that do not occur somewhere in <code>matchSet</code>.

 * Works just like C's strcspn but with Unicode.

 *

 * @param string The string in which to search, NUL-terminated.

 * @param matchSet A NUL-terminated string defining a set of code points

 *                 for which to search in the text string.

 * @return The number of initial characters in <code>string</code> that do not

 *         occur in <code>matchSet</code>.

 * @see u_strspn

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2

u_strcspn(const UChar *string, const UChar *matchSet);

/**

 * Returns the number of consecutive characters in <code>string</code>,

 * beginning with the first, that occur somewhere in <code>matchSet</code>.

 * Works just like C's strspn but with Unicode.

 *

 * @param string The string in which to search, NUL-terminated.

 * @param matchSet A NUL-terminated string defining a set of code points

 *                 for which to search in the text string.

 * @return The number of initial characters in <code>string</code> that do

 *         occur in <code>matchSet</code>.

 * @see u_strcspn

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2

u_strspn(const UChar *string, const UChar *matchSet);

/**

 * The string tokenizer API allows an application to break a string into

 * tokens. Unlike strtok(), the saveState (the current pointer within the

 * original string) is maintained in saveState. In the first call, the

 * argument src is a pointer to the string. In subsequent calls to

 * return successive tokens of that string, src must be specified as

 * NULL. The value saveState is set by this function to maintain the

 * function's position within the string, and on each subsequent call

 * you must give this argument the same variable. This function does

 * handle surrogate pairs. This function is similar to the strtok_r()

 * the POSIX Threads Extension (1003.1c-1995) version.

 *

 * @param src String containing token(s). This string will be modified.

 *            After the first call to u_strtok_r(), this argument must

 *            be NULL to get to the next token.

 * @param delim Set of delimiter characters (Unicode code points).

 * @param saveState The current pointer within the original string,

 *              which is set by this function. The saveState

 *              parameter should the address of a local variable of type

 *              UChar *. (i.e. defined "Uhar *myLocalSaveState" and use

 *              &myLocalSaveState for this parameter).

 * @return A pointer to the next token found in src, or NULL

 *         when there are no more tokens.

 * @stable ICU 2.0

 */

U_STABLE UChar * U_EXPORT2

u_strtok_r(UChar    *src, 

     const UChar    *delim,

           UChar   **saveState);

/**

 * Compare two Unicode strings for bitwise equality (code unit order).

 *

 * @param s1 A string to compare.

 * @param s2 A string to compare.

 * @return 0 if <code>s1</code> and <code>s2</code> are bitwise equal; a negative

 * value if <code>s1</code> is bitwise less than <code>s2,</code>; a positive

 * value if <code>s1</code> is bitwise greater than <code>s2</code>.

 * @stable ICU 2.0

 */

U_STABLE int32_t  U_EXPORT2

u_strcmp(const UChar     *s1, 

         const UChar     *s2);

/**

 * Compare two Unicode strings in code point order.

 * See u_strCompare for details.

 *

 * @param s1 A string to compare.

 * @param s2 A string to compare.

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

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

 * in code point order

 * @stable ICU 2.0

 */

U_STABLE int32_t U_EXPORT2

u_strcmpCodePointOrder(const UChar *s1, const UChar *s2);

/**

 * Compare two Unicode strings (binary order).

 *

 * The comparison can be done in code unit order or in code point order.

 * They differ only in UTF-16 when

 * comparing supplementary code points (U+10000..U+10ffff)

 * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).

 * In code unit order, high BMP code points sort after supplementary code points

 * because they are stored as pairs of surrogates which are at U+d800..U+dfff.

 *

 * This functions works with strings of different explicitly specified lengths

 * unlike the ANSI C-like u_strcmp() and u_memcmp() etc.

 * NUL-terminated strings are possible with length arguments of -1.

 *

 * @param s1 First source string.

 * @param length1 Length of first source string, or -1 if NUL-terminated.

 *

 * @param s2 Second source string.

 * @param length2 Length of second source string, or -1 if NUL-terminated.

 *

 * @param codePointOrder Choose between code unit order (FALSE)

 *                       and code point order (TRUE).

 *

 * @return <0 or 0 or >0 as usual for string comparisons

 *

 * @stable ICU 2.2

 */

U_STABLE int32_t U_EXPORT2

u_strCompare(const UChar *s1, int32_t length1,

             const UChar *s2, int32_t length2,

             UBool codePointOrder);

/**

 * Compare two Unicode strings (binary order)

 * as presented by UCharIterator objects.

 * Works otherwise just like u_strCompare().

 *

 * Both iterators are reset to their start positions.

 * When the function returns, it is undefined where the iterators

 * have stopped.

 *

 * @param iter1 First source string iterator.

 * @param iter2 Second source string iterator.

 * @param codePointOrder Choose between code unit order (FALSE)

 *                       and code point order (TRUE).

 *

 * @return <0 or 0 or >0 as usual for string comparisons

 *

 * @see u_strCompare

 *

 * @stable ICU 2.6

 */

U_STABLE int32_t U_EXPORT2

u_strCompareIter(UCharIterator *iter1, UCharIterator *iter2, UBool codePointOrder);

#ifndef U_COMPARE_CODE_POINT_ORDER

/* see also unistr.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

/**

 * Compare two strings case-insensitively using full case folding.

 * This is equivalent to

 *   u_strCompare(u_strFoldCase(s1, options),

 *                u_strFoldCase(s2, options),

 *                (options&U_COMPARE_CODE_POINT_ORDER)!=0).

 *

 * The comparison can be done in UTF-16 code unit order or in code point order.

 * They differ only when comparing supplementary code points (U+10000..U+10ffff)

 * to BMP code points near the end of the BMP (i.e., U+e000..U+ffff).

 * In code unit order, high BMP code points sort after supplementary code points

 * because they are stored as pairs of surrogates which are at U+d800..U+dfff.

 *

 * This functions works with strings of different explicitly specified lengths

 * unlike the ANSI C-like u_strcmp() and u_memcmp() etc.

 * NUL-terminated strings are possible with length arguments of -1.

 *

 * @param s1 First source string.

 * @param length1 Length of first source string, or -1 if NUL-terminated.

 *

 * @param s2 Second source string.

 * @param length2 Length of second source string, or -1 if NUL-terminated.

 *

 * @param options A bit set of options:

 *   - U_FOLD_CASE_DEFAULT or 0 is used for default options:

 *     Comparison in code unit order with default case folding.

 *

 *   - U_COMPARE_CODE_POINT_ORDER

 *     Set to choose code point order instead of code unit order

 *     (see u_strCompare for details).

 *

 *   - U_FOLD_CASE_EXCLUDE_SPECIAL_I

 *