<wctype.h>

[Added with Amendment 1]

iswalnum · iswalpha · iswblank · iswcntrl · iswdigit · iswgraph · iswlower · iswprint · iswpunct · iswspace · iswupper · iswxdigit · towlower · towctrans · towupper · wctrans · wctype

Include the standard header <wctype.h> to declare several functions that are useful for classifying and mapping codes from the target wide-character set.

Every function that has a parameter of type wint_t can accept the value of the macro WEOF or any valid wide-character code (of type wchar_t). Thus, the argument can be the value returned by any of the functions: btowc, fgetwc, fputwc, getwc, getwchar, putwc, putwchar, towctrans, towlower, towupper, or ungetwc. You must not call these functions with other wide-character argument values.

The wide-character classification functions are strongly related to the (byte) character classification functions. Each function isXXX has a corresponding wide-character classification function iswXXX. Moreover, the wide-character classification functions are interrelated much the same way as their corresponding byte functions, with two added provisos:

• The function iswprint, unlike isprint, can return a nonzero value for additional space characters besides the wide-character equivalent of space (L' '). Any such additional characters return a nonzero value for iswspace and return zero for iswgraph or iswpunct.
• The characters in each wide-character class are a superset of the characters in the corresponding byte class. If the call isXXX(c) returns a nonzero value, then the corresponding call iswXXX(btowc(c)) also returns a nonzero value.

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:

• iswcntrl (provided the characters cause iswprint to return zero)
• iswpunct (provided the characters cause iswalnum to return zero)

Moreover, a locale other than the "C" locale can define additional characters for:

• iswalpha, iswupper, and iswlower (provided the characters cause iswcntrl, iswdigit, iswpunct, and iswspace to return zero)
• iswblank (provided the characters cause iswalnum to return zero)
• iswspace (provided the characters cause iswpunct to return zero)

Note that the last rule differs slightly from the corresponding rule for the function isspace, as indicated above. Note also that an implementation can define a locale other than the "C" locale in which a character can cause iswalpha (and hence iswalnum) to return nonzero, yet still cause iswupper and iswlower to return zero.

WEOF

#define WEOF <wint_t constant expression>

The macro yields the return value, of type wint_t, used to signal the end of a wide stream or to report an error condition.

    /* TYPES */
typedef s_type wctrans_t;
typedef s_type wctype_t;
typedef i_type wint_t;

    /* FUNCTIONS */
int iswalnum(wint_t c);
int iswalpha(wint_t c);
int iswblank(wint_t c); [added with C99]
int iswcntrl(wint_t c);
int iswctype(wint_t c, wctype_t category);
int iswdigit(wint_t c);
int iswgraph(wint_t c);
int iswlower(wint_t c);
int iswprint(wint_t c);
int iswpunct(wint_t c);
int iswspace(wint_t c);
int iswupper(wint_t c);
int iswxdigit(wint_t c);

wint_t towctrans(wint_t c, wctrans_t category);
wint_t towlower(wint_t c);
wint_t towupper(wint_t c);

wctrans_t wctrans(const char *property);
wctype_t wctype(const char *property);

iswalnum

int iswalnum(wint_t c);

The function returns nonzero if c is any of:

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
0 1 2 3 4 5 6 7 8 9

or any other locale-specific alphabetic character.

iswalpha

int iswalpha(wint_t c);

The function returns nonzero if c is any of:

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

or any other locale-specific alphabetic character.

iswblank

int iswblank(wint_t c); [added with C99]

The function returns nonzero if c is any of:

HT space

or any other locale-specific blank character.

iswcntrl

int iswcntrl(wint_t c);

The function returns nonzero if c is any of:

BEL BS CR FF HT NL VT

or any other implementation-defined control character.

iswctype

int iswctype(wint_t c, wctype_t category);

The function returns nonzero if c is any character in the category category. The value of category must have been returned by an earlier successful call to wctype.

iswdigit

int iswdigit(wint_t c);

