Prev | Contents | Next

32 <wctype.h> Wide Character Classification and Transformation

Function Description
iswalnum() Test if a wide character is alphanumeric.
iswalpha() Tests if a wide character is alphabetic
iswblank() Tests if this is a wide blank character
iswcntrl() Tests if this is a wide control character.
iswctype() Determine wide character classification
iswdigit() Test if this wide character is a digit
iswgraph() Test to see if a wide character is a printable non-space
iswlower() Tests if a wide character is lowercase
iswprint() Tests if a wide character is printable
iswpunct() Test if a wide character is punctuation
iswspace() Test if a wide character is whitespace
iswupper() Tests if a wide character is uppercase
iswxdigit() Tests if a wide character is a hexadecimal digit
towctrans() Convert wide characters to upper or lowercase
towlower() Convert an uppercase wide character to lowercase
towupper() Convert a lowercase wide character to uppercase
wctrans() Helper function for towctrans()
wctype() Helper function for iswctype()

This is like <ctype.h> except for wide characters.

With it you can test for character classifications (like “is this character whitespace?”) or do basic character conversions (like “force this character to lowercase”).


32.1 iswalnum()

Test if a wide character is alphanumeric.

Synopsis

#include <wctype.h>

int iswalnum(wint_t wc);

Description

Basically tests if a character is alphabetic (A-Z or a-z) or a digit (0-9). But some other characters might also qualify based on the locale.

This is equivalent to testing if iswalpha() or iswdigit() is true.

Return Value

Returns true if the character is alphanumeric.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                  testing this char
    //                           v
    wprintf(L"%ls\n", iswalnum(L'a')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswalnum(L'B')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswalnum(L'5')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswalnum(L'?')? L"yes": L"no");  // no
}

See Also

iswalpha(), iswdigit(), isalnum()


32.2 iswalpha()

Tests if a wide character is alphabetic

Synopsis

#include <wctype.h>

int iswalpha(wint_t wc);

Description

Basically tests if a character is alphabetic (A-Z or a-z). But some other characters might also qualify based on the locale. (If other characters qualify, they won’t be control characters, digits, punctuation, or spaces.)

This is the same as testing for iswupper() or iswlower().

Return Value

Returns true if the character is alphabetic.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                  testing this char
    //                           v
    wprintf(L"%ls\n", iswalpha(L'a')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswalpha(L'B')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswalpha(L'5')? L"yes": L"no");  // no
    wprintf(L"%ls\n", iswalpha(L'?')? L"yes": L"no");  // no
}

See Also

iswalnum(), isalpha()


32.3 iswblank()

Tests if this is a wide blank character

Synopsis

#include <wctype.h>

int iswblank(wint_t wc);

Description

Blank characters are whitespace that are also used as word separators on the same line. In the “C” locale, the only blank characters are space and tab.

Other locales might define other blank characters.

Return Value

Returns true if this is a blank character.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswblank(L' ')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswblank(L'\t')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswblank(L'\n')? L"yes": L"no");  // no
    wprintf(L"%ls\n", iswblank(L'a')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswblank(L'?')? L"yes": L"no");   // no
}

See Also

iswspace(), isblank()


32.4 iswcntrl()

Tests if this is a wide control character.

Synopsis

#include <wctype.h>

int iswcntrl(wint_t wc);

Description

The spec is pretty barren, here. But I’m just going to assume that it works like the non-wide version. So let’s look at that.

A control character is a locale-specific non-printing character.

For the “C” locale, this means control characters are in the range 0x00 to 0x1F (the character right before SPACE) and 0x7F (the DEL character).

Basically if it’s not an ASCII (or Unicode less than 128) printable character, it’s a control character in the “C” locale.

Probably.

Return Value

Returns true if this is a control character.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswcntrl(L'\t')? L"yes": L"no");  // yes (tab)
    wprintf(L"%ls\n", iswcntrl(L'\n')? L"yes": L"no");  // yes (newline)
    wprintf(L"%ls\n", iswcntrl(L'\r')? L"yes": L"no");  // yes (return)
    wprintf(L"%ls\n", iswcntrl(L'\a')? L"yes": L"no");  // yes (bell)
    wprintf(L"%ls\n", iswcntrl(L' ')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswcntrl(L'a')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswcntrl(L'?')? L"yes": L"no");   // no
}

See Also

iscntrl()


32.5 iswdigit()

Test if this wide character is a digit

Synopsis

#include <wctype.h>

int iswdigit(wint_t wc);

Description

Tests if the wide character is a digit (0-9).

Return Value

