public member function
<locale>

std::ctype::is

single character (1)
            bool is (mask m, char_type c) const;
sequence (2)
const char_type* is (const char_type* low,
                     const char_type* high, mask* vec) const;
Classify characters
The first version (1) returns whether c belongs to any of the categories specified in bitmask m.

The second version (2) classifies the characters in the range [low,high), sequentially filling the array vec with the bitmask classification of each character.

In ctype's generic template, this function simply calls the virtual protected member do_is, which does the above by default.

In the char specialization (ctype<char>), this function uses the internal table to directly return the results without calling any virtual member.

Parameters

m
Bitmask of member type mask (inherited from ctype_base) specifying against which category the character is checked. If the bitmask combines more than one category, the function returns true if the character belongs to any of the categories.
It may be any bitwise combination of the following member bitmask values:
member constantvaluedescription
spaceunspecified (unique bits)white-space character
printunspecified (unique bits)printable character
cntrlunspecified (unique bits)control character
upperunspecified (unique bits)uppercase letter
lowerunspecified (unique bits)lowercase letter
alphaunspecified (unique bits)alphabetic character
digitunspecified (unique bits)decimal digit
punctunspecified (unique bits)punctuation character
xdigitunspecified (unique bits)hexadecimal digit
alnumalpha|digitalpha-numeric character
graphalnum|punctcharacter with graphic representation
member constantvaluedescription
spaceunspecified (unique bits)white-space character
printunspecified (unique bits)printable character
cntrlunspecified (unique bits)control character
upperunspecified (unique bits)uppercase letter
lowerunspecified (unique bits)lowercase letter
alphaunspecified (unique bits)alphabetic character
digitunspecified (unique bits)decimal digit
punctunspecified (unique bits)punctuation character
xdigitunspecified (unique bits)hexadecimal digit
blankunspecified (unique bits)blank character
alnumalpha|digitalpha-numeric character
graphalnum|punctcharacter with graphic representation
See <cctype> for details on how ASCII characters are classified with respect to these categories.
c
Character to classify.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).
low, high
Pointer to the beginning and end of the sequence of characters. The range used is [low,high), which contains all the characters between low and high, including the character pointed by low but not the character pointed by high.
Note that null characters (if any) are also classified, and the function proceeds beyond them, until the entire range is completed.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).
vec
Destination array, with enough storage for at least (high-low) elements of type mask.
This array is filled with the combination of mask values corresponding to each character.

Return value

The first version (1) returns true if c classifies in any of the categories passed as mask m.

The second version (2) returns high.
Member type char_type is the facet's character type (defined as an alias of ctype's template parameter, charT).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
// ctype::is example
#include <iostream>       // std::cout, std::boolalpha
#include <locale>         // std::locale, std::ctype, std::use_facet

int main ()
{
  std::locale loc;
  const char quote[] = "It is wonderful how much may be done if we are always doing.";
                      // (Attributed to Thomas Jefferson)

  std::cout << '"' << quote << "\"\n";

  // single character:
  std::cout << "The quote begins with an uppercase letter? ";
  std::cout << std::boolalpha;
  std::cout << std::use_facet< std::ctype<char> >(loc).is (std::ctype<char>::upper, quote[0]);
  std::cout << '\n';

  // sequence of characters:
  int cx = 0;
  std::ctype<char>::mask * masks = new std::ctype<char>::mask [60];
  std::use_facet< std::ctype<char> >(loc).is (quote, quote+60, masks);
  for (int i=0; i<60; ++i) if (masks[i] & std::ctype<char>::space) ++cx;
  std::cout << "The quote has " << cx << " whitespaces.\n";
  return 0;
}


Output:

"It is wonderful how much may be done if we are always doing."
The quote begins with an uppercase letter? true
The quote has 12 whitespaces.

Data races

The object is accessed.
In (2), the elements in the range [low,high) are accessed, and the elements in the array pointed by vec are modified.

Exception safety

If an exception is thrown, there are no changes in the facet object, although characters in the destination array may have been affected.

See also

ctype::scan_is
Return first character in category (public member function )
ctype::scan_not
Return first character not in category (public member function )
ctype::do_is
Classify characters [virtual] (protected virtual member function )

C++