DataMuseum.dk

top - metrics - download

    Length: 2913 (0xb61)
    Types: TextFile
    Names: »XCnvWCToMB.3«

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

TextFile

.\" $Header: XCnvWCToMB.3,v 1.4 91/02/04 09:40:13 morisaki Exp $
.\" $Date: 91/02/04 09:40:13 $
.\" Copyright 1990, 1991 by OMRON Corporation.
.\" Copyright 1991 by the Massachusetts Institute of Technology.
.TH Xlocale 3X11 "" "June 30, 1990"
.SH NAME
.B XConvertWCToMB
\- conversion from  WC string to mb string
.SH SYNOPSIS
.B int XConvertWCToMB\f2(wc_str, wc_len, mb_str, mb_bytes, scanned_len)
.br
.B wchar \f2*wc_str\f3;
.br
.B int \f2wc_len\f3;
.br
.B unsigned char \f2*mb_str\f3;
.br
.B int \f2*mb_bytes\f3;
.br
.B int \f2*scanned_len\f3;
.SH ARGUMENTS
.IP \fIwc_str\fP 1i
In: wchar string.
.br
.IP \fIwc_len\fP 1i 
In: length of wchar string, counted in wchars.
.br
.IP \fImb_str\fP 1i 
Out: conversion buffer of result mb string.
.br
.IP \fImb_bytes\fP 1i 
In/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
.br
.IP \fIscanned_len\fP 1i 
Out: scanned number of wchars,
counted in wchars
.br
.SH DESCRIPTION
The
.B 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.
.PP
When fucntion returns at any time, scanned_len always remembers
where stopped.
.PP
The caller of this funcion 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 reduntant designation sequence if the codeset is state-dependent.
.PP
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 proccessed wchars. 
Caller can move wc_str to (wc_str + *scanned_len) for next conversion.
.PP
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:
.IP "" 2
If a byte of wchar code is wrong, replace it with the mininum character 
of the current encoding.
.PP
Then function continues to do conversion.
.PP
Both the WNULL character and wc_len will terminate the conversion.
.PP
All errors are defined 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 XConvertWCToMB returns the following value:
.TP
.B Success
successful conversion.
.TP
.B BadBuffer
buffer was exhausted
.TP
.B "> 0"
unvertable code in wchar string.
.SH "SEE ALSO"
Refer to "CT and WC" for their definitions.