NAME

_XConvertMBToCT − conversion from mb string to CT

SYNOPSIS

int _XConvertMBToCT(xlocale, mb_str, mb_bytes, ct_str, ct_bytes,
scanned_bytes, state)
XLocale xlocale;
char *mb_str;
int mb_bytes;
char *ct_str;
int *ct_bytes;
int *scanned_bytes;
_State *state;

ARGUMENTS

xlocaleIn: specifies locale, the default NULL is the current locale. 

mb_strIn: multibyte string. 

mb_bytesIn: length of mb string, counted in bytes. 

ct_strOut: conversion buffer of result CT string. 

ct_bytesIn/Out: as "In" it is length of buffer ct_str passed by caller; as "Out" it is the returned length of converted CT string, both counted in bytes. 

scanned_bytes
Out: scanned number of bytes of mb_str,

stateIn/Out: as "In" it is the state at the beginning of mb string; as "Out" it is the current state stopped at the last converted mb string. 

DESCRIPTION

The _XConvertMBToCT converts the multibyte string encoded in the specified xlocale to CT string.  After a successful conversion the default state designation of CT (usually it’s Latin-1 GL) will be appended at ct_str if the last state is not default state.  And function will automatically append a null character to ct_str if more room in output buffer ct_str.  This null character is not counted in length of CT string. 

When function returns at any time, scanned_bytes always remembers where stopped, and state always remembers the current state of xlocale if it is state-dependent codeset. 

The caller of this function has to provide the output buffer ct_str.  By using scanned_bytes and state, the caller can break a large mb string into pieces, and convert one piece at a time.  The result of CT string is concatenatable. However concatenation may produce redundant designation sequence. 

If the codeset of the xlocale is state-dependent and the mb_str is passed as NULL pointer, the function will set initial state in the specified xlocale.  Usually, the application should calls it with NULL mb_str for first conversion as the following:

_XConvertMBToCT(NULL, mb_bytes, wc_str,
            &mb_bytes, &scanned)

The function returns BadBuffer meaning that the output buffer ct_str was exhausted. In this case function ensure that the ct_str stores already converted CT string; ct_bytes stores number of bytes of ct_str; the scanned_bytes stores the number of already processed mb string.  Caller can move mb_str to (mb_str + *scanned_bytes) for next conversion. 

The function returns a number greater than zero meaning a BadEncoding, the unconvertable codes in mb string were met.  In this case the function will automatically recover the wrong code with the following algorithm:

If a byte of mb codepoint is wrong, replace it with the minimum byte of the character encoded in the current charset. 

Then function continues to do conversion. 

Both the null character and mb_bytes will terminate the conversion. 

All errors are defined less than zero, i.e.:

#define Success         0

#define BadBuffer      -1

#define BadTerminate   -2

#define BadEncoding    -3

RETURNED VALUE

The _XConvertMBToCT returns the following value:

Success
successful conversion.

BadBuffer
buffer was exhausted.

BadTerminate
mb_str terminated at uncomplete codepoint.

BadEncoding
wrong codepoints can not be recovered.

> 0 number of wrong codepoints, but recovered. 

SEE ALSO

Refer to "CT and WC" for their definitions.