Name

ctype class template — Facet for classifying characters

Synopsis

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:
  virtual ~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;
};

The ctype class template is a facet for classifying characters.

See Also

The ctype<char> specialization is described in its own section later in this chapter. The standard also mandates the ctype<wchar_t> instantiation. Both instantiations depend on the implementation's native character set.

As with other facets, the public members call virtual, protected members with the same name prefaced by do_. Thus, to use the facet, call the public functions, such as narrow, which calls do_narrow. The descriptions below are for the virtual functions because they do the real work. Imagine that for each virtual function description, there is a corresponding description for a public, nonvirtual function, such as:

The following are the virtual, protected members of ctype:

virtual bool do_is (mask m, charT c) const, virtual const charT* do_is (const charT* low, const charT* high, mask* dest) const

Classifies a single character c or a sequence of characters [low, high). The first form tests the classification mask, M, of c and returns (M & m) != 0. The second form determines the mask for each character in the range and stores the mask values in the dest array (which must be large enough to hold high - low masks), returning high. See Table 13-19 (under the ctype_base class) for a description of the mask type.

virtual char do_narrow (charT c, char dfault) const, virtual const charT* do_narrow (const charT* low, const charT* high, char dfault, char* dest) const

Converts a character c or a sequence of characters [low, high) to narrow characters of type char. The first form returns the narrow character, and the second form stores the characters in the array dest (which must be large enough to hold high - low characters), returning high. If a charT source character cannot be converted to a narrow character, the first function returns dfault, and the second function stores dfault in dest as the narrow version of that character.

virtual const charT* do_scan_is (mask m, const charT* low, const charT* high) const

Searches the sequence of characters [low, high) for the first character that matches m, that is, for which do_is(m, c) is true. The return value is a pointer to the first matching character, or high if no characters match m.

virtual const charT* do_scan_not (mask m, const charT* low, const charT* high) const

Searches the sequence of characters [low, high) for the first character that does not match m, that is, for which do_is(m, c) is false. The return value is a pointer to the first matching character, or high if every character matches m.

virtual charT do_tolower (charT c) const, virtual const charT* do_tolower (charT* low, const charT* high) const

Converts a character c or a sequence of characters [low, high) to lowercase. The first form returns the lowercase version of c, or it returns c if c does not have a lowercase counterpart.

The second form modifies the character sequence: each character in [low, high) is replaced by its lowercase counterpart; if a character cannot be converted to lowercase, it is not touched. The function returns high.

virtual charT do_toupper (charT c) const, virtual const charT* do_toupper (charT* low, const charT* high) const

Converts a character c or a sequence of characters [low, high) to uppercase. The first form returns the uppercase version of c, or it returns c if c does not have a uppercase counterpart.

The second form modifies the character sequence: each character in [low, high) is replaced by its uppercase counterpart; if a character cannot be converted to uppercase, it is not touched. The function returns high.

virtual charT do_widen (char c) const, virtual const char* do_widen (const char* low, const char* high, charT* dest) const

Converts a narrow character c or a sequence of narrow characters [low, high) to characters of type charT. The first form returns the new character, and the second form stores the characters in the array dest (which must be large enough to hold high - low characters), returning high.