28 Localization library [localization]

28.4 Standard locale categories [locale.categories]

28.4.2 The ctype category [category.ctype]

28.4.2.2 Class template ctype [locale.ctype]

28.4.2.2.1 General [locale.ctype.general]

namespace std { template<class charT> class ctype : public locale::facet, public ctype_base { public: using char_type = charT; explicit ctype(size_t refs = 0); bool is(mask m, charT c) const; const charT* is(const charT* low, const charT* high, mask* vec) const; const charT* scan_is(mask m, const charT* low, const charT* high) const; const charT* scan_not(mask m, const charT* low, const charT* high) const; charT toupper(charT c) const; const charT* toupper(charT* low, const charT* high) const; charT tolower(charT c) const; const charT* tolower(charT* low, const charT* high) const; charT widen(char c) const; const char* widen(const char* low, const char* high, charT* to) const; char narrow(charT c, char dfault) const; const charT* narrow(const charT* low, const charT* high, char dfault, char* to) const; static locale::id id; protected: ~ctype(); virtual bool do_is(mask m, charT c) const; virtual const charT* do_is(const charT* low, const charT* high, mask* vec) const; virtual const charT* do_scan_is(mask m, const charT* low, const charT* high) const; virtual const charT* do_scan_not(mask m, const charT* low, const charT* high) const; virtual charT do_toupper(charT) const; virtual const charT* do_toupper(charT* low, const charT* high) const; virtual charT do_tolower(charT) const; virtual const charT* do_tolower(charT* low, const charT* high) const; virtual charT do_widen(char) const; virtual const char* do_widen(const char* low, const char* high, charT* dest) const; virtual char do_narrow(charT, char dfault) const; virtual const charT* do_narrow(const charT* low, const charT* high, char dfault, char* dest) const; }; }
Class ctype encapsulates the C library <cctype> features.
istream members are required to use ctype<> for character classing during input parsing.
The specializations required in Table 106 ([locale.category]), namely ctype<char> and ctype<wchar_­t>, implement character classing appropriate to the implementation's native character set.

28.4.2.2.2 ctype members [locale.ctype.members]

bool is(mask m, charT c) const; const charT* is(const charT* low, const charT* high, mask* vec) const;
Returns: do_­is(m, c) or do_­is(low, high, vec).
const charT* scan_is(mask m, const charT* low, const charT* high) const;
Returns: do_­scan_­is(m, low, high).
const charT* scan_not(mask m, const charT* low, const charT* high) const;
Returns: do_­scan_­not(m, low, high).
charT toupper(charT) const; const charT* toupper(charT* low, const charT* high) const;
Returns: do_­toupper(c) or do_­toupper(low, high).
charT tolower(charT c) const; const charT* tolower(charT* low, const charT* high) const;
Returns: do_­tolower(c) or do_­tolower(low, high).
charT widen(char c) const; const char* widen(const char* low, const char* high, charT* to) const;
Returns: do_­widen(c) or do_­widen(low, high, to).
char narrow(charT c, char dfault) const; const charT* narrow(const charT* low, const charT* high, char dfault, char* to) const;
Returns: do_­narrow(c, dfault) or do_­narrow(low, high, dfault, to).

28.4.2.2.3 ctype virtual functions [locale.ctype.virtuals]

bool do_is(mask m, charT c) const; const charT* do_is(const charT* low, const charT* high, mask* vec) const;
Effects: Classifies a character or sequence of characters.
For each argument character, identifies a value M of type ctype_­base​::​mask.
The second form identifies a value M of type ctype_­base​::​mask for each *p where (low <= p && p < high), and places it into vec[p - low].
Returns: The first form returns the result of the expression (M & m) != 0; i.e., true if the character has the characteristics specified.
The second form returns high.
const charT* do_scan_is(mask m, const charT* low, const charT* high) const;
Effects: Locates a character in a buffer that conforms to a classification m.
Returns: The smallest pointer p in the range [low, high) such that is(m, *p) would return true; otherwise, returns high.
const charT* do_scan_not(mask m, const charT* low, const charT* high) const;
Effects: Locates a character in a buffer that fails to conform to a classification m.
Returns: The smallest pointer p, if any, in the range [low, high) such that is(m, *p) would return false; otherwise, returns high.
charT do_toupper(charT c) const; const charT* do_toupper(charT* low, const charT* high) const;
Effects: Converts a character or characters to upper case.
The second form replaces each character *p in the range [low, high) for which a corresponding upper-case character exists, with that character.
Returns: The first form returns the corresponding upper-case character if it is known to exist, or its argument if not.
The second form returns high.
charT do_tolower(charT c) const; const charT* do_tolower(charT* low, const charT* high) const;
Effects: Converts a character or characters to lower case.
The second form replaces each character *p in the range [low, high) and for which a corresponding lower-case character exists, with that character.
Returns: The first form returns the corresponding lower-case character if it is known to exist, or its argument if not.
The second form returns high.
charT do_widen(char c) const; const char* do_widen(const char* low, const char* high, charT* dest) const;
Effects: Applies the simplest reasonable transformation from a char value or sequence of char values to the corresponding charT value or values.251
The only characters for which unique transformations are required are those in the basic character set ([lex.charset]).
For any named ctype category with a ctype<charT> facet ctc and valid ctype_­base​::​mask value M, (ctc.​is(M, c) || !is(M, do_­widen(c)) ) is true.252
The second form transforms each character *p in the range [low, high), placing the result in dest[p - low].
Returns: The first form returns the transformed value.
The second form returns high.
char do_narrow(charT c, char dfault) const; const charT* do_narrow(const charT* low, const charT* high, char dfault, char* dest) const;
Effects: Applies the simplest reasonable transformation from a charT value or sequence of charT values to the corresponding char value or values.
For any character c in the basic character set ([lex.charset]) the transformation is such that do_widen(do_narrow(c, 0)) == c
For any named ctype category with a ctype<char> facet ctc however, and ctype_­base​::​mask value M, (is(M, c) || !ctc.is(M, do_narrow(c, dfault)) ) is true (unless do_­narrow returns dfault).
In addition, for any digit character c, the expression (do_­narrow(c, dfault) - '0') evaluates to the digit value of the character.
The second form transforms each character *p in the range [low, high), placing the result (or dfault if no simple transformation is readily available) in dest[p - low].
Returns: The first form returns the transformed value; or dfault if no mapping is readily available.
The second form returns high.
251)251)
The char argument of do_­widen is intended to accept values derived from character-literals for conversion to the locale's encoding.
252)252)
In other words, the transformed character is not a member of any character classification that c is not also a member of.