/*
**********************************************************************
-* Copyright (C) 1999-2003, International Business Machines
+* Copyright (C) 1999-2006, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
* ucnv.h:
* <h2>Character Conversion C API</h2>
*
* <p>This API is used to convert codepage or character encoded data to and
- * from UTF-16. You can open a converter with {@link ucnv_open()}. With that
+ * from UTF-16. You can open a converter with {@link ucnv_open() }. With that
* converter, you can get its properties, set options, convert your data and
* close the converter.</p>
*
* <p>Since many software programs recogize different converter names for
* different types of converters, there are other functions in this API to
- * iterate over the converter aliases. The functions {@link ucnv_getAvailableName()},
- * {@link ucnv_getAlias()} and {@link ucnv_getStandardName()} are some of the
+ * iterate over the converter aliases. The functions {@link ucnv_getAvailableName() },
+ * {@link ucnv_getAlias() } and {@link ucnv_getStandardName() } are some of the
* more frequently used alias functions to get this information.</p>
*
* <p>When a converter encounters an illegal, irregular, invalid or unmappable character
* its default behavior is to use a substitution character to replace the
- * bad byte sequence. This behavior can be changed by using {@link ucnv_getFromUCallBack()}
- * or {@link ucnv_getToUCallBack()} on the converter. The header ucnv_err.h defines
+ * bad byte sequence. This behavior can be changed by using {@link ucnv_setFromUCallBack() }
+ * or {@link ucnv_setToUCallBack() } on the converter. The header ucnv_err.h defines
* many other callback actions that can be used instead of a character substitution.</p>
*
* <p>More information about this API can be found in our
- * <a href="http://oss.software.ibm.com/icu/userguide/conversion.html">User's
+ * <a href="http://icu.sourceforge.net/userguide/conversion.html">User's
* Guide</a>.</p>
*/
#ifndef UCNV_H
#define UCNV_H
-/** Forward declaring the UConverter structure. @stable ICU 2.0 */
-struct UConverter;
-
-/** @stable ICU 2.0 */
-typedef struct UConverter UConverter;
-
-#include "unicode/utypes.h"
#include "unicode/ucnv_err.h"
#include "unicode/uenum.h"
* See unicode/uset.h
*
* @see ucnv_getUnicodeSet
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
struct USet;
+/** @stable ICU 2.6 */
typedef struct USet USet;
#endif
+#if !UCONFIG_NO_CONVERSION
+
U_CDECL_BEGIN
/** Maximum length of a converter name including the terminating NULL @stable ICU 2.0 */
* @param codeUnits Points to 'length' bytes of the concerned codepage sequence
* @param length Size (in bytes) of the concerned codepage sequence
* @param reason Defines the reason the callback was invoked
+ * @param pErrorCode ICU error code in/out parameter.
+ * For converter callback functions, set to a conversion error
+ * before the call, and the callback may reset it to U_ZERO_ERROR.
* @see ucnv_setToUCallBack
* @see UConverterToUnicodeArgs
* @stable ICU 2.0
const char *codeUnits,
int32_t length,
UConverterCallbackReason reason,
- UErrorCode *);
+ UErrorCode *pErrorCode);
/**
* Function pointer for error callback in the unicode to codepage direction.
* @param length Size (in bytes) of the concerned codepage sequence
* @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.
* @param reason Defines the reason the callback was invoked
+ * @param pErrorCode ICU error code in/out parameter.
+ * For converter callback functions, set to a conversion error
+ * before the call, and the callback may reset it to U_ZERO_ERROR.
* @see ucnv_setFromUCallBack
* @stable ICU 2.0
*/
int32_t length,
UChar32 codePoint,
UConverterCallbackReason reason,
- UErrorCode *);
+ UErrorCode *pErrorCode);
U_CDECL_END
* See convrtrs.txt.
*
* @see ucnv_open
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
#define UCNV_VERSION_OPTION_STRING ",version="
* See convrtrs.txt.
*
* @see ucnv_open
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
#define UCNV_SWAP_LFNL_OPTION_STRING ",swaplfnl"
/**
- * Do a fuzzy compare of a two converter/alias names. The comparison
- * is case-insensitive. It also ignores the characters '-', '_', and
- * ' ' (dash, underscore, and space). Thus the strings "UTF-8",
- * "utf_8", and "Utf 8" are exactly equivalent.
- *
+ * Do a fuzzy compare of two converter/alias names.
+ * The comparison is case-insensitive, ignores leading zeroes if they are not
+ * followed by further digits, and ignores all but letters and digits.
+ * Thus the strings "UTF-8", "utf_8", "u*T@f08" and "Utf 8" are exactly equivalent.
+ * See section 1.4, Charset Alias Matching in Unicode Technical Standard #22
+ * at http://www.unicode.org/reports/tr22/
+ *
* @param name1 a converter name or alias, zero-terminated
* @param name2 a converter name or alias, zero-terminated
* @return 0 if the names match, or a negative value if the name1
* lexically follows name2.
* @stable ICU 2.0
*/
-U_CAPI int U_EXPORT2
+U_STABLE int U_EXPORT2
ucnv_compareNames(const char *name1, const char *name2);
/**
- * Creates a UConverter object with the names specified as a C string.
+ * Creates a UConverter object with the name of a coded character set specified as a C string.
* The actual name will be resolved with the alias file
* using a case-insensitive string comparison that ignores
- * the delimiters '-', '_', and ' ' (dash, underscore, and space).
- * E.g., the names "UTF8", "utf-8", and "Utf 8" are all equivalent.
+ * leading zeroes and all non-alphanumeric characters.
+ * E.g., the names "UTF8", "utf-8", "u*T@f08" and "Utf 8" are all equivalent.
+ * (See also ucnv_compareNames().)
* If <code>NULL</code> is passed for the converter name, it will create one with the
* getDefaultName return value.
*
*
* <p>The conversion behavior and names can vary between platforms. ICU may
* convert some characters differently from other platforms. Details on this topic
- * are in the <a href="http://oss.software.ibm.com/icu/userguide/conversion.html">User's
- * Guide</a>.</p>
- *
- * @param converterName Name of the uconv table, may have options appended
+ * are in the <a href="http://icu.sourceforge.net/userguide/conversion.html">User's
+ * Guide</a>. Aliases starting with a "cp" prefix have no specific meaning
+ * other than its an alias starting with the letters "cp". Please do not
+ * associate any meaning to these aliases.</p>
+ *
+ * @param converterName Name of the coded character set table.
+ * This may have options appended to the string.
+ * IANA alias character set names, IBM CCSIDs starting with "ibm-",
+ * Windows codepage numbers starting with "windows-" are frequently
+ * used for this parameter. See ucnv_getAvailableName and
+ * ucnv_getAlias for a complete list that is available.
+ * If this parameter is NULL, the default converter will be used.
* @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT>
* @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
* @see ucnv_openU
* @see ucnv_openCCSID
+ * @see ucnv_getAvailableName
+ * @see ucnv_getAlias
+ * @see ucnv_getDefaultName
* @see ucnv_close
+ * @ee ucnv_compareNames
* @stable ICU 2.0
*/
-U_CAPI UConverter* U_EXPORT2
+U_STABLE UConverter* U_EXPORT2
ucnv_open(const char *converterName, UErrorCode *err);
* The name should be limited to the ASCII-7 alphanumerics range.
* The actual name will be resolved with the alias file
* using a case-insensitive string comparison that ignores
- * the delimiters '-', '_', and ' ' (dash, underscore, and space).
- * E.g., the names "UTF8", "utf-8", and "Utf 8" are all equivalent.
+ * leading zeroes and all non-alphanumeric characters.
+ * E.g., the names "UTF8", "utf-8", "u*T@f08" and "Utf 8" are all equivalent.
+ * (See also ucnv_compareNames().)
* If <TT>NULL</TT> is passed for the converter name, it will create
* one with the ucnv_getDefaultName() return value.
* If the alias is ambiguous, then the preferred converter is used
* and the status is set to U_AMBIGUOUS_ALIAS_WARNING.
- * @param name : name of the uconv table in a zero terminated
+ *
+ * <p>See ucnv_open for the complete details</p>
+ * @param name Name of the UConverter table in a zero terminated
* Unicode string
* @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR,
* U_FILE_ACCESS_ERROR</TT>
* @see ucnv_open
* @see ucnv_openCCSID
* @see ucnv_close
- * @see ucnv_getDefaultName
+ * @ee ucnv_compareNames
* @stable ICU 2.0
*/
-U_CAPI UConverter* U_EXPORT2
+U_STABLE UConverter* U_EXPORT2
ucnv_openU(const UChar *name,
UErrorCode *err);
* @see UConverterPlatform
* @stable ICU 2.0
*/
-U_CAPI UConverter* U_EXPORT2
+U_STABLE UConverter* U_EXPORT2
ucnv_openCCSID(int32_t codepage,
UConverterPlatform platform,
UErrorCode * err);
* <p>The packageName and converterName must point to an ICU udata object, as defined by
* <code> udata_open( packageName, "cnv", converterName, err) </code> or equivalent.
* Typically, packageName will refer to a (.dat) file, or to a package registered with
- * udata_setAppData().</p>
+ * udata_setAppData(). Using a full file or directory pathname for packageName is deprecated.</p>
*
* <p>The name will NOT be looked up in the alias mechanism, nor will the converter be
* stored in the converter cache or the alias table. The only way to open further converters
* is call this function multiple times, or use the ucnv_safeClone() function to clone a
* 'master' converter.</p>
+ *
+ * <p>A future version of ICU may add alias table lookups and/or caching
+ * to this function.</p>
*
* <p>Example Use:
* <code>cnv = ucnv_openPackage("myapp", "myconverter", &err);</code>
* @see ucnv_open
* @see ucnv_safeClone
* @see ucnv_close
- * @draft ICU 2.2
+ * @stable ICU 2.2
*/
-U_CAPI UConverter* U_EXPORT2
+U_STABLE UConverter* U_EXPORT2
ucnv_openPackage(const char *packageName, const char *converterName, UErrorCode *err);
/**
- * Thread safe cloning operation
+ * Thread safe converter cloning operation.
+ * For most efficient operation, pass in a stackBuffer (and a *pBufferSize)
+ * with at least U_CNV_SAFECLONE_BUFFERSIZE bytes of space.
+ * If the buffer size is sufficient, then the clone will use the stack buffer;
+ * otherwise, it will be allocated, and *pBufferSize will indicate
+ * the actual size. (This should not occur with U_CNV_SAFECLONE_BUFFERSIZE.)
+ *
+ * You must ucnv_close() the clone in any case.
+ *
+ * If *pBufferSize==0, (regardless of whether stackBuffer==NULL or not)
+ * then *pBufferSize will be changed to a sufficient size
+ * for cloning this converter,
+ * without actually cloning the converter ("pure pre-flighting").
+ *
+ * If *pBufferSize is greater than zero but not large enough for a stack-based
+ * clone, then the converter is cloned using newly allocated memory
+ * and *pBufferSize is changed to the necessary size.
+ *
+ * If the converter clone fits into the stack buffer but the stack buffer is not
+ * sufficiently aligned for the clone, then the clone will use an
+ * adjusted pointer and use an accordingly smaller buffer size.
+ *
* @param cnv converter to be cloned
* @param stackBuffer user allocated space for the new clone. If NULL new memory will be allocated.
* If buffer is not large enough, new memory will be allocated.
* Clients can use the U_CNV_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations.
- * @param pBufferSize pointer to size of allocated space.
- * If *pBufferSize == 0, a sufficient size for use in cloning will
- * be returned ('pre-flighting')
- * If *pBufferSize is not enough for a stack-based safe clone,
- * new memory will be allocated.
+ * @param pBufferSize pointer to size of allocated space. pBufferSize must not be NULL.
* @param status to indicate whether the operation went on smoothly or there were errors
- * An informational status value, U_SAFECLONE_ALLOCATED_ERROR, is used if any allocations were necessary.
+ * An informational status value, U_SAFECLONE_ALLOCATED_WARNING,
+ * is used if any allocations were necessary.
+ * However, it is better to check if *pBufferSize grew for checking for
+ * allocations because warning codes can be overridden by subsequent
+ * function calls.
* @return pointer to the new clone
* @stable ICU 2.0
*/
-U_CAPI UConverter * U_EXPORT2
+U_STABLE UConverter * U_EXPORT2
ucnv_safeClone(const UConverter *cnv,
void *stackBuffer,
int32_t *pBufferSize,
UErrorCode *status);
-/** @stable ICU 2.0 */
-#define U_CNV_SAFECLONE_BUFFERSIZE 3072
+/**
+ * \def U_CNV_SAFECLONE_BUFFERSIZE
+ * Definition of a buffer size that is designed to be large enough for
+ * converters to be cloned with ucnv_safeClone().
+ * @stable ICU 2.0
+ */
+#define U_CNV_SAFECLONE_BUFFERSIZE 1024
/**
* Deletes the unicode converter and releases resources associated
* @see ucnv_openCCSID
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_close(UConverter * converter);
/**
* Fills in the output parameter, subChars, with the substitution characters
* as multiple bytes.
+ * If ucnv_setSubstString() set a Unicode string because the converter is
+ * stateful, then subChars will be an empty string.
*
* @param converter the Unicode converter
* @param subChars the subsitution characters
* @param err the outgoing error status code.
* If the substitution character array is too small, an
* <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
+ * @see ucnv_setSubstString
* @see ucnv_setSubstChars
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getSubstChars(const UConverter *converter,
char *subChars,
int8_t *len,
/**
* Sets the substitution chars when converting from unicode to a codepage. The
* substitution is specified as a string of 1-4 bytes, and may contain
- * <TT>NULL</TT> byte.
+ * <TT>NULL</TT> bytes.
+ * The subChars must represent a single character. The caller needs to know the
+ * byte sequence of a valid character in the converter's charset.
+ * For some converters, for example some ISO 2022 variants, only single-byte
+ * substitution characters may be supported.
+ * The newer ucnv_setSubstString() function relaxes these limitations.
+ *
* @param converter the Unicode converter
* @param subChars the substitution character byte sequence we want set
* @param len the number of bytes in subChars
* @param err the error status code. <TT>U_INDEX_OUTOFBOUNDS_ERROR </TT> if
* len is bigger than the maximum number of bytes allowed in subchars
+ * @see ucnv_setSubstString
* @see ucnv_getSubstChars
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_setSubstChars(UConverter *converter,
const char *subChars,
int8_t len,
UErrorCode *err);
+/**
+ * Set a substitution string for converting from Unicode to a charset.
+ * The caller need not know the charset byte sequence for each charset.
+ *
+ * Unlike ucnv_setSubstChars() which is designed to set a charset byte sequence
+ * for a single character, this function takes a Unicode string with
+ * zero, one or more characters, and immediately verifies that the string can be
+ * converted to the charset.
+ * If not, or if the result is too long (more than 32 bytes as of ICU 3.6),
+ * then the function returns with an error accordingly.
+ *
+ * Also unlike ucnv_setSubstChars(), this function works for stateful charsets
+ * by converting on the fly at the point of substitution rather than setting
+ * a fixed byte sequence.
+ *
+ * @param cnv The UConverter object.
+ * @param s The Unicode string.
+ * @param length The number of UChars in s, or -1 for a NUL-terminated string.
+ * @param err Pointer to a standard ICU error code. Its input value must
+ * pass the U_SUCCESS() test, or else the function returns
+ * immediately. Check for U_FAILURE() on output or use with
+ * function chaining. (See User Guide for details.)
+ *
+ * @see ucnv_setSubstChars
+ * @see ucnv_getSubstChars
+ * @draft ICU 3.6
+ */
+U_DRAFT void U_EXPORT2
+ucnv_setSubstString(UConverter *cnv,
+ const UChar *s,
+ int32_t length,
+ UErrorCode *err);
+
/**
* Fills in the output parameter, errBytes, with the error characters from the
* last failing conversion.
* <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getInvalidChars(const UConverter *converter,
char *errBytes,
int8_t *len,
* <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getInvalidUChars(const UConverter *converter,
UChar *errUChars,
int8_t *len,
* @param converter the Unicode converter
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_reset(UConverter *converter);
/**
* @param converter the Unicode converter
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_resetToUnicode(UConverter *converter);
/**
* @param converter the Unicode converter
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_resetFromUnicode(UConverter *converter);
/**
- * Returns the maximum length of bytes used by a character. This varies
- * between 1 and 4
- * @param converter the Unicode converter
- * @return the maximum number of bytes allowed by this particular converter
+ * Returns the maximum number of bytes that are output per UChar in conversion
+ * from Unicode using this converter.
+ * The returned number can be used with UCNV_GET_MAX_BYTES_FOR_STRING
+ * to calculate the size of a target buffer for conversion from Unicode.
+ *
+ * Note: Before ICU 2.8, this function did not return reliable numbers for
+ * some stateful converters (EBCDIC_STATEFUL, ISO-2022) and LMBCS.
+ *
+ * This number may not be the same as the maximum number of bytes per
+ * "conversion unit". In other words, it may not be the intuitively expected
+ * number of bytes per character that would be published for a charset,
+ * and may not fulfill any other purpose than the allocation of an output
+ * buffer of guaranteed sufficient size for a given input length and converter.
+ *
+ * Examples for special cases that are taken into account:
+ * - Supplementary code points may convert to more bytes than BMP code points.
+ * This function returns bytes per UChar (UTF-16 code unit), not per
+ * Unicode code point, for efficient buffer allocation.
+ * - State-shifting output (SI/SO, escapes, etc.) from stateful converters.
+ * - When m input UChars are converted to n output bytes, then the maximum m/n
+ * is taken into account.
+ *
+ * The number returned here does not take into account
+ * (see UCNV_GET_MAX_BYTES_FOR_STRING):
+ * - callbacks which output more than one charset character sequence per call,
+ * like escape callbacks
+ * - initial and final non-character bytes that are output by some converters
+ * (automatic BOMs, initial escape sequence, final SI, etc.)
+ *
+ * Examples for returned values:
+ * - SBCS charsets: 1
+ * - Shift-JIS: 2
+ * - UTF-16: 2 (2 per BMP, 4 per surrogate _pair_, BOM not counted)
+ * - UTF-8: 3 (3 per BMP, 4 per surrogate _pair_)
+ * - EBCDIC_STATEFUL (EBCDIC mixed SBCS/DBCS): 3 (SO + DBCS)
+ * - ISO-2022: 3 (always outputs UTF-8)
+ * - ISO-2022-JP: 6 (4-byte escape sequences + DBCS)
+ * - ISO-2022-CN: 8 (4-byte designator sequences + 2-byte SS2/SS3 + DBCS)
+ *
+ * @param converter The Unicode converter.
+ * @return The maximum number of bytes per UChar that are output by ucnv_fromUnicode(),
+ * to be used together with UCNV_GET_MAX_BYTES_FOR_STRING for buffer allocation.
+ *
+ * @see UCNV_GET_MAX_BYTES_FOR_STRING
* @see ucnv_getMinCharSize
* @stable ICU 2.0
*/
-U_CAPI int8_t U_EXPORT2
+U_STABLE int8_t U_EXPORT2
ucnv_getMaxCharSize(const UConverter *converter);
+/**
+ * Calculates the size of a buffer for conversion from Unicode to a charset.
+ * The calculated size is guaranteed to be sufficient for this conversion.
+ *
+ * It takes into account initial and final non-character bytes that are output
+ * by some converters.
+ * It does not take into account callbacks which output more than one charset
+ * character sequence per call, like escape callbacks.
+ * The default (substitution) callback only outputs one charset character sequence.
+ *
+ * @param length Number of UChars to be converted.
+ * @param maxCharSize Return value from ucnv_getMaxCharSize() for the converter
+ * that will be used.
+ * @return Size of a buffer that will be large enough to hold the output bytes of
+ * converting length UChars with the converter that returned the maxCharSize.
+ *
+ * @see ucnv_getMaxCharSize
+ * @stable ICU 2.8
+ */
+#define UCNV_GET_MAX_BYTES_FOR_STRING(length, maxCharSize) \
+ (((int32_t)(length)+10)*(int32_t)(maxCharSize))
+
/**
* Returns the minimum byte length for characters in this codepage.
- * This is either 1 or 2 for all supported codepages.
+ * This is usually either 1 or 2.
* @param converter the Unicode converter
* @return the minimum number of bytes allowed by this particular converter
* @see ucnv_getMaxCharSize
* @stable ICU 2.0
*/
-U_CAPI int8_t U_EXPORT2
+U_STABLE int8_t U_EXPORT2
ucnv_getMinCharSize(const UConverter *converter);
/**
* @see ucnv_getName
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_getDisplayName(const UConverter *converter,
const char *displayLocale,
UChar *displayName,
* @see ucnv_getDisplayName
* @stable ICU 2.0
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getName(const UConverter *converter, UErrorCode *err);
/**
* @see ucnv_getPlatform
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_getCCSID(const UConverter *converter,
UErrorCode *err);
* @return The codepage platform
* @stable ICU 2.0
*/
-U_CAPI UConverterPlatform U_EXPORT2
+U_STABLE UConverterPlatform U_EXPORT2
ucnv_getPlatform(const UConverter *converter,
UErrorCode *err);
* @return the type of the converter
* @stable ICU 2.0
*/
-U_CAPI UConverterType U_EXPORT2
+U_STABLE UConverterType U_EXPORT2
ucnv_getType(const UConverter * converter);
/**
* @see ucnv_getType
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getStarters(const UConverter* converter,
UBool starters[256],
UErrorCode* err);
+
/**
* Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet().
* @see ucnv_getUnicodeSet
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
typedef enum UConverterUnicodeSet {
- /** Select the set of roundtrippable Unicode code points. @draft ICU 2.6 */
+ /** Select the set of roundtrippable Unicode code points. @stable ICU 2.6 */
UCNV_ROUNDTRIP_SET,
- /** Number of UConverterUnicodeSet selectors. @draft ICU 2.6 */
+ /** Number of UConverterUnicodeSet selectors. @stable ICU 2.6 */
UCNV_SET_COUNT
} UConverterUnicodeSet;
+
/**
* Returns the set of Unicode code points that can be converted by an ICU converter.
*
* sets with different properties.
*
* @param cnv The converter for which a set is requested.
- * @param set A valid USet; it will be cleared by the function before
+ * @param setFillIn A valid USet *. It will be cleared by this function before
* the converter's specific set is filled into the USet.
- * @param which A UConverterUnicodeSet selector;
+ * @param whichSet A UConverterUnicodeSet selector;
* currently UCNV_ROUNDTRIP_SET is the only supported value.
* @param pErrorCode ICU error code in/out parameter.
* Must fulfill U_SUCCESS before the function call.
* @see UConverterUnicodeSet
* @see uset_open
* @see uset_close
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getUnicodeSet(const UConverter *cnv,
- USet *set,
- UConverterUnicodeSet which,
+ USet *setFillIn,
+ UConverterUnicodeSet whichSet,
UErrorCode *pErrorCode);
/**
* @see ucnv_setToUCallBack
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getToUCallBack (const UConverter * converter,
UConverterToUCallback *action,
const void **context);
* @see ucnv_setFromUCallBack
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getFromUCallBack (const UConverter * converter,
UConverterFromUCallback *action,
const void **context);
* @see ucnv_getToUCallBack
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_setToUCallBack (UConverter * converter,
UConverterToUCallback newAction,
const void* newContext,
* @see ucnv_getFromUCallBack
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_setFromUCallBack (UConverter * converter,
UConverterFromUCallback newAction,
const void *newContext,
* consumed. At that point, the caller should reset the source and
* sourceLimit pointers to point to the next chunk.
*
+ * At the end of the stream (flush==TRUE), the input is completely consumed
+ * when *source==sourceLimit and no error code is set.
+ * The converter object is then automatically reset by this function.
+ * (This means that a converter need not be reset explicitly between data
+ * streams if it finishes the previous stream without errors.)
+ *
* This is a <I>stateful</I> conversion. Additionally, even when all source data has
* been consumed, some data may be in the converters' internal state.
* Call this function repeatedly, updating the target pointers with
* @see ucnv_setToUCallBack
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_fromUnicode (UConverter * converter,
char **target,
const char *targetLimit,
* returned, it means that all of the source buffer has been
* consumed. At that point, the caller should reset the source and
* sourceLimit pointers to point to the next chunk.
+ *
+ * At the end of the stream (flush==TRUE), the input is completely consumed
+ * when *source==sourceLimit and no error code is set
+ * The converter object is then automatically reset by this function.
+ * (This means that a converter need not be reset explicitly between data
+ * streams if it finishes the previous stream without errors.)
*
* This is a <I>stateful</I> conversion. Additionally, even when all source data has
* been consumed, some data may be in the converters' internal state.
* @see ucnv_getNextUChar
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_toUnicode(UConverter *converter,
UChar **target,
const UChar *targetLimit,
* It is only useful for whole strings, not for streaming conversion.
*
* The maximum output buffer capacity required (barring output from callbacks) will be
- * srcLength*ucnv_getMaxCharSize(cnv).
+ * UCNV_GET_MAX_BYTES_FOR_STRING(srcLength, ucnv_getMaxCharSize(cnv)).
*
* @param cnv the converter object to be used (ucnv_resetFromUnicode() will be called)
* @param src the input Unicode string
* and a buffer of the indicated length would need to be passed in
* @see ucnv_fromUnicode
* @see ucnv_convert
+ * @see UCNV_GET_MAX_BYTES_FOR_STRING
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_fromUChars(UConverter *cnv,
char *dest, int32_t destCapacity,
const UChar *src, int32_t srcLength,
* @see ucnv_convert
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_toUChars(UConverter *cnv,
UChar *dest, int32_t destCapacity,
const char *src, int32_t srcLength,
UErrorCode *pErrorCode);
/**
- * Will convert a codepage buffer into unicode one character at a time.
- * <p>This function was written to be efficient when transcoding small
- * amounts of data at a time.
- * In that case it will be more efficient than \Ref{ucnv_toUnicode}.
- * When converting large buffers use \Ref{ucnv_toUnicode}.</p>
+ * Convert a codepage buffer into Unicode one character at a time.
+ * The input is completely consumed when the U_INDEX_OUTOFBOUNDS_ERROR is set.
+ *
+ * Advantage compared to ucnv_toUnicode() or ucnv_toUChars():
+ * - Faster for small amounts of data, for most converters, e.g.,
+ * US-ASCII, ISO-8859-1, UTF-8/16/32, and most "normal" charsets.
+ * (For complex converters, e.g., SCSU, UTF-7 and ISO 2022 variants,
+ * it uses ucnv_toUnicode() internally.)
+ * - Convenient.
+ *
+ * Limitations compared to ucnv_toUnicode():
+ * - Always assumes flush=TRUE.
+ * This makes ucnv_getNextUChar() unsuitable for "streaming" conversion,
+ * that is, for where the input is supplied in multiple buffers,
+ * because ucnv_getNextUChar() will assume the end of the input at the end
+ * of the first buffer.
+ * - Does not provide offset output.
+ *
+ * It is possible to "mix" ucnv_getNextUChar() and ucnv_toUnicode() because
+ * ucnv_getNextUChar() uses the current state of the converter
+ * (unlike ucnv_toUChars() which always resets first).
+ * However, if ucnv_getNextUChar() is called after ucnv_toUnicode()
+ * stopped in the middle of a character sequence (with flush=FALSE),
+ * then ucnv_getNextUChar() will always use the slower ucnv_toUnicode()
+ * internally until the next character boundary.
+ * (This is new in ICU 2.6. In earlier releases, ucnv_getNextUChar() had to
+ * start at a character boundary.)
+ *
+ * Instead of using ucnv_getNextUChar(), it is recommended
+ * to convert using ucnv_toUnicode() or ucnv_toUChars()
+ * and then iterate over the text using U16_NEXT() or a UCharIterator (uiter.h)
+ * or a C++ CharacterIterator or similar.
+ * This allows streaming conversion and offset output, for example.
*
* <p>Handling of surrogate pairs and supplementary-plane code points:<br>
* There are two different kinds of codepages that provide mappings for surrogate characters:
* @see ucnv_convert
* @stable ICU 2.0
*/
-U_CAPI UChar32 U_EXPORT2
+U_STABLE UChar32 U_EXPORT2
ucnv_getNextUChar(UConverter * converter,
const char **source,
const char * sourceLimit,
* Internally, two conversions - ucnv_toUnicode() and ucnv_fromUnicode() -
* are used, "pivoting" through 16-bit Unicode.
*
+ * Important: For streaming conversion (multiple function calls for successive
+ * parts of a text stream), the caller must provide a pivot buffer explicitly,
+ * and must preserve the pivot buffer and associated pointers from one
+ * call to another. (The buffer may be moved if its contents and the relative
+ * pointer positions are preserved.)
+ *
* There is a similar function, ucnv_convert(),
* which has the following limitations:
* - it takes charset names, not converter objects, so that
*
* By contrast, ucnv_convertEx()
* - takes UConverter parameters instead of charset names
- * - fully exposes the pivot buffer for complete error handling
+ * - fully exposes the pivot buffer for streaming conversion and complete error handling
*
* ucnv_convertEx() also provides further convenience:
* - an option to reset the converters at the beginning
* or set U_STRING_NOT_TERMINATED_WARNING if the output exactly fills
* the target buffer
* - the pivot buffer can be provided internally;
+ * possible only for whole-string conversion, not streaming conversion;
* in this case, the caller will not be able to get details about where an
* error occurred
* (if pivotStart==NULL, see below)
* @see ucnv_toUnicode
* @see ucnv_fromUChars
* @see ucnv_toUChars
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_convertEx(UConverter *targetCnv, UConverter *sourceCnv,
char **target, const char *targetLimit,
const char **source, const char *sourceLimit,
* @see ucnv_getNextUChar
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_convert(const char *toConverterName,
const char *fromConverterName,
char *target,
* @see ucnv_toUnicode
* @see ucnv_fromUChars
* @see ucnv_toUChars
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_toAlgorithmic(UConverterType algorithmicType,
UConverter *cnv,
char *target, int32_t targetCapacity,
* @see ucnv_toUnicode
* @see ucnv_fromUChars
* @see ucnv_toUChars
- * @draft ICU 2.6
+ * @stable ICU 2.6
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_fromAlgorithmic(UConverter *cnv,
UConverterType algorithmicType,
char *target, int32_t targetCapacity,
* @see ucnv_close
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_flushCache(void);
/**
* @see ucnv_getAvailableName
* @stable ICU 2.0
*/
-U_CAPI int32_t U_EXPORT2
+U_STABLE int32_t U_EXPORT2
ucnv_countAvailable(void);
/**
* @see ucnv_countAvailable
* @stable ICU 2.0
*/
-U_CAPI const char* U_EXPORT2
+U_STABLE const char* U_EXPORT2
ucnv_getAvailableName(int32_t n);
/**
* @see ucnv_getAvailableName
* @see uenum_close
* @see uenum_next
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
-U_CAPI UEnumeration * U_EXPORT2
+U_STABLE UEnumeration * U_EXPORT2
ucnv_openAllNames(UErrorCode *pErrorCode);
/**
* @return number of names on alias list for given alias
* @stable ICU 2.0
*/
-U_CAPI uint16_t U_EXPORT2
+U_STABLE uint16_t U_EXPORT2
ucnv_countAliases(const char *alias, UErrorCode *pErrorCode);
/**
* @see ucnv_countAliases
* @stable ICU 2.0
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getAlias(const char *alias, uint16_t n, UErrorCode *pErrorCode);
/**
* @param pErrorCode result of operation
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_getAliases(const char *alias, const char **aliases, UErrorCode *pErrorCode);
/**
* @see ucnv_getStandardName
* @see uenum_close
* @see uenum_next
- * @draft ICU 2.2
+ * @stable ICU 2.2
*/
-U_CAPI UEnumeration * U_EXPORT2
+U_STABLE UEnumeration * U_EXPORT2
ucnv_openStandardNames(const char *convName,
const char *standard,
UErrorCode *pErrorCode);
* @return number of standards
* @stable ICU 2.0
*/
-U_CAPI uint16_t U_EXPORT2
+U_STABLE uint16_t U_EXPORT2
ucnv_countStandards(void);
/**
* @return returns the name of the standard at given index. Owned by the library.
* @stable ICU 2.0
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getStandard(uint16_t n, UErrorCode *pErrorCode);
/**
* then <code>NULL</code> is returned. Owned by the library.
* @stable ICU 2.0
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getStandardName(const char *name, const char *standard, UErrorCode *pErrorCode);
/**
* then <code>NULL</code> is returned. The returned string is
* owned by the library.
* @see ucnv_getStandardName
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getCanonicalName(const char *alias, const char *standard, UErrorCode *pErrorCode);
/**
* @see ucnv_setDefaultName
* @stable ICU 2.0
*/
-U_CAPI const char * U_EXPORT2
+U_STABLE const char * U_EXPORT2
ucnv_getDefaultName(void);
/**
- * sets the current default converter name. Caller must own the storage for 'name'
- * and preserve it indefinitely.
+ * This function sets the current default converter name.
+ * DO NOT call this function from multiple threads! This function is not
+ * thread safe. If this function needs to be called, it should be called
+ * during application initialization. Most of the time, the results from
+ * ucnv_getDefaultName() is sufficient for your application.
* @param name the converter name to be the default (must exist).
* @see ucnv_getDefaultName
- * @system SYSTEM API
+ * @system
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_setDefaultName(const char *name);
/**
* @see ucnv_isAmbiguous
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_fixFileSeparator(const UConverter *cnv, UChar *source, int32_t sourceLen);
/**
* character, FALSE otherwise.
* @stable ICU 2.0
*/
-U_CAPI UBool U_EXPORT2
+U_STABLE UBool U_EXPORT2
ucnv_isAmbiguous(const UConverter *cnv);
/**
* mapping, FALSE otherwise.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
ucnv_setFallback(UConverter *cnv, UBool usesFallback);
/**
* @return TRUE if the converter uses fallback, FALSE otherwise.
* @stable ICU 2.0
*/
-U_CAPI UBool U_EXPORT2
+U_STABLE UBool U_EXPORT2
ucnv_usesFallback(const UConverter *cnv);
/**
* UErrorCode err = U_ZERO_ERROR;
* char input[] = { '\xEF','\xBB', '\xBF','\x41','\x42','\x43' };
* int32_t signatureLength = 0;
- * char *encoding = ucnv_detectUnicodeSignatures(input,sizeof(input),&signatureLength,&err);
+ * char *encoding = ucnv_detectUnicodeSignature(input,sizeof(input),&signatureLength,&err);
* UConverter *conv = NULL;
* UChar output[100];
* UChar *target = output, *out;
* @param signatureLength A pointer to int32_t to receive the number of bytes that make up the signature
* of the detected UTF. 0 if not detected.
* Can be a NULL pointer.
- * @param pErrorCode A pointer to receive information about any errors that may occur during detection.
- * Must be a valid pointer to an error code value, which must not indicate a failure
- * before the function call.
+ * @param pErrorCode ICU error code in/out parameter.
+ * Must fulfill U_SUCCESS before the function call.
* @return The name of the encoding detected. NULL if encoding is not detected.
* @stable ICU 2.4
*/
-U_CAPI const char* U_EXPORT2
+U_STABLE const char* U_EXPORT2
ucnv_detectUnicodeSignature(const char* source,
int32_t sourceLength,
int32_t *signatureLength,
UErrorCode *pErrorCode);
+/**
+ * Returns the number of UChars held in the converter's internal state
+ * because more input is needed for completing the conversion. This function is
+ * useful for mapping semantics of ICU's converter interface to those of iconv,
+ * and this information is not needed for normal conversion.
+ * @param cnv The converter in which the input is held
+ * @param status ICU error code in/out parameter.
+ * Must fulfill U_SUCCESS before the function call.
+ * @return The number of UChars in the state. -1 if an error is encountered.
+ * @draft ICU 3.4
+ */
+U_DRAFT int32_t U_EXPORT2
+ucnv_fromUCountPending(const UConverter* cnv, UErrorCode* status);
+
+/**
+ * Returns the number of chars held in the converter's internal state
+ * because more input is needed for completing the conversion. This function is
+ * useful for mapping semantics of ICU's converter interface to those of iconv,
+ * and this information is not needed for normal conversion.
+ * @param cnv The converter in which the input is held as internal state
+ * @param status ICU error code in/out parameter.
+ * Must fulfill U_SUCCESS before the function call.
+ * @return The number of chars in the state. -1 if an error is encountered.
+ * @draft ICU 3.4
+ */
+U_DRAFT int32_t U_EXPORT2
+ucnv_toUCountPending(const UConverter* cnv, UErrorCode* status);
+
#endif
-/*_UCNV*/
+#endif
+/*_UCNV*/
projects / apple / icu.git / blobdiff