---
name: "std::ctype"
section: "3"
platform: "linux"
package: "gcc"
version: "16.2.1+r23+gd564253eb6c8-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/std::ctype"
---

# std::ctype(3)

Primary class template ctype facet.

## NAME

std::ctype\< \_CharT \> - Primary class template ctype facet.

## SYNOPSIS

\#include \<locale\>

Inherits **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

Inherited by **std::ctype\_byname\< \_CharT \>**.

### Public Types

typedef const int \* **\_\_to\_type**\
 typedef \_CharT **char\_type**\
 typedef \_\_ctype\_abstract\_base\< \_CharT \>::mask **mask**\

### Public Member Functions

**ctype** (size\_t \_\_refs=0)\
 const char\_type \* **is** (const char\_type \*\_\_lo, const char\_type \*\_\_hi, mask \*\_\_vec) const\
 Return a mask array.  bool **is** (mask \_\_m, char\_type \_\_c) const\
 Test char\_type classification.  char **narrow** (char\_type \_\_c, char \_\_dfault) const\
 Narrow char\_type to char.  const char\_type \* **narrow** (const char\_type \*\_\_lo, const char\_type \*\_\_hi, char \_\_dfault, char \*\_\_to) const\
 Narrow array to char array.  const char\_type \* **scan\_is** (mask \_\_m, const char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Find char\_type matching a mask.  const char\_type \* **scan\_not** (mask \_\_m, const char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Find char\_type not matching a mask.  const char\_type \* **tolower** (char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Convert array to lowercase.  char\_type **tolower** (char\_type \_\_c) const\
 Convert to lowercase.  const char\_type \* **toupper** (char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Convert array to uppercase.  char\_type **toupper** (char\_type \_\_c) const\
 Convert to uppercase.  char\_type **widen** (char \_\_c) const\
 Widen char to char\_type.  const char \* **widen** (const char \*\_\_lo, const char \*\_\_hi, char\_type \*\_\_to) const\
 Widen array to char\_type.

### Static Public Attributes

static const mask **alnum**\
 static const mask **alpha**\
 static const mask **blank**\
 static const mask **cntrl**\
 static const mask **digit**\
 static const mask **graph**\
 static **locale::id** **id**\
 The facet id for ctype\<char\_type\>.  static const mask **lower**\
 static const mask **print**\
 static const mask **punct**\
 static const mask **space**\
 static const mask **upper**\
 static const mask **xdigit**\

### Protected Member Functions

virtual const char\_type \* **do\_is** (const char\_type \*\_\_lo, const char\_type \*\_\_hi, mask \*\_\_vec) const\
 Return a mask array.  virtual bool **do\_is** (mask \_\_m, char\_type \_\_c) const\
 Test char\_type classification.  virtual char **do\_narrow** (char\_type, char \_\_dfault) const\
 Narrow char\_type to char.  virtual const char\_type \* **do\_narrow** (const char\_type \*\_\_lo, const char\_type \*\_\_hi, char \_\_dfault, char \*\_\_to) const\
 Narrow char\_type array to char.  virtual const char\_type \* **do\_scan\_is** (mask \_\_m, const char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Find char\_type matching mask.  virtual const char\_type \* **do\_scan\_not** (mask \_\_m, const char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Find char\_type not matching mask.  virtual const char\_type \* **do\_tolower** (char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Convert array to lowercase.  virtual char\_type **do\_tolower** (char\_type \_\_c) const\
 Convert to lowercase.  virtual const char\_type \* **do\_toupper** (char\_type \*\_\_lo, const char\_type \*\_\_hi) const\
 Convert array to uppercase.  virtual char\_type **do\_toupper** (char\_type \_\_c) const\
 Convert to uppercase.  virtual char\_type **do\_widen** (char \_\_c) const\
 Widen char.  virtual const char \* **do\_widen** (const char \*\_\_lo, const char \*\_\_hi, char\_type \*\_\_dest) const\
 Widen char array.

### Static Protected Member Functions

static \_\_c\_locale **\_S\_clone\_c\_locale** (\_\_c\_locale &\_\_cloc)  throw ()\
 static void **\_S\_create\_c\_locale** (\_\_c\_locale &\_\_cloc, const char \*\_\_s, \_\_c\_locale \_\_old=0)\
 static void **\_S\_destroy\_c\_locale** (\_\_c\_locale &\_\_cloc)\
 static \_\_c\_locale **\_S\_get\_c\_locale** ()\
 static const char \* **\_S\_get\_c\_name** ()  throw ()\
 static \_\_c\_locale **\_S\_lc\_ctype\_c\_locale** (\_\_c\_locale \_\_cloc, const char \*\_\_s)\

## Detailed Description

### template\<typename \_CharT\>

class std::ctype\< \_CharT \>"Primary class template ctype facet.

This template class defines classification and conversion functions for character sets. It wraps cctype functionality. Ctype gets used by streams for many I/O operations.

This template provides the protected virtual functions the developer will have to replace in a derived class or specialization to make a working facet. The public functions that access them are defined in \_\_ctype\_abstract\_base, to allow for implementation flexibility. See ctype\<wchar\_t\> for an example. The functions are documented in \_\_ctype\_abstract\_base.

Note: implementations are provided for all the protected virtual functions, but will likely not be useful.

## Member Function Documentation

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_is (const char\_type \* \_\_lo, const char\_type \* \_\_hi, mask \* \_\_vec) const \[protected\], \[virtual\]

Return a mask array. This function finds the mask for each char\_type in the range \[lo,hi) and successively writes it to vec. vec must have as many elements as the input.

do\_is() is a hook for a derived facet to change the behavior of classifying. do\_is() must always return the same result for the same input.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_vec* Pointer to an array of mask storage.

**Returns**

*\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual bool std::ctype\< \_CharT \>::do\_is (mask \_\_m, char\_type \_\_c) const \[protected\], \[virtual\]

Test char\_type classification. This function finds a mask M for *c* and compares it to mask *m*.

do\_is() is a hook for a derived facet to change the behavior of classifying. do\_is() must always return the same result for the same input.

**Parameters**

*\_\_c* The char\_type to find the mask of. \
 *\_\_m* The mask to compare against.

**Returns**

(M & \_\_m) != 0.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual char std::ctype\< \_CharT \>::do\_narrow (char\_type \_\_c, char \_\_dfault) const \[protected\], \[virtual\]

Narrow char\_type to char. This virtual function converts the argument to char using the simplest reasonable transformation. If the conversion fails, dfault is returned instead.

do\_narrow() is a hook for a derived facet to change the behavior of narrowing. do\_narrow() must always return the same result for the same input.

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_c* The char\_type to convert. \
 *\_\_dfault* Char to return if conversion fails.

**Returns**

The converted char.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

Referenced by **std::ctype\< char \>::narrow()**, and **std::ctype\< char \>::narrow()**.

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_narrow (const char\_type \* \_\_lo, const char\_type \* \_\_hi, char \_\_dfault, char \* \_\_to) const \[protected\], \[virtual\]

Narrow char\_type array to char. This virtual function converts each char\_type in the range \[\_\_lo,\_\_hi) to char using the simplest reasonable transformation and writes the results to the destination array. For any element in the input that cannot be converted, *\_\_dfault* is used instead.

do\_narrow() is a hook for a derived facet to change the behavior of narrowing. do\_narrow() must always return the same result for the same input.

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_dfault* Char to use if conversion fails. \
 *\_\_to* Pointer to the destination array.

**Returns**

*\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_scan\_is (mask \_\_m, const char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[protected\], \[virtual\]

Find char\_type matching mask. This function searches for and returns the first char\_type c in \[\_\_lo,\_\_hi) for which is(\_\_m,c) is true.

do\_scan\_is() is a hook for a derived facet to change the behavior of match searching. do\_is() must always return the same result for the same input.

**Parameters**

*\_\_m* The mask to compare against. \
 *\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

Pointer to a matching char\_type if found, else *\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_scan\_not (mask \_\_m, const char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[protected\], \[virtual\]

Find char\_type not matching mask. This function searches for and returns a pointer to the first char\_type c of \[lo,hi) for which is(m,c) is false.

do\_scan\_is() is a hook for a derived facet to change the behavior of match searching. do\_is() must always return the same result for the same input.

**Parameters**

*\_\_m* The mask to compare against. \
 *\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

Pointer to a non-matching char\_type if found, else *\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_tolower (char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[protected\], \[virtual\]

Convert array to lowercase. This virtual function converts each char\_type in the range \[\_\_lo,\_\_hi) to lowercase if possible. Other elements remain untouched.

do\_tolower() is a hook for a derived facet to change the behavior of lowercasing. do\_tolower() must always return the same result for the same input.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

*\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual char\_type std::ctype\< \_CharT \>::do\_tolower (char\_type \_\_c) const \[protected\], \[virtual\]

Convert to lowercase. This virtual function converts the argument to lowercase if possible. If not possible (for example, '2'), returns the argument.

do\_tolower() is a hook for a derived facet to change the behavior of lowercasing. do\_tolower() must always return the same result for the same input.

**Parameters**

*\_\_c* The char\_type to convert.

**Returns**

The lowercase char\_type if convertible, else *\_\_c*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

Referenced by **std::ctype\< char \>::tolower()**, and **std::ctype\< char \>::tolower()**.

### template\<typename \_CharT\> virtual const char\_type \* std::ctype\< \_CharT \>::do\_toupper (char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[protected\], \[virtual\]

Convert array to uppercase. This virtual function converts each char\_type in the range \[\_\_lo,\_\_hi) to uppercase if possible. Other elements remain untouched.

do\_toupper() is a hook for a derived facet to change the behavior of uppercasing. do\_toupper() must always return the same result for the same input.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

*\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> virtual char\_type std::ctype\< \_CharT \>::do\_toupper (char\_type \_\_c) const \[protected\], \[virtual\]

Convert to uppercase. This virtual function converts the char\_type argument to uppercase if possible. If not possible (for example, '2'), returns the argument.

do\_toupper() is a hook for a derived facet to change the behavior of uppercasing. do\_toupper() must always return the same result for the same input.

**Parameters**

*\_\_c* The char\_type to convert.

**Returns**

The uppercase char\_type if convertible, else *\_\_c*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

Referenced by **std::ctype\< char \>::toupper()**, and **std::ctype\< char \>::toupper()**.

### template\<typename \_CharT\> virtual char\_type std::ctype\< \_CharT \>::do\_widen (char \_\_c) const \[protected\], \[virtual\]

Widen char. This virtual function converts the char to char\_type using the simplest reasonable transformation.

do\_widen() is a hook for a derived facet to change the behavior of widening. do\_widen() must always return the same result for the same input.

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_c* The char to convert.

**Returns**

The converted char\_type

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

Referenced by **std::ctype\< char \>::widen()**, and **std::ctype\< char \>::widen()**.

### template\<typename \_CharT\> virtual const char \* std::ctype\< \_CharT \>::do\_widen (const char \* \_\_lo, const char \* \_\_hi, char\_type \* \_\_to) const \[protected\], \[virtual\]

Widen char array. This function converts each char in the input to char\_type using the simplest reasonable transformation.

do\_widen() is a hook for a derived facet to change the behavior of widening. do\_widen() must always return the same result for the same input.

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_lo* Pointer to start range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_to* Pointer to the destination array.

**Returns**

*\_\_hi*.

Implements **std::\_\_ctype\_abstract\_base\< \_CharT \>**.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::is (const char\_type \* \_\_lo, const char\_type \* \_\_hi, mask \* \_\_vec) const \[inline\], \[inherited\]

Return a mask array. This function finds the mask for each char\_type in the range \[lo,hi) and successively writes it to vec. vec must have as many elements as the char array. It does so by returning the value of ctype\<char\_type\>::do\_is().

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_vec* Pointer to an array of mask storage.

**Returns**

*\_\_hi*.

### template\<typename \_CharT\> bool std::\_\_ctype\_abstract\_base\< \_CharT \>::is (mask \_\_m, char\_type \_\_c) const \[inline\], \[inherited\]

Test char\_type classification. This function finds a mask M for *\_\_c* and compares it to mask *\_\_m*. It does so by returning the value of ctype\<char\_type\>::do\_is().

**Parameters**

*\_\_c* The char\_type to compare the mask of. \
 *\_\_m* The mask to compare against.

**Returns**

(M & \_\_m) != 0.

Referenced by **std::time\_get\< \_CharT, \_InIter \>::get()**.

### template\<typename \_CharT\> char std::\_\_ctype\_abstract\_base\< \_CharT \>::narrow (char\_type \_\_c, char \_\_dfault) const \[inline\], \[inherited\]

Narrow char\_type to char. This function converts the char\_type to char using the simplest reasonable transformation. If the conversion fails, dfault is returned instead. It does so by returning ctype\<char\_type\>::do\_narrow(\_\_c).

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_c* The char\_type to convert. \
 *\_\_dfault* Char to return if conversion fails.

**Returns**

The converted char.

Referenced by **std::time\_get\< \_CharT, \_InIter \>::do\_get\_year()**, **std::time\_get\< \_CharT, \_InIter \>::get()**, and **std::time\_put\< \_CharT, \_OutIter \>::put()**.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::narrow (const char\_type \* \_\_lo, const char\_type \* \_\_hi, char \_\_dfault, char \* \_\_to) const \[inline\], \[inherited\]

Narrow array to char array. This function converts each char\_type in the input to char using the simplest reasonable transformation and writes the results to the destination array. For any char\_type in the input that cannot be converted, *dfault* is used instead. It does so by returning ctype\<char\_type\>::do\_narrow(\_\_lo, \_\_hi, \_\_dfault, \_\_to).

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_dfault* Char to use if conversion fails. \
 *\_\_to* Pointer to the destination array.

**Returns**

*\_\_hi*.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::scan\_is (mask \_\_m, const char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[inline\], \[inherited\]

Find char\_type matching a mask. This function searches for and returns the first char\_type c in \[lo,hi) for which is(m,c) is true. It does so by returning ctype\<char\_type\>::do\_scan\_is().

**Parameters**

*\_\_m* The mask to compare against. \
 *\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

Pointer to matching char\_type if found, else *\_\_hi*.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::scan\_not (mask \_\_m, const char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[inline\], \[inherited\]

Find char\_type not matching a mask. This function searches for and returns the first char\_type c in \[lo,hi) for which is(m,c) is false. It does so by returning ctype\<char\_type\>::do\_scan\_not().

**Parameters**

*\_\_m* The mask to compare against. \
 *\_\_lo* Pointer to first char in range. \
 *\_\_hi* Pointer to end of range.

**Returns**

Pointer to non-matching char if found, else *\_\_hi*.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::tolower (char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[inline\], \[inherited\]

Convert array to lowercase. This function converts each char\_type in the range \[\_\_lo,\_\_hi) to lowercase if possible. Other elements remain untouched. It does so by returning ctype\<char\_type\>:: do\_tolower(\_\_lo, \_\_hi).

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

*\_\_hi*.

### template\<typename \_CharT\> char\_type std::\_\_ctype\_abstract\_base\< \_CharT \>::tolower (char\_type \_\_c) const \[inline\], \[inherited\]

Convert to lowercase. This function converts the argument to lowercase if possible. If not possible (for example, '2'), returns the argument. It does so by returning ctype\<char\_type\>::do\_tolower(c).

**Parameters**

*\_\_c* The char\_type to convert.

**Returns**

The lowercase char\_type if convertible, else *\_\_c*.

Referenced by **std::time\_get\< \_CharT, \_InIter \>::get()**.

### template\<typename \_CharT\> const char\_type \* std::\_\_ctype\_abstract\_base\< \_CharT \>::toupper (char\_type \* \_\_lo, const char\_type \* \_\_hi) const \[inline\], \[inherited\]

Convert array to uppercase. This function converts each char\_type in the range \[lo,hi) to uppercase if possible. Other elements remain untouched. It does so by returning ctype\<char\_type\>:: do\_toupper(lo, hi).

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range.

**Returns**

*\_\_hi*.

### template\<typename \_CharT\> char\_type std::\_\_ctype\_abstract\_base\< \_CharT \>::toupper (char\_type \_\_c) const \[inline\], \[inherited\]

Convert to uppercase. This function converts the argument to uppercase if possible. If not possible (for example, '2'), returns the argument. It does so by returning ctype\<char\_type\>::do\_toupper().

**Parameters**

*\_\_c* The char\_type to convert.

**Returns**

The uppercase char\_type if convertible, else *\_\_c*.

Referenced by **std::time\_get\< \_CharT, \_InIter \>::get()**.

### template\<typename \_CharT\> char\_type std::\_\_ctype\_abstract\_base\< \_CharT \>::widen (char \_\_c) const \[inline\], \[inherited\]

Widen char to char\_type. This function converts the char argument to char\_type using the simplest reasonable transformation. It does so by returning ctype\<char\_type\>::do\_widen(c).

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_c* The char to convert.

**Returns**

The converted char\_type.

Referenced by **std::money\_get\< \_CharT, \_InIter \>::do\_get()**, **std::time\_get\< \_CharT, \_InIter \>::do\_get()**, **std::money\_put\< \_CharT, \_OutIter \>::do\_put()**, and **std::time\_put\< \_CharT, \_OutIter \>::do\_put()**.

### template\<typename \_CharT\> const char \* std::\_\_ctype\_abstract\_base\< \_CharT \>::widen (const char \* \_\_lo, const char \* \_\_hi, char\_type \* \_\_to) const \[inline\], \[inherited\]

Widen array to char\_type. This function converts each char in the input to char\_type using the simplest reasonable transformation. It does so by returning ctype\<char\_type\>::do\_widen(c).

Note: this is not what you want for codepage conversions. See codecvt for that.

**Parameters**

*\_\_lo* Pointer to start of range. \
 *\_\_hi* Pointer to end of range. \
 *\_\_to* Pointer to the destination array.

**Returns**

*\_\_hi*.

## Member Data Documentation

### template\<typename \_CharT\> locale::id std::ctype\< \_CharT \>::id \[static\]

The facet id for ctype\<char\_type\>.

## Author

Generated automatically by Doxygen for libstdc++ from the source code.