wchar.html

ST20 Embedded Toolset R2.0.5用于开发基于ST20芯片机顶盒软件的开发平台,2.0.5版本,国内找不到的.在国外论坛上花了N天才找到!

<P>where <CODE>internal</CODE> is an object of type
<A HREF="#mbstate_t"><CODE>mbstate_t</CODE></A>
internal to the <CODE>mbrlen</CODE> function. At
<A HREF="lib_over.html#program startup">program startup</A>,
<CODE>internal</CODE> is initialized to the
<A HREF="charset.html#initial conversion state">initial conversion state</A>.
No other library function
alters the value stored in <CODE>internal</CODE>.</P>

<P>The function returns:</P>

<UL>
<LI><CODE>(<A HREF="#size_t">size_t</A>)-2</CODE> if,
after converting all <CODE>n</CODE> characters, the resulting
<A HREF="charset.html#conversion state">conversion state</A>
indicates an incomplete multibyte character

<LI><CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>
if the function detects an encoding error
before completing the next multibyte character, in which case the
function stores the value
<A HREF="errno.html#EILSEQ"><CODE>EILSEQ</CODE></A> in
<A HREF="errno.html#errno"><CODE>errno</CODE></A> and leaves the resulting
<A HREF="charset.html#conversion state">conversion state</A> undefined

<LI>zero, if the next completed character is a null character, in
which case the resulting
<A HREF="charset.html#conversion state">conversion state</A> is the
<A HREF="charset.html#initial conversion state">initial conversion state</A>

<LI><CODE>x,</CODE> the number of bytes needed to complete the next muitibyte
character, in which case the resulting
<A HREF="charset.html#conversion state">conversion state</A> indicates
that <CODE>x</CODE> bytes have been converted
</UL>

<P>Thus, <CODE>mbrlen</CODE> effectively returns the number of bytes
that would be consumed in successfully converting a multibyte character
to a wide character (without storing the converted wide character),
or an error code if the conversion cannot succeed.</P>

<H2><A NAME="mbrtowc"><CODE>mbrtowc</CODE></A></H2>

<PRE>size_t <B>mbrtowc</B>(wchar_t *pwc, const char *s,
    size_t n, mbstate_t *ps);</PRE>

<P>The function determines the number of bytes in a multibyte string
that completes the next multibyte character, if possible.</P>

<P>If <CODE>ps</CODE> is not a null pointer, the
<A HREF="charset.html#conversion state">conversion state</A> for
the multibyte string is assumed to be <CODE>*ps</CODE>. Otherwise, it is
assumed to be <CODE>&amp;internal</CODE>,
where <CODE>internal</CODE> is an object of type
<A HREF="#mbstate_t"><CODE>mbstate_t</CODE></A>
internal to the <CODE>mbrtowc</CODE> function. At
<A HREF="lib_over.html#program startup">program startup</A>,
<CODE>internal</CODE> is initialized to the
<A HREF="charset.html#initial conversion state">initial conversion state</A>.
No other library function alters the value stored
in <CODE>internal</CODE>.</P>

<P>If <CODE>s</CODE> is not a null pointer,
the function determines <CODE>x,</CODE>
the number of bytes in the multibyte string <CODE>s</CODE> that complete
or contribute to the next multibyte character. (<CODE>x</CODE> cannot be
greater than <CODE>n</CODE>.) Otherwise, the function effectively returns
<CODE>mbrtowc(0, "", 1, ps)</CODE>,
ignoring <CODE>pwc</CODE> and <CODE>n</CODE>.
(The function thus returns zero only if the
<A HREF="charset.html#conversion state">conversion state</A> indicates
that no incomplete multibyte character is pending from a previous call to
<A HREF="#mbrlen"><CODE>mbrlen</CODE></A>,
<CODE>mbrtowc</CODE>, or
<A HREF="#mbsrtowcs"><CODE>mbsrtowcs</CODE></A> for the
same string and
<A HREF="charset.html#conversion state">conversion state</A>.)</P>

<P>If <CODE>pwc</CODE> is not a null pointer, the function converts a
completed multibyte character to its corresponding wide-character
value and stores that value in <CODE>*pwc</CODE>.</P>

<P>The function returns:</P>

<UL>
<LI><CODE>(<A HREF="#size_t">size_t</A>)-2</CODE> if,
after converting all <CODE>n</CODE> characters, the resulting
<A HREF="charset.html#conversion state">conversion state</A>
indicates an incomplete multibyte character

<LI><CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>
if the function detects an encoding error
before completing the next multibyte character, in which case the
function stores the value
<A HREF="errno.html#EILSEQ"><CODE>EILSEQ</CODE></A> in
<A HREF="errno.html#errno"><CODE>errno</CODE></A>
and leaves the resulting
<A HREF="charset.html#conversion state">conversion state</A> undefined

<LI>zero, if the next completed character is a null character, in
which case the resulting
<A HREF="charset.html#conversion state">conversion state</A> is the
<A HREF="charset.html#initial conversion state">initial conversion state</A>

