X11R5

NAME

_XConvertWCToMB − conversion from  WC string to mb string

SYNOPSIS

int _XConvertWCToMB(xlocale, wc_str, wc_len, mb_str, mb_bytes,
scanned_len)
XLocale xlocale;
wchar ∗wc_str;
int wc_len;
unsigned char ∗mb_str;
int ∗mb_bytes;
int ∗scanned_len;

ARGUMENTS

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

wc_strIn: wchar string. 

wc_lenIn: length of wchar string, counted in wchars. 

mb_strOut: conversion buffer of result mb string. 

mb_bytesIn/Out: as "In" it is length of buffer mb_str passed by caller; as "Out" it is the returned length of converted mb string, both counted in bytes

scanned_lenOut: scanned number of wchars, counted in wchars

DESCRIPTION

The _XConvertWCToMB converts the wc string to multibyte string encoded in the current locale.  After successful conversion function will automatically append a null to mb_str if more room in output buffer mb_str.  This null character is not counted in length of mb string. 

When function returns at any time, scanned_len always remembers where stopped. 

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

The function returns BadBuffer meaning that the output buffer mb_str was exhausted. In this case function ensure that the mb_str stores already converted mb string; mb_bytes stores number of bytes of mb_str; the scanned_len stores the number of already processed wchars.  Caller can move wc_str to (wc_str + ∗scanned_len) for next conversion. 

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

If a byte of wchar code is wrong, replace it with the minimum character of the current encoding. 

Then function continues to do conversion. 

Both the WNULL character and wc_len 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 _XConvertWCToMB returns the following value:

Success
successful conversion.

BadBuffer
buffer was exhausted.

BadTerminate
String was terminated at an 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.