ucnv.h

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

 *     utf8Cnv=myGetCachedUTF8Converter(pErrorCode);
 *     if(U_FAILURE(*pErrorCode)) {
 *         return 0;
 *     }
 *
 *     target=u8;
 *     ucnv_convertEx(cnv, utf8Cnv,
 *                    &target, u8+capacity,
 *                    &s, length>=0 ? s+length : NULL,
 *                    NULL, NULL, NULL, NULL,
 *                    TRUE, TRUE,
 *                    pErrorCode);
 * 
 *     myReleaseCachedUTF8Converter(utf8Cnv);
 *
 *     // return the output string length, but without preflighting
 *     return (int32_t)(target-u8);
 * }
 * \endcode
 *
 * @param targetCnv     Output converter, used to convert from the UTF-16 pivot
 *                      to the target using ucnv_fromUnicode().
 * @param sourceCnv     Input converter, used to convert from the source to
 *                      the UTF-16 pivot using ucnv_toUnicode().
 * @param target        I/O parameter, same as for ucnv_fromUChars().
 *                      Input: *target points to the beginning of the target buffer.
 *                      Output: *target points to the first unit after the last char written.
 * @param targetLimit   Pointer to the first unit after the target buffer.
 * @param source        I/O parameter, same as for ucnv_toUChars().
 *                      Input: *source points to the beginning of the source buffer.
 *                      Output: *source points to the first unit after the last char read.
 * @param sourceLimit   Pointer to the first unit after the source buffer.
 * @param pivotStart    Pointer to the UTF-16 pivot buffer. If pivotStart==NULL,
 *                      then an internal buffer is used and the other pivot
 *                      arguments are ignored and can be NULL as well.
 * @param pivotSource   I/O parameter, same as source in ucnv_fromUChars() for
 *                      conversion from the pivot buffer to the target buffer.
 * @param pivotTarget   I/O parameter, same as target in ucnv_toUChars() for
 *                      conversion from the source buffer to the pivot buffer.
 *                      It must be pivotStart<=*pivotSource<=*pivotTarget<=pivotLimit
 *                      and pivotStart<pivotLimit (unless pivotStart==NULL).
 * @param pivotLimit    Pointer to the first unit after the pivot buffer.
 * @param reset         If TRUE, then ucnv_resetToUnicode(sourceCnv) and
 *                      ucnv_resetFromUnicode(targetCnv) are called, and the
 *                      pivot pointers are reset (*pivotTarget=*pivotSource=pivotStart).
 * @param flush         If true, indicates the end of the input.
 *                      Passed directly to ucnv_toUnicode(), and carried over to
 *                      ucnv_fromUnicode() when the source is empty as well.
 * @param pErrorCode    ICU error code in/out parameter.
 *                      Must fulfill U_SUCCESS before the function call.
 *                      U_BUFFER_OVERFLOW_ERROR always refers to the target buffer
 *                      because overflows into the pivot buffer are handled internally.
 *                      Other conversion errors are from the source-to-pivot
 *                      conversion if *pivotSource==pivotStart, otherwise from
 *                      the pivot-to-target conversion.
 *
 * @see ucnv_convert
 * @see ucnv_fromAlgorithmic
 * @see ucnv_toAlgorithmic
 * @see ucnv_fromUnicode
 * @see ucnv_toUnicode
 * @see ucnv_fromUChars
 * @see ucnv_toUChars
 * @stable ICU 2.6
 */
U_STABLE void U_EXPORT2
ucnv_convertEx(UConverter *targetCnv, UConverter *sourceCnv,
               char **target, const char *targetLimit,
               const char **source, const char *sourceLimit,
               UChar *pivotStart, UChar **pivotSource,
               UChar **pivotTarget, const UChar *pivotLimit,
               UBool reset, UBool flush,
               UErrorCode *pErrorCode);

