--- name: "std::ctype" section: "3cxx" platform: "linux" package: "libstdc++-12-doc" version: "12.4.0-5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/std::ctype/3cxx" --- # std::ctype(3cxx) Primary class template ctype facet. ## NAME std::ctype\< \_CharT \> - Primary class template ctype facet. ## SYNOPSIS `#include ` 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\ **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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\ 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\::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*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_is()**. ### template\ 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\::do\_is(). **Parameters** *\_\_c* The char\_type to compare the mask of. \ *\_\_m* The mask to compare against. **Returns** (M & \_\_m) != 0. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_is()**. ### template\ 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\::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. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_narrow()**. ### template\ 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\::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*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_narrow()**. ### template\ 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\::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*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_scan\_is()**. ### template\ 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\::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*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_scan\_not()**. ### template\ 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\:: do\_tolower(\_\_lo, \_\_hi). **Parameters** *\_\_lo* Pointer to start of range. \ *\_\_hi* Pointer to end of range. **Returns** *\_\_hi*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_tolower()**. ### template\ 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\::do\_tolower(c). **Parameters** *\_\_c* The char\_type to convert. **Returns** The lowercase char\_type if convertible, else *\_\_c*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_tolower()**. ### template\ 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\:: do\_toupper(lo, hi). **Parameters** *\_\_lo* Pointer to start of range. \ *\_\_hi* Pointer to end of range. **Returns** *\_\_hi*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_toupper()**. ### template\ 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\::do\_toupper(). **Parameters** *\_\_c* The char\_type to convert. **Returns** The uppercase char\_type if convertible, else *\_\_c*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_toupper()**. ### template\ 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\::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. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_widen()**. ### template\ 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\::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*. References **std::\_\_ctype\_abstract\_base\< \_CharT \>::do\_widen()**. ## Member Data Documentation ### template\ locale::id std::ctype\< \_CharT \>::id` [static]` The facet id for ctype\ ## Author Generated automatically by Doxygen for libstdc++ from the source code.