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;

ARGUMENTS

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 function returns at any time, scanned_len always remembers where stopped. 

The caller of this function 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 redundant 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 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 _XConvertWCToCT 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.