STD::__CTYPE_ABSTRACT_BASE(3cxx)

📦
version 14-20240412 · 18 versions
, in ubuntu noble

💖 NAME 💖

okay bestie, welcome to the manual page for std::__ctype_abstract_base< _CharT >, straight outta section 3cxx — it's the Common base for ctype facet, and yes it's exactly as much of a team-player as that sounds 🫶

✨ SYNOPSIS ✨

first things first, you gotta pull it in:

#include <locale>

Inherits std::locale::facet, and std::ctype_base.

Inherited by std::ctype< _CharT >.

🌸 Public Types 🌸

  • typedef const int * __to_type — the pointer-to-int type, lowkey just vibing here ✨
  • typedef _CharT char_type — Typedef for the template parameter. that's the whole job. iconic.
  • typedef unsigned short mask — the mask type, unsigned short, used for all the classifying business 💅

🦋 Public Member Functions 🦋

  • 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 🌈

all of these are static const mask, no cap, one per classification:

  • 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 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 🎀

  • __ctype_abstract_base (size_t __refs=0) — the protected constructor, default __refs=0, respect it 👑
  • virtual const char_type * do_is (const char_type *__lo, const char_type *__hi, mask *__vec) const =0 — Return a mask array.
  • virtual bool do_is (mask __m, char_type __c) const =0 — Test char_type classification.
  • virtual char do_narrow (char_type __c, char __dfault) const =0 — Narrow char_type to char.
  • virtual const char_type * do_narrow (const char_type *__lo, const char_type *__hi, char __dfault, char *__to) const =0 — Narrow char_type array to char.
  • virtual const char_type * do_scan_is (mask __m, const char_type *__lo, const char_type *__hi) const =0 — Find char_type matching mask.
  • virtual const char_type * do_scan_not (mask __m, const char_type *__lo, const char_type *__hi) const =0 — Find char_type not matching mask.
  • virtual const char_type * do_tolower (char_type *__lo, const char_type *__hi) const =0 — Convert array to lowercase.
  • virtual char_type do_tolower (char_type __c) const =0 — Convert to lowercase.
  • virtual const char_type * do_toupper (char_type *__lo, const char_type *__hi) const =0 — Convert array to uppercase.
  • virtual char_type do_toupper (char_type __c) const =0 — Convert to uppercase.
  • virtual char_type do_widen (char __c) const =0 — Widen char.
  • virtual const char * do_widen (const char *__lo, const char *__hi, char_type *__to) const =0 — Widen char array.

🧚 Static Protected Member Functions 🧚

  • static __c_locale _S_clone_c_locale (__c_locale &__cloc) throw () — clones that locale, and yeah, throw (), it's giving old-school 💀
  • static void _S_create_c_locale (__c_locale &__cloc, const char *__s, __c_locale __old=0) — creates the C locale, with __old=0 by default
  • static void _S_destroy_c_locale (__c_locale &__cloc) — destroys the C locale (rip, but make it clean ✨)
  • static __c_locale _S_get_c_locale () — grabs the C locale for you
  • static const char * _S_get_c_name () throw () — gets the C locale name, also throw ()
  • static __c_locale _S_lc_ctype_c_locale (__c_locale __cloc, const char *__s) — the LC_CTYPE C locale situation 🎀

🔥 Detailed Description 🔥

template<typename _CharT>
    class std::__ctype_abstract_base< _CharT >

"Common base for ctype facet.

so here's the tea, bestie: this template class provides implementations of the public functions that forward to the protected virtual functions ☕

and it also provides abstract stubs for the protected virtual functions. like, it hands you the blueprint and then goes "you finish it" 💅 periodt.

⭐ Member Typedef Documentation ⭐

char_type

template<typename _CharT >
typedef _CharT std::__ctype_abstract_base< _CharT >::char_type

Typedef for the template parameter. literally just _CharT wearing a little name tag 🏷️

💜 Member Function Documentation 💜

do_is (the range one) — return a mask array

template<typename _CharT >
virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_is (const char_type * __lo,
                                             const char_type * __hi,
                                             mask * __vec) const [protected],
                                             [pure virtual]

okay so this one 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 — no skimping, no cap.

do_is() is a hook for a derived facet to change the behavior of classifying. and do_is() must always return the same result for the same input. consistency queen 👑

Parameters

  • __lo — Pointer to start of range.
  • __hi — Pointer to end of range.
  • __vec — Pointer to an array of mask storage.

Returns

__hi. yeah, it just gives you back the end pointer. slay ✨

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

do_is (the mask-comparison one) — test char_type classification

template<typename _CharT >
virtual bool
std::__ctype_abstract_base< _CharT >::do_is (mask __m,
                                             char_type __c) const [protected],
                                             [pure virtual]

this one finds a mask M for c and compares it to mask m. a little one-on-one, very main character energy 🔍

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. that's the whole test, bestie 💅

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

Referenced by std::__ctype_abstract_base< _CharT >::is(), and std::__ctype_abstract_base< _CharT >::is().

do_narrow (single char) — narrow char_type to char

