_XConvertCTToWC(3X11) X11R5 _XConvertCTToWC(3X11)NAME
_XConvertCTToWC - conversion from CT string to WC string
SYNOPSIS
int _XConvertCTToWC(xlocale, ct_str, ct_bytes, wc_str, wc_len,
scanned_bytes, state)
XLocale xlocale;
char *ct_str;
int ct_bytes;
wchar *wc_str;
int *wc_len;
int *scanned_bytes;
_State *state;
ARGUMENTS
xlocale In: specifies locale, the default NULL is the current locale.
ct_str In: CT string.
ct_bytes In: length of CT 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 CT bytes converted when the function returns.
state In/Out: as "In" it is the state at the beginning of the CT
string; as "Out" it is the current state stopped at last con‐
verted CT encoding. The state is defined internally by Xlib.
If this pointer is null, the function will assume the state
to be the default CT state. Of course, nothing will be put in
the null pointer. Do not modify or free this data.
DESCRIPTION
The _XConvertCTToWC converts the string encoded in CT to string encoded
in wchar. After a successful conversion, the null character WNULL will
be appended to wc_str if there is room for it in the buffer. The ter‐
minator WNULL of wchar string is not counted in length of output buffer
wc_len.
The returned state will point to a state of the encoding in the inter‐
nal table, so do not modify or free this pointer.
When function returns at any time, scanned_bytes always remembers where
stopped, and state always remembers the current CT state if it is not
null pointer.
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 CT string into
pieces, and convert one piece at a time.
In other hand caller can pass any broken CT 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). Usually, the application passes the NULL to state for
first conversion as the following:
char *state = NULL;
_XConvertCTToWC(NULL, ct_str, ct_len, mb_str,
&mb_len, &scanned, &state)
The conversion function returns the value of variable state to use for
the conversion of the next unconverted piece of the same string. And
so on.
If the value of state is invalid or null-pointer, the function will
suppose the default state of CT as initial. The default state of CT is
defined in 3 cases of encoding:
1. no control sequence, GL and GR of Latin-1 is supposed.
2. control sequence of Latin-1 GL only, GR of Latin-1 is supposed
too.
3. control sequence of Latin-1 GR only, GL of Latin-1 is supposed
too.
The function returns the BadBuffer meaning that the output buffer
wc_str was exhausted. The function returns the BadTerminate meaning
that the CT string ct_str is terminated uncompletely, e.g., uncompleted
ESC sequence or uncompleted code point ended at tail of ct_str.
Only in both the case of BadBuffer and BadTerminate the caller can move
pointer ct_str to (ct_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 state stores the last state of encoding.
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.
The function returns BadEncoding meaning for unrecoverable wrong code
which is actually wrong escape sequence, or not registered by system
yet.
Both the null character and ct_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 _XConvertCTToWC will return the following values:
Success
successful conversion.
BadBuffer
output buffer(wc_str) was exhausted.
BadTerminate
BadEncoding
wrong codepoints can not be recovered.
> 0 number of wrong codepoints, but recovered.
SEE ALSO
Refer to "CT and WC" for their definitions.
_XConvertCTToWC(3X11)
