1416 lines
59 KiB
HTML
1416 lines
59 KiB
HTML
<HTML><HEAD><TITLE><wchar.h></TITLE></HEAD><BODY BGCOLOR="#FFFFFF">
|
|
|
|
<H1><A NAME="<wchar.h>"><CODE><wchar.h></CODE></A>
|
|
[Added with
|
|
<A HREF="lib_over.html#Amendment 1" tppabs="http://ccs.ucsd.edu/c/lib_over.html#Amendment 1">Amendment 1</A>]</H1><HR>
|
|
|
|
<P><B><CODE><A HREF="#btowc">btowc</A>
|
|
· <A HREF="#fgetwc">fgetwc</A>
|
|
· <A HREF="#fgetws">fgetws</A>
|
|
· <A HREF="#fputwc">fputwc</A>
|
|
· <A HREF="#fputws">fputws</A>
|
|
· <A HREF="#fwide">fwide</A>
|
|
· <A HREF="#fwprintf">fwprintf</A>
|
|
· <A HREF="#fwscanf">fwscanf</A>
|
|
· <A HREF="#getwc">getwc</A>
|
|
· <A HREF="#getwchar">getwchar</A>
|
|
· <A HREF="#mbrlen">mbrlen</A>
|
|
· <A HREF="#mbrtowc">mbrtowc</A>
|
|
· <A HREF="#mbsinit">mbsinit</A>
|
|
· <A HREF="#mbsrtowcs">mbsrtowcs</A>
|
|
· <A HREF="#mbstate_t">mbstate_t</A>
|
|
· <A HREF="#NULL">NULL</A>
|
|
· <A HREF="#putwc">putwc</A>
|
|
· <A HREF="#putwchar">putwchar</A>
|
|
· <A HREF="#size_t">size_t</A>
|
|
· <A HREF="#swprintf">swprintf</A>
|
|
· <A HREF="#swscanf">swscanf</A>
|
|
· <A HREF="#tm">tm</A>
|
|
· <A HREF="#ungetwc">ungetwc</A>
|
|
· <A HREF="#vfwprintf">vfwprintf</A>
|
|
· <A HREF="#vswprintf">vswprintf</A>
|
|
· <A HREF="#vwprintf">vwprintf</A>
|
|
· <A HREF="#WCHAR_MAX">WCHAR_MAX</A>
|
|
· <A HREF="#WCHAR_MIN">WCHAR_MIN</A>
|
|
· <A HREF="#wchar_t">wchar_t</A>
|
|
· <A HREF="#wcrtomb">wcrtomb</A>
|
|
· <A HREF="#wcscat">wcscat</A>
|
|
· <A HREF="#wcschr">wcschr</A>
|
|
· <A HREF="#wcscmp">wcscmp</A>
|
|
· <A HREF="#wcscoll">wcscoll</A>
|
|
· <A HREF="#wcscpy">wcscpy</A>
|
|
· <A HREF="#wcscspn">wcscspn</A>
|
|
· <A HREF="#wcsftime">wcsftime</A>
|
|
· <A HREF="#wcslen">wcslen</A>
|
|
· <A HREF="#wcsncat">wcsncat</A>
|
|
· <A HREF="#wcsncmp">wcsncmp</A>
|
|
· <A HREF="#wcsncpy">wcsncpy</A>
|
|
· <A HREF="#wcspbrk">wcspbrk</A>
|
|
· <A HREF="#wcsrchr">wcsrchr</A>
|
|
· <A HREF="#wcsrtombs">wcsrtombs</A>
|
|
· <A HREF="#wcsspn">wcsspn</A>
|
|
· <A HREF="#wcsstr">wcsstr</A>
|
|
· <A HREF="#wcstod">wcstod</A>
|
|
· <A HREF="#wcstok">wcstok</A>
|
|
· <A HREF="#wcstol">wcstol</A>
|
|
· <A HREF="#wcstoul">wcstoul</A>
|
|
· <A HREF="#wcsxfrm">wcsxfrm</A>
|
|
· <A HREF="#wctob">wctob</A>
|
|
· <A HREF="#WEOF">WEOF</A>
|
|
· <A HREF="#wint_t">wint_t</A>
|
|
· <A HREF="#wmemchr">wmemchr</A>
|
|
· <A HREF="#wmemcmp">wmemcmp</A>
|
|
· <A HREF="#wmemcpy">wmemcpy</A>
|
|
· <A HREF="#wmemmove">wmemmove</A>
|
|
· <A HREF="#wmemset">wmemset</A>
|
|
· <A HREF="#wprintf">wprintf</A>
|
|
· <A HREF="#wscanf">wscanf</A>
|
|
</CODE></B></P>
|
|
<HR>
|
|
|
|
<P><CODE>
|
|
#define <A HREF="#NULL"><B>NULL</B></A>
|
|
<I><either 0, 0L, or (void *)0></I> <B>[0 in C++]</B><BR>
|
|
#define <A HREF="#WCHAR_MAX"><B>WCHAR_MAX</B></A>
|
|
<I><#if expression >= 127></I><BR>
|
|
#define <A HREF="#WCHAR_MIN"><B>WCHAR_MIN</B></A>
|
|
<I><#if expression <= 0></I><BR>
|
|
#define <A HREF="#WEOF"><B>WEOF</B></A>
|
|
<I><</I>wint_t <I>constant expression></I><BR>
|
|
wint_t <A HREF="#btowc"><B>btowc</B></A>(int c);<BR>
|
|
wint_t <A HREF="#fgetwc"><B>fgetwc</B></A>(FILE *stream);<BR>
|
|
wchar_t *<A HREF="#fgetws"><B>fgetws</B></A>(wchar_t *s, int n,
|
|
FILE *stream);<BR>
|
|
wint_t <A HREF="#fputwc"><B>fputwc</B></A>(wchar_t c,
|
|
FILE *stream);<BR>
|
|
int <A HREF="#fputws"><B>fputws</B></A>(const wchar_t *s,
|
|
FILE *stream);<BR>
|
|
int <A HREF="#fwide"><B>fwide</B></A>(FILE *stream,
|
|
int mode);<BR>
|
|
int <A HREF="#fwprintf"><B>fwprintf</B></A>(FILE *stream,
|
|
const wchar_t *format, ...);<BR>
|
|
int <A HREF="#fwscanf"><B>fwscanf</B></A>(FILE *stream,
|
|
const wchar_t *format, ...);<BR>
|
|
wint_t <A HREF="#getwc"><B>getwc</B></A>(FILE *stream);<BR>
|
|
wint_t <A HREF="#getwchar"><B>getwchar</B></A>(void);<BR>
|
|
size_t <A HREF="#mbrlen"><B>mbrlen</B></A>(const char *s,
|
|
size_t n, mbstate_t *ps);<BR>
|
|
size_t <A HREF="#mbrtowc"><B>mbrtowc</B></A>(wchar_t *pwc,
|
|
const char *s, size_t n, mbstate_t *ps);<BR>
|
|
int <A HREF="#mbsinit"><B>mbsinit</B></A>(const
|
|
mbstate_t *ps);<BR>
|
|
size_t <A HREF="#mbsrtowcs"><B>mbsrtowcs</B></A>(wchar_t *dst,
|
|
const char **src, size_t len, mbstate_t *ps);<BR>
|
|
typedef
|
|
<I>o-type</I> <A HREF="#mbstate_t"><B>mbstate_t</B></A>;<BR>
|
|
wint_t <A HREF="#putwc"><B>putwc</B></A>(wchar_t c,
|
|
FILE *stream);<BR>
|
|
wint_t <A HREF="#putwchar"><B>putwchar</B></A>(wchar_t c);<BR>
|
|
typedef <I>ui-type</I> <A HREF="#size_t"><B>size_t</B></A>;<BR>
|
|
int <A HREF="#swprintf"><B>swprintf</B></A>(wchar_t *s,
|
|
size_t n, const wchar_t *format, ...);<BR>
|
|
int <A HREF="#swscanf"><B>swscanf</B></A>(const wchar_t *s,
|
|
const wchar_t *format, ...);<BR>
|
|
struct <A HREF="#tm"><B>tm</B></A>;<BR>
|
|
wint_t <A HREF="#ungetwc"><B>ungetwc</B></A>(wint_t c,
|
|
FILE *stream);<BR>
|
|
int <A HREF="#vfwprintf"><B>vfwprintf</B></A>(FILE *stream,
|
|
const wchar_t *format, va_list arg);<BR>
|
|
int <A HREF="#vswprintf"><B>vswprintf</B></A>(wchar_t *s,
|
|
size_t n, const wchar_t *format, va_list arg);<BR>
|
|
int <A HREF="#vwprintf"><B>vwprintf</B></A>(const wchar_t *format,
|
|
va_list arg);<BR>
|
|
typedef <I>i-type</I> <A HREF="#wchar_t"><B>wchar_t</B></A>;
|
|
<B>[keyword in C++]</B><BR>
|
|
size_t <A HREF="#wcrtomb"><B>wcrtomb</B></A>(char *s,
|
|
wchar_t wc, mbstate_t *ps);<BR>
|
|
wchar_t *<A HREF="#wcscat"><B>wcscat</B></A>(wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
wchar_t *<A HREF="#wcschr"><B>wcschr</B></A>(const wchar_t *s,
|
|
wchar_t c);<BR>
|
|
int <A HREF="#wcscmp"><B>wcscmp</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
int <A HREF="#wcscoll"><B>wcscoll</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
wchar_t *<A HREF="#wcscpy"><B>wcscpy</B></A>(wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
size_t <A HREF="#wcscspn"><B>wcscspn</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
size_t <A HREF="#wcsftime"><B>wcsftime</B></A>(wchar_t *s,
|
|
size_t maxsize, const wchar_t *format, const struct tm *timeptr);<BR>
|
|
size_t <A HREF="#wcslen"><B>wcslen</B></A>(const wchar_t *s);<BR>
|
|
wchar_t *<A HREF="#wcsncat"><B>wcsncat</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
int <A HREF="#wcsncmp"><B>wcsncmp</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
wchar_t *<A HREF="#wcsncpy"><B>wcsncpy</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
wchar_t *<A HREF="#wcspbrk"><B>wcspbrk</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
wchar_t *<A HREF="#wcsrchr"><B>wcsrchr</B></A>(const wchar_t *s,
|
|
wchar_t c);<BR>
|
|
size_t <A HREF="#wcsrtombs"><B>wcsrtombs</B></A>(char *dst,
|
|
const wchar_t **src, size_t len, mbstate_t *ps);<BR>
|
|
size_t <A HREF="#wcsspn"><B>wcsspn</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
wchar_t *<A HREF="#wcsstr"><B>wcsstr</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2);<BR>
|
|
double <A HREF="#wcstod"><B>wcstod</B></A>(const wchar_t *nptr,
|
|
wchar_t **endptr);<BR>
|
|
wchar_t *<A HREF="#wcstok"><B>wcstok</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, wchar_t **ptr);<BR>
|
|
long <A HREF="#wcstol"><B>wcstol</B></A>(const wchar_t *nptr,
|
|
wchar_t **endptr, int base);<BR>
|
|
unsigned long <A HREF="#wcstoul"><B>wcstoul</B></A>(const
|
|
wchar_t *nptr, wchar_t **endptr, int base);<BR>
|
|
size_t <A HREF="#wcsxfrm"><B>wcsxfrm</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
int <A HREF="#wctob"><B>wctob</B></A>(wint_t c);<BR>
|
|
typedef <I>i_type</I> <A HREF="#wint_t"><B>wint_t</B></A>;<BR>
|
|
wchar_t *<A HREF="#wmemchr"><B>wmemchr</B></A>(const wchar_t *s,
|
|
wchar_t c, size_t n);<BR>
|
|
int <A HREF="#wmemcmp"><B>wmemcmp</B></A>(const wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
wchar_t *<A HREF="#wmemcpy"><B>wmemcpy</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
wchar_t *<A HREF="#wmemmove"><B>wmemmove</B></A>(wchar_t *s1,
|
|
const wchar_t *s2, size_t n);<BR>
|
|
wchar_t *<A HREF="#wmemset"><B>wmemset</B></A>(wchar_t *s,
|
|
wchar_t c, size_t n);<BR>
|
|
int <A HREF="#wprintf"><B>wprintf</B></A>(const wchar_t *format,
|
|
...);<BR>
|
|
int <A HREF="#wscanf"><B>wscanf</B></A>(const wchar_t *format,
|
|
...);
|
|
</CODE></P>
|
|
|
|
<P>Include the standard header <B><CODE><wchar.h></CODE></B>
|
|
so that you can perform input and output operations on
|
|
wide streams or manipulate wide strings.</P>
|
|
|
|
<H2><A NAME="NULL"><CODE>NULL</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>NULL</B> <I><either 0, 0L, or (void *)0></I>
|
|
<B>[0 in C++]</B>
|
|
</CODE></P>
|
|
|
|
<P>The macro yields a null pointer constant that is usable as an
|
|
<A HREF="express.html#address constant expression" tppabs="http://ccs.ucsd.edu/c/express.html#address constant expression">
|
|
address constant expression</A>.</P>
|
|
|
|
<H2><A NAME="WCHAR_MAX"><CODE>WCHAR_MAX</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>WCHAR_MAX</B> <I><#if expression >= 127></I>
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
#define <B>WCHAR_MIN</B> <I><#if expression <= 0></I>
|
|
</CODE></P>
|
|
|
|
<P>The macro yields the minimum value for type
|
|
<A HREF="#wchar_t"><CODE>wchar_t</CODE></A>.</P>
|
|
|
|
<H2><A NAME="WEOF"><CODE>WEOF</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>WEOF</B> <I><</I>wint_t <I>constant expression></I>
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/lib_file.html#wide stream">wide stream</A>
|
|
or to report an error condition.</P>
|
|
|
|
<H2><A NAME="btowc"><CODE>btowc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>btowc</B>(int c);
|
|
</CODE></P>
|
|
|
|
<P>The function returns
|
|
<A HREF="#WEOF"><CODE>WEOF</CODE></A> if <CODE>c</CODE> equals
|
|
<A HREF="stdio.html#EOF" tppabs="http://ccs.ucsd.edu/c/stdio.html#EOF"><CODE>EOF</CODE></A>.
|
|
Otherwise, it converts <CODE>(unsigned char)c</CODE>
|
|
as a one-byte multibyte character beginning in the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversoon state</A>,
|
|
as if by calling
|
|
<A HREF="#mbrtowc"><CODE>mbrtowc</CODE></A>.
|
|
If the conversion succeeds, the function returns the wide-character
|
|
conversion. Otherwise, it returns
|
|
<A HREF="#WEOF"><CODE>WEOF</CODE></A>.</P>
|
|
|
|
<H2><A NAME="fgetwc"><CODE>fgetwc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>fgetwc</B>(FILE *stream);
|
|
</CODE></P>
|
|
|
|
<P>The function reads the next wide character <CODE>c</CODE> (if present)
|
|
from the input stream <CODE>stream</CODE>,
|
|
advances the file-position indicator (if defined), and returns
|
|
<CODE>(<A HREF="#wint_t">wint_t</A>)c</CODE>.
|
|
If the function sets either the end-of-file indicator
|
|
or the error indicator, it returns
|
|
<A HREF="#WEOF"><CODE>WEOF</CODE></A>.</P>
|
|
|
|
<H2><A NAME="fgetws"><CODE>fgetws</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>fgetws</B>(wchar_t *s, int n, FILE *stream);
|
|
</CODE></P>
|
|
|
|
<P>The function reads wide characters
|
|
from the input stream <CODE>stream</CODE>
|
|
and stores them in successive elements of the array
|
|
beginning at <CODE>s</CODE> and continuing until it stores
|
|
<CODE>n - 1</CODE> wide characters, stores an <CODE><I>NL</I></CODE>
|
|
wide character, or sets the end-of-file or error indicators. If
|
|
<CODE>fgetws</CODE> stores any wide characters, it concludes by storing
|
|
a null wide character in the next element of the array. It returns
|
|
<CODE>s</CODE> if it stores any wide characters and it has not set the error
|
|
indicator for the stream; otherwise, it returns a null pointer. If
|
|
it sets the error indicator, the array contents are indeterminate.</P>
|
|
|
|
<H2><A NAME="fputwc"><CODE>fputwc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>fputwc</B>(wchar_t c, FILE *stream);
|
|
</CODE></P>
|
|
|
|
<P>The function writes the wide character <CODE>c</CODE> to the output
|
|
stream <CODE>stream</CODE>, advances the file-position indicator
|
|
(if defined), and returns
|
|
<CODE>(<A HREF="#wint_t">wint_t</A>)c</CODE>.
|
|
If the function sets the error indicator for the stream, it returns
|
|
<A HREF="#WEOF"><CODE>WEOF</CODE></A>.</P>
|
|
|
|
<H2><A NAME="fputws"><CODE>fputws</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>fputws</B>(const wchar_t *s, FILE *stream);
|
|
</CODE></P>
|
|
|
|
<P>The function accesses wide characters from the string <CODE>s</CODE>
|
|
and writes them to the output stream <CODE>stream</CODE>. The function does
|
|
not write the terminating null wide character. It returns a nonnegative
|
|
value if it has not set the error indicator; otherwise, it returns
|
|
<A HREF="#WEOF"><CODE>WEOF</CODE></A>.</P>
|
|
|
|
<H2><A NAME="fwide"><CODE>fwide</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>fwide</B>(FILE *stream, int mode);
|
|
</CODE></P>
|
|
|
|
<P>The function determines the orientation of the stream <CODE>stream</CODE>.
|
|
If <CODE>mode</CODE> is greater than zero,
|
|
it first attempts to make the stream
|
|
<A HREF="lib_file.html#wide oriented" tppabs="http://ccs.ucsd.edu/c/lib_file.html#wide oriented">wide oriented</A>.
|
|
If <CODE>mode</CODE> is less than zero,
|
|
it first attempts to make the stream
|
|
<A HREF="lib_file.html#byte oriented" tppabs="http://ccs.ucsd.edu/c/lib_file.html#byte oriented">byte oriented</A>.
|
|
In any event, the function returns:</P>
|
|
|
|
<UL>
|
|
<LI>a value greater than zero if the stream is left
|
|
<A HREF="lib_file.html#wide oriented" tppabs="http://ccs.ucsd.edu/c/lib_file.html#wide oriented">wide oriented</A>
|
|
|
|
<LI>zero if the stream is left
|
|
<A HREF="lib_file.html#unbound stream" tppabs="http://ccs.ucsd.edu/c/lib_file.html#unbound stream">unbound</A>
|
|
|
|
<LI>a value less than zero if the stream is left
|
|
<A HREF="lib_file.html#byte oriented" tppabs="http://ccs.ucsd.edu/c/lib_file.html#byte oriented">byte oriented</A>
|
|
</UL>
|
|
|
|
<P>In no event will the function alter the orientation of a stream
|
|
once it has been oriented.</P>
|
|
|
|
<H2><A NAME="fwprintf"><CODE>fwprintf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>fwprintf</B>(FILE *stream, const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<H2><A NAME="fwscanf"><CODE>fwscanf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>fwscanf</B>(FILE *stream, const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_scan.html#Scan Functions" tppabs="http://ccs.ucsd.edu/c/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 character from the stream <CODE>stream</CODE>. It returns the number
|
|
of input items matched and assigned, or it returns
|
|
<A HREF="stdio.html#EOF" tppabs="http://ccs.ucsd.edu/c/stdio.html#EOF"><CODE>EOF</CODE></A> if the
|
|
function does not store values before it sets the end-of-file or error
|
|
indicator for the stream.</P>
|
|
|
|
<H2><A NAME="getwc"><CODE>getwc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>getwc</B>(FILE *stream);
|
|
</CODE></P>
|
|
|
|
<P>The function has the same effect as
|
|
<CODE><A HREF="#fgetwc">fgetwc</A>(stream)</CODE> except
|
|
that a macro version of <CODE>getwc</CODE> can evaluate
|
|
<CODE>stream</CODE> more than once.</P>
|
|
|
|
<H2><A NAME="getwchar"><CODE>getwchar</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>getwchar</B>(void);
|
|
</CODE></P>
|
|
|
|
<P>The function has the same effect as
|
|
<CODE><A HREF="#fgetwc">fgetwc</A>(stdin)</CODE>.</P>
|
|
|
|
<H2><A NAME="mbrlen"><CODE>mbrlen</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>mbrlen</B>(const char *s, size_t n, mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<P>The function is equivalent to the call:</P>
|
|
|
|
<P><CODE>
|
|
<A HREF="#mbrtowc">mbrtowc</A>(0, s, n,
|
|
ps != 0 ? ps : &internal)
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>,
|
|
<CODE>internal</CODE> is initialized to the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/errno.html#EILSEQ"><CODE>EILSEQ</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A> and leaves the resulting
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A> is the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
size_t <B>mbrtowc</B>(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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>&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" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>,
|
|
<CODE>internal</CODE> is initialized to the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/errno.html#EILSEQ"><CODE>EILSEQ</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
and leaves the resulting
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A> is the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
int <B>mbsinit</B>(const mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>.
|
|
Otherwise, it returns zero.</P>
|
|
|
|
<H2><A NAME="mbsrtowcs"><CODE>mbsrtowcs</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>mbsrtowcs</B>(wchar_t *dst, const char **src, size_t len, mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
x = mbrtowc(dst, *src, n, ps != 0 ? ps : &internal)
|
|
</CODE></P>
|
|
|
|
<P>where <CODE>n</CODE> is some value > 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" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>,
|
|
<CODE>internal</CODE> is initialized to the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
typedef <I>o-type</I> <B>mbstate_t;</B>
|
|
</CODE></P>
|
|
|
|
<P>The type is an object type <I>o-type</I> that can represent a
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
mbstate_t mbst = {0};
|
|
</CODE></P>
|
|
|
|
<P>ensures that <CODE>mbst</CODE> represents the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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="putwc"><CODE>putwc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>putwc</B>(wchar_t c, FILE *stream);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wint_t <B>putwchar</B>(wchar_t c);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
typedef <I>ui-type</I> <B>size_t;</B>
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/express.html#sizeof operator"><I>sizeof</I></A> operator.</P>
|
|
|
|
<H2><A NAME="swprintf"><CODE>swprintf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>swprintf</B>(wchar_t *s, size_t n, const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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.
|
|
It returns the number of wide characters generated -- not including
|
|
the null wide character.</P>
|
|
|
|
<H2><A NAME="swscanf"><CODE>swscanf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>swscanf</B>(const wchar_t *s, const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_scan.html#Scan Functions" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
struct <B>tm;</B>
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/time.html#tm">tm</A></CODE> an incomplete type.
|
|
Include the header
|
|
<A HREF="time.html#<time.h>" tppabs="http://ccs.ucsd.edu/c/time.html#<time.h>"><CODE><time.h></CODE></A>
|
|
to complete the type.</P>
|
|
|
|
<H2><A NAME="ungetwc"><CODE>ungetwc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wint_t <B>ungetwc</B>(wint_t c, FILE *stream);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
int <B>vfwprintf</B>(FILE *stream, const wchar_t *format, va_list arg);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/stdarg.html#va_end"><CODE>va_end</CODE></A>
|
|
after the function returns.</P>
|
|
|
|
<H2><A NAME="vswprintf"><CODE>vswprintf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>vswprintf</B>(wchar_t *s, size_t n, const wchar_t *format, va_list arg);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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.
|
|
It returns the number of 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
|
|
<A HREF="stdarg.html#va_start" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/stdarg.html#va_end"><CODE>va_end</CODE></A>
|
|
after the function returns.</P>
|
|
|
|
<H2><A NAME="vwprintf"><CODE>vwprintf</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>vwprintf</B>(const wchar_t *format, va_list arg);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/stdarg.html#va_end"><CODE>va_end</CODE></A>
|
|
after the function returns.</P>
|
|
|
|
<H2><A NAME="wchar_t"><CODE>wchar_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>i-type</I> <B>wchar_t;</B> <B>[keyword in C++]</B>
|
|
</CODE></P>
|
|
|
|
<P>The type is the integer type <CODE><I>i-type</I></CODE> of a
|
|
<A HREF="charset.html#wide-character constant" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/charset.html#Wide-Character Encoding">wide character</A>.</P>
|
|
|
|
<H2><A NAME="wcrtomb"><CODE>wcrtomb</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcrtomb</B>(char *s, wchar_t wc, mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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>&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" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>,
|
|
<CODE>internal</CODE> is initialized to the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/charset.html#shift sequence">shift sequence</A>
|
|
needed to restore the
|
|
<A HREF="charset.html#initial shift state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/errno.html#EILSEQ"><CODE>EILSEQ</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
and leaves the resulting
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcscat</B>(wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcschr</B>(const wchar_t *s, wchar_t c);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
int <B>wcscmp</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
int <B>wcscoll</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcscpy</B>(wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcscspn</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcsftime</B>(wchar_t *s, size_t maxsize, const wchar_t *format, const struct tm *timeptr);
|
|
</CODE></P>
|
|
|
|
<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 < 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" tppabs="http://ccs.ucsd.edu/c/time.html#strftime"><CODE>strftime</CODE></A>. The current
|
|
<A HREF="locale.html#locale category" tppabs="http://ccs.ucsd.edu/c/locale.html#locale category">locale category</A>
|
|
<A HREF="locale.html#LC_TIME" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcslen</B>(const wchar_t *s);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcsncat</B>(wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
int <B>wcsncmp</B>(const wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcsncpy</B>(wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcspbrk</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>&s1[i]</CODE>; otherwise, it returns a null pointer.</P>
|
|
|
|
<H2><A NAME="wcsrchr"><CODE>wcsrchr</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcsrchr</B>(const wchar_t *s, wchar_t c);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcsrtombs</B>(char *dst, const wchar_t **src, size_t len, mbstate_t *ps);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
x = wcrtomb(dst ? dst : buf, *src, ps != 0 ? ps : &internal)
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/lib_over.html#program startup">program startup</A>,
|
|
<CODE>internal</CODE> is initialized to the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/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
|
|
that stores a complete null multibyte character at <CODE>dst</CODE>
|
|
(including any
|
|
<A HREF="charset.html#shift sequence" tppabs="http://ccs.ucsd.edu/c/charset.html#shift sequence">shift sequence</A>
|
|
needed to restore the
|
|
<A HREF="charset.html#initial shift state" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcsspn</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcsstr</B>(const wchar_t *s1, const wchar_t *s2);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
double <B>wcstod</B>(const wchar_t *nptr, wchar_t **endptr);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/math.html#range error">range error</A> occurs,
|
|
<CODE>wcstod</CODE> behaves exactly as the functions declared in
|
|
<A HREF="math.html#<math.h>" tppabs="http://ccs.ucsd.edu/c/math.html#<math.h>"><CODE><math.h></CODE></A>.</P>
|
|
|
|
<H2><A NAME="wcstok"><CODE>wcstok</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wcstok</B>(wchar_t *s1, const wchar_t *s2, wchar_t **ptr);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
long <B>wcstol</B>(const wchar_t *nptr, wchar_t **endptr, int base);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A> and returns either
|
|
<A HREF="limits.html#LONG_MAX" tppabs="http://ccs.ucsd.edu/c/limits.html#LONG_MAX"><CODE>LONG_MAX</CODE></A>
|
|
if <CODE>x</CODE> is positive or
|
|
<A HREF="limits.html#LONG_MIN" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
unsigned long <B>wcstoul</B>(const wchar_t *nptr, wchar_t **endptr, int base);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A> and returns
|
|
<A HREF="limits.html#LONG_MAX" tppabs="http://ccs.ucsd.edu/c/limits.html#LONG_MAX"><CODE>ULONG_MAX</CODE></A>.
|
|
|
|
<H2><A NAME="wcsxfrm"><CODE>wcsxfrm</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcsxfrm</B>(wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
int <B>wctob</B>(wint_t c);
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/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="#WEOF"><CODE>WEOF</CODE></A>.</P>
|
|
|
|
<H2><A NAME="wint_t"><CODE>wint_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>i_type</I> <B>wint_t;</B>
|
|
</CODE></P>
|
|
|
|
<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" tppabs="http://ccs.ucsd.edu/c/express.html#Promoting">promoted</A>.</P>
|
|
|
|
<H2><A NAME="wmemchr"><CODE>wmemchr</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wmemchr</B>(const wchar_t *s, wchar_t c, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
int <B>wmemcmp</B>(const wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wmemcpy</B>(wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wmemmove</B>(wchar_t *s1, const wchar_t *s2, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
wchar_t *<B>wmemset</B>(wchar_t *s, wchar_t c, size_t n);
|
|
</CODE></P>
|
|
|
|
<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>
|
|
|
|
<P><CODE>
|
|
int <B>wprintf</B>(const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_prin.html#Print Functions" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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>
|
|
|
|
<P><CODE>
|
|
int <B>wscanf</B>(const wchar_t *format, ...);
|
|
</CODE></P>
|
|
|
|
<P>The function
|
|
<A HREF="lib_scan.html#Scan Functions" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/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" tppabs="http://ccs.ucsd.edu/c/index.html#Table of Contents">Table of Contents</A></B> and the
|
|
<B><A HREF="_index.html" tppabs="http://ccs.ucsd.edu/c/_index.html">Index</A></B>.</P>
|
|
|
|
<P><I>
|
|
<A HREF="crit_pb.html" tppabs="http://ccs.ucsd.edu/c/crit_pb.html">Copyright</A> © 1989-1996
|
|
by P.J. Plauger and Jim Brodie. All rights reserved.</I></P>
|
|
|
|
</BODY></HTML>
|