<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”).
iswalnum()Test if a wide character is alphanumeric.
#include <wctype.h>
int iswalnum(wint_t wc);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.
Returns true if the character is alphanumeric.
#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
}iswalpha(), iswdigit(), isalnum()
iswalpha()Tests if a wide character is alphabetic
#include <wctype.h>
int iswalpha(wint_t wc);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().
Returns true if the character is alphabetic.
#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
}iswblank()Tests if this is a wide blank character
#include <wctype.h>
int iswblank(wint_t wc);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.
Returns true if this is a blank character.
#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
}iswcntrl()Tests if this is a wide control character.
#include <wctype.h>
int iswcntrl(wint_t wc);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.
Returns true if this is a control character.
#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
}iswdigit()Test if this wide character is a digit
#include <wctype.h>
int iswdigit(wint_t wc);Tests if the wide character is a digit (0-9).
Returns true if the character is a digit.
#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
}iswgraph()Test to see if a wide character is a printable non-space
#include <wctype.h>
int iswgraph(wint_t wc);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.
Returns true if this is a printable non-space character.
#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
}iswprint(), iswspace(), isgraph()
iswlower()Tests if a wide character is lowercase
#include <wctype.h>
int iswlower(wint_t wc);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)Returns true if the wide character is lowercase.
#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
}islower(), iswupper(), iswalpha(), towupper(), towlower()
iswprint()Tests if a wide character is printable
#include <wctype.h>
int iswprint(wint_t wc);Tests if a wide character is printable, including space (' '). So like isgraph(), except space isn’t left out in the cold.
Returns true if the wide character is printable, including space (' ').
#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
}isprint(), iswgraph(), iswcntrl()
iswpunct()Test if a wide character is punctuation
#include <wctype.h>
int iswpunct(wint_t wc);Tests if a wide character is punctuation.
This means for any given locale:
!isspace(c) && !isalnum(c)True if the wide character is punctuation.
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
}ispunct(), iswspace(), iswalnum()
iswspace()Test if a wide character is whitespace
#include <wctype.h>
int iswspace(wint_t wc);Tests if c is a whitespace character. These are probably:
' ')'\f')'\n')'\r')'\t')'\v')Other locales might specify other whitespace characters. iswalnum(), iswgraph(), and iswpunct() are all false for all whitespace characters.
True if the character is whitespace.
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
}iswupper()Tests if a wide character is uppercase
#include <wctype.h>
int iswupper(wint_t wc);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)Returns true if the wide character is uppercase.
#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
}isupper(), iswlower(), iswalpha(), towupper(), towlower()
iswxdigit()Tests if a wide character is a hexadecimal digit
#include <wctype.h>
int iswxdigit(wint_t wc);Returns true if the wide character is a hexadecimal digit. Namely if it’s 0-9, a-f, or A-F.
True if the character is a hexadecimal digit.
#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
}iswctype()Determine wide character classification
#include <wctype.h>
int iswctype(wint_t wc, wctype_t desc);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.
Returns true if the wide character wc matches the character class in desc.
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!wctype()Helper function for iswctype()
#include <wctype.h>
wctype_t wctype(const char *property);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.
Returns the wctype_t value associated with the given property.
If an invalid value is passed for property, returns 0.
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!towlower()Convert an uppercase wide character to lowercase
#include <wctype.h>
wint_t towlower(wint_t wc);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.
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.
#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)
}tolower(), towupper(), iswlower(), iswupper()
towupper()Convert a lowercase wide character to uppercase
#include <wctype.h>
wint_t towupper(wint_t wc);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.
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.
#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)
}toupper(), towlower(), iswlower(), iswupper()
towctrans()Convert wide characters to upper or lowercase
#include <wctype.h>
wint_t towctrans(wint_t wc, wctrans_t desc);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.
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.
#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 -> '!'wctrans(), towupper(), towlower()
wctrans()Helper function for towctrans()
#include <wctype.h>
wctrans_t wctrans(const char *property);This is a helper function for generating the second argument to towctrans().
You can pass in one of two things for the property:
toupper to make towctrans() behave like towupper()tolower to make towctrans() behave like towlower()On success, returns a value that can be used as the desc argument to towctrans().
Otherwise, if the property isn’t recognized, returns 0.
#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 -> '!'