22 Localization library [localization]

22.4 Standard locale categories [locale.categories]

22.4.1 The ctype category [category.ctype]

22.4.1.1 Class template ctype [locale.ctype]

namespace std {
  template <class charT>
  class ctype : public locale::facet, public ctype_base {
  public:
    typedef charT char_type;

    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*, 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 [tab:localization.category.facets] ([locale.category]), namely ctype<char> and ctype<wchar_t>, implement character classing appropriate to the implementation's native character set.

22.4.1.1.1 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*, char dfault, char* to) const;

Returns: do_narrow(c,dfault) or do_narrow(low,high,dfault,to)

22.4.1.1.2 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.240 The only characters for which unique transformations are required are those in the basic source 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.241

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 source 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.

The char argument of do_widen is intended to accept values derived from character literals for conversion to the locale's encoding.

In other words, the transformed character is not a member of any character classification that c is not also a member of.