template<typename _CharT >
virtual char
std::__ctype_abstract_base< _CharT >::do_narrow (char_type __c,
                                                 char __dfault) const [protected],
                                                 [pure virtual]

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. fr fr, don't come for this function when you actually needed codecvt 😭

Parameters

  • __c — The char_type to convert.
  • __dfault — char to return if conversion fails.

Returns

The converted char.

Implemented in std::ctype< wchar_t >, and std::ctype< _CharT >.

Referenced by std::__ctype_abstract_base< _CharT >::narrow(), and std::__ctype_abstract_base< _CharT >::narrow().

do_narrow (the array one) — narrow char_type array to char

template<typename _CharT >
virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_narrow (const char_type * __lo,
                                                 const char_type * __hi,
                                                 char __dfault,
                                                 char * __to) const [protected],
                                                 [pure virtual]

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. (yes bestie, the same warning again, it's serious 💀)

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

do_scan_is — find char_type matching mask

template<typename _CharT >
virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_scan_is (mask __m,
                                                  const char_type * __lo,
                                                  const char_type * __hi) const [protected],
                                                  [pure virtual]

this function searches for and returns the first char_type c in [__lo,__hi) for which is(__m,c) is true. first match wins, no looking back 💅

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. (yes, it says do_is() there — that's literally what the page says, we're not arguing with it 🙈)

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

Referenced by std::__ctype_abstract_base< _CharT >::scan_is().

do_scan_not — find char_type not matching mask

template<typename _CharT >
virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_scan_not (mask __m,
                                                   const char_type * __lo,
                                                   const char_type * __hi) const [protected],
                                                   [pure virtual]

this function searches for and returns a pointer to the first char_type c of [lo,hi) for which is(m,c) is false. the contrarian search, we love her 🦋

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. (again — same wording as the page, keeping it verbatim bestie 🫶)

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

Referenced by std::__ctype_abstract_base< _CharT >::scan_not().

do_tolower (the array one) — convert array to lowercase

template<typename _CharT >
virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_tolower (char_type * __lo,
                                                  const char_type * __hi) const [protected],
                                                  [pure virtual]

this virtual function converts each char_type in the range [__lo,__hi) to lowercase if possible. other elements remain untouched — no notes, they stay exactly as they are 🙈

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

do_tolower (the single one) — convert to lowercase

template<typename _CharT >
virtual char_type
std::__ctype_abstract_base< _CharT >::do_tolower (char_type __c) const [protected],
                                                  [pure virtual]

this virtual function converts the argument to lowercase if possible. if it's not possible (for example, '2'), it returns the argument. '2' is already perfect, it doesn't need to change 💀✨

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

okay that's the do_* crew covered, bestie — and there's more coming, so don't wander off 🍓

Still on do_tolower() for one last sec — because the lowercasing that bubbles up through the wrapper gets used by, and I quote:

  • Referenced by std::__ctype_abstract_base< _CharT >::tolower(), and std::__ctype_abstract_base< _CharT >::tolower().

(yeah, both overloads. the whole fam is in on it 💅)

do_toupper() — the array one 🡕

template<typename _CharT > virtual const char_type *
std::__ctype_abstract_base< _CharT >::do_toupper (char_type * __lo,
const char_type * __hi) const [protected],  [pure virtual]

Ok so this is convert array to uppercase, bestie. This virtual function converts each char_type in the range [__lo,__hi) to uppercase if possible. Other elements remain untouched — like, they're just vibing, no glow-up for them.

do_toupper() is a hook for a derived facet to change the behavior of uppercasing. And it's got that main-character consistency rule: do_toupper() must always return the same result for the same input. No cap. 🎀

Parameters

  • __lo — Pointer to start of range.
  • __hi — Pointer to end of range.

Returns __hi. That's it, that's the return. ✨

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

do_toupper() — the single-char one 🡕

template<typename _CharT > virtual char_type
std::__ctype_abstract_base< _CharT >::do_toupper (char_type __c) const
[protected],  [pure virtual]

Convert to uppercase but make it one (1) character. This virtual function converts the char_type argument to uppercase if possible. If not possible (for example, '2'), returns the argument — because '2' is already living its truth, honestly. 😌

Same hook situation: do_toupper() is a hook for a derived facet to change the behavior of uppercasing, and 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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

Referenced by std::__ctype_abstract_base< _CharT >::toupper(), and std::__ctype_abstract_base< _CharT >::toupper(). (again, both of them. iconique.)

do_widen() — char-flavoured 🦋

template<typename _CharT > virtual char_type
std::__ctype_abstract_base< _CharT >::do_widen (char __c) const [protected],
[pure virtual]

Widen char. This virtual function converts the char to char_type using the simplest reasonable transformation. Like, no drama, no overthinking, just the basic glow-up from char to char_type. ✨

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. fr fr, wrong tool, don't do it.

Parameters

  • __c — The char to convert.

Returns The converted char_type.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

Referenced by std::__ctype_abstract_base< _CharT >::widen(), and std::__ctype_abstract_base< _CharT >::widen().

do_widen() — the array edition 🦋🦋

template<typename _CharT > virtual const char *
std::__ctype_abstract_base< _CharT >::do_widen (const char * __lo,
const char * __hi, char_type * __to) const [protected],  [pure virtual]

Widen char array. This function converts each char in the input to char_type using the simplest reasonable transformation. Whole squad, one by one. 🫶

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.

Implemented in std::ctype< _CharT >, and std::ctype< wchar_t >.

is() — gimme that mask array 👑

template<typename _CharT > const char_type *
std::__ctype_abstract_base< _CharT >::is (const char_type * __lo,
const char_type * __hi, mask * __vec) const [inline]

Return a mask array. This function finds the mask for each char_type in the range [lo,hi) and successively writes it to vec. And heads up: vec must have as many elements as the char array — no short-changing it, she needs room. 💅

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.

References std::__ctype_abstract_base< _CharT >::do_is().

is() — the mask comparison one 🔍

template<typename _CharT > bool std::__ctype_abstract_base< _CharT >::is
(mask __m, char_type __c) const [inline]

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.

References std::__ctype_abstract_base< _CharT >::do_is().

Referenced by std::time_get< _CharT, _InIter >::get().

narrow() — single char, bringing it down to size 🍓

template<typename _CharT > char std::__ctype_abstract_base< _CharT >::narrow
(char_type __c, char __dfault) const [inline]

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 — your safety net, bestie. 🫶

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.

References std::__ctype_abstract_base< _CharT >::do_narrow().

Referenced by std::time_get< _CharT, _InIter >::do_get_year(), std::time_get< _CharT, _InIter >::get(), and std::time_put< _CharT, _OutIter >::put().

narrow() — array to char array 🍓🍓

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]

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 — the fallback queen 👑.

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.

