X11R5

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

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

mb_strIn: multibyte string. 

mb_bytesIn: length of mb strings, counted in bytes. 

wc_strOut: conversion buffer of result wchar string. 

wc_lenIn/Out: as "In" it is length of buffer wc_str passed by caller; as "Out" it is the returned number of converted wchars. 

scanned_bytes
Number of mb bytes converted when the function returns.

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 _XConvertMBToWC converts the multibyte string encoded in the specified 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 conversion 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 xlocale.  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 conversion.  And function ensure that the wc_str stores the already converted 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.