wchar.html

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

that stores a complete null multibyte character at <CODE>dst</CODE>
(including 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>),
the function 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="#wcrtomb"><CODE>wcrtomb</CODE></A>
returns <CODE>(<A HREF="#size_t">size_t</A>)-1</CODE>,
indicating that it has detected an invalid wide-character code

<LI>the number of bytes successfully converted, not including the
terminating null byte
</UL>

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

<PRE>size_t <B>wcsspn</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>none</I> of the elements
of the wide string <CODE>s2</CODE> and returns <CODE>i</CODE>. It considers
the terminating null wide character as
part of the wide string <CODE>s1</CODE> only.</P>

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

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

<P>The function searches for the first sequence of elements in
the wide string <CODE>s1</CODE> that matches the sequence of elements in
the wide string <CODE>s2</CODE>, <I>not</I> including its terminating null
wide character. If successful, the function returns the address of
the matching first element; otherwise, it returns a null pointer.</P>

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

<PRE>double <B>wcstod</B>(const wchar_t *nptr,
    wchar_t **endptr);</PRE>

<P>The function converts the initial wide characters of the wide
string <CODE>s</CODE> to an equivalent value <CODE>x</CODE>
of type <I>double.</I> If <CODE>endptr</CODE> is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in <CODE>*endptr</CODE>.
The function then returns <CODE>x</CODE>.</P>

<P>The initial wide characters of the wide string <CODE>s</CODE> must
match the same pattern as recognized by the function
<A HREF="stdlib.html#strtod"><CODE>strtod</CODE></A>,
where each wide character <CODE>wc</CODE> is converted as if by calling
<CODE><A HREF="#wctob">wctob</A>(wc))</CODE>.</P>

<P>If the wide string <CODE>s</CODE> matches this pattern,
its equivalent value is the value returned by
<A HREF="stdlib.html#strtod"><CODE>strtod</CODE></A>
for the converted sequence.
If the wide string <CODE>s</CODE> does not match a valid pattern,
the value stored in <CODE>*endptr</CODE> is <CODE>s</CODE>,
and <CODE>x</CODE> is zero. If a
<A HREF="math.html#range error">range error</A> occurs,
<CODE>wcstod</CODE> behaves exactly as the functions declared in
<A HREF="math.html#&lt;math.h&gt;"><CODE>&lt;math.h&gt;</CODE></A>.</P>

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

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

<P>If <CODE>s1</CODE> is not a null pointer, the function begins a search
of the wide string <CODE>s1</CODE>. Otherwise, it begins a search of the
wide string whose address was last stored in <CODE>*ptr</CODE> on an earlier
call to the function, as described below. The search proceeds as follows:</P>

<OL>
<LI>The function searches the wide string for <CODE>begin,</CODE> the
address of the first element that equals <I>none</I> of the elements
of the wide string <CODE>s2</CODE> (a set of token separators). It considers
the terminating null character as part of the search wide string only.

<LI>If the search does not find an element, the function stores
the address of the terminating null wide character in <CODE>*ptr</CODE>
(so that a subsequent search beginning with that address will fail)
and returns a null pointer. Otherwise, the function searches from
<CODE>begin</CODE> for <CODE>end,</CODE>
the address of the first element that
equals <I>any one</I> of the elements of the wide string <CODE>s2</CODE>.
It again considers the terminating null wide character as part of
the search string only.

<LI>If the search does not find an element, the function stores
the address of the terminating null wide character in <CODE>*ptr</CODE>.
Otherwise, it stores a null wide character in the element whose address
is <CODE>end.</CODE> Then it stores the address of the next element after
<CODE>end</CODE> in <CODE>*ptr</CODE>
(so that a subsequent search beginning with
that address will continue with the remaining elements of the string)
and returns <CODE>begin</CODE>.
</OL>

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

<PRE>long <B>wcstol</B>(const wchar_t *nptr, wchar_t **endptr,
    int base);</PRE>

<P>The function converts the initial wide characters of the wide
string <CODE>s</CODE> to an equivalent value <CODE>x</CODE>
of type <I>long.</I> If <CODE>endptr</CODE> is not a null pointer,
the function stores a pointer to the unconverted remainder
of the wide string in <CODE>*endptr</CODE>.
The function then returns <CODE>x</CODE>.</P>

<P>The initial wide characters of the wide string <CODE>s</CODE> must
match the same pattern as recognized by the function
<A HREF="stdlib.html#strtol"><CODE>strtol</CODE></A>,
with the same <CODE>base</CODE> argument,
where each wide character <CODE>wc</CODE> is converted as if by calling
<CODE><A HREF="#wctob">wctob</A>(wc))</CODE>.</P>

<P>If the wide string <CODE>s</CODE> matches this pattern,
its equivalent value is the value returned by
<A HREF="stdlib.html#strtol"><CODE>strtol</CODE></A>,
with the same <CODE>base</CODE> argument,
for the converted sequence.
If the wide string <CODE>s</CODE> does not match a valid pattern,
the value stored in <CODE>*endptr</CODE> is <CODE>s</CODE>,
and <CODE>x</CODE> is zero. If the equivalent value is too large
in magnitude to represent as type <I>long,</I>
<CODE>wcstol</CODE> stores the value of
<A HREF="errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
<A HREF="errno.html#errno"><CODE>errno</CODE></A> and returns either
<A HREF="limits.html#LONG_MAX"><CODE>LONG_MAX</CODE></A>
if <CODE>x</CODE> is positive or
<A HREF="limits.html#LONG_MIN"><CODE>LONG_MIN</CODE></A>
if <CODE>x</CODE> is negative.</P>

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