/**
 * Convert from one external charset to another.
 * Internally, two converters are opened according to the name arguments,
 * then the text is converted to and from the 16-bit Unicode "pivot"
 * using ucnv_convertEx(), then the converters are closed again.
 *
 * This is a convenience function, not an efficient way to convert a lot of text:
 * ucnv_convert()
 * - takes charset names, not converter objects, so that
 *   - two converters are opened for each call
 *   - only single-string conversion is possible, not streaming operation
 * - does not provide enough information to find out,
 *   in case of failure, whether the toUnicode or
 *   the fromUnicode conversion failed
 * - allows NUL-terminated input
 *   (only a single NUL byte, will not work for charsets with multi-byte NULs)
 *   (if sourceLength==-1, see parameters)
 * - terminate with a NUL on output
 *   (only a single NUL byte, not useful for charsets with multi-byte NULs),
 *   or set U_STRING_NOT_TERMINATED_WARNING if the output exactly fills
 *   the target buffer
 * - a pivot buffer is provided internally
 *
 * The function returns when one of the following is true:
 * - the entire source text has been converted successfully to the target buffer
 *   and either the target buffer is terminated with a single NUL byte
 *   or the error code is set to U_STRING_NOT_TERMINATED_WARNING
 * - a target buffer overflow occurred (U_BUFFER_OVERFLOW_ERROR)
 *   and the full output string length is returned ("preflighting")
 * - a conversion error occurred
 *   (other U_FAILURE(), see description of pErrorCode)
 *
 * @param toConverterName   The name of the converter that is used to convert
 *                          from the UTF-16 pivot buffer to the target.
 * @param fromConverterName The name of the converter that is used to convert
 *                          from the source to the UTF-16 pivot buffer.
 * @param target            Pointer to the output buffer.
 * @param targetCapacity    Capacity of the target, in bytes.
 * @param source            Pointer to the input buffer.
 * @param sourceLength      Length of the input text, in bytes, or -1 for NUL-terminated input.
 * @param pErrorCode        ICU error code in/out parameter.
 *                          Must fulfill U_SUCCESS before the function call.
 * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity
 *         and a U_BUFFER_OVERFLOW_ERROR is set.
 *
 * @see ucnv_convertEx
 * @see ucnv_fromAlgorithmic
 * @see ucnv_toAlgorithmic
 * @see ucnv_fromUnicode
 * @see ucnv_toUnicode
 * @see ucnv_fromUChars
 * @see ucnv_toUChars
 * @see ucnv_getNextUChar
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
ucnv_convert(const char *toConverterName,
             const char *fromConverterName,
             char *target,
             int32_t targetCapacity,
             const char *source,
             int32_t sourceLength,
             UErrorCode *pErrorCode);

/**
 * Convert from one external charset to another.
 * Internally, the text is converted to and from the 16-bit Unicode "pivot"
 * using ucnv_convertEx(). ucnv_toAlgorithmic() works exactly like ucnv_convert()
 * except that the two converters need not be looked up and opened completely.
 *
 * The source-to-pivot conversion uses the cnv converter parameter.
 * The pivot-to-target conversion uses a purely algorithmic converter
 * according to the specified type, e.g., UCNV_UTF8 for a UTF-8 converter.
 *
 * Internally, the algorithmic converter is opened and closed for each
 * function call, which is more efficient than using the public ucnv_open()
 * but somewhat less efficient than only resetting an existing converter
 * and using ucnv_convertEx().
 *
 * This function is more convenient than ucnv_convertEx() for single-string
 * conversions, especially when "preflighting" is desired (returning the length
 * of the complete output even if it does not fit into the target buffer;
 * see the User Guide Strings chapter). See ucnv_convert() for details.
 *
 * @param algorithmicType   UConverterType constant identifying the desired target
 *                          charset as a purely algorithmic converter.
 *                          Those are converters for Unicode charsets like
 *                          UTF-8, BOCU-1, SCSU, UTF-7, IMAP-mailbox-name, etc.,
 *                          as well as US-ASCII and ISO-8859-1.
 * @param cnv               The converter that is used to convert
 *                          from the source to the UTF-16 pivot buffer.
 * @param target            Pointer to the output buffer.
 * @param targetCapacity    Capacity of the target, in bytes.
 * @param source            Pointer to the input buffer.
 * @param sourceLength      Length of the input text, in bytes
 * @param pErrorCode        ICU error code in/out parameter.
 *                          Must fulfill U_SUCCESS before the function call.
 * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity
 *         and a U_BUFFER_OVERFLOW_ERROR is set.
 *
 * @see ucnv_fromAlgorithmic
 * @see ucnv_convert
 * @see ucnv_convertEx
 * @see ucnv_fromUnicode
 * @see ucnv_toUnicode
 * @see ucnv_fromUChars
 * @see ucnv_toUChars
 * @stable ICU 2.6
 */
U_STABLE int32_t U_EXPORT2
ucnv_toAlgorithmic(UConverterType algorithmicType,
                   UConverter *cnv,
                   char *target, int32_t targetCapacity,
                   const char *source, int32_t sourceLength,
                   UErrorCode *pErrorCode);

