ustring.h

linux下开源浏览器WebKit的源码,市面上的很多商用浏览器都是移植自WebKit

 * @param dst The destination string.
 * @param src The source string.
 * @param n The maximum number of characters to copy.
 * @return A pointer to <code>dst</code>.
 * @stable ICU 2.0
 */
U_STABLE UChar* U_EXPORT2
u_strncpy(UChar     *dst, 
     const UChar     *src, 
     int32_t     n);

#if !UCONFIG_NO_CONVERSION

/**
 * Copy a byte string encoded in the default codepage to a ustring.
 * Adds a null terminator.
 * Performs a host byte to UChar conversion
 *
 * @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_uastrcpy(UChar *dst,
               const char *src );

/**
 * Copy a byte string encoded in the default codepage to a ustring.
 * Copies at most <code>n</code> characters.  The result will be null terminated
 * if the length of <code>src</code> is less than <code>n</code>.
 * Performs a host byte to UChar conversion
 *
 * @param dst The destination string.
 * @param src The source string.
 * @param n The maximum number of characters to copy.
 * @return A pointer to <code>dst</code>.
 * @stable ICU 2.0
 */
U_STABLE UChar* U_EXPORT2 u_uastrncpy(UChar *dst,
            const char *src,
            int32_t n);

/**
 * Copy ustring to a byte string encoded in the default codepage.
 * Adds a null terminator.
 * Performs a UChar to host byte conversion
 *
 * @param dst The destination string.
 * @param src The source string.
 * @return A pointer to <code>dst</code>.
 * @stable ICU 2.0
 */
U_STABLE char* U_EXPORT2 u_austrcpy(char *dst,
            const UChar *src );

/**
 * Copy ustring to a byte string encoded in the default codepage.
 * Copies at most <code>n</code> characters.  The result will be null terminated
 * if the length of <code>src</code> is less than <code>n</code>.
 * Performs a UChar to host byte conversion
 *
 * @param dst The destination string.
 * @param src The source string.
 * @param n The maximum number of characters to copy.
 * @return A pointer to <code>dst</code>.
 * @stable ICU 2.0
 */
U_STABLE char* U_EXPORT2 u_austrncpy(char *dst,
            const UChar *src,
            int32_t n );

#endif

/**
 * Synonym for memcpy(), but with UChars only.
 * @param dest The destination string
 * @param src The source string
 * @param count The number of characters to copy
 * @return A pointer to <code>dest</code>
 * @stable ICU 2.0
 */
U_STABLE UChar* U_EXPORT2
u_memcpy(UChar *dest, const UChar *src, int32_t count);

/**
 * Synonym for memmove(), but with UChars only.
 * @param dest The destination string
 * @param src The source string
 * @param count The number of characters to move
 * @return A pointer to <code>dest</code>
 * @stable ICU 2.0
 */
U_STABLE UChar* U_EXPORT2
u_memmove(UChar *dest, const UChar *src, int32_t count);

/**
 * Initialize <code>count</code> characters of <code>dest</code> to <code>c</code>.
 *
 * @param dest The destination string.
 * @param c The character to initialize the string.
 * @param count The maximum number of characters to set.
 * @return A pointer to <code>dest</code>.
 * @stable ICU 2.0
 */
U_STABLE UChar* U_EXPORT2
u_memset(UChar *dest, UChar c, int32_t count);

/**
 * Compare the first <code>count</code> UChars of each buffer.
 *
 * @param buf1 The first string to compare.
 * @param buf2 The second string to compare.
 * @param count The maximum number of UChars to compare.
 * @return When buf1 < buf2, a negative number is returned.
 *      When buf1 == buf2, 0 is returned.
 *      When buf1 > buf2, a positive number is returned.
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
u_memcmp(const UChar *buf1, const UChar *buf2, int32_t count);

/**
 * Compare two Unicode strings in code point order.
 * This is different in UTF-16 from u_memcmp() if supplementary characters are present.
 * For details, see u_strCompare().
 *
 * @param s1 A string to compare.
 * @param s2 A string to compare.
 * @param count The maximum number of characters 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_memcmpCodePointOrder(const UChar *s1, const UChar *s2, int32_t count);

/**
 * 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 (contains <code>count</code> UChars).
 * @param c The BMP code point to find.
 * @param count The length of the string.
 * @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_strFindFirst
 */
U_STABLE UChar* U_EXPORT2
u_memchr(const UChar *s, UChar c, int32_t count);

/**
 * 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 (contains <code>count</code> UChars).
 * @param c The code point to find.
 * @param count The length of the string.
 * @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_strFindFirst
 */
U_STABLE UChar* U_EXPORT2
u_memchr32(const UChar *s, UChar32 c, int32_t count);

/**
 * 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 (contains <code>count</code> UChars).
 * @param c The BMP code point to find.
 * @param count The length of the string.
 * @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_memrchr32
 * @see u_strFindLast
 */
U_STABLE UChar* U_EXPORT2
u_memrchr(const UChar *s, UChar c, int32_t count);

