42. Wide character classification and mapping utilities <wctype.h>

42.1. Introduction

The header <wctype.h> declares three data types, one macro, and many functions.

The types declared are

! wint_t

described in Introduction;

wctrans_t

which is a scalar type that can hold values which represent locale-specific character mappings; and

wctype_t

which is a scalar type that can hold values which represent locale-specific character classifications.

The macro defined is WEOF (described in Introduction).

The functions declared are grouped as follows:

  • Functions that provide wide character classification;
  • Extensible functions that provide wide character classification;
  • Functions that provide wide character case mapping;
  • Extensible functions that provide wide character mapping.

For all functions described in this subclause that accept an argument of type wint_t, the value shall be representable as a wchar_t or shall equal the value of the macro WEOF. If this argument has any other value, the behavior is undefined.

The behavior of these functions is affected by the LC_CTYPE category of the current locale.

42.2. Wide character classification utilities

The header <wctype.h> declares several functions useful for classifying wide characters.

The term printing wide character refers to a member of a locale-specific set of wide characters, each of which occupies at least one printing position on a display device. The term control wide character refers to a member of a locale-specific set of wide characters that are not printing wide characters.

42.2.1. Wide character classification functions

The functions in this subclause return nonzero (true) if and only if the value of the argument wc conforms to that in the description of the function.

Each of the following functions returns true for each wide character that corresponds (as if by a call to the wctob function) to a single-byte character for which the corresponding character classification function from Character classification functions returns true, except that the iswgraph and iswpunct functions may differ with respect to wide characters other than L' ' that are both printing and white-space wide characters. [1]

Forward references: the wctob function (The wctob function).

[1]For example, if the expression isalpha(wctob(wc)) evaluates to true, then the call iswalpha(wc) also returns true. But, if the expression isgraph(wctob(wc)) evaluates to true (which cannot occur for wc == L' ' of course), then either iswgraph(wc) or iswprint(wc) && iswspace(wc) is true, but not both.

42.2.1.1. The iswalnum function

Synopsis

#include <wctype.h>
int iswalnum(wint_t wc);

Description

The iswalnum function tests for any wide character for which iswalpha or iswdigit is true.

42.2.1.2. The iswalpha function

Synopsis

#include <wctype.h>
int iswalpha(wint_t wc);

Description

The iswalpha function tests for any wide character for which iswupper or iswlower is true, or any wide character that is one of a locale-specific set of alphabetic wide characters for which none of iswcntrl, iswdigit, iswpunct or iswspace is true. [2]

[2]The functions iswlower and iswupper test true or false separately for each of these additional wide characters; all four combinations are possible.

42.2.1.3. The iswblank function

Synopsis

#include <wctype.h>
int iswblank(wint_t wc);

Description

The iswblank function tests for any wide character that is a standard blank wide character or is one of a locale-specific set of wide characters for which iswspace is true and that is used to separate words within a line of text. The standard blank wide characters are the following: space (L' '), and horizontal tab (L'\t'). In the “C” locale, iswblank returns true only for the standard blank characters.

42.2.1.4. The iswcntrl function

Synopsis

#include <wctype.h>
int iswcntrl(wint_t wc);

Description

The iswcntrl function tests for any control wide character.

42.2.1.5. The iswdigit function

Synopsis

#include <wctype.h>
int iswdigit(wint_t wc);

Description

The iswdigit function tests for any wide character that corresponds to a decimal-digit character (as defined in Character Sets).

42.2.1.6. The iswgraph function

Synopsis

#include <wctype.h>
int iswgraph(wint_t wc);

Description

The iswgraph function tests for any wide character for which iswprint is true and iswspace is false. [3]

42.2.1.7. The iswlower function

Synopsis

#include <wctype.h>
int iswlower(wint_t wc);

Description

The iswlower function tests for any wide character that corresponds to a lowercase letter or is one of a locale-specific set of wide characters for which none of iswcntrl, iswdigit, iswpunct or iswspace is true.

42.2.1.8. The iswprint function

Synopsis

#include <wctype.h>
int iswprint(wint_t wc);

Description

The iswprint function tests for any printing wide character.

42.2.1.9. The iswpunct function

Synopsis

#include <wctype.h>
int iswpunct(wint_t wc);

Description

The iswpunct function tests for any printing wide character that is one of a locale-specific set of punctuation wide characters for which neither iswspace nor iswalnum is true. [3]

[3]Note that the behavior of the iswgraph and iswpunct functions may differ from their corresponding functions in Character classification functions with respect to printing, white-space, single-byte execution characters other than ‘ ‘.

