_XConvertMBToCT(3X11) X11R5 _XConvertMBToCT(3X11)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
xlocale In: specifies locale, the default NULL is the current locale.
mb_str In: multibyte string.
mb_bytes In: length of mb string, counted in bytes.
ct_str Out: conversion buffer of result CT string.
ct_bytes In/Out: as "In" it is length of buffer ct_str passed by call‐
er; 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,
state In/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 speci‐
fied 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 auto‐
matically append a null character to ct_str if more room in output buf‐
fer 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 conver‐
sion.
The function returns a number greater than zero meaning a BadEncoding,
the unconvertable codes in mb string were met. In this case the func‐
tion will automatically recover the wrong code with the following algo‐
rithm:
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.
_XConvertMBToCT(3X11)