<LI><CODE>x,</CODE> the number of bytes needed to complete the next muitibyte
character, in which case the resulting
<A HREF="charset.html#conversion state">conversion state</A> indicates
that <CODE>x</CODE> bytes have been converted
</UL>

<H2><A NAME="mbsinit"><CODE>mbsinit</CODE></A></H2>

<PRE>int <B>mbsinit</B>(const mbstate_t *ps);</PRE>

<P>The function returns a nonzero value if <CODE>ps</CODE> is a null
pointer or if <CODE>*ps</CODE> designates an
<A HREF="charset.html#initial conversion state">initial conversion state</A>.
Otherwise, it returns zero.</P>

<H2><A NAME="mbsrtowcs"><CODE>mbsrtowcs</CODE></A></H2>

<PRE>size_t <B>mbsrtowcs</B>(wchar_t *dst, const char **src,
    size_t len, mbstate_t *ps);</PRE>

<P>The function converts the multibyte string beginning at <CODE>*src</CODE>
to a sequence of wide characters as if by repeated calls of the form:</P>

<PRE>x = mbrtowc(dst, *src, n, ps != 0 ? ps : &amp;internal)</PRE>

<P>where <CODE>n</CODE> is some value &gt; 0 and <CODE>internal</CODE>
is an object of type
<A HREF="#mbstate_t"><CODE>mbstate_t</CODE></A>
internal to the <CODE>mbsrtowcs</CODE> function. At
<A HREF="lib_over.html#program startup">program startup</A>,
<CODE>internal</CODE> is initialized to the
<A HREF="charset.html#initial conversion state">initial conversion state</A>.
No other library function alters the value
stored in <CODE>internal</CODE>.</P>

<P>If <CODE>dst</CODE> is not a null pointer,
the <CODE>mbsrtowcs</CODE> function stores at most <CODE>len</CODE>
wide characters by calls to
<A HREF="#mbrtowc"><CODE>mbrtowc</CODE></A>.
The function effectively increments <CODE>dst</CODE> by one
and <CODE>*src</CODE> by <CODE>x</CODE> after each call to
<A HREF="#mbrtowc"><CODE>mbrtowc</CODE></A>
that stores a converted wide character.
After a call that returns zero,
<CODE>mbsrtowcs</CODE> stores a null wide character
at <CODE>dst</CODE> and stores
a null pointer at <CODE>*src</CODE>.</P>

<P>If <CODE>dst</CODE> is a null pointer,
<CODE>len</CODE> is effectively assigned a large value.</P>

<P>The function returns:</P>

<UL>
<LI><CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>, if a call to
<A HREF="#mbrtowc"><CODE>mbrtowc</CODE></A> returns
<CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>,
indicating that it has detected an encoding error before completing
the next multibyte character

<LI>the number of multibyte characters successfully converted, not
including the terminating null character
</UL>

<H2><A NAME="mbstate_t"><CODE>mbstate_t</CODE></A></H2>

<PRE>typedef <I>o-type</I> <B>mbstate_t;</B></PRE>

<P>The type is an object type <I>o-type</I> that can represent a
<A HREF="charset.html#conversion state">conversion state</A>
for any of the functions
<A HREF="#mbrlen"><CODE>mbrlen</CODE></A>,
<A HREF="#mbrtowc"><CODE>mbrtowc</CODE></A>,
<A HREF="#mbsrtowcs"><CODE>mbsrtowcs</CODE></A>,
<A HREF="#wcrtomb"><CODE>wcrtomb</CODE></A>, or
<A HREF="#wcsrtombs"><CODE>wcsrtombs</CODE></A>.
A definition of the form:</P>

<PRE>mbstate_t mbst = {0};</PRE>

<P>ensures that <CODE>mbst</CODE> represents the
<A HREF="charset.html#initial conversion state">initial conversion state</A>.
Note, however, that other values stored in an object of type
<CODE>mbstate_t</CODE> can also represent this state.
To test safely for this state, use the function
<A HREF="#mbsinit"><CODE>mbsinit</CODE></A>.</P>

<H2><A NAME="NULL"><CODE>NULL</CODE></A></H2>

<PRE>#define <B>NULL</B> <I>&lt;either 0, 0L, or (void *)0&gt;</I> <B>[0 in C++]</B></PRE>

<P>The macro yields a null pointer constant that is usable as an
<A HREF="express.html#address constant expression">
address constant expression</A>.</P>

<H2><A NAME="putwc"><CODE>putwc</CODE></A></H2>

<PRE>wint_t <B>putwc</B>(wchar_t c, FILE *stream);</PRE>

<P>The function has the same effect as
<CODE><A HREF="#fputwc">fputwc</A>(c, stream)</CODE>
except that a macro version of <CODE>putwc</CODE>
can evaluate <CODE>stream</CODE> more than once.</P>

<H2><A NAME="putwchar"><CODE>putwchar</CODE></A></H2>

<PRE>wint_t <B>putwchar</B>(wchar_t c);</PRE>

<P>The function has the same effect as
<CODE><A HREF="#fputwc">fputwc</A>(c, stdout)</CODE>.</P>

