Main Page   Class Hierarchy   Compound List   File List   Header Files   Sources   Compound Members   File Members  

ucnv.h File Reference

Character Conversion C API. More...


Defines

#define UCNV_MAX_CONVERTER_NAME_LENGTH
#define UCNV_MAX_FULL_FILE_NAME_LENGTH
#define UCNV_SI
#define UCNV_SO
#define UCNV_OPTION_SEP_CHAR
Character that separates converter names from options and options from each other. More...

#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. More...

#define UCNV_VALUE_SEP_STRING
String version of UCNV_VALUE_SEP_CHAR.

#define UCNV_LOCALE_OPTION_STRING
Converter option for specifying a locale. More...


Typedefs

typedef struct UConverter UConverter
typedef void (* UConverterToUCallback )( void* context, UConverterToUnicodeArgs *args, const char *codePoints, int32_t length, UConverterCallbackReason reason, UErrorCode *)
typedef void (* UConverterFromUCallback )( void* context, UConverterFromUnicodeArgs *args, const UChar* codeUnits, int32_t length, UChar32 codePoint, UConverterCallbackReason reason, UErrorCode *)

Enumerations

enum  UConverterType { UCNV_UNSUPPORTED_CONVERTER, UCNV_SBCS, UCNV_DBCS, UCNV_MBCS, UCNV_LATIN_1, UCNV_UTF8, UCNV_UTF16_BigEndian, UCNV_UTF16_LittleEndian, UCNV_EBCDIC_STATEFUL, UCNV_ISO_2022, UCNV_LMBCS_1, 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_NUMBER_OF_SUPPORTED_CONVERTER_TYPES }
enum  UConverterPlatform { UCNV_UNKNOWN, UCNV_IBM }

Functions

U_CAPI UConverter* U_EXPORT2 ucnv_open (const char *converterName, UErrorCode * err)
Creates a UConverter object with the names specified as a C string. More...

U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name, UErrorCode * err)
Creates a Unicode converter with the names specified as unicode string. More...

U_CAPI UConverter* U_EXPORT2 ucnv_openCCSID (int32_t codepage, UConverterPlatform platform, UErrorCode * err)
Creates a UConverter object using a CCSID number. More...

U_CAPI void U_EXPORT2 ucnv_close (UConverter * converter)
Deletes the unicode converter. More...

U_CAPI void U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 ucnv_setSubstChars (UConverter * converter, const char *subChars, int8_t len, UErrorCode * err)
Sets the substitution chars when converting from unicode to a codepage. More...

U_CAPI void U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 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. More...

U_CAPI void U_EXPORT2 ucnv_reset (UConverter * converter)
Resets the state of stateful conversion to the default state. More...

U_CAPI int8_t U_EXPORT2 ucnv_getMaxCharSize (const UConverter * converter)
Returns the maximum length of bytes used by a character. More...

U_CAPI int8_t U_EXPORT2 ucnv_getMinCharSize (const UConverter * converter)
Returns the minimum byte length for characters in this codepage. More...

U_CAPI int32_t U_EXPORT2 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, in the case the locale contains no display name, the internal ASCII name will be filled in. More...

U_CAPI const char* U_EXPORT2 ucnv_getName (const UConverter * converter, UErrorCode * err)
Gets the name of the converter (zero-terminated). More...

U_CAPI int32_t U_EXPORT2 ucnv_getCCSID (const UConverter * converter, UErrorCode * err)
Gets a codepage number associated with the converter. More...

U_CAPI UConverterPlatform U_EXPORT2 ucnv_getPlatform (const UConverter * converter, UErrorCode * err)
Gets a codepage platform associated with the converter. More...

U_CAPI UConverterType U_EXPORT2 ucnv_getType (const UConverter * converter)
Gets the type of conversion associated with the converter e.g. More...

U_CAPI void U_EXPORT2 ucnv_getStarters (const UConverter* converter, UBool starters[256], UErrorCode* err)
Gets the "starter" bytes for the converters of type MBCS will fill in an U_ILLEGAL_ARGUMENT_ERROR if converter passed in is not MBCS. More...

