DataMuseum.dk

top - metrics - download

    Length: 3897 (0xf39)
    Types: TextFile
    Names: »XCnvMBToWC.3«

└─⟦276d19d6e⟧ Bits:30007243 EUUGD5_I: X11R5
    └─⟦4856bf7e7⟧ »./mit-4/mit-4.00« 
        └─⟦635ff9e7e⟧ 
            └─⟦this⟧ »mit/doc/I18N/Xsi/Xlc/XCnvMBToWC.3« 

TextFile

.\" $Header: XCnvMBToWC.3,v 1.5 91/02/04 09:37:49 morisaki Exp $
.\" $Date: 91/02/04 09:37:49 $
.\" Copyright 1990, 1991 by OMRON Corporation.
.\" Copyright 1991 by the Massachusetts Institute of Technology.
.TH Xlocale 3X11 "" "June 30, 1990"
.SH NAME
.B XConvertMBToWC
\- conversion from  CT string to mb string.
.SH SYNOPSIS
.B int XConvertMBToWC\f2(mb_str, mb_bytes, wc_str, wc_len,
.br
.B                                    \f2scanned_bytes)
.br
.B unsigned char \f2*mb_str\f3;
.br
.B int \f2mb_bytes\f3;
.br
.B wchar \f2*wc_str\f3;
.br
.B int \f2*wc_len\f3;
.br
.B int \f2*scanned_bytes\f3;
.br
.SH ARGUMENTS
.IP \fImb_str\fP 1i 
In: multibyte string.
.br
.IP \fImb_bytes\fP 1i 
In: length of mb strings, counted in bytes.
.br
.IP \fIwc_str\fP 1i
Out: conversion buffer of result wchar string.
.br
.IP \fIwc_len\fP 1i 
In/Out: as "In" it is length of buffer wc_str passed by caller; 
as "Out" it is the returned number of converted wchars. 
.br
.IP \fIscanned_bytes\fP 1i 
Number of mb bytes converted when the function returns.
.br
.SH DESCRIPTION
The
.B XConvertMBToWC
converts the multibyte string encoded in the current locale 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.
.PP
When function returns at any time, scanned_bytes always remembers
where stopped, and isostate always remembers the current CT state
if it is not null pointer.
.PP
The caller of this funcion 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 isostate, the caller can break a large
mb string into pieces, and convert one piece at a time.
.PP
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 current locale is state-dependent and
the mb_str is passed as NULL pointer, the function will set
initial state in the current locale.
Usually, the application should calls it with NULL mb_str for first 
conversion as the following:
.IP "" "   "
\f3XConvertMBToWC(NULL, mb_bytes, wc_str,
            &mb_len, &scanned)\f2
.PP
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.
.PP
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); 
.PP
The function returns a number greate than zero meaning a number of
wrong codepoints recovered by the funcition.
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 untill
one of the results Success, BadTerminate, BadBuffer or BadEncoding
is met.
.PP
Both the null character and mb_bytes will terminate the conversion.
.PP
All error status are defined to be less than zero, i.e.:
.IP "" 2
#define Success          0
.IP
#define BadBuffer       -1
.IP
#define BadTerminate    -2
.IP
#define BadEncoding     -3
.SH RETURNED VALUE
The
.B XConvertMBToWC will return the following values:
.TP
.B Success
successful conversion.
.TP
.B BadBuffer
output buffer(wc_str) was exhausted.
.TP
.B BadTerminate
.TP
.B BadEncoding 
wrong escape sequence function can not recover.
.TP
.B "> 0"
unconvertable compound text was met.
.SH SEE ALSO
Refer to "CT and WC" for their definitions.