/**
 * 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 (contains <code>count</code> UChars).
 * @param c The code point to find.
 * @param count The length of the string.
 * @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_strFindLast
 */
U_STABLE UChar* U_EXPORT2
u_memrchr32(const UChar *s, UChar32 c, int32_t count);

/**
 * Unicode String literals in C.
 * We need one macro to declare a variable for the string
 * and to statically preinitialize it if possible,
 * and a second macro to dynamically intialize such a string variable if necessary.
 *
 * 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.
 *
 * A pair of macros for a single string must be used with the same
 * parameters.
 * 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.
 *
 * Usage:
 * <pre>
 * &#32;   U_STRING_DECL(ustringVar1, "Quick-Fox 2", 11);
 * &#32;   U_STRING_DECL(ustringVar2, "jumps 5%", 8);
 * &#32;   static UBool didInit=FALSE;
 * &#32;
 * &#32;   int32_t function() {
 * &#32;       if(!didInit) {
 * &#32;           U_STRING_INIT(ustringVar1, "Quick-Fox 2", 11);
 * &#32;           U_STRING_INIT(ustringVar2, "jumps 5%", 8);
 * &#32;           didInit=TRUE;
 * &#32;       }
 * &#32;       return u_strcmp(ustringVar1, ustringVar2);
 * &#32;   }
 * </pre>
 * @stable ICU 2.0
 */
#if U_SIZEOF_WCHAR_T==U_SIZEOF_UCHAR && U_CHARSET_FAMILY==U_ASCII_FAMILY
#   define U_STRING_DECL(var, cs, length) static const wchar_t var[(length)+1]={ L ## cs }
    /**@stable ICU 2.0 */
#   define U_STRING_INIT(var, cs, length)
#elif U_SIZEOF_UCHAR==1 && U_CHARSET_FAMILY==U_ASCII_FAMILY
#   define U_STRING_DECL(var, cs, length) static const UChar var[(length)+1]={ (const UChar *)cs }
    /**@stable ICU 2.0 */
#   define U_STRING_INIT(var, cs, length)
#else
#   define U_STRING_DECL(var, cs, length) static UChar var[(length)+1]
    /**@stable ICU 2.0 */
#   define U_STRING_INIT(var, cs, length) u_charsToUChars(cs, var, length+1)
#endif

/**
 * Unescape a string of characters and write the resulting
 * Unicode characters to the destination buffer.  The following escape
 * sequences are recognized:
 *
 * \\uhhhh       4 hex digits; h in [0-9A-Fa-f]
 * \\Uhhhhhhhh   8 hex digits
 * \\xhh         1-2 hex digits
 * \\x{h...}     1-8 hex digits
 * \\ooo         1-3 octal digits; o in [0-7]
 * \\cX          control-X; X is masked with 0x1F
 *
 * as well as the standard ANSI C escapes:
 *
 * \\a => U+0007, \\b => U+0008, \\t => U+0009, \\n => U+000A,
 * \\v => U+000B, \\f => U+000C, \\r => U+000D, \\e => U+001B,
 * \\" => U+0022, \\' => U+0027, \\? => U+003F, \\\\ => U+005C
 *
 * Anything else following a backslash is generically escaped.  For
 * example, "[a\\-z]" returns "[a-z]".
 *
 * If an escape sequence is ill-formed, this method returns an empty
 * string.  An example of an ill-formed sequence is "\\u" followed by
 * fewer than 4 hex digits.
 *
 * The above characters are recognized in the compiler's codepage,
 * that is, they are coded as 'u', '\\', etc.  Characters that are
 * not parts of escape sequences are converted using u_charsToUChars().
 *
 * This function is similar to UnicodeString::unescape() but not
 * identical to it.  The latter takes a source UnicodeString, so it
 * does escape recognition but no conversion.
 *
 * @param src a zero-terminated string of invariant characters
 * @param dest pointer to buffer to receive converted and unescaped
 * text and, if there is room, a zero terminator.  May be NULL for
 * preflighting, in which case no UChars will be written, but the
 * return value will still be valid.  On error, an empty string is
 * stored here (if possible).
 * @param destCapacity the number of UChars that may be written at
 * dest.  Ignored if dest == NULL.
 * @return the length of unescaped string.
 * @see u_unescapeAt
 * @see UnicodeString#unescape()
 * @see UnicodeString#unescapeAt()
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
u_unescape(const char *src,
           UChar *dest, int32_t destCapacity);

U_CDECL_BEGIN
/**
 * Callback function for u_unescapeAt() that returns a character of
 * the source text given an offset and a context pointer.  The context
 * pointer will be whatever is passed into u_unescapeAt().
 *
 * @param offset pointer to the offset that will be passed to u_unescapeAt().
 * @param context an opaque pointer passed directly into u_unescapeAt()
 * @return the character represented by the escape sequence at
 * offset
 * @see u_unescapeAt
 * @stable ICU 2.0
 */