U_CAPI void U_EXPORT2 ucnv_getToUCallBack (const UConverter * converter, UConverterToUCallback *action, void **context)
Gets the current calback function used by the converter when illegal or invalid sequence found. More...

U_CAPI void U_EXPORT2 ucnv_getFromUCallBack (const UConverter * converter, UConverterFromUCallback *action, void **context)
Gets the current callback function used by the converter when illegal or invalid sequence found. More...

U_CAPI void U_EXPORT2 ucnv_setToUCallBack (UConverter * converter, UConverterToUCallback newAction, void* newContext, UConverterToUCallback *oldAction, void** oldContext, UErrorCode * err)
Gets the current callback function used by the converter when illegal or invalid sequence found. More...

U_CAPI void U_EXPORT2 ucnv_setFromUCallBack (UConverter * converter, UConverterFromUCallback newAction, void *newContext, UConverterFromUCallback *oldAction, void **oldContext, UErrorCode * err)
Gets the current callback function used by the converter when illegal or invalid sequence found. More...

U_CAPI void U_EXPORT2 ucnv_fromUnicode (UConverter * converter, char **target, const char *targetLimit, const UChar ** source, const UChar * sourceLimit, int32_t* offsets, UBool flush, UErrorCode * err)
Transcodes an array of unicode characters to an array of codepage characters. More...

U_CAPI void U_EXPORT2 ucnv_toUnicode (UConverter * converter, UChar ** target, const UChar * targetLimit, const char **source, const char *sourceLimit, int32_t* offsets, UBool flush, UErrorCode * err)
Converts an array of codepage characters into an array of unicode characters. More...

U_CAPI int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter, char *target, int32_t targetCapacity, const UChar * source, int32_t sourceLength, UErrorCode * err)
Transcodes the source Unicode string to the target string in a codepage encoding with the specified Unicode converter. More...

U_CAPI int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter, UChar * target, int32_t targetCapacity, const char *source, int32_t sourceSize, UErrorCode * err)
Transcode the source string in codepage encoding to the target string in Unicode encoding. More...

U_CAPI UChar32 U_EXPORT2 ucnv_getNextUChar (UConverter * converter, const char **source, const char *sourceLimit, UErrorCode * err)
U_CAPI int32_t U_EXPORT2 ucnv_convert (const char *toConverterName, const char *fromConverterName, char *target, int32_t targetCapacity, const char *source, int32_t sourceLength, UErrorCode * err)
U_CAPI int32_t U_EXPORT2 ucnv_flushCache (void)
SYSTEM API Iterates through every cached converter and frees all the unused ones. More...

U_CAPI const char* U_EXPORT2 ucnv_getAvailableName (int32_t n)
provides a string containing the internal name (based on the alias file) of the converter. More...

U_CAPI int32_t U_EXPORT2 ucnv_countAvailable (void)
returns the number of available converters. More...

U_CAPI uint16_t ucnv_countAliases (const char *alias, UErrorCode *pErrorCode)
Gives the number of aliases for given converter or alias name. More...

U_CAPI const char* ucnv_getAlias (const char *alias, uint16_t n, UErrorCode *pErrorCode)
Gives the name of the alias at given index of alias list. More...

U_CAPI void ucnv_getAliases (const char *alias, const char **aliases, UErrorCode *pErrorCode)
Fill-up the list of alias names for the given alias. More...

U_CAPI uint16_t ucnv_countStandards (void)
Gives the number of standards associated to converter names. More...

U_CAPI const char* ucnv_getStandard (uint16_t n, UErrorCode *pErrorCode)
Gives the name of the standard at given index of standard list. More...

U_CAPI const char* ucnv_getStandardName (const char *name, const char *standard, UErrorCode *pErrorCode)
Returns a standard name for a given converter name. More...

U_CAPI const char* U_EXPORT2 ucnv_getDefaultName (void)
returns the current default converter name. More...

