_XConvertMBToWC(3X11) X11R5 _XConvertMBToWC(3X11)NAME
_XConvertMBToWC - conversion from CT string to mb string.
SYNOPSIS
int _XConvertMBToWC(xlocale, mb_str, mb_bytes, wc_str, wc_len,
scanned_bytes, state)
XLocale xlocale;
unsigned char *mb_str;
int mb_bytes;
wchar *wc_str;
int *wc_len;
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 strings, counted in bytes.
wc_str Out: conversion buffer of result wchar string.
wc_len In/Out: as "In" it is length of buffer wc_str passed by call‐
er; as "Out" it is the returned number of converted wchars.
scanned_bytes
Number of mb bytes converted when the function returns.
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 _XConvertMBToWC converts the multibyte string encoded in the speci‐
fied xlocale to wchar string. After a successful conversion, the null
character WNULL will be appended to wc_str if there is room for it in
the buffer. The terminator WNULL of wchar string is not counted in
length of output buffer wc_len.
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 wc_str,
and store the buffer length (in wchars) into wc_len as input. By using
scanned_bytes and state, the caller can break a large mb string into
pieces, and convert one piece at a time.
In other hand caller can pass any broken mb string to this function for
doing conversion. For example, caller can still be trying of conver‐
sion when the error BadBuffer is occurred(output buffer was exhausted).
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 xlo‐
cale. Usually, the application should calls it with NULL mb_str for
first conversion as the following:
_XConvertMBToWC(NULL, mb_bytes, wc_str,
&mb_len, &scanned)
The function returns the BadBuffer meaning that the output buffer
wc_str was exhausted. The function returns the BadTerminate meaning
that the mb string is terminated uncompletely, e.g., uncompleted ESC
sequence or uncompleted code point ended at tail of mb_str.
Only in both the case of BadBuffer and BadTerminate the caller can move
pointer mb_str to (mb_str + *scanned_bytes), then continue to do con‐
version. And function ensure that the wc_str stores the already con‐
verted wchar string; wc_len counts the number of them in wchars(not
bytes);
The function returns a number greater than zero meaning a number of
wrong codepoints recovered by the function. The wrong codepoint will
be recovered with the first codepoint of the charset at which the wrong
codepoint occurs. After replaced, the function will continue to do
conversion until one of the results Success, BadTerminate, BadBuffer or
BadEncoding is met.
Both the null character and mb_bytes will terminate the conversion.
All error status are defined to be less than zero, i.e.:
#define Success 0
#define BadBuffer -1
#define BadTerminate -2
#define BadEncoding -3
RETURNED VALUE
The _XConvertMBToWC will return the following values:
Success
successful conversion.
BadBuffer
output buffer(wc_str) 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.
_XConvertMBToWC(3X11)
