X11R5

NAME

_XConvertWCToCT − conversion from WC string to CT

SYNOPSIS

int _XConvertWCToCT(xlocale, wc_str, wc_len, ct_str, ct_bytes,
XLocale xlocale;
wchar ∗wc_str;
int wc_len;
char ∗ct_str;
int ∗ct_bytes;
int ∗scanned_len;

PARAMETERS

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

wc_strIn: wchar string. 

wc_lenIn: length of wchar string, counted in wchars. 

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_lenOut: scanned number of wchars, counted in wchars

DESCRIPTION

The _XConvertWCToCT converts the string encoded in wchar to string encoded in CT.  After a successful conversion the default state designation of CT will be appended at ct_str if the last state is not same as 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 fucntion returns at any time, scanned_len always remembers where stopped. 

The caller of this funcion has to provide the output buffer ct_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 CT string is concatenatable. However concatenation may produce reduntant designation sequence. 

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_len stores the number of already proccessed wchars.  Caller can move wc_str to (wc_str + ∗scanned_len) for next conversion. 

The function returns a number greate 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 mininum 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 _XConvertWCToCT returns the following value:

Success
successful conversion.

BadBuffer
buffer was exhausted.

BadEncoding
wrong codepoints can not be recovered.

> 0 number of wrong codepoints, but recovered. 

RELATED INFORMATION

Refer to "CT and WC" for their definitions.