References std::__ctype_abstract_base< _CharT >::do_narrow().

scan_is() — first match wins 🌸

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]

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.

References std::__ctype_abstract_base< _CharT >::do_scan_is().

scan_not() — first non-match, a hater detector 💀

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]

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.

References std::__ctype_abstract_base< _CharT >::do_scan_not().

tolower() — the array glow-down 💜

template<typename _CharT > const char_type *
std::__ctype_abstract_base< _CharT >::tolower (char_type * __lo,
const char_type * __hi) const [inline]

Convert array to lowercase. This function converts each char_type in the range [__lo,__hi) to lowercase if possible. Other elements remain untouched — they said "not my era" and stayed put. 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.

References std::__ctype_abstract_base< _CharT >::do_tolower().

tolower() — single char 💜

template<typename _CharT > char_type
std::__ctype_abstract_base< _CharT >::tolower (char_type __c) const [inline]

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.

References std::__ctype_abstract_base< _CharT >::do_tolower().

Referenced by std::time_get< _CharT, _InIter >::get().

toupper() — the array, but LOUD 🔥

template<typename _CharT > const char_type *
std::__ctype_abstract_base< _CharT >::toupper (char_type * __lo,
const char_type * __hi) const [inline]

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

(not me noticing the original drops the underscores in lo, hi here — I'm keeping it exact, don't come for me 🙈)

Parameters

  • __lo — Pointer to start of range.
  • __hi — Pointer to end of range.

Returns __hi.

References std::__ctype_abstract_base< _CharT >::do_toupper().

toupper() — single char, all caps energy 🔥

template<typename _CharT > char_type
std::__ctype_abstract_base< _CharT >::toupper (char_type __c) const [inline]

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.

References std::__ctype_abstract_base< _CharT >::do_toupper().

Referenced by std::time_get< _CharT, _InIter >::get().

widen() — char to char_type 🌈

template<typename _CharT > char_type
std::__ctype_abstract_base< _CharT >::widen (char __c) const [inline]

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. (third time's the charm, she really means it 💀)

Parameters

  • __c — The char to convert.

Returns The converted char_type.

References std::__ctype_abstract_base< _CharT >::do_widen().

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(). (the whole moneytime industrial complex, honestly 🫶)

widen() — the array version, final boss 🌈✨

template<typename _CharT > const char *
std::__ctype_abstract_base< _CharT >::widen (const char * __lo,
const char * __hi, char_type * __to) const [inline]

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.

References std::__ctype_abstract_base< _CharT >::do_widen().

👑 AUTHOR 👑

So like… nobody actually wrote this one, bestie. 😭

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

That's it, that's the whole author situation — Doxygen did the ✨werk✨, pulling straight from libstdc++'s source code. No mysterious human genius to thank here, just a documentation generator doing its thing and producing this whole page on autopilot. 🫶

And that's a wrap on std::__ctype_ab..._base< _CharT >, bestie! 🎀 You made it through the typedefs, the member functions, and now the very meta "who made this" moment. Highkey iconic of you to read the whole thing. 💅

This lil' page lives in the libstdc++ docs — the one and only — and it's the std::__ctype_ab..._base< _CharT >(3cxx) page, so if you ever need to find your way back, that's the name to search. 🌸

Go forth and <ctype> responsibly, queen. 👑✨

📦 where this page comes from