Files
oldlinux-files/Ref-docs/C/wctype.html
2024-02-19 00:21:47 -05:00

463 lines
17 KiB
HTML

<HTML><HEAD><TITLE>&lt;wctype.h&gt;</TITLE></HEAD><BODY BGCOLOR="#FFFFFF">
<H1><A NAME="&lt;wctype.h&gt;"><CODE>&lt;wctype.h&gt;</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><CODE>
int <A HREF="#iswalnum"><B>iswalnum</B></A>(wint_t c);<BR>
int <A HREF="#iswalpha"><B>iswalpha</B></A>(wint_t c);<BR>
int <A HREF="#iswcntrl"><B>iswcntrl</B></A>(wint_t c);<BR>
int <A HREF="#iswctype"><B>iswctype</B></A>(wint_t c,
wctype_t category);<BR>
int <A HREF="#iswdigit"><B>iswdigit</B></A>(wint_t c);<BR>
int <A HREF="#iswgraph"><B>iswgraph</B></A>(wint_t c);<BR>
int <A HREF="#iswlower"><B>iswlower</B></A>(wint_t c);<BR>
int <A HREF="#iswprint"><B>iswprint</B></A>(wint_t c);<BR>
int <A HREF="#iswpunct"><B>iswpunct</B></A>(wint_t c);<BR>
int <A HREF="#iswspace"><B>iswspace</B></A>(wint_t c);<BR>
int <A HREF="#iswupper"><B>iswupper</B></A>(wint_t c);<BR>
int <A HREF="#iswxdigit"><B>iswxdigit</B></A>(wint_t c);<BR>
wint_t <A HREF="#towctrans"><B>towctrans</B></A>(wint_t c,
wctrans_t category);<BR>
wint_t <A HREF="#towlower"><B>towlower</B></A>(wint_t c);<BR>
wint_t <A HREF="#towupper"><B>towupper</B></A>(wint_t c);<BR>
wctrans_t <A HREF="#wctrans"><B>wctrans</B></A>(const
char *property);<BR>
typedef <I>s_type</I>
<A HREF="#wctrans_t"><B>wctrans_t</B></A>;<BR>
wctype_t <A HREF="#wctype"><B>wctype</B></A>(const
char *property);<BR>
typedef
<I>s_type</I> <A HREF="#wctype_t"><B>wctype_t</B></A>;<BR>
typedef <I>i_type</I> <A HREF="#wint_t"><B>wint_t</B></A>;<BR>
</CODE></P>
<P>Include the standard header <B><CODE>&lt;wctype.h&gt;</CODE></B>
to declare several functions that are useful
for classifying and mapping codes from the target wide-character set.</P>
<P>Every function that has a parameter of type
<A HREF="#wint_t"><CODE>wint_t</CODE></A>
can accept the value of the macro
<A HREF="#WEOF"><CODE>WEOF</CODE></A>
or any valid wide-character code (of type
<A HREF="stddef.html#wchar_t" tppabs="http://ccs.ucsd.edu/c/stddef.html#wchar_t"><CODE>wchar_t</CODE></A>).
Thus, the argument can be the value returned by any of the functions:
<A HREF="wchar.html#btowc" tppabs="http://ccs.ucsd.edu/c/wchar.html#btowc"><CODE>btowc</CODE></A>,
<A HREF="wchar.html#fgetwc" tppabs="http://ccs.ucsd.edu/c/wchar.html#fgetwc"><CODE>fgetwc</CODE></A>,
<A HREF="wchar.html#fputwc" tppabs="http://ccs.ucsd.edu/c/wchar.html#fputwc"><CODE>fputwc</CODE></A>,
<A HREF="wchar.html#getwc" tppabs="http://ccs.ucsd.edu/c/wchar.html#getwc"><CODE>getwc</CODE></A>,
<A HREF="wchar.html#getwchar" tppabs="http://ccs.ucsd.edu/c/wchar.html#getwchar"><CODE>getwchar</CODE></A>,
<A HREF="wchar.html#putwc" tppabs="http://ccs.ucsd.edu/c/wchar.html#putwc"><CODE>putwc</CODE></A>,
<A HREF="wchar.html#putwchar" tppabs="http://ccs.ucsd.edu/c/wchar.html#putwchar"><CODE>putwchar</CODE></A>,
<A HREF="#towctrans"><CODE>towctrans</CODE></A>,
<A HREF="#towlower"><CODE>towlower</CODE></A>,
<A HREF="#towupper"><CODE>towupper</CODE></A>, or
<A HREF="wchar.html#ungetwc" tppabs="http://ccs.ucsd.edu/c/wchar.html#ungetwc"><CODE>ungetwc</CODE></A>.
You must not call these functions
with other wide-character argument values.</P>
<P>The
<B><A NAME="wide-character classification">
wide-character classification</A></B>
functions are strongly related to the (byte)
<A HREF="ctype.html#character classification" tppabs="http://ccs.ucsd.edu/c/ctype.html#character classification">character classification</A>
functions. Each function <CODE>is<I>XXX</I></CODE>
has a corresponding wide-character classification
function <CODE>isw<I>XXX</I></CODE>.
Moreover, the wide-character classification functions
are interrelated much the same way as their corresponding
byte functions, with two added provisos:</P>
<UL>
<LI>The function
<A HREF="#iswprint"><CODE>iswprint</CODE></A>, unlike
<A HREF="ctype.html#isprint" tppabs="http://ccs.ucsd.edu/c/ctype.html#isprint"><CODE>isprint</CODE></A>,
can return a nonzero value for additional space characters
besides the wide-character equivalent of <CODE><I>space</I></CODE>
(<CODE>L' '</CODE>). Any such additional characters
return a nonzero value for
<A HREF="#iswspace"><CODE>iswspace</CODE></A> and return zero for
<A HREF="#iswgraph"><CODE>iswgraph</CODE></A> or
<A HREF="#iswpunct"><CODE>iswpunct</CODE></A>.
<LI>The characters in each wide-character class are a superset of
the characters in the corresponding byte class.
If the call <CODE>is<I>XXX</I>(c)</CODE> returns a nonzero value,
then the corresponding call <CODE>isw<I>XXX</I>(btowc(c))</CODE>
also returns a nonzero value.
</UL>
<P>An implementation can define additional characters that return
nonzero for some of these functions. Any character set can contain
additional characters that return nonzero for:</P>
<UL>
<LI><A HREF="#iswpunct"><CODE>iswpunct</CODE></A>
(provided the characters cause
<A HREF="#iswalnum"><CODE>iswalnum</CODE></A> to return zero)
<LI><A HREF="#iswcntrl"><CODE>iswcntrl</CODE></A>
(provided the characters cause
<A HREF="#iswprint"><CODE>iswprint</CODE></A> to return zero)
</UL>
<P>Moreover, a
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A> other than the
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale can define
additional characters for:</P>
<UL>
<LI><A HREF="#iswalpha"><CODE>iswalpha</CODE></A>,
<A HREF="#iswupper"><CODE>iswupper</CODE></A>, and
<A HREF="#iswlower"><CODE>iswlower</CODE></A>
(provided the characters cause
<A HREF="#iswcntrl"><CODE>iswcntrl</CODE></A>,
<A HREF="#iswdigit"><CODE>iswdigit</CODE></A>,
<A HREF="#iswpunct"><CODE>iswpunct</CODE></A>, and
<A HREF="#iswspace"><CODE>iswspace</CODE></A> to return zero)
<LI><A HREF="#iswspace"><CODE>iswspace</CODE></A>
(provided the characters cause
<A HREF="#iswpunct"><CODE>iswpunct</CODE></A> to return zero)
</UL>
<P>Note that the last rule differs slightly from the corresponding
rule for the function
<A HREF="ctype.html#isspace" tppabs="http://ccs.ucsd.edu/c/ctype.html#isspace"><CODE>isspace</CODE></A>,
as indicated above.
Note also that an implementation can define a
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A> other than the
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale
in which a character can cause
<A HREF="#iswalpha"><CODE>iswalpha</CODE></A> (and hence
<A HREF="#iswalnum"><CODE>iswalnum</CODE></A>)
to return nonzero, yet still cause
<A HREF="#iswupper"><CODE>iswupper</CODE></A> and
<A HREF="#iswlower"><CODE>iswlower</CODE></A> to return zero.</P>
<H2><A NAME="WEOF"><CODE>WEOF</CODE></A></H2>
<P><CODE>
#define <B>WEOF</B> <I>&lt;</I>wint_t <I>constant expression&gt;</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="iswalnum"><CODE>iswalnum</CODE></A></H2>
<P><CODE>
int <B>iswalnum</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
o 1 2 3 4 5 6 7 8 9</PRE>
<P> or any other locale-specific alphabetic character.</P>
<H2><A NAME="iswalpha"><CODE>iswalpha</CODE></A></H2>
<P><CODE>
int <B>iswalpha</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z</PRE>
<P> or any other locale-specific alphabetic character.</P>
<H2><A NAME="iswcntrl"><CODE>iswcntrl</CODE></A></H2>
<P><CODE>
int <B>iswcntrl</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
<I>BEL BS CR FF HT NL VT</I></PRE>
<P>or any other implementation-defined control character.</P>
<H2><A NAME="iswctype"><CODE>iswctype</CODE></A></H2>
<P><CODE>
int <B>iswctype</B>(wint_t c, wctype_t category);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any character in
the category <CODE>category</CODE>.
The value of <CODE>category</CODE> must have
been returned by an earlier successful call to
<A HREF="#wctype"><CODE>wctype</CODE></A>.</P>
<H2><A NAME="iswdigit"><CODE>iswdigit</CODE></A></H2>
<P><CODE>
int <B>iswdigit</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
0 1 2 3 4 5 6 7 8 9</PRE>
<H2><A NAME="iswgraph"><CODE>iswgraph</CODE></A></H2>
<P><CODE>
int <B>iswgraph</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE>
is any character for which either
<A HREF="#iswalnum"><CODE>iswalnum</CODE></A> or
<A HREF="#iswpunct"><CODE>iswpunct</CODE></A> returns nonzero.</P>
<H2><A NAME="iswlower"><CODE>iswlower</CODE></A></H2>
<P><CODE>
int <B>iswlower</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
a b c d e f g h i j k l m n o p q r s t u v w x y z</PRE>
<P> or any other locale-specific lowercase character.</P>
<H2><A NAME="iswprint"><CODE>iswprint</CODE></A></H2>
<P><CODE>
int <B>iswprint</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE>
is <CODE><I>space</I></CODE>, a character for which
<A HREF="#iswgraph"><CODE>iswgraph</CODE></A>
returns nonzero, or an implementation-defined
subset of the characters for which
<A HREF="#iswspace"><CODE>iswspace</CODE></A>
returns nonzero.</P>
<H2><A NAME="iswpunct"><CODE>iswpunct</CODE></A></H2>
<P><CODE>
int <B>iswpunct</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
! " # % &amp; ' ( ) ; &lt;
= &gt; ? [ \ ] * + , -
. / : ^ _ { | } ~</PRE>
<P>or any other implementation-defined punctuation character.</P>
<H2><A NAME="iswspace"><CODE>iswspace</CODE></A></H2>
<P><CODE>
int <B>iswspace</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
<I>CR FF HT NL VT space</I></PRE>
<P>or any other locale-specific space character.</P>
<H2><A NAME="iswupper"><CODE>iswupper</CODE></A></H2>
<P><CODE>
int <B>iswupper</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of:</P>
<PRE>
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z</PRE>
<P>or any other locale-specific uppercase character.</P>
<H2><A NAME="iswxdigit"><CODE>iswxdigit</CODE></A></H2>
<P><CODE>
int <B>iswxdigit</B>(wint_t c);
</CODE></P>
<P>The function returns nonzero if <CODE>c</CODE> is any of</P>
<PRE>
0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F</PRE>
<H2><A NAME="towctrans"><CODE>towctrans</CODE></A></H2>
<P><CODE>
wint_t <B>towctrans</B>(wint_t c, wctrans_t category);
</CODE></P>
<P>The function returns the transformation of the character <CODE>c</CODE>,
using the transform in the category <CODE>category</CODE>. The value of
<CODE>category</CODE> must have been returned
by an earlier successful call to
<A HREF="#wctrans"><CODE>wctrans</CODE></A>.</P>
<H2><A NAME="towlower"><CODE>towlower</CODE></A></H2>
<P><CODE>
wint_t <B>towlower</B>(wint_t c);
</CODE></P>
<P>The function returns the corresponding lowercase letter
if one exists and if
<CODE><A HREF="#iswupper">iswupper</A>(c)</CODE>;
otherwise, it returns <CODE>c</CODE>.</P>
<H2><A NAME="towupper"><CODE>towupper</CODE></A></H2>
<P><CODE>
wint_t <B>towupper</B>(wint_t c);
</CODE></P>
<P>The function returns the corresponding uppercase letter
if one exists and if
<CODE><A HREF="#iswlower">iswlower</A>(c)</CODE>;
otherwise, it returns <CODE>c</CODE>.</P>
<H2><A NAME="wctrans"><CODE>wctrans</CODE></A></H2>
<P><CODE>
wctrans_t <B>wctrans</B>(const char *property);
</CODE></P>
<P>The function determines a mapping from one set of wide-character
codes to another. If the
<A HREF="locale.html#LC_CTYPE" tppabs="http://ccs.ucsd.edu/c/locale.html#LC_CTYPE"><CODE>LC_CTYPE</CODE></A>
category of the current
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>
does not define a mapping whose name matches
the property string <CODE>property</CODE>, the function returns zero.
Otherwise, it returns a nonzero value suitable
for use as the second argument to a subsequent call to
<A HREF="#towctrans"><CODE>towctrans</CODE></A>.</P>
<P>The following pairs of calls have the same behavior in all
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locales</A>
(but an implementation can define additional mappings even in the
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale):</P>
<P><CODE><A HREF="#towlower">towlower</A>(c) <B>same as</B>
<A HREF="#towctrans">towctrans</A>(c, wctrans("tolower"))<BR>
<A HREF="#towupper">towupper</A>(c) <B>same as</B>
<A HREF="#towctrans">towctrans</A>(c,
wctrans("toupper"))</CODE></P>
<H2><A NAME="wctrans_t"><CODE>wctrans_t</CODE></A></H2>
<P><CODE>
typedef <I>s_type</I> <B>wctrans_t</B>;
</CODE></P>
<P>The type is the scalar type <CODE><I>s-type</I></CODE>
that can represent locale-specific character mappings,
as specified by the return value of
<A HREF="#wctrans"><CODE>wctrans</CODE></A>.</P>
<H2><A NAME="wctype"><CODE>wctype</CODE></A></H2>
<P><CODE>
wctype_t <B>wctype</B>(const char *property);
</CODE></P>
<P><CODE>
wctrans_t wctrans(const char *property);
<P>The function determines a classification rule
for wide-character codes. If the
<A HREF="locale.html#LC_CTYPE" tppabs="http://ccs.ucsd.edu/c/locale.html#LC_CTYPE"><CODE>LC_CTYPE</CODE></A>
category of the current
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>
does not define a classification rule whose name matches
the property string <CODE>property</CODE>, the function returns zero.
Otherwise, it returns a nonzero value suitable
for use as the second argument to a subsequent call to
<A HREF="#towctrans"><CODE>towctrans</CODE></A>.</P>
<P>The following pairs of calls have the same behavior in all
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locales</A> (but an implementation
can define additional classification rules even in the
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale):</P>
<P><CODE><A HREF="#iswalnum">iswalnum</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("alnum"))<BR>
<A HREF="#iswalpha">iswalpha</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("alpha"))<BR>
<A HREF="#iswcntrl">iswcntrl</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("cntrl"))<BR>
<A HREF="#iswdigit">iswdigit</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("digit"))<BR>
<A HREF="#iswgraph">iswgraph</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("graph"))<BR>
<A HREF="#iswlower">iswlower</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("lower"))<BR>
<A HREF="#iswprint">iswprint</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("print"))<BR>
<A HREF="#iswpunct">iswpunct</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("punct"))<BR>
<A HREF="#iswspace">iswspace</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("space"))<BR>
<A HREF="#iswupper">iswupper</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("upper"))<BR>
<A HREF="#iswxdigit">iswxdigit</A>(c) <B>same as</B>
<A HREF="#iswctype">iswctype</A>(c, wctype("xdigit"))</CODE></P>
<H2><A NAME="wctype_t"><CODE>wctype_t</CODE></A></H2>
<P><CODE>
typedef <I>s_type</I> <B>wctype_t</B>;
</CODE></P>
<P>The type is the scalar type <CODE><I>s-type</I></CODE> that can represent
locale-specific character classifications,
as specified by the return value of
<A HREF="#wctype"><CODE>wctype</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="stddef.html#wchar_t" tppabs="http://ccs.ucsd.edu/c/stddef.html#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>
<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> &#169; 1989-1996
by P.J. Plauger and Jim Brodie. All rights reserved.</I></P>
</BODY></HTML>