42.2.1.10. The iswspace function

Synopsis

#include <wctype.h>
int iswspace(wint_t wc);

Description

The iswspace function tests for any wide character that corresponds to a locale-specific set of white-space wide characters for which none of iswalnum, iswgraph or iswpunct is true.

42.2.1.11. The iswupper function

Synopsis

#include <wctype.h>
int iswupper(wint_t wc);

Description

The iswupper function tests for any wide character that corresponds to an uppercase letter or is one of a locale-specific set of wide characters for which none of iswcntrl, iswdigit, iswpunct or iswspace is true.

42.2.1.12. The iswxdigit function

Synopsis

#include <wctype.h>
int iswxdigit(wint_t wc);

Description

The iswxdigit function tests for any wide character that corresponds to a hexadecimal-digit character (as defined in Integer Constants).

42.2.2. Extensible wide character classification functions

The functions wctype and iswctype provide extensible wide character classification as well as testing equivalent to that performed by the functions described in the previous subclause (Wide character classification functions).

42.2.2.1. The iswctype function

Synopsis

#include <wctype.h>
int iswctype(wint_t wc, wctype_t desc);

Description

The iswctype function determines whether the wide character wc has the property described by desc. The current setting of the LC_CTYPE category shall be the same as during the call to wctype that returned the value desc.

Each of the following expressions has a truth-value equivalent to the call to the wide character classification function (Wide character classification functions) in the comment that follows the expression:

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

Returns

The iswctype function returns nonzero (true) if and only if the value of the wide character wc has the property described by desc.

Forward references: the wctype function (The wctype function).

42.2.2.2. The wctype function

Synopsis

#include <wctype.h>
wctype_t wctype(const char *property);

Description

The wctype function constructs a value with type wctype_t that describes a class of wide characters identified by the string argument property.

The strings listed in the description of the iswctype function shall be valid in all locales as property arguments to the wctype function.

Returns

If property identifies a valid class of wide characters according to the LC_CTYPE category of the current locale, the wctype function returns a nonzero value that is valid as the second argument to the iswctype function; otherwise, it returns zero.

42.3. Wide character case mapping utilities

The header <wctype.h> declares several functions useful for mapping wide characters.

42.3.1. Wide character case mapping functions

42.3.1.1. The towlower function

Synopsis

#include <wctype.h>
wint_t towlower(wint_t wc);

Description

The towlower function converts an uppercase letter to a corresponding lowercase letter.

Returns

If the argument is a wide character for which iswupper is true and there are one or more corresponding wide characters, as specified by the current locale, for which iswlower is true, the towlower function returns one of the corresponding wide characters (always the same one for any giv en locale); otherwise, the argument is returned unchanged.

42.3.1.2. The towupper function

Synopsis

#include <wctype.h>
wint_t towupper(wint_t wc);

Description

The towupper function converts a lowercase letter to a corresponding uppercase letter.

Returns

If the argument is a wide character for which iswlower is true and there are one or more corresponding wide characters, as specified by the current locale, for which iswupper is true, the towupper function returns one of the corresponding wide characters (always the same one for any giv en locale); otherwise, the argument is returned unchanged.

42.3.2. Extensible wide character case mapping functions

The functions wctrans and towctrans provide extensible wide character mapping as well as case mapping equivalent to that performed by the functions described in the previous subclause (Wide character case mapping functions).

42.3.2.1. The towctrans function

Synopsis

#include <wctype.h>
wint_t towctrans(wint_t wc, wctrans_t desc);

Description

The towctrans function maps the wide character wc using the mapping described by desc. The current setting of the LC_CTYPE category shall be the same as during the call to wctrans that returned the value desc.

Each of the following expressions behaves the same as the call to the wide character case mapping function (Wide character case mapping functions) in the comment that follows the expression:

towctrans(wc, wctrans("tolower")) // towlower(wc)
towctrans(wc, wctrans("toupper")) // towupper(wc)

Returns

The towctrans function returns the mapped value of wc using the mapping described by desc.

42.3.2.2. The wctrans function

Synopsis

#include <wctype.h>
wctrans_t wctrans(const char *property);

Description

The wctrans function constructs a value with type wctrans_t that describes a mapping between wide characters identified by the string argument property.

The strings listed in the description of the towctrans function shall be valid in all locales as property arguments to the wctrans function.

Returns

If property identifies a valid mapping of wide characters according to the LC_CTYPE category of the current locale, the wctrans function returns a nonzero value that is valid as the second argument to the towctrans function; otherwise, it returns zero.