<PRE>unsigned long <B>wcstoul</B>(const wchar_t *nptr,
     wchar_t **endptr, int base);</PRE>

<P>The function converts the initial wide characters of the wide
string <CODE>s</CODE> to an equivalent value <CODE>x</CODE>
of type <I>unsigned long.</I> If <CODE>endptr</CODE> is not a null pointer,
it stores a pointer to the unconverted remainder
of the wide string in <CODE>*endptr</CODE>.
The function then returns <CODE>x</CODE>.</P>

<P><CODE>wcstoul</CODE> converts strings exactly as does
<A HREF="#wcstol"><CODE>wcstol</CODE></A>,
but checks only if the equivalent value is too large
to represent as type <I>unsigned long.</I>
In this case, <CODE>wcstoul</CODE> stores the value of
<A HREF="errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
<A HREF="errno.html#errno"><CODE>errno</CODE></A> and returns
<A HREF="limits.html#ULONG_MAX"><CODE>ULONG_MAX</CODE></A>.

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

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

<P>The function stores a wide string in the array
whose first element has the address <CODE>s1</CODE>. It stores no more than
<CODE>n</CODE> wide characters, <I>including</I> the terminating null wide
character, and returns the number of wide characters needed to represent
the entire wide string, <I>not</I> including the terminating null
wide character. If the value returned is <CODE>n</CODE> or greater, the
values stored in the array are indeterminate. (If <CODE>n</CODE> is zero,
<CODE>s1</CODE> can be a null pointer.)</P>

<P><CODE>wcsxfrm</CODE> generates the wide string it stores from the
wide string <CODE>s2</CODE> by using a transformation rule that depends
on the current
<A HREF="locale.html#locale">locale</A>.
For example, if <CODE>x</CODE> is a transformation
of <CODE>s1</CODE> and <CODE>y</CODE> is a transformation
of <CODE>s2</CODE>, then
<CODE><A HREF="#wcscmp">wcscmp</A>(x, y)</CODE>
returns the same value as
<CODE><A HREF="#wcscoll">wcscoll</A>(s1, s2)</CODE>.</P>

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

<PRE>int <B>wctob</B>(wint_t c);</PRE>

<P>The function determines whether <CODE>c</CODE> can be represented
as a one-byte multibyte character <CODE>x</CODE>, beginning in the
<A HREF="charset.html#initial shift state">initial shift state</A>.
(It effectively calls
<A HREF="#wcrtomb"><CODE>wcrtomb</CODE></A>
to make the conversion.) If so, the function returns
<CODE>x</CODE>. Otherwise, it returns
<A HREF="stdio.html#EOF"><CODE>EOF</CODE></A>.</P>

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

<PRE>#define <B>WEOF</B> <I>&lt;</I>wint_t <I>constant expression&gt;</I></PRE>

<P>The macro yields the return value, of type
<A HREF="#wint_t"><CODE>wint_t</CODE></A>,
used to signal the end of a
<A HREF="lib_file.html#wide stream">wide stream</A>
or to report an error condition.</P>

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

<PRE>typedef <I>i_type</I> <B>wint_t;</B></PRE>

<P>The type is the integer type <CODE><I>i_type</I></CODE>
that can represent all values of type
<A HREF="#wchar_t"><CODE>wchar_t</CODE></A>
as well as the value of the macro
<A HREF="#WEOF"><CODE>WEOF</CODE></A>,
and that doesn't change when
<A HREF="express.html#Promoting">promoted</A>.</P>

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

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

<P>The function searches for the first element of an array
beginning at the address <CODE>s</CODE> with size <CODE>n</CODE>,
that equals <CODE>c</CODE>. If successful,
it returns the address of the matching element;
otherwise, it returns a null pointer.</P>

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

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

<P>The function compares successive elements from two arrays
beginning at the addresses <CODE>s1</CODE> and <CODE>s2</CODE>
(both of size <CODE>n</CODE>),
until it finds elements that are not equal:</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, the function returns a negative number.
</UL>

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

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

<P>The function copies the array beginning at
the address <CODE>s2</CODE> to the array beginning at
the address <CODE>s1</CODE> (both of size <CODE>n</CODE>).
It returns <CODE>s1</CODE>.
The elements of the arrays can be accessed and stored in any order.</P>

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

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

<P>The function copies the array beginning at
<CODE>s2</CODE> to the array beginning at <CODE>s1</CODE> (both
of size <CODE>n</CODE>). It returns <CODE>s1</CODE>.
If the arrays overlap, the
function accesses each of the element values from <CODE>s2</CODE> before
it stores a new value in that element, so the copy is not corrupted.</P>

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

<PRE>wchar_t *<B>wmemset</B>(wchar_t *s, wchar_t c, size_t n);</PRE>

<P>The function stores <CODE>c</CODE> in each of the elements of the
array beginning at <CODE>s</CODE>, with size <CODE>n</CODE>.
It returns <CODE>s</CODE>.</P>

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

<PRE>int <B>wprintf</B>(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 writes
each generated wide character to the stream
<A HREF="stdio.html#stdout"><CODE>stdout</CODE></A>. 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>

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

<PRE>int <B>wscanf</B>(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 obtains each
scanned wide character from the stream
<A HREF="stdio.html#stdin"><CODE>stdin</CODE></A>. It returns the
number of input 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 sets the end-of-file
or error indicators for the stream.</P>

<HR>
<P>See also the
<B><A HREF="index.html#Table of Contents">Table of Contents</A></B> and the
<B><A HREF="_index.html">Index</A></B>.</P>

<P><I>
<A HREF="crit_pb.html">Copyright</A> &#169; 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.</I></P>

<!--V4.01:1125--></BODY></HTML>