U_CAPI void U_EXPORT2 ucnv_setDefaultName (const char *name)
sets the current default converter name. More...

U_CAPI void U_EXPORT2 ucnv_fixFileSeparator (const UConverter *cnv, UChar* source, int32_t sourceLen)
Fixes the backslash character mismapping. More...

U_CAPI UBool U_EXPORT2 ucnv_isAmbiguous (const UConverter *cnv)
Determines if the converter contains ambiguous mappings of the same character or not. More...

U_CAPI void U_EXPORT2 ucnv_setFallback (UConverter *cnv, UBool usesFallback)
Sets the converter to use fallback mapping or not. More...

U_CAPI UBool U_EXPORT2 ucnv_usesFallback (const UConverter *cnv)
Determines if the converter uses fallback mappings or not. More...


Variables

struct UConverter


Detailed Description

Character Conversion C API.

Character Conversion C API documentation is still under construction. Please check for updates soon.

Definition in file ucnv.h.


Define Documentation

#define UCNV_MAX_CONVERTER_NAME_LENGTH ()

Definition at line 38 of file ucnv.h.

#define UCNV_MAX_FULL_FILE_NAME_LENGTH ()

Definition at line 39 of file ucnv.h.

#define UCNV_SI ()

Definition at line 41 of file ucnv.h.

#define UCNV_SO ()

Definition at line 42 of file ucnv.h.

#define UCNV_OPTION_SEP_CHAR ()

Character that separates converter names from options and options from each other.

See also:
ucnv_open()

Definition at line 103 of file ucnv.h.

#define UCNV_OPTION_SEP_STRING ()

String version of UCNV_OPTION_SEP_CHAR.

Definition at line 106 of file ucnv.h.

#define UCNV_VALUE_SEP_CHAR ()

Character that separates a converter option from its value.

See also:
ucnv_open()

Definition at line 112 of file ucnv.h.

#define UCNV_VALUE_SEP_STRING ()

String version of UCNV_VALUE_SEP_CHAR.

Definition at line 115 of file ucnv.h.

#define UCNV_LOCALE_OPTION_STRING ()

Converter option for specifying a locale.

See also:
ucnv_open()

Definition at line 121 of file ucnv.h.


Typedef Documentation

typedef struct UConverter UConverter

Definition at line 30 of file ucnv.h.

typedef void (* UConverterToUCallback)( void* context, UConverterToUnicodeArgs *args, const char *codePoints, int32_t length, UConverterCallbackReason reason, UErrorCode *)

Definition at line 80 of file ucnv.h.

typedef void (* UConverterFromUCallback)( void* context, UConverterFromUnicodeArgs *args, const UChar* codeUnits, int32_t length, UChar32 codePoint, UConverterCallbackReason reason, UErrorCode *)

Definition at line 88 of file ucnv.h.


Enumeration Type Documentation

enum UConverterType

Enumeration values:
UCNV_UNSUPPORTED_CONVERTER  
UCNV_SBCS  
UCNV_DBCS  
UCNV_MBCS  
UCNV_LATIN_1  
UCNV_UTF8  
UCNV_UTF16_BigEndian  
UCNV_UTF16_LittleEndian  
UCNV_EBCDIC_STATEFUL  
UCNV_ISO_2022  
UCNV_LMBCS_1  
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_NUMBER_OF_SUPPORTED_CONVERTER_TYPES  

Definition at line 44 of file ucnv.h.

enum UConverterPlatform

Enumeration values:
UCNV_UNKNOWN  
UCNV_IBM  

Definition at line 75 of file ucnv.h.


Function Documentation

U_CAPI UConverter *U_EXPORT2 ucnv_open (const char * converterName, UErrorCode * err)

Creates a UConverter object with the names 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. If NULL is passed for the converter name, it will create one with the getDefaultName return value.

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 UCNV_OPTION_SEP_CHAR between the name and the first option and also between adjacent options.