/**
 * Convert from one external charset to another.
 * Internally, the text is converted to and from the 16-bit Unicode "pivot"
 * using ucnv_convertEx(). ucnv_fromAlgorithmic() works exactly like ucnv_convert()
 * except that the two converters need not be looked up and opened completely.
 *
 * The source-to-pivot conversion uses a purely algorithmic converter
 * according to the specified type, e.g., UCNV_UTF8 for a UTF-8 converter.
 * The pivot-to-target conversion uses the cnv converter parameter.
 *
 * Internally, the algorithmic converter is opened and closed for each
 * function call, which is more efficient than using the public ucnv_open()
 * but somewhat less efficient than only resetting an existing converter
 * and using ucnv_convertEx().
 *
 * This function is more convenient than ucnv_convertEx() for single-string
 * conversions, especially when "preflighting" is desired (returning the length
 * of the complete output even if it does not fit into the target buffer;
 * see the User Guide Strings chapter). See ucnv_convert() for details.
 *
 * @param cnv               The converter that is used to convert
 *                          from the UTF-16 pivot buffer to the target.
 * @param algorithmicType   UConverterType constant identifying the desired source
 *                          charset as a purely algorithmic converter.
 *                          Those are converters for Unicode charsets like
 *                          UTF-8, BOCU-1, SCSU, UTF-7, IMAP-mailbox-name, etc.,
 *                          as well as US-ASCII and ISO-8859-1.
 * @param target            Pointer to the output buffer.
 * @param targetCapacity    Capacity of the target, in bytes.
 * @param source            Pointer to the input buffer.
 * @param sourceLength      Length of the input text, in bytes
 * @param pErrorCode        ICU error code in/out parameter.
 *                          Must fulfill U_SUCCESS before the function call.
 * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity
 *         and a U_BUFFER_OVERFLOW_ERROR is set.
 *
 * @see ucnv_fromAlgorithmic
 * @see ucnv_convert
 * @see ucnv_convertEx
 * @see ucnv_fromUnicode
 * @see ucnv_toUnicode
 * @see ucnv_fromUChars
 * @see ucnv_toUChars
 * @stable ICU 2.6
 */
U_STABLE int32_t U_EXPORT2
ucnv_fromAlgorithmic(UConverter *cnv,
                     UConverterType algorithmicType,
                     char *target, int32_t targetCapacity,
                     const char *source, int32_t sourceLength,
                     UErrorCode *pErrorCode);

/**
 * Frees up memory occupied by unused, cached converter shared data.
 *
 * @return the number of cached converters successfully deleted
 * @see ucnv_close
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
ucnv_flushCache(void);

/**
 * Returns the number of available converters, as per the alias file.
 *
 * @return the number of available converters
 * @see ucnv_getAvailableName
 * @stable ICU 2.0
 */
U_STABLE int32_t U_EXPORT2
ucnv_countAvailable(void);

/**
 * Gets the canonical converter name of the specified converter from a list of
 * all available converters contaied in the alias file. All converters
 * in this list can be opened.
 *
 * @param n the index to a converter available on the system (in the range <TT>[0..ucnv_countAvaiable()]</TT>)
 * @return a pointer a string (library owned), or <TT>NULL</TT> if the index is out of bounds.
 * @see ucnv_countAvailable
 * @stable ICU 2.0
 */
U_STABLE const char* U_EXPORT2
ucnv_getAvailableName(int32_t n);

/**
 * Returns a UEnumeration to enumerate all of the canonical converter
 * names, as per the alias file, regardless of the ability to open each
 * converter.
 *
 * @return A UEnumeration object for getting all the recognized canonical
 *   converter names.
 * @see ucnv_getAvailableName
 * @see uenum_close
 * @see uenum_next
 * @stable ICU 2.4
 */
U_STABLE UEnumeration * U_EXPORT2
ucnv_openAllNames(UErrorCode *pErrorCode);

/**
 * Gives the number of aliases for a given converter or alias name.
 * If the alias is ambiguous, then the preferred converter is used
 * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.
 * This method only enumerates the listed entries in the alias file.
 * @param alias alias name
 * @param pErrorCode error status
 * @return number of names on alias list for given alias
 * @stable ICU 2.0
 */
U_STABLE uint16_t U_EXPORT2 
ucnv_countAliases(const char *alias, UErrorCode *pErrorCode);

/**
 * Gives the name of the alias at given index of alias list.
 * This method only enumerates the listed entries in the alias file.
 * If the alias is ambiguous, then the preferred converter is used
 * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.
 * @param ali