<H2><A NAME="size_t"><CODE>size_t</CODE></A></H2>

<PRE>typedef <I>ui-type</I> <B>size_t;</B></PRE>

<P>The type is the unsigned integer type <CODE><I>ui-type</I></CODE>
of an object that you declare to store the result of the
<A HREF="express.html#sizeof operator"><I>sizeof</I></A> operator.</P>

<H2><A NAME="swprintf"><CODE>swprintf</CODE></A></H2>

<PRE>int <B>swprintf</B>(wchar_t *s, size_t n,
    const wchar_t *format, ...);</PRE>

<P>The function
<A HREF="lib_prin.html#Print Functions">generates formatted text</A>,
under the control of the format <CODE>format</CODE>
and any additional arguments, and stores
each generated character in successive locations of the array object whose
first element has the address <CODE>s</CODE>. The function concludes
by storing a null wide character in the next location of the array.
If it cannot generate and store all characters in an array of size <CODE>n</CODE>,
the function returns a negative number. Otherwise,
it returns the number of wide characters generated -- not including
the null wide character.</P>

<H2><A NAME="swscanf"><CODE>swscanf</CODE></A></H2>

<PRE>int <B>swscanf</B>(const wchar_t *s,
    const wchar_t *format, ...);</PRE>

<P>The function
<A HREF="lib_scan.html#Scan Functions">scans formatted text</A>,
under the control of the format <CODE>format</CODE>
and any additional arguments. It accesses each scanned
character from successive locations of the array object whose first
element has the address <CODE>s</CODE>.
It returns the number of items matched and assigned, or it returns
<A HREF="stdio.html#EOF"><CODE>EOF</CODE></A> if the function does not store
values before it accesses a null wide character from the array.</P>

<H2><A NAME="tm"><CODE>tm</CODE></A></H2>

<PRE>struct <B>tm;</B></PRE>

<P><CODE>struct</CODE> <CODE>tm</CODE> contains members that describe various
properties of the calendar time. The declaration in this header leaves
<CODE>struct <A HREF="time.html#tm">tm</A></CODE> an incomplete type.
Include the header
<A HREF="time.html#&lt;time.h&gt;"><CODE>&lt;time.h&gt;</CODE></A>
to complete the type.</P>

<H2><A NAME="ungetwc"><CODE>ungetwc</CODE></A></H2>

<PRE>wint_t <B>ungetwc</B>(wint_t c, FILE *stream);</PRE>

<P>If <CODE>c</CODE> is not equal to
<A HREF="#WEOF"><CODE>WEOF</CODE></A>, the function stores
<CODE>(<A HREF="#wchar_t">wchar_t</A>)c</CODE>
in the object whose address is <CODE>stream</CODE> and
clears the end-of-file indicator. If <CODE>c</CODE> equals
<A HREF="#WEOF"><CODE>WEOF</CODE></A> or
the store cannot occur, the function returns
<A HREF="#WEOF"><CODE>WEOF</CODE></A>; otherwise,
it returns <CODE>(<A HREF="#wchar_t">wchar_t</A>)c</CODE>.
A subsequent library function call that
reads a wide character from the stream <CODE>stream</CODE> obtains this
stored value, which is then forgotten.</P>

<P>Thus, you can effectively
<A HREF="stdio.html#push back">push back</A> a wide character
to a stream after reading a wide character.</P>

<H2><A NAME="vfwprintf"><CODE>vfwprintf</CODE></A></H2>

<PRE>int <B>vfwprintf</B>(FILE *stream, const wchar_t *format,
    va_list arg);</PRE>

<P>The function
<A HREF="lib_prin.html#Print Functions">generates formatted text</A>,
under the control of the format <CODE>format</CODE>
and any additional arguments, and writes
each generated wide character to the stream <CODE>stream</CODE>.
It returns the number of wide characters generated,
or it returns a negative value
if the function sets the error indicator for the stream.</P>

<P>The function accesses additional arguments by using the context
information designated by <CODE>ap</CODE>.
The program must execute the macro
<A HREF="stdarg.html#va_start"><CODE>va_start</CODE></A>
before it calls the function, and then execute the macro
<A HREF="stdarg.html#va_end"><CODE>va_end</CODE></A>
after the function returns.</P>

<H2><A NAME="vswprintf"><CODE>vswprintf</CODE></A></H2>

<PRE>int <B>vswprintf</B>(wchar_t *s, size_t n, const wchar_t *format,
    va_list arg);</PRE>

<P>The function
<A HREF="lib_prin.html#Print Functions">generates formatted text</A>,
under the control of the format <CODE>format</CODE>
and any additional arguments, and stores
each generated wide character in successive locations of the array object
whose first element has the address <CODE>s</CODE>.
The function concludes by storing a null wide character
in the next location of the array.
If it cannot generate and store all characters in an array of size <CODE>n</CODE>,
the function returns a negative number. Otherwise,
it returns the number of wide characters generated -- not including
the null wide character.</P>

<P>The function accesses additional arguments by using the context
information designated by <CODE>ap</CODE>.
The program must execute the macro