The function returns nonzero if c is any of:

0 1 2 3 4 5 6 7 8 9

iswgraph

int iswgraph(wint_t c);

The function returns nonzero if c is any character for which either iswalnum or iswpunct returns nonzero.

iswlower

int iswlower(wint_t c);

The function returns nonzero if c is any of:

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

or any other locale-specific lowercase character.

iswprint

int iswprint(wint_t c);

The function returns nonzero if c is space, a character for which iswgraph returns nonzero, or an implementation-defined subset of the characters for which iswspace returns nonzero.

iswpunct

int iswpunct(wint_t c);

The function returns nonzero if c is any of:

! " # % & ' ( ) ; <
= > ? [ \ ] * + , -
. / : ^ _ { | } ~

or any other implementation-defined punctuation character.

iswspace

int iswspace(wint_t c);

The function returns nonzero if c is any of:

CR FF HT NL VT space

or any other locale-specific space character.

iswupper

int iswupper(wint_t c);

The function returns nonzero if c is any of:

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

or any other locale-specific uppercase character.

iswxdigit

int iswxdigit(wint_t c);

The function returns nonzero if c is any of

0 1 2 3 4 5 6 7 8 9 a b c d e f A B C D E F

towctrans

wint_t towctrans(wint_t c, wctrans_t category);

The function returns the transformation of the character c, using the transform in the category category. The value of category must have been returned by an earlier successful call to wctrans.

towlower

wint_t towlower(wint_t c);

The function returns the corresponding lowercase letter if one exists and if iswupper(c); otherwise, it returns c.

towupper

wint_t towupper(wint_t c);

The function returns the corresponding uppercase letter if one exists and if iswlower(c); otherwise, it returns c.

wctrans

wctrans_t wctrans(const char *property);

The function determines a mapping from one set of wide-character codes to another. If the LC_CTYPE category of the current locale does not define a mapping whose name matches the property string property, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to towctrans.

The following pairs of calls have the same behavior in all locales (but an implementation can define additional mappings even in the "C" locale):

towlower(c) same as towctrans(c, wctrans("tolower"))
towupper(c) same as towctrans(c, wctrans("toupper"))

wctrans_t

typedef s_type wctrans_t;

The type is the scalar type s-type that can represent locale-specific character mappings, as specified by the return value of wctrans.

wctype

wctype_t wctype(const char *property);

wctrans_t wctrans(const char *property);

The function determines a classification rule for wide-character codes. If the LC_CTYPE category of the current locale does not define a classification rule whose name matches the property string property, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to towctrans.

The following pairs of calls have the same behavior in all locales (but an implementation can define additional classification rules even in the "C" locale):

iswalnum(c)  same as iswctype(c, wctype("alnum"))
iswalpha(c)  same as iswctype(c, wctype("alpha"))
iswblank(c)  same as iswctype(c, wctype("blank"))
iswcntrl(c)  same as iswctype(c, wctype("cntrl"))
iswdigit(c)  same as iswctype(c, wctype("digit"))
iswgraph(c)  same as iswctype(c, wctype("graph"))
iswlower(c)  same as iswctype(c, wctype("lower"))
iswprint(c)  same as iswctype(c, wctype("print"))
iswpunct(c)  same as iswctype(c, wctype("punct"))
iswspace(c)  same as iswctype(c, wctype("space"))
iswupper(c)  same as iswctype(c, wctype("upper"))
iswxdigit(c) same as iswctype(c, wctype("xdigit"))

wctype_t

typedef s_type wctype_t;

The type is the scalar type s-type that can represent locale-specific character classifications, as specified by the return value of wctype.

wint_t

typedef i_type wint_t;

The type is the integer type i_type that can represent all values of type wchar_t as well as the value of the macro WEOF, and that doesn't change when promoted.

See also the Table of Contents and the Index.

Copyright © 1989-2002 by P.J. Plauger and Jim Brodie. All rights reserved.