Returns true if the character is a digit.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswdigit(L'0')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswdigit(L'5')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswdigit(L'a')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswdigit(L'B')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswdigit(L'?')? L"yes": L"no");   // no
}

See Also

iswalnum(), isdigit()


32.6 iswgraph()

Test to see if a wide character is a printable non-space

Synopsis

#include <wctype.h>

int iswgraph(wint_t wc);

Description

Returns true if this is a printable (non-control) character and also not a whitespace character.

Basically if iswprint() is true and iswspace() is false.

Return Value

Returns true if this is a printable non-space character.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswgraph(L'0')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswgraph(L'a')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswgraph(L'B')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswgraph(L'?')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswgraph(L' ')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswgraph(L'\n')? L"yes": L"no");  // no
}

See Also

iswprint(), iswspace(), isgraph()


32.7 iswlower()

Tests if a wide character is lowercase

Synopsis

#include <wctype.h>

int iswlower(wint_t wc);

Description

Tests if a character is lowercase, in the range a-z.

In other locales, there could be other lowercase characters. In all cases, to be lowercase, the following must be true:

!iswcntrl(c) && !iswdigit(c) && !iswpunct(c) && !iswspace(c)

Return Value

Returns true if the wide character is lowercase.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswlower(L'c')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswlower(L'0')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswlower(L'B')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswlower(L'?')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswlower(L' ')? L"yes": L"no");   // no
}

See Also

islower(), iswupper(), iswalpha(), towupper(), towlower()


32.8 iswprint()

Tests if a wide character is printable

Synopsis

#include <wctype.h>

int iswprint(wint_t wc);

Description

Tests if a wide character is printable, including space (' '). So like isgraph(), except space isn’t left out in the cold.

Return Value

Returns true if the wide character is printable, including space (' ').

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswprint(L'c')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswprint(L'0')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswprint(L' ')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswprint(L'\r')? L"yes": L"no");  // no
}

See Also

isprint(), iswgraph(), iswcntrl()


32.9 iswpunct()

Test if a wide character is punctuation

Synopsis

#include <wctype.h>

int iswpunct(wint_t wc);

Description

Tests if a wide character is punctuation.

This means for any given locale:

!isspace(c) && !isalnum(c)

Return Value

True if the wide character is punctuation.

Example

Results may vary based on locale.

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswpunct(L',')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswpunct(L'!')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswpunct(L'c')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswpunct(L'0')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswpunct(L' ')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswpunct(L'\n')? L"yes": L"no");  // no
}

See Also

ispunct(), iswspace(), iswalnum()


32.10 iswspace()

Test if a wide character is whitespace

Synopsis

#include <wctype.h>

int iswspace(wint_t wc);

Description

Tests if c is a whitespace character. These are probably:

Other locales might specify other whitespace characters. iswalnum(), iswgraph(), and iswpunct() are all false for all whitespace characters.

Return Value

True if the character is whitespace.

Example

Results may vary based on locale.

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswspace(L' ')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswspace(L'\n')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswspace(L'\t')? L"yes": L"no");  // yes
    wprintf(L"%ls\n", iswspace(L',')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswspace(L'!')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswspace(L'c')? L"yes": L"no");   // no
}

See Also

isspace(), iswblank()


32.11 iswupper()

Tests if a wide character is uppercase

Synopsis

#include <wctype.h>

int iswupper(wint_t wc);

Description

Tests if a character is uppercase in the current locale.

To be uppercase, the following must be true:

!iscntrl(c) && !isdigit(c) && !ispunct(c) && !isspace(c)

Return Value

Returns true if the wide character is uppercase.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                   testing this char
    //                           v
    wprintf(L"%ls\n", iswupper(L'B')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswupper(L'c')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswupper(L'0')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswupper(L'?')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswupper(L' ')? L"yes": L"no");   // no
}

See Also

isupper(), iswlower(), iswalpha(), towupper(), towlower()


32.12 iswxdigit()

Tests if a wide character is a hexadecimal digit

Synopsis

#include <wctype.h>

int iswxdigit(wint_t wc);

Description

Returns true if the wide character is a hexadecimal digit. Namely if it’s 0-9, a-f, or A-F.

Return Value

True if the character is a hexadecimal digit.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                    testing this char
    //                            v
    wprintf(L"%ls\n", iswxdigit(L'B')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswxdigit(L'c')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswxdigit(L'2')? L"yes": L"no");   // yes
    wprintf(L"%ls\n", iswxdigit(L'G')? L"yes": L"no");   // no
    wprintf(L"%ls\n", iswxdigit(L'?')? L"yes": L"no");   // no
}

See Also

isxdigit(), iswdigit()


