wchar.html

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

<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="vwprintf"><CODE>vwprintf</CODE></A></H2>

<PRE>int <B>vwprintf</B>(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
<A HREF="stdio.html#stdout"><CODE>stdout</CODE></A>.
It returns the number of characters generated,
or 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="WCHAR_MAX"><CODE>WCHAR_MAX</CODE></A></H2>

<PRE>#define <B>WCHAR_MAX</B> <I>&lt;#if expression &gt;= 127&gt;</I></PRE>

<P>The macro yields the maximum value for type
<A HREF="#wchar_t"><CODE>wchar_t</CODE></A>.</P>

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

<PRE>#define <B>WCHAR_MIN</B> <I>&lt;#if expression &lt;= 0&gt;</I></PRE>

<P>The macro yields the minimum value for type
<A HREF="#wchar_t"><CODE>wchar_t</CODE></A>.</P>

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

<PRE>typedef <I>i-type</I> <B>wchar_t;</B> <B>[keyword in C++]</B></PRE>

<P>The type is the integer type <CODE><I>i-type</I></CODE> of a
<A HREF="charset.html#wide-character constant">
wide-character constant</A>, such as <CODE>L'X'</CODE>.
You declare an object of type <CODE>wchar_t</CODE> to hold a
<A HREF="charset.html#Wide-Character Encoding">wide character</A>.</P>

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

<PRE>size_t <B>wcrtomb</B>(char *s, wchar_t wc, mbstate_t *ps);</PRE>

<P>The function determines the number of bytes needed to represent
the wide character <CODE>wc</CODE> as a multibyte character, if possible.
(Not all values representable as type
<A HREF="#wchar_t"><CODE>wchar_t</CODE></A>
are necessarily valid wide-character codes.)</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>wcrtomb</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
and <CODE>wc</CODE> is a valid wide-character
code, the function determines <CODE>x,</CODE> the number of bytes needed
to represent <CODE>wc</CODE> as a multibyte character,
and stores the converted bytes in the array of <I>char</I>
beginning at <CODE>s</CODE>. (<CODE>x</CODE> cannot be greater than
<A HREF="stdlib.html#MB_CUR_MAX"><CODE>MB_CUR_MAX</CODE></A>.)
If <CODE>wc</CODE> is a null wide character,
the function stores any
<A HREF="charset.html#shift sequence">shift sequence</A>
needed to restore the
<A HREF="charset.html#initial shift state">initial shift state</A>.
followed by a null byte. The resulting conversion state is the
<A HREF="charset.html#initial conversion state">
initial conversion state</A>.</P>

<P>If <CODE>s</CODE> is a null pointer, the function effectively returns
<CODE>wcrtomb(buf, L'\0', ps)</CODE>, where <CODE>buf</CODE> is a
buffer internal to the function. (The function thus returns the number
of bytes needed to restore the
<A HREF="charset.html#initial conversion state">initial conversion state</A>
and to terminate the multibyte string
pending from a previous call to <CODE>wcrtomb</CODE> or
<A HREF="#wcsrtombs"><CODE>wcsrtombs</CODE></A>
for the same string and
<A HREF="charset.html#conversion state">conversion state</A>.)</P>

<P>The function returns:</P>

<UL>
<LI><CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>
if <CODE>wc</CODE> is an invalid wide-character code,
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><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 generated
</UL>

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

<PRE>wchar_t *<B>wcscat</B>(wchar_t *s1, const wchar_t *s2);</PRE>

<P>The function copies the wide string <CODE>s2</CODE>, including its
terminating null wide character, to successive elements of the array
that stores the wide string <CODE>s1</CODE>, beginning
with the element that stores the terminating null wide character of
<CODE>s1</CODE>. It returns <CODE>s1</CODE>.</P>

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

<PRE>wchar_t *<B>wcschr</B>(const wchar_t *s, wchar_t c); <B>[not in C++]</B>
const wchar_t *<B>wcschr</B>(const wchar_t *s, wchar_t c); <B>[C++ only]</B>
wchar_t *<B>wcschr</B>(wchar_t *s, wchar_t c); <B>[C++ only]</B></PRE>

<P>The function searches for the first element of the wide string
<CODE>s</CODE> that equals <CODE>c</CODE>.
It considers the terminating null wide
character as part of the wide string. If successful, the function
returns the address of the matching element; otherwise, it returns
a null pointer.</P>

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

<PRE>int <B>wcscmp</B>(const wchar_t *s1, const wchar_t *s2);</PRE>

<P>The function compares successive elements from two wide strings,
<CODE>s1</CODE> and <CODE>s2</CODE>,
until it finds elements that are not equal.</P>

<UL>
<LI>If all elements are equal, the function returns zero.
</UL>

<UL>
<LI>If the differing element from <CODE>s1</CODE> is greater than the
element from <CODE>s2</CODE>, the function returns a positive number.

<LI>Otherwise, the function returns a negative number.
</UL>

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

<PRE>int <B>wcscoll</B>(const wchar_t *s1, const wchar_t *s2);</PRE>

<P>The function compares two wide strings,
<CODE>s1</CODE> and <CODE>s2</CODE>,
using a comparison rule that depends on the current
<A HREF="locale.html#locale">locale</A>. If <CODE>s1</CODE> compares
greater than <CODE>s2</CODE> by this rule,
the function returns a positive number.
If the two wide strings compare equal, it returns zero. Otherwise, it
returns a negative number.</P>

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

<PRE>wchar_t *<B>wcscpy</B>(wchar_t *s1, const wchar_t *s2);</PRE>

<P>The function copies the wide string <CODE>s2</CODE>, including its
terminating null wide character, to successive elements of the array
whose first element has the address <CODE>s1</CODE>. It
returns <CODE>s1</CODE>.</P>

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

<PRE>size_t <B>wcscspn</B>(const wchar_t *s1, const wchar_t *s2);</PRE>

<P>The function searches for the first element <CODE>s1[i]</CODE>
in the wide string <CODE>s1</CODE> that equals <I>any one</I> of the elements
of the wide string <CODE>s2</CODE> and returns <CODE>i.</CODE>
Each terminating null wide character is considered
part of its wide string.</P>

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

<PRE>size_t <B>wcsftime</B>(wchar_t *s, size_t maxsize,
    const wchar_t *format, const struct tm *timeptr);</PRE>

<P>The function generates formatted text, under the control of
the format <CODE>format</CODE> and the values stored in the time structure
<CODE>*tptr</CODE>. It stores each generated wide character in successive
locations of the array object of size <CODE>n</CODE> whose first element
has the address <CODE>s</CODE>. The function then stores a null wide character
in the next location of the array. It returns <CODE>x</CODE>, the number
of wide characters generated, if <CODE>x &lt; n</CODE>; otherwise,
it returns zero, and the values stored in the array are indeterminate.</P>

<P>For each wide character other than <CODE>%</CODE> in the format, the
function stores that wide character in the array object. Each occurrence
of <CODE>%</CODE> followed by another character in the format is a
<B><A NAME="conversion specifier">conversion specifier.</A></B>
For each conversion specifier, the function stores a
replacement wide character sequence. Conversion specifiers are the
same as for the function
<A HREF="time.html#strftime"><CODE>strftime</CODE></A>. The current
<A HREF="locale.html#locale category">locale category</A>
<A HREF="locale.html#LC_TIME"><CODE>LC_TIME</CODE></A> can affect these
replacement character sequences.</P>

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

<PRE>size_t <B>wcslen</B>(const wchar_t *s);</PRE>

<P>The function returns the number of wide characters in the wide
string <CODE>s</CODE>, <I>not</I> including
its terminating null wide character.</P>

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

<PRE>wchar_t *<B>wcsncat</B>(wchar_t *s1, const wchar_t *s2,
    size_t n);</PRE>

<P>The function copies the wide string <CODE>s2</CODE>, <I>not</I> including
its terminating null wide character,
to successive elements of the array
that stores the wide string <CODE>s1</CODE>, beginning
with the element that stores the terminating null wide character of
<CODE>s1</CODE>. The function copies no more than
<CODE>n</CODE> wide characters from <CODE>s2</CODE>.
It then stores a null wide character, in the next
element to be altered in <CODE>s1</CODE>, and returns <CODE>s1</CODE>.</P>

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

<PRE>int <B>wcsncmp</B>(const wchar_t *s1, const wchar_t *s2,
    size_t n);</PRE>

<P>The function compares successive elements from two wide strings,
<CODE>s1</CODE> and <CODE>s2</CODE>, until it finds elements
that are not equal or until it has compared the first
<CODE>n</CODE> elements of the two wide strings.</P>

<UL>
<LI>If all elements are equal, the function returns zero.
<LI>If the differing element from <CODE>s1</CODE> is greater than the
element from <CODE>s2</CODE>, the function returns a positive number.

<LI>Otherwise, it returns a negative number.
</UL>

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

<PRE>wchar_t *<B>wcsncpy</B>(wchar_t *s1, const wchar_t *s2,
    size_t n);</PRE>

<P>The function copies the wide string <CODE>s2</CODE>, <I>not</I> including
its terminating null wide character, to successive elements of the array
whose first element has the address <CODE>s1</CODE>.
It copies no more than <CODE>n</CODE> wide characters
from <CODE>s2</CODE>. The function then stores
zero or more null wide characters in the next elements
to be altered in <CODE>s1</CODE> until it stores a total of <CODE>n</CODE>
wide characters. It returns <CODE>s1</CODE>.</P>

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

<PRE>wchar_t *<B>wcspbrk</B>(const wchar_t *s1, const wchar_t *s2); <B>[not in C++]</B>
const wchar_t *<B>wcspbrk</B>(const wchar_t *s1, const wchar_t *s2); <B>[C++ only]</B>
wchar_t *<B>wcspbrk</B>(wchar_t *s1, const wchar_t *s2); <B>[C++ only]</B></PRE>

<P>The function searches for the first element <CODE>s1[i]</CODE>
in the wide string <CODE>s1</CODE> that equals <I>any one</I> of the elements
of the wide string <CODE>s2</CODE>. It considers each terminating null wide
character as part of its wide string. If <CODE>s1[i]</CODE> is not
the terminating null wide character, the function returns
<CODE>&amp;s1[i]</CODE>; otherwise, it returns a null pointer.</P>

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

<PRE>wchar_t *<B>wcsrchr</B>(const wchar_t *s, wchar_t c); <B>[not in C++]</B>
const wchar_t *<B>wcsrchr</B>(const wchar_t *s, wchar_t c); <B>[C++ only]</B>
wchar_t *<B>wcsrchr</B>(wchar_t *s, wchar_t c); <B>[C++ only]</B></PRE>

<P>The function searches for the last element of the wide string
<CODE>s</CODE> that equals <CODE>c</CODE>.
It considers the terminating null wide
character as part of the wide string. If successful, the function
returns the address of the matching element; otherwise, it returns
a null pointer.</P>

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

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

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

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

<P>where <CODE>buf</CODE> is an array of type <I>char</I>
and <CODE>internal</CODE> is an object of type
<A HREF="#mbstate_t"><CODE>mbstate_t</CODE></A>,
both internal to the <CODE>wcsrtombs</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>wcsrtombs</CODE> function stores at most
<CODE>len</CODE> bytes by calls to
<A HREF="#wcrtomb"><CODE>wcrtomb</CODE></A>. The function
effectively increments <CODE>dst</CODE> by <CODE>x</CODE>
and <CODE>*src</CODE> by one after each call to
<A HREF="#wcrtomb"><CODE>wcrtomb</CODE></A>
that stores a <I>complete</I> converted
multibyte character in the remaining space available. After a call