Parameters:
converterName   : name of the uconv table, may have options appended
err   outgoing error status U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND
Returns:
the created Unicode converter object, or NULL if an error occured
See also:
ucnv_openU() , ucnv_openCCSID() , ucnv_close()
Stable:

U_CAPI UConverter *U_EXPORT2 ucnv_openU (const UChar * name, UErrorCode * err)

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 the delimiters '-', '_', and ' ' (dash, underscore, and space). E.g., the names "UTF8", "utf-8", and "Utf 8" are all equivalent. If NULL is passed for the converter name, it will create one with the getDefaultName return value.

Parameters:
converterName   : name of the uconv table in a zero terminated Unicode string
err   outgoing error status U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND
Returns:
the created Unicode converter object, or NULL if an error occured
See also:
ucnv_open() , ucnv_openCCSID() , ucnv_close()
Stable:

U_CAPI UConverter *U_EXPORT2 ucnv_openCCSID (int32_t codepage, UConverterPlatform platform, UErrorCode * err)

Creates a UConverter object using a CCSID number.

Parameters:
codepage   : codepage # of the uconv table
platform   : codepage's platform (now only IBM supported)
err   error status U_MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND
Returns:
the created Unicode converter object, or NULL if and error occured
See also:
ucnv_open() , ucnv_openU() , ucnv_close()
Stable:

U_CAPI void U_EXPORT2 ucnv_close (UConverter * converter)

Deletes the unicode converter.

Parameters:
converter   the converter object to be deleted
See also:
ucnv_open() , ucnv_openU() , ucnv_openCCSID()
Stable:

U_CAPI void U_EXPORT2 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.

Parameters:
converter:   the Unicode converter
subChars:   the subsitution characters
len:   on input the capacity of subChars, on output the number of bytes copied to it
err:   the outgoing error status code. If the substitution character array is too small, an U_INDEX_OUTOFBOUNDS_ERROR will be returned.
See also:
ucnv_setSubstChars()
Stable:

U_CAPI void U_EXPORT2 ucnv_setSubstChars (UConverter * converter, const char * subChars, int8_t len, UErrorCode * err)

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 NULL byte. The fill-in parameter err will get the error status on return.

Parameters:
converter   the Unicode converter
subChars   the substitution character byte sequence we want set
len   the number of bytes in subChars
err   the error status code. U_INDEX_OUTOFBOUNDS_ERROR if len is bigger than the maximum number of bytes allowed in subchars
See also:
ucnv_getSubstChars()
Stable:

U_CAPI void U_EXPORT2 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.

Parameters:
converter:   the Unicode converter
errBytes:   the bytes in error
len:   on input the capacity of errBytes, on output the number of bytes copied to it
err:   the outgoing error status code. If the substitution character array is too small, an U_INDEX_OUTOFBOUNDS_ERROR will be returned.
Stable:

U_CAPI void U_EXPORT2 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.

Parameters:
converter:   the Unicode converter
errUChars:   the UChars in error
len:   on input the capacity of errUChars, on output the number of UChars copied to it
err:   the outgoing error status code. If the substitution character array is too small, an U_INDEX_OUTOFBOUNDS_ERROR will be returned.
Stable:

U_CAPI void U_EXPORT2 ucnv_reset (UConverter * converter)

Resets the state of stateful conversion to the default state.

This is used in the case of error to restart a conversion from a known default state. it will also empty the internal output buffers.

Parameters:
converter   the Unicode converter
Stable:

U_CAPI int8_t U_EXPORT2 ucnv_getMaxCharSize (const UConverter * converter)

Returns the maximum length of bytes used by a character.

This varies between 1 and 4

Parameters:
converter   the Unicode converter
Returns:
the maximum number of bytes allowed by this particular converter
See also:
ucnv_getMinCharSize()
Stable:

U_CAPI int8_t U_EXPORT2 ucnv_getMinCharSize (const UConverter * converter)

Returns the minimum byte length for characters in this codepage.

This is either 1 or 2 for all supported codepages.

Parameters:
converter   the Unicode converter
Returns:
the minimum number of bytes allowed by this particular converter
See also:
ucnv_getMaxCharSize()
Stable:

U_CAPI int32_t U_EXPORT2 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, in the case the locale contains no display name, the internal ASCII name will be filled in.

Parameters:
converter   the Unicode converter.
displayLocale   is the specific Locale we want to localised for
displayName   user provided buffer to be filled in
displayNameCapacty   size of displayName Buffer
err:   outgoing error code.
Returns:
displayNameLength number of UChar needed in displayName
See also:
ucnv_getName()
Stable:

U_CAPI const char *U_EXPORT2 ucnv_getName (const UConverter * converter, UErrorCode * err)

Gets the name of the converter (zero-terminated).

the name will be the internal name of the converter, the lifetime of the returned string will be that of the converter passed to this function.

Parameters:
converter   the Unicode converter
err   UErrorCode status
Returns:
the internal name of the converter
See also:
ucnv_getDisplayName()
Stable:

U_CAPI int32_t U_EXPORT2 ucnv_getCCSID (const UConverter * converter, UErrorCode * err)

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 IBM registered codepages and return zero for the codepage number. The error code fill-in parameter indicates if the codepage number is available.

Parameters:
converter   the Unicode converter
err   the error status code. the converter is NULL or if converter's data table is NULL.
Returns:
If any error occurrs, -1 will be returned otherwise, the codepage number will be returned
Stable:

U_CAPI UConverterPlatform U_EXPORT2 ucnv_getPlatform (const UConverter * converter, UErrorCode * err)

Gets a codepage platform associated with the converter.

Currently, only IBM is supported The error code fill-in parameter indicates if the codepage number is available.

Parameters:
converter   the Unicode converter
err   the error status code. the converter is NULL or if converter's data table is NULL.
Returns:
The codepage platform
Stable:

U_CAPI UConverterType U_EXPORT2 ucnv_getType (const UConverter * converter)

Gets the type of conversion associated with the converter e.g.

SBCS, MBCS, DBCS, UTF8, UTF16_BE, UTF16_LE, ISO_2022, EBCDIC_STATEFUL, LATIN_1

Parameters:
converter:   a valid, opened converter
Returns:
the type of the converter
Stable:

U_CAPI void U_EXPORT2 ucnv_getStarters (const UConverter * converter, UBool starters[256], UErrorCode * err)

Gets the "starter" bytes for the converters of type MBCS will fill in an U_ILLEGAL_ARGUMENT_ERROR if converter passed in is not MBCS.

fills in an array of boolean, with the value of the byte as offset to the array. At return, if TRUE is found in at offset 0x20, it means that the byte 0x20 is a starter byte in this converter.

Parameters:
converter:   a valid, opened converter of type MBCS
starters:   an array of size 256 to be filled in
err:   an array of size 256 to be filled in
See also:
ucnv_getType()
Stable:

U_CAPI void U_EXPORT2 ucnv_getToUCallBack (const UConverter * converter, UConverterToUCallback * action, void ** context)

Gets the current calback function used by the converter when illegal or invalid sequence found.

Parameters:
converter   the unicode converter
action   the callback function pointer
context   the callback function state
See also:
ucnv_setToUCallBack()
Stable:

U_CAPI void U_EXPORT2 ucnv_getFromUCallBack (const UConverter * converter, UConverterFromUCallback * action, void ** context)

Gets the current callback function used by the converter when illegal or invalid sequence found.

Parameters:
converter   the unicode converter
action   the callback function pointer
context   the callback function state
See also:
ucnv_setFromUCallBack()
Stable:

U_CAPI void U_EXPORT2 ucnv_setToUCallBack (UConverter * converter, UConverterToUCallback newAction, void * newContext, UConverterToUCallback * oldAction, void ** oldContext, UErrorCode * err)

Gets the current callback function used by the converter when illegal or invalid sequence found.

Parameters:
converter   the unicode converter
newAction   the callback function we want to set.
newContext   the new toUnicode callback function state
oldAction   the previously assigned callback function pointer
oldContext   the new toUnicode callback function state
err   The error code status
See also:
ucnv_getToUCallBack()
Stable:

U_CAPI void U_EXPORT2 ucnv_setFromUCallBack (UConverter * converter, UConverterFromUCallback newAction, void * newContext, UConverterFromUCallback * oldAction, void ** oldContext, UErrorCode * err)

Gets the current callback function used by the converter when illegal or invalid sequence found.

Parameters:
converter   the unicode converter
newAction   the callback function we want to set.
newContext   the new fromUnicode callback function state
oldAction   the previously assigned callback function pointer
oldContext   the new fromUnicode callback function state
err   The error code status
See also:
ucnv_getFromUCallBack()
Stable:

U_CAPI void U_EXPORT2 ucnv_fromUnicode (UConverter * converter, char ** target, const char * targetLimit, const UChar ** source, const UChar * sourceLimit, int32_t * offsets, UBool flush, UErrorCode * err)

Transcodes an array of unicode characters to an array of codepage characters.

The source pointer is an I/O parameter, it starts out pointing where the function is to begin transcoding, and ends up pointing after the first sequence of the bytes that it encounters that are semantically invalid. if ucnv_setToUCallBack is called with an action other than STOP before a call is made to this API, consumed and source should point to the same place (unless target ends with an imcomplete sequence of bytes and flush is FALSE). the target buffer buffer needs to be a least the size of the maximum # of bytes per characters allowed by the target codepage.

Parameters:
converter   the Unicode converter
converter   the Unicode converter
target   : I/O parameter. Input : Points to the beginning of the buffer to copy codepage characters to. Output : points to after the last codepage character copied to target.
targetLimit   the pointer to the end of the target array
source   the source Unicode character array
sourceLimit   the pointer to the end of the source array
offsets   if NULL is passed, nothing will happen to it, otherwise it needs to have the same number of allocated cells as target. Will fill in offsets from target to source pointer e.g: offsets[3] is equal to 6, it means that the target[3] was a result of transcoding source[6] For output data carried across calls -1 will be placed for offsets.
flush   TRUE if the buffer is the last buffer of the conversion interation and the conversion will finish with this call, FALSE otherwise.
err   the error status. U_ILLEGAL_ARGUMENT_ERROR will be set if the converter is NULL. U_BUFFER_OVERFLOW_ERROR will be set if the target is full and there is still input left in the source.
See also:
ucnv_fromUChars() , ucnv_convert() , ucnv_getMinCharSize() , ucnv_setToUCallBack()
Draft:
backslash versus Yen sign in shift-JIS

U_CAPI void U_EXPORT2 ucnv_toUnicode (UConverter * converter, UChar ** target, const UChar * targetLimit, const char ** source, const char * sourceLimit, int32_t * offsets, UBool flush, UErrorCode * err)

Converts an array of codepage characters into an array of unicode characters.

The source pointer is an I/O parameter, it starts out pointing at the place to begin translating, and ends up pointing after the first sequence of the bytes that it encounters that are semantically invalid. if ucnv_setFromUCallBack is called with an action other than STOP before a call is made to this API, consumed and source should point to the same place (unless target ends with an imcomplete sequence of bytes and flush is FALSE).

Parameters:
converter   the Unicode converter
target   : I/O parameter. Input : Points to the beginning of the buffer to copy Unicode characters to. Output : points to after the last UChar copied to target.
targetLimit   the pointer to the end of the target array
source   the source codepage character array
sourceLimit   the pointer to the end of the source array
offsets   if NULL is passed, nothing will happen to it, otherwise it needs to have the same number of allocated cells as target. Will fill in offsets from target to source pointer e.g: offsets[3] is equal to 6, it means that the target[3] was a result of transcoding source[6] For output data carried across calls -1 will be placed for offsets.
flush   TRUE if the buffer is the last buffer and the conversion will finish in this call, FALSE otherwise.
err   the error code status U_ILLEGAL_ARGUMENT_ERROR will be returned if the converter is NULL, or if targetLimit and sourceLimit are misaligned. U_BUFFER_OVERFLOW_ERROR will be set if the target is full and there is still input left in the source.
See also:
ucnv_toUChars() , ucnv_getNextUChar() , ucnv_convert() , ucnv_setFromUCallBack()
Stable:

U_CAPI int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter, char * target, int32_t targetCapacity, const UChar * source, int32_t sourceLength, UErrorCode * err)

Transcodes the source Unicode string to the target string in a codepage encoding with the specified Unicode converter.

For example, if a Unicode to/from JIS converter is specified, the source string in Unicode will be transcoded to JIS encoding. The result will be stored in JIS encoding. if any problems during conversion are encountered it will SUBSTITUTE with the default (initial) substitute characters. This function is a more convenient but less efficient version of \Ref{ucnv_fromUnicode}.

Parameters:
converter   the Unicode converter
source   the source Unicode string (zero Terminated)
target   the target string in codepage encoding (not zero-terminated because some codepage do not use '\0' as a string terminator
targetCapacity   Input the number of bytes available in the target buffer
source   the source buffer to convert with
sourceLength   the length of the source buffer. If -1 is passed in as the value, the source buffer is NULL terminated string and whole source buffer will be converted.
err   the error status code. U_ILLEGAL_ARGUMENT_ERROR is returned if the converter is NULL or the source or target string is empty. U_BUFFER_OVERFLOW_ERROR will be set if the target is full and there is still input left in the source.
Returns:
number of bytes needed in target, regardless of targetCapacity
See also:
ucnv_fromUnicode() , ucnv_convert()
Draft:
backslash versus Yen sign in shift-JIS

U_CAPI int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter, UChar * target, int32_t targetCapacity, const char * source, int32_t sourceSize, UErrorCode * err)

Transcode the source string in codepage encoding to the target string in Unicode encoding.

For example, if a Unicode to/from JIS converter is specified, the source string in JIS encoding will be transcoded to Unicode and placed into a provided target buffer. if any problems during conversion are encountered it will SUBSTITUTE with the Unicode REPLACEMENT char We recomment, the size of the target buffer needs to be at least as long as the maximum # of bytes per char in this character set. A zero-terminator will be placed at the end of the target buffer This function is a more convenient but less efficient version of \Ref{ucnv_toUnicode}.

Parameters:
converter   the Unicode converter
source   the source string in codepage encoding
target   the target string in Unicode encoding
targetCapacity   capacity of the target buffer
sourceSize   : Number of bytes in source to be transcoded
err   the error status code U_MEMORY_ALLOCATION_ERROR will be returned if the the internal process buffer cannot be allocated for transcoding. U_ILLEGAL_ARGUMENT_ERROR is returned if the converter is NULL or if the source or target string is empty. U_BUFFER_OVERFLOW_ERROR will be set if the target is full and there is still input left in the source.
Returns:
the number of UChar needed in target (including the zero terminator)
See also:
ucnv_getNextUChar() , ucnv_toUnicode() , ucnv_convert()
Stable:

U_CAPI UChar32 U_EXPORT2 ucnv_getNextUChar (UConverter * converter, const char ** source, const char * sourceLimit, UErrorCode * err)

U_CAPI int32_t U_EXPORT2 ucnv_convert (const char * toConverterName, const char * fromConverterName, char * target, int32_t targetCapacity, const char * source, int32_t sourceLength, UErrorCode * err)

U_CAPI int32_t U_EXPORT2 ucnv_flushCache (void)

SYSTEM API Iterates through every cached converter and frees all the unused ones.

Returns:
the number of cached converters successfully deleted
Stable:
System:

U_CAPI const char *U_EXPORT2 ucnv_getAvailableName (int32_t n)

provides a string containing the internal name (based on the alias file) of the converter.

given an index.

Parameters:
n   the number of converters available on the system ([0..ucnv_countAvaiable()])
Returns:
a pointer a string (library owned), or NULL if the index is out of bounds.
See also:
ucnv_countAvailable()
Stable:

U_CAPI int32_t U_EXPORT2 ucnv_countAvailable (void)

returns the number of available converters.

Returns:
the number of available converters
See also:
ucnv_getAvailableName()
Stable:

U_CAPI uint16_t ucnv_countAliases (const char * alias, UErrorCode * pErrorCode)

Gives the number of aliases for given converter or alias name.

Note that additional aliases are recognized by ucnv_open(). This method only enumerates the listed entries in the alias file.

Parameters:
alias   alias name
pErrorCode   result of operation
Returns:
number of names on alias list
Stable:

U_CAPI const char * ucnv_getAlias (const char * alias, uint16_t n, UErrorCode * pErrorCode)

Gives the name of the alias at given index of alias list.

Note that additional aliases are recognized by ucnv_open(). This method only enumerates the listed entries in the alias file.

Parameters:
alias   alias name
n   index in alias list
pErrorCode   result of operation
Returns:
returns the name of the alias at given index
Stable:

U_CAPI void ucnv_getAliases (const char * alias, const char ** aliases, UErrorCode * pErrorCode)

Fill-up the list of alias names for the given alias.

Note that additional aliases are recognized by ucnv_open(). This method only enumerates the listed entries in the alias file.

Parameters:
alias   alias name
aliases   fill-in list, aliases is a pointer to an array of ucnv_countAliases() string-pointers (const char *) that will be filled in
pErrorCode   result of operation
Stable:

U_CAPI uint16_t ucnv_countStandards (void)

Gives the number of standards associated to converter names.

Returns:
number of standards
Stable:

U_CAPI const char * ucnv_getStandard (uint16_t n, UErrorCode * pErrorCode)

Gives the name of the standard at given index of standard list.

Parameters:
n   index in standard list
pErrorCode   result of operation
Returns:
returns the name of the standard at given index
Stable:

U_CAPI const char * ucnv_getStandardName (const char * name, const char * standard, UErrorCode * pErrorCode)

Returns a standard name for a given converter name.

Parameters:
name   original converter name
standard   name of the standard governing the names; MIME and IANA are such standards
Returns:
returns the standard converter name; if a standard converter name cannot be determined, then NULL is returned
Stable:

U_CAPI const char *U_EXPORT2 ucnv_getDefaultName (void)

returns the current default converter name.

Returns:
returns the current default converter name; if a default converter name cannot be determined, then NULL is returned
See also:
ucnv_setDefaultName()
Stable:

U_CAPI void U_EXPORT2 ucnv_setDefaultName (const char * name)

sets the current default converter name.

The lifetime of the return ptr is that of the library

Parameters:
name:   the converter name you want as default (has to appear in alias file)
See also:
ucnv_getDefaultName()
System:

U_CAPI void U_EXPORT2 ucnv_fixFileSeparator (const UConverter * cnv, UChar * source, int32_t sourceLen)

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.

Parameters:
source   the input buffer to be fixed
sourceLength   the length of the input buffer
Draft:

U_CAPI UBool U_EXPORT2 ucnv_isAmbiguous (const UConverter * cnv)

Determines if the converter contains ambiguous mappings of the same character or not.

Returns:
TRUE if the converter contains ambiguous mapping of the same character, FALSE otherwise.
Draft:

U_CAPI void U_EXPORT2 ucnv_setFallback (UConverter * cnv, UBool usesFallback)

Sets the converter to use fallback mapping or not.

Parameters:
cnv   The converter to set the fallback mapping usage for.
usesFallback   TRUE if the user wants the converter to take advantage of the fallback mapping, FALSE otherwise.
Draft:

U_CAPI UBool U_EXPORT2 ucnv_usesFallback (const UConverter * cnv)

Determines if the converter uses fallback mappings or not.

Returns:
TRUE if the converter uses fallback, FALSE otherwise.
Draft:

Variable Documentation

struct UConverter

Definition at line 29 of file ucnv.h.


Generated at Wed Aug 16 16:05:29 2000 for ICU1.6 by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999