32.13 iswctype()

Determine wide character classification

Synopsis

#include <wctype.h>

int iswctype(wint_t wc, wctype_t desc);

Description

This is the Swiss Army knife of classification functions; it’s all the other ones rolled into one.

You call it with something like this:

if (iswctype(c, wctype("digit")))  // or "alpha" or "space" or...

and it behaves just like you’d called:

if (iswdigit(c))

The difference is that you can specify the type of matching you want to do as a string at runtime, which might be convenient.

iswctype() relies on the return value from the wctype() call to get its work done.

Stolen from the spec, here are the iswctype() calls and their equivalents:

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

See the wctype() documentation for how that helper function works.

Return Value

Returns true if the wide character wc matches the character class in desc.

Example

Test for a given character classification at when the classification isn’t known at compile time:

#include <stdio.h>  // for fflush(stdout)
#include <wchar.h>
#include <wctype.h>

int main(void)
{
    wchar_t c;        // Holds a single wide character (to test)
    char desc[128];   // Holds the character class

    // Get the character and classification from the user
    wprintf(L"Enter a character and character class: ");
    fflush(stdout);
    wscanf(L"%lc %s", &c, desc);

    // Compute the type from the given class
    wctype_t t = wctype(desc);

    if (t == 0)
        // If the type is 0, it's an unknown class
        wprintf(L"Unknown character class: \"%s\"\n", desc);
    else {
        // Otherwise, let's test the character and see if its that
        // classification
        if (iswctype(c, t))
            wprintf(L"Yes! '%lc' is %s!\n", c, desc);
        else
            wprintf(L"Nope! '%lc' is not %s.\n", c, desc);
    }
}

Output:

Enter a character and character class: 5 digit
Yes! '5' is digit!

Enter a character and character class: b digit
Nope! 'b' is not digit.

Enter a character and character class: x alnum
Yes! 'x' is alnum!

See Also

wctype()


32.14 wctype()

Helper function for iswctype()

Synopsis

#include <wctype.h>

wctype_t wctype(const char *property);

Description

This function returns an opaque value for the given property that is meant to be passed as the second argument to iswctype().

The returned value is of type wctype_t.

Valid properties in all locales are:

"alnum"   "alpha"   "blank"   "cntrl"
"digit"   "graph"   "lower"   "print"
"punct"   "space"   "upper"   "xdigit"

Other properties might be defined as determined by the LC_CTYPE category of the current locale.

See the iswctype() reference page for more usage details.

Return Value

Returns the wctype_t value associated with the given property.

If an invalid value is passed for property, returns 0.

Example

Test for a given character classification at when the classification isn’t known at compile time:

#include <stdio.h>  // for fflush(stdout)
#include <wchar.h>
#include <wctype.h>

int main(void)
{
    wchar_t c;        // Holds a single wide character (to test)
    char desc[128];   // Holds the character class

    // Get the character and classification from the user
    wprintf(L"Enter a character and character class: ");
    fflush(stdout);
    wscanf(L"%lc %s", &c, desc);

    // Compute the type from the given class
    wctype_t t = wctype(desc);

    if (t == 0)
        // If the type is 0, it's an unknown class
        wprintf(L"Unknown character class: \"%s\"\n", desc);
    else {
        // Otherwise, let's test the character and see if its that
        // classification
        if (iswctype(c, t))
            wprintf(L"Yes! '%lc' is %s!\n", c, desc);
        else
            wprintf(L"Nope! '%lc' is not %s.\n", c, desc);
    }
}

Output:

Enter a character and character class: 5 digit
Yes! '5' is digit!

Enter a character and character class: b digit
Nope! 'b' is not digit.

Enter a character and character class: x alnum
Yes! 'x' is alnum!

See Also

iswctype()


32.15 towlower()

Convert an uppercase wide character to lowercase

Synopsis

#include <wctype.h>

wint_t towlower(wint_t wc);

Description

If the character is upper (i.e. iswupper(c) is true), this function returns the corresponding lowercase letter.

Different locales might have different upper and lowercase letters.

Return Value

If the letter wc is uppercase, a lowercase version of that letter will be returned according to the current locale.

If the letter is not uppercase, wc is returned unchanged.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                  changing this char
    //                           v
    wprintf(L"%lc\n", towlower(L'B'));  // b (made lowercase!)
    wprintf(L"%lc\n", towlower(L'e'));  // e (unchanged)
    wprintf(L"%lc\n", towlower(L'!'));  // ! (unchanged)
}

See Also

tolower(), towupper(), iswlower(), iswupper()


32.16 towupper()

Convert a lowercase wide character to uppercase

