#include "unicode/ucnv_err.h"
#include "unicode/uenum.h"
Go to the source code of this file.
Defines | |
#define | UCNV_MAX_CONVERTER_NAME_LENGTH 60 |
Maximum length of a converter name including the terminating NULL. | |
#define | UCNV_MAX_FULL_FILE_NAME_LENGTH (600+UCNV_MAX_CONVERTER_NAME_LENGTH) |
Maximum length of a converter name including path and terminating NULL. | |
#define | UCNV_SI 0x0F |
Shift in for EBDCDIC_STATEFUL and iso2022 states. | |
#define | UCNV_SO 0x0E |
Shift out for EBDCDIC_STATEFUL and iso2022 states. | |
#define | UCNV_OPTION_SEP_CHAR ',' |
Character that separates converter names from options and options from each other. | |
#define | UCNV_OPTION_SEP_STRING "," |
String version of UCNV_OPTION_SEP_CHAR. | |
#define | UCNV_VALUE_SEP_CHAR '=' |
Character that separates a converter option from its value. | |
#define | UCNV_VALUE_SEP_STRING "=" |
String version of UCNV_VALUE_SEP_CHAR. | |
#define | UCNV_LOCALE_OPTION_STRING ",locale=" |
Converter option for specifying a locale. | |
#define | UCNV_VERSION_OPTION_STRING ",version=" |
Converter option for specifying a version selector (0. | |
#define | UCNV_SWAP_LFNL_OPTION_STRING ",swaplfnl" |
Converter option for EBCDIC SBCS or mixed-SBCS/DBCS (stateful) codepages. | |
#define | U_CNV_SAFECLONE_BUFFERSIZE 1024 |
Definition of a buffer size that is designed to be large enough for converters to be cloned with ucnv_safeClone(). | |
#define | UCNV_GET_MAX_BYTES_FOR_STRING(length, maxCharSize) (((int32_t)(length)+10)*(int32_t)(maxCharSize)) |
Calculates the size of a buffer for conversion from Unicode to a charset. | |
Typedefs | |
typedef USet | USet |
typedef UConverterToUnicodeArgs * | args |
typedef UConverterToUnicodeArgs const char * | codeUnits |
typedef UConverterToUnicodeArgs const char int32_t | length |
typedef UConverterToUnicodeArgs const char int32_t UConverterCallbackReason | reason |
typedef UConverterToUnicodeArgs const char int32_t UConverterCallbackReason UErrorCode * | pErrorCode |
typedef UConverterFromUnicodeArgs const UChar int32_t UChar32 | codePoint |
typedef enum UConverterUnicodeSet | UConverterUnicodeSet |
Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet(). | |
Enumerations | |
enum | UConverterType { UCNV_UNSUPPORTED_CONVERTER = -1, UCNV_SBCS = 0, UCNV_DBCS = 1, UCNV_MBCS = 2, UCNV_LATIN_1 = 3, UCNV_UTF8 = 4, UCNV_UTF16_BigEndian = 5, UCNV_UTF16_LittleEndian = 6, UCNV_UTF32_BigEndian = 7, UCNV_UTF32_LittleEndian = 8, UCNV_EBCDIC_STATEFUL = 9, UCNV_ISO_2022 = 10, UCNV_LMBCS_1 = 11, UCNV_LMBCS_2, UCNV_LMBCS_3, UCNV_LMBCS_4, UCNV_LMBCS_5, UCNV_LMBCS_6, UCNV_LMBCS_8, UCNV_LMBCS_11, UCNV_LMBCS_16, UCNV_LMBCS_17, UCNV_LMBCS_18, UCNV_LMBCS_19, UCNV_LMBCS_LAST = UCNV_LMBCS_19, UCNV_HZ, UCNV_SCSU, UCNV_ISCII, UCNV_US_ASCII, UCNV_UTF7, UCNV_BOCU1, UCNV_UTF16, UCNV_UTF32, UCNV_CESU8, UCNV_IMAP_MAILBOX, UCNV_NUMBER_OF_SUPPORTED_CONVERTER_TYPES } |
Enum for specifying basic types of converters. More... | |
enum | UConverterPlatform { UCNV_UNKNOWN = -1, UCNV_IBM = 0 } |
Enum for specifying which platform a converter ID refers to. More... | |
enum | UConverterUnicodeSet { UCNV_ROUNDTRIP_SET, UCNV_SET_COUNT } |
Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet(). More... | |
Functions | |
typedef | void (1 *UConverterToUCallback)(const void *context |
Function pointer for error callback in the codepage to unicode direction. | |
int | ucnv_compareNames (const char *name1, const char *name2) |
Do a fuzzy compare of two converter/alias names. | |
UConverter * | ucnv_open (const char *converterName, UErrorCode *err) |
Creates a UConverter object with the name of a coded character set specified as a C string. | |
UConverter * | ucnv_openU (const UChar *name, UErrorCode *err) |
Creates a Unicode converter with the names specified as unicode string. | |
UConverter * | ucnv_openCCSID (int32_t codepage, UConverterPlatform platform, UErrorCode *err) |
Creates a UConverter object from a CCSID number and platform pair. | |
UConverter * | ucnv_openPackage (const char *packageName, const char *converterName, UErrorCode *err) |
UConverter * | ucnv_safeClone (const UConverter *cnv, void *stackBuffer, int32_t *pBufferSize, UErrorCode *status) |
Thread safe converter cloning operation. | |
void | ucnv_close (UConverter *converter) |
Deletes the unicode converter and releases resources associated with just this instance. | |
void | ucnv_getSubstChars (const UConverter *converter, char *subChars, int8_t *len, UErrorCode *err) |
Fills in the output parameter, subChars, with the substitution characters as multiple bytes. | |
void | ucnv_setSubstChars (UConverter *converter, const char *subChars, int8_t len, UErrorCode *err) |
Sets the substitution chars when converting from unicode to a codepage. | |
void | ucnv_setSubstString (UConverter *cnv, const UChar *s, int32_t length, UErrorCode *err) |
Set a substitution string for converting from Unicode to a charset. | |
void | ucnv_getInvalidChars (const UConverter *converter, char *errBytes, int8_t *len, UErrorCode *err) |
Fills in the output parameter, errBytes, with the error characters from the last failing conversion. | |
void | ucnv_getInvalidUChars (const UConverter *converter, UChar *errUChars, int8_t *len, UErrorCode *err) |
Fills in the output parameter, errChars, with the error characters from the last failing conversion. | |
void | ucnv_reset (UConverter *converter) |
Resets the state of a converter to the default state. | |
void | ucnv_resetToUnicode (UConverter *converter) |
Resets the to-Unicode part of a converter state to the default state. | |
void | ucnv_resetFromUnicode (UConverter *converter) |
Resets the from-Unicode part of a converter state to the default state. | |
int8_t | ucnv_getMaxCharSize (const UConverter *converter) |
Returns the maximum number of bytes that are output per UChar in conversion from Unicode using this converter. | |
int8_t | ucnv_getMinCharSize (const UConverter *converter) |
Returns the minimum byte length for characters in this codepage. | |
int32_t | ucnv_getDisplayName (const UConverter *converter, const char *displayLocale, UChar *displayName, int32_t displayNameCapacity, UErrorCode *err) |
Returns the display name of the converter passed in based on the Locale passed in. | |
const char * | ucnv_getName (const UConverter *converter, UErrorCode *err) |
Gets the internal, canonical name of the converter (zero-terminated). | |
int32_t | ucnv_getCCSID (const UConverter *converter, UErrorCode *err) |
Gets a codepage number associated with the converter. | |
UConverterPlatform | ucnv_getPlatform (const UConverter *converter, UErrorCode *err) |
Gets a codepage platform associated with the converter. | |
UConverterType | ucnv_getType (const UConverter *converter) |
Gets the type of the converter e.g. | |
void | ucnv_getStarters (const UConverter *converter, UBool starters[256], UErrorCode *err) |
Gets the "starter" (lead) bytes for converters of type MBCS. | |
void | ucnv_getUnicodeSet (const UConverter *cnv, USet *setFillIn, UConverterUnicodeSet whichSet, UErrorCode *pErrorCode) |
Returns the set of Unicode code points that can be converted by an ICU converter. | |
void | ucnv_getToUCallBack (const UConverter *converter, UConverterToUCallback *action, const void **context) |
Gets the current calback function used by the converter when an illegal or invalid codepage sequence is found. | |
void | ucnv_getFromUCallBack (const UConverter *converter, UConverterFromUCallback *action, const void **context) |
Gets the current callback function used by the converter when illegal or invalid Unicode sequence is found. | |
void | ucnv_setToUCallBack (UConverter *converter, UConverterToUCallback newAction, const void *newContext, UConverterToUCallback *oldAction, const void **oldContext, UErrorCode *err) |
Changes the callback function used by the converter when an illegal or invalid sequence is found. | |
void | ucnv_setFromUCallBack (UConverter *converter, UConverterFromUCallback newAction, const void *newContext, UConverterFromUCallback *oldAction, const void **oldContext, UErrorCode *err) |
Changes the current callback function used by the converter when an illegal or invalid sequence is found. | |
void | ucnv_fromUnicode (UConverter *converter, char **target, const char *targetLimit, const UChar **source, const UChar *sourceLimit, int32_t *offsets, UBool flush, UErrorCode *err) |
Converts an array of unicode characters to an array of codepage characters. | |
void | ucnv_toUnicode (UConverter *converter, UChar **target, const UChar *targetLimit, const char **source, const char *sourceLimit, int32_t *offsets, UBool flush, UErrorCode *err) |
Converts a buffer of codepage bytes into an array of unicode UChars characters. | |
int32_t | ucnv_fromUChars (UConverter *cnv, char *dest, int32_t destCapacity, const UChar *src, int32_t srcLength, UErrorCode *pErrorCode) |
Convert the Unicode string into a codepage string using an existing UConverter. | |
int32_t | ucnv_toUChars (UConverter *cnv, UChar *dest, int32_t destCapacity, const char *src, int32_t srcLength, UErrorCode *pErrorCode) |
Convert the codepage string into a Unicode string using an existing UConverter. | |
UChar32 | ucnv_getNextUChar (UConverter *converter, const char **source, const char *sourceLimit, UErrorCode *err) |
Convert a codepage buffer into Unicode one character at a time. | |
void | 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 using two existing UConverters. | |
int32_t | 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. | |
int32_t | 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. | |
int32_t | ucnv_fromAlgorithmic (UConverter *cnv, UConverterType algorithmicType, char *target, int32_t targetCapacity, const char *source, int32_t sourceLength, UErrorCode *pErrorCode) |
Convert from one external charset to another. | |
int32_t | ucnv_flushCache (void) |
Frees up memory occupied by unused, cached converter shared data. | |
int32_t | ucnv_countAvailable (void) |
Returns the number of available converters, as per the alias file. | |
const char * | ucnv_getAvailableName (int32_t n) |
Gets the canonical converter name of the specified converter from a list of all available converters contaied in the alias file. | |
UEnumeration * | ucnv_openAllNames (UErrorCode *pErrorCode) |
Returns a UEnumeration to enumerate all of the canonical converter names, as per the alias file, regardless of the ability to open each converter. | |
uint16_t | ucnv_countAliases (const char *alias, UErrorCode *pErrorCode) |
Gives the number of aliases for a given converter or alias name. | |
const char * | ucnv_getAlias (const char *alias, uint16_t n, UErrorCode *pErrorCode) |
Gives the name of the alias at given index of alias list. | |
void | ucnv_getAliases (const char *alias, const char **aliases, UErrorCode *pErrorCode) |
Fill-up the list of alias names for the given alias. | |
UEnumeration * | ucnv_openStandardNames (const char *convName, const char *standard, UErrorCode *pErrorCode) |
Return a new UEnumeration object for enumerating all the alias names for a given converter that are recognized by a standard. | |
uint16_t | ucnv_countStandards (void) |
Gives the number of standards associated to converter names. | |
const char * | ucnv_getStandard (uint16_t n, UErrorCode *pErrorCode) |
Gives the name of the standard at given index of standard list. | |
const char * | ucnv_getStandardName (const char *name, const char *standard, UErrorCode *pErrorCode) |
Returns a standard name for a given converter name. | |
const char * | ucnv_getCanonicalName (const char *alias, const char *standard, UErrorCode *pErrorCode) |
This function will return the internal canonical converter name of the tagged alias. | |
const char * | ucnv_getDefaultName (void) |
returns the current default converter name. | |
void | ucnv_setDefaultName (const char *name) |
This function sets the current default converter name. | |
void | ucnv_fixFileSeparator (const UConverter *cnv, UChar *source, int32_t sourceLen) |
Fixes the backslash character mismapping. | |
UBool | ucnv_isAmbiguous (const UConverter *cnv) |
Determines if the converter contains ambiguous mappings of the same character or not. | |
void | ucnv_setFallback (UConverter *cnv, UBool usesFallback) |
Sets the converter to use fallback mapping or not. | |
UBool | ucnv_usesFallback (const UConverter *cnv) |
Determines if the converter uses fallback mappings or not. | |
const char * | ucnv_detectUnicodeSignature (const char *source, int32_t sourceLength, int32_t *signatureLength, UErrorCode *pErrorCode) |
Detects Unicode signature byte sequences at the start of the byte stream and returns the charset name of the indicated Unicode charset. | |
int32_t | ucnv_fromUCountPending (const UConverter *cnv, UErrorCode *status) |
Returns the number of UChars held in the converter's internal state because more input is needed for completing the conversion. | |
int32_t | ucnv_toUCountPending (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 API is used to convert codepage or character encoded data to and from UTF-16. You can open a converter with ucnv_open(). With that converter, you can get its properties, set options, convert your data and close the converter.
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 ucnv_getAvailableName(), ucnv_getAlias() and ucnv_getStandardName() are some of the more frequently used alias functions to get this information.
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 ucnv_setFromUCallBack() or ucnv_setToUCallBack() on the converter. The header ucnv_err.h defines many other callback actions that can be used instead of a character substitution.
More information about this API can be found in our User's Guide.
Definition in file ucnv.h.
|
Definition of a buffer size that is designed to be large enough for converters to be cloned with ucnv_safeClone().
|
|
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.
|
|
Converter option for specifying a locale. For example, ucnv_open("SCSU,locale=ja", &errorCode); See convrtrs.txt.
|
|
Maximum length of a converter name including the terminating NULL.
|
|
Maximum length of a converter name including path and terminating NULL.
|
|
Character that separates converter names from options and options from each other.
|
|
String version of UCNV_OPTION_SEP_CHAR.
|
|
Shift in for EBDCDIC_STATEFUL and iso2022 states.
|
|
Shift out for EBDCDIC_STATEFUL and iso2022 states.
|
|
Converter option for EBCDIC SBCS or mixed-SBCS/DBCS (stateful) codepages. Swaps Unicode mappings for EBCDIC LF and NL codes, as used on S/390 (z/OS) Unix System Services (Open Edition). For example, ucnv_open("ibm-1047,swaplfnl", &errorCode); See convrtrs.txt.
|
|
Character that separates a converter option from its value.
|
|
String version of UCNV_VALUE_SEP_CHAR.
|
|
Converter option for specifying a version selector (0. .9) for some converters. For example, ucnv_open("UTF-7,version=1", &errorCode); See convrtrs.txt.
|
|
Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet().
|
|
|
|
Enum for specifying which platform a converter ID refers to. The use of platform/CCSID is not recommended. See ucnv_openCCSID().
|
|
Enum for specifying basic types of converters.
|
|
Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet().
|
|
Deletes the unicode converter and releases resources associated with just this instance. Does not free up shared converter tables.
|
|
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/
|
|
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()
The function returns when one of the following is true:
|
|
Convert from one external charset to another using two existing UConverters. 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:
By contrast, ucnv_convertEx()
ucnv_convertEx() also provides further convenience:
The function returns when one of the following is true:
Limitation compared to the direct use of ucnv_fromUnicode() and ucnv_toUnicode(): ucnv_convertEx() does not provide offset information. Limitation compared to ucnv_fromUChars() and ucnv_toUChars(): ucnv_convertEx() does not support preflighting directly. Sample code for converting a single string from one external charset to UTF-8, ignoring the location of errors:
int32_t myToUTF8(UConverter *cnv, const char *s, int32_t length, char *u8, int32_t capacity, UErrorCode *pErrorCode) { UConverter *utf8Cnv; char *target; if(U_FAILURE(*pErrorCode)) { return 0; } 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); }
|
|
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.
|
|
Returns the number of available converters, as per the alias file.
|
|
Gives the number of standards associated to converter names.
|
|
Detects Unicode signature byte sequences at the start of the byte stream and returns the charset name of the indicated Unicode charset. NULL is returned when no Unicode signature is recognized. The number of bytes in the signature is output as well. The caller can ucnv_open() a converter using the charset name. The first code unit (UChar) from the start of the stream will be U+FEFF (the Unicode BOM/signature character) and can usually be ignored. For most Unicode charsets it is also possible to ignore the indicated number of initial stream bytes and start converting after them. However, there are stateful Unicode charsets (UTF-7 and BOCU-1) for which this will not work. Therefore, it is best to ignore the first output UChar instead of the input signature bytes. Usage: UErrorCode err = U_ZERO_ERROR; char input[] = { '\xEF','\xBB', '\xBF','\x41','\x42','\x43' }; int32_t signatureLength = 0; char *encoding = ucnv_detectUnicodeSignature(input,sizeof(input),&signatureLength,&err); UConverter *conv = NULL; UChar output[100]; UChar *target = output, *out; char *source = input; if(encoding!=NULL && U_SUCCESS(err)){ // should signature be discarded ? conv = ucnv_open(encoding, &err); // do the conversion ucnv_toUnicode(conv, target, output + sizeof(output)/U_SIZEOF_UCHAR, source, input + sizeof(input), NULL, TRUE, &err); out = output; if (discardSignature){ ++out; // ignore initial U+FEFF } while(out != target) { printf("%04x ", *out++); } puts(""); }
|
|
Fixes the backslash character mismapping. For example, in SJIS, the backslash character in the ASCII portion is also used to represent the yen currency sign. When mapping from Unicode character 0x005C, it's unclear whether to map the character back to yen or backslash in SJIS. This function will take the input buffer and replace all the yen sign characters with backslash. This is necessary when the user tries to open a file with the input buffer on Windows. This function will test the converter to see whether such mapping is required. You can sometimes avoid using this function by using the correct version of Shift-JIS.
|
|
Frees up memory occupied by unused, cached converter shared data.
|
|
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.
|
|
Convert the Unicode string into a codepage string using an existing UConverter. The output string is NUL-terminated if possible. This function is a more convenient but less powerful version of ucnv_fromUnicode(). It is only useful for whole strings, not for streaming conversion. The maximum output buffer capacity required (barring output from callbacks) will be UCNV_GET_MAX_BYTES_FOR_STRING(srcLength, ucnv_getMaxCharSize(cnv)).
|
|
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.
|
|
Converts an array of unicode characters to an array of codepage characters. This function is optimized for converting a continuous stream of data in buffer-sized chunks, where the entire source and target does not fit in available buffers. The source pointer is an in/out parameter. It starts out pointing where the conversion is to begin, and ends up pointing after the last UChar consumed. Target similarly starts out pointer at the first available byte in the output buffer, and ends up pointing after the last byte written to the output. The converter always attempts to consume the entire source buffer, unless (1.) the target buffer is full, or (2.) a failing error is returned from the current callback function. When a successful error status has been 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 stateful 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 the next empty chunk of target in case of a
|
|
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.
|
|
Fill-up the list of alias names for the given alias. 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.
|
|
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.
|
|
This function will return the internal canonical converter name of the tagged alias. This is the opposite of ucnv_openStandardNames, which returns the tagged alias given the canonical name.
Example alias table:
Result of ucnv_getStandardName("alias1", "STANDARD1") from example alias table:
|
|
Gets a codepage number associated with the converter.
This is not guaranteed to be the one used to create the converter. Some converters do not represent platform registered codepages and return zero for the codepage number. The error code fill-in parameter indicates if the codepage number is available. Does not check if the converter is Important: The use of CCSIDs is not recommended because it is limited to only two platforms in principle and only one (UCNV_IBM) in the current ICU converter API. Also, CCSIDs are insufficient to identify IBM Unicode conversion tables precisely. For more details see ucnv_openCCSID().
|
|
returns the current default converter name.
|
|
Returns the display name of the converter passed in based on the Locale passed in. If the locale contains no display name, the internal ASCII name will be filled in.
|
|
Gets the current callback function used by the converter when illegal or invalid Unicode sequence is found. Context pointers are always owned by the caller.
|
|
Fills in the output parameter, errBytes, with the error characters from the last failing conversion.
|
|
Fills in the output parameter, errChars, with the error characters from the last failing conversion.
|
|
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:
The number returned here does not take into account (see UCNV_GET_MAX_BYTES_FOR_STRING):
Examples for returned values:
|
|
Returns the minimum byte length for characters in this codepage. This is usually either 1 or 2.
|
|
Gets the internal, canonical name of the converter (zero-terminated). The lifetime of the returned string will be that of the converter passed to this function.
|
|
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():
Limitations compared to ucnv_toUnicode():
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.
Handling of surrogate pairs and supplementary-plane code points:
|
|
Gets a codepage platform associated with the converter.
Currently, only
|
|
Gives the name of the standard at given index of standard list.
|
|
Returns a standard name for a given converter name.
Example alias table:
Result of ucnv_getStandardName("conv", "STANDARD1") from example alias table:
|
|
Gets the "starter" (lead) bytes for converters of type MBCS.
Will fill in an
|
|
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.
|
|
Gets the current calback function used by the converter when an illegal or invalid codepage sequence is found. Context pointers are always owned by the caller.
|
|
Gets the type of the converter e.g. SBCS, MBCS, DBCS, UTF8, UTF16_BE, UTF16_LE, ISO_2022, EBCDIC_STATEFUL, LATIN_1
|
|
Returns the set of Unicode code points that can be converted by an ICU converter. The current implementation returns only one kind of set (UCNV_ROUNDTRIP_SET): The set of all Unicode code points that can be roundtrip-converted (converted without any data loss) with the converter. This set will not include code points that have fallback mappings or are only the result of reverse fallback mappings. See UTR #22 "Character Mapping Markup Language" at http://www.unicode.org/reports/tr22/ This is useful for example for
In the future, there may be more UConverterUnicodeSet choices to select sets with different properties.
|
|
Determines if the converter contains ambiguous mappings of the same character or not.
|
|
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 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 A converter name for ICU 1.5 and above may contain options like a locale specification to control the specific behavior of the newly instantiated converter. The meaning of the options depends on the particular converter. If an option is not defined for or recognized by a given converter, then it is ignored.
Options are appended to the converter name string, with a If the alias is ambiguous, then the preferred converter is used and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 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 User's Guide. 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.
|
|
Returns a UEnumeration to enumerate all of the canonical converter names, as per the alias file, regardless of the ability to open each converter.
|
|
Creates a UConverter object from a CCSID number and platform pair. Note that the usefulness of this function is limited to platforms with numeric encoding IDs. Only IBM and Microsoft platforms use numeric (16-bit) identifiers for encodings. In addition, IBM CCSIDs and Unicode conversion tables are not 1:1 related. For many IBM CCSIDs there are multiple (up to six) Unicode conversion tables, and for some Unicode conversion tables there are multiple CCSIDs. Some "alternate" Unicode conversion tables are provided by the IBM CDRA conversion table registry. The most prominent example of a systematic modification of conversion tables that is not provided in the form of conversion table files in the repository is that S/390 Unix System Services swaps the codes for Line Feed and New Line in all EBCDIC codepages, which requires such a swap in the Unicode conversion tables as well. Only IBM default conversion tables are accessible with ucnv_openCCSID(). ucnv_getCCSID() will return the same CCSID for all conversion tables that are associated with that CCSID. Currently, the only "platform" supported in the ICU converter API is UCNV_IBM. In summary, the use of CCSIDs and the associated API functions is not recommended. In order to open a converter with the default IBM CDRA Unicode conversion table, you can use this function or use the prefix "ibm-": char name[20]; sprintf(name, "ibm-%hu", ccsid); cnv=ucnv_open(name, &errorCode); In order to open a converter with the IBM S/390 Unix System Services variant of a Unicode/EBCDIC conversion table, you can use the prefix "ibm-" together with the option string UCNV_SWAP_LFNL_OPTION_STRING: char name[20]; sprintf(name, "ibm-%hu" UCNV_SWAP_LFNL_OPTION_STRING, ccsid); cnv=ucnv_open(name, &errorCode); In order to open a converter from a Microsoft codepage number, use the prefix "cp": char name[20]; sprintf(name, "cp%hu", codepageID); cnv=ucnv_open(name, &errorCode); If the alias is ambiguous, then the preferred converter is used and the status is set to U_AMBIGUOUS_ALIAS_WARNING.
|
|
Creates a UConverter object specified from a packageName and a converterName.
The packageName and converterName must point to an ICU udata object, as defined by 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. A future version of ICU may add alias table lookups and/or caching to this function.
Example Use:
|
|
Return a new UEnumeration object for enumerating all the alias names for a given converter that are recognized by a standard.
This method only enumerates the listed entries in the alias file. The convrtrs.txt file can be modified to change the results of this function. The first result in this list is the same result given by
|
|
Creates a Unicode converter with the names specified as unicode string.
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 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 See ucnv_open for the complete details
|
|
Resets the state of a converter to the default state. This is used in the case of an error, to restart a conversion from a known default state. It will also empty the internal output buffers.
|
|
Resets the from-Unicode part of a converter state to the default state. This is used in the case of an error to restart a conversion from Unicode to a known default state. It will also empty the internal output buffers used for the conversion from Unicode codepoints.
|
|
Resets the to-Unicode part of a converter state to the default state. This is used in the case of an error to restart a conversion to Unicode to a known default state. It will also empty the internal output buffers used for the conversion to Unicode codepoints.
|
|
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.
|
|
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.
|
|
Sets the converter to use fallback mapping or not.
|
|
Changes the current callback function used by the converter when an illegal or invalid sequence is found. Context pointers are always owned by the caller. Predefined actions and contexts can be found in the ucnv_err.h header.
|
|
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
|
|
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.
|
|
Changes the callback function used by the converter when an illegal or invalid sequence is found. Context pointers are always owned by the caller. Predefined actions and contexts can be found in the ucnv_err.h header.
|
|
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.
|
|
Convert the codepage string into a Unicode string using an existing UConverter. The output string is NUL-terminated if possible. This function is a more convenient but less powerful version of ucnv_toUnicode(). It is only useful for whole strings, not for streaming conversion. The maximum output buffer capacity required (barring output from callbacks) will be 2*srcLength (each char may be converted into a surrogate pair).
|
|
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.
|
|
Converts a buffer of codepage bytes into an array of unicode UChars characters. This function is optimized for converting a continuous stream of data in buffer-sized chunks, where the entire source and target does not fit in available buffers. The source pointer is an in/out parameter. It starts out pointing where the conversion is to begin, and ends up pointing after the last byte of source consumed. Target similarly starts out pointer at the first available UChar in the output buffer, and ends up pointing after the last UChar written to the output. It does NOT necessarily keep UChar sequences together. The converter always attempts to consume the entire source buffer, unless (1.) the target buffer is full, or (2.) a failing error is returned from the current callback function. When a successful error status has been 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 stateful 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 the next empty chunk of target in case of a
|
|
Determines if the converter uses fallback mappings or not.
|
|
Function pointer for error callback in the codepage to unicode direction. Called when an error has occured in conversion to unicode, or on open/close of the callback (see reason).
|