Synopsis

#include <wctype.h>

wint_t towupper(wint_t wc);

Description

If the character is lower (i.e. iswlower(c) is true), this function returns the corresponding uppercase letter.

Different locales might have different upper and lowercase letters.

Return Value

If the letter wc is lowercase, an uppercase version of that letter will be returned according to the current locale.

If the letter is not lowercase, wc is returned unchanged.

Example

#include <wchar.h>
#include <wctype.h>

int main(void)
{
    //                  changing this char
    //                           v
    wprintf(L"%lc\n", towupper(L'B'));  // B (unchanged)
    wprintf(L"%lc\n", towupper(L'e'));  // E (made uppercase!)
    wprintf(L"%lc\n", towupper(L'!'));  // ! (unchanged)
}

See Also

toupper(), towlower(), iswlower(), iswupper()


32.17 towctrans()

Convert wide characters to upper or lowercase

Synopsis

#include <wctype.h>

wint_t towctrans(wint_t wc, wctrans_t desc);

Description

This is the Swiss Army knife of character conversion functions; it’s all the other ones rolled into one. And by “all the other ones” I mean towupper() and towlower(), since those are the only ones there are.

You call it with something like this:

if (towctrans(c, wctrans("toupper")))  // or "tolower"

and it behaves just like you’d called:

towupper(c);

The difference is that you can specify the type of conversion you want to do as a string at runtime, which might be convenient.

towctrans() relies on the return value from the wctrans() call to get its work done.

towctrans() call Hard-coded equivalent
towctrans(c, wctrans("toupper")) towupper(c)
towctrans(c, wctrans("tolower")) towlower(c)

See the wctrans() documentation for how that helper function works.

Return Value

Returns the character wc as if run through towupper() or towlower(), depending on the value of desc.

If the character already matches the classification, it is returned as-is.

Example

#include <stdio.h>  // for fflush(stdout)
#include <wchar.h>
#include <wctype.h>

int main(void)
{
    wchar_t c;        // Holds a single wide character (to test)
    char desc[128];   // Holds the conversion type

    // Get the character and conversion type from the user
    wprintf(L"Enter a character and conversion type: ");
    fflush(stdout);
    wscanf(L"%lc %s", &c, desc);

    // Compute the type from the given conversion type
    wctrans_t t = wctrans(desc);

    if (t == 0)
        // If the type is 0, it's an unknown conversion type
        wprintf(L"Unknown conversion: \"%s\"\n", desc);
    else {
        // Otherwise, let's do the conversion
        wint_t result = towctrans(c, t);
        wprintf(L"'%lc' -> %s -> '%lc'\n", c, desc, result);
    }
}

Output on my system:

Enter a character and conversion type: b toupper
'b' -> toupper -> 'B'

Enter a character and conversion type: B toupper
'B' -> toupper -> 'B'

Enter a character and conversion type: B tolower
'B' -> tolower -> 'b'

Enter a character and conversion type: ! toupper
'!' -> toupper -> '!'

See Also

wctrans(), towupper(), towlower()


32.18 wctrans()

Helper function for towctrans()

Synopsis

#include <wctype.h>

wctrans_t wctrans(const char *property);

Description

This is a helper function for generating the second argument to towctrans().

You can pass in one of two things for the property:

Return Value

On success, returns a value that can be used as the desc argument to towctrans().

Otherwise, if the property isn’t recognized, returns 0.

Example

#include <stdio.h>  // for fflush(stdout)
#include <wchar.h>
#include <wctype.h>

int main(void)
{
    wchar_t c;        // Holds a single wide character (to test)
    char desc[128];   // Holds the conversion type

    // Get the character and conversion type from the user
    wprintf(L"Enter a character and conversion type: ");
    fflush(stdout);
    wscanf(L"%lc %s", &c, desc);

    // Compute the type from the given conversion type
    wctrans_t t = wctrans(desc);

    if (t == 0)
        // If the type is 0, it's an unknown conversion type
        wprintf(L"Unknown conversion: \"%s\"\n", desc);
    else {
        // Otherwise, let's do the conversion
        wint_t result = towctrans(c, t);
        wprintf(L"'%lc' -> %s -> '%lc'\n", c, desc, result);
    }
}

Output on my system:

Enter a character and conversion type: b toupper
'b' -> toupper -> 'B'

Enter a character and conversion type: B toupper
'B' -> toupper -> 'B'

Enter a character and conversion type: B tolower
'B' -> tolower -> 'b'

Enter a character and conversion type: ! toupper
'!' -> toupper -> '!'

See Also

towctrans()


Prev | Contents | Next