25 Localization library [localization]

25.4 Standard locale categories [locale.categories]

25.4.1 The ctype category [category.ctype]

namespace std {
  class ctype_base {
  public:
    using mask = T;

    // numeric values are for exposition only.
    static const mask space = 1 << 0;
    static const mask print = 1 << 1;
    static const mask cntrl = 1 << 2;
    static const mask upper = 1 << 3;
    static const mask lower = 1 << 4;
    static const mask alpha = 1 << 5;
    static const mask digit = 1 << 6;
    static const mask punct = 1 << 7;
    static const mask xdigit = 1 << 8;
    static const mask blank = 1 << 9;
    static const mask alnum = alpha | digit;
    static const mask graph = alnum | punct;
  };
}
1
#

Тип mask - это bitmask type.

25.4.1.1 Class template ctype [locale.ctype]

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

      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* high, 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;
    };
}
1
#

Класс ctype инкапсулирует библиотеки C <cctype> функции. istream члены должны использоваться ctype<> для классификации символов во время синтаксического анализа входных данных.

2
#

Специализации, требуемые в Table 69 ([locale.category]), а именно ctype<char> и ctype<wchar_­t>, реализуют классификацию символов, соответствующую собственному набору символов реализации.

25.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;

1
#

Returns: do_­is(m, c) или do_­is(low, high, vec).

const charT* scan_is(mask m, const charT* low, const charT* high) const;

2
#

Returns: do_­scan_­is(m, low, high).

const charT* scan_not(mask m, const charT* low, const charT* high) const;

3
#

Returns: do_­scan_­not(m, low, high).

charT toupper(charT) const; const charT* toupper(charT* low, const charT* high) const;

4
#

Returns: do_­toupper(c) или do_­toupper(low, high).

charT tolower(charT c) const; const charT* tolower(charT* low, const charT* high) const;

5
#

Returns: do_­tolower(c) или do_­tolower(low, high).

charT widen(char c) const; const char* widen(const char* low, const char* high, charT* to) const;

6
#

Returns: do_­widen(c) или do_­widen(low, high, to).

char narrow(charT c, char dfault) const; const charT* narrow(const charT* low, const charT* high, char dfault, char* to) const;

7
#

Returns: do_­narrow(c, dfault) или do_­narrow(low, high, dfault, to).

25.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;

1
#

Effects: Классифицирует символ или последовательность символов. Для каждого символа аргумента определяет значение M типа ctype_­base​::​mask. Вторая форма определяет значение M типа ctype_­base​::​mask для каждого *p where (low <= p && p < high)и помещает его в vec[p - low].

2
#

Returns: Первая форма возвращает результат выражения (M & m) != 0; то есть, true если персонаж имеет указанные характеристики. Вторая форма возвращается high.

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

3
#

Effects: Находит в буфере символ, соответствующий классификации m.

4
#

Returns: Наименьший указатель p в диапазоне [low, high) , который is(m, *p) будет возвращать true; в противном случае возвращается high.

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

5
#

Effects: Находит в буфере символ, не соответствующий классификации m.

6
#

Returns: Наименьший указатель p, если таковой имеется, в диапазоне [low, high) , который is(m, *p) может возвращать false; в противном случае возвращается high.

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

7
#

Effects: Преобразует символ или символы в верхний регистр. Вторая форма заменяет каждый символ *p в диапазоне, [low, high) для которого существует соответствующий символ верхнего регистра, этим символом.

8
#

Returns: Первая форма возвращает соответствующий символ верхнего регистра, если известно, что он существует, или его аргумент, если нет. Вторая форма возвращается high.

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

9
#

Effects: Преобразует символ или символы в нижний регистр. Вторая форма заменяет каждый символ *p в диапазоне, [low, high) для которого существует соответствующий символ нижнего регистра, на этот символ.

10
#

Returns: Первая форма возвращает соответствующий символ нижнего регистра, если известно, что он существует, или его аргумент, если нет. Вторая форма возвращается high.

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

11
#

Effects: Применяет простейшее разумное преобразование char значения или последовательности char значений в соответствующее charT значение или значения.233 Единственные символы, для которых требуются уникальные преобразования, - это символы в basic source character set.

Для любого имени ctype категории с ctype <charT> фаской ctc и действительным ctype_­base​::​mask значением M, (ctc.​is(M, c) || !is(M, do_­widen(c)) ) является true.234

Вторая форма преобразует каждый символ *p в диапазоне [low, high), помещая результат в dest[p - low].

12
#

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;

13
#

Effects: Применяет простейшее разумное преобразование charT значения или последовательности charT значений в соответствующее char значение или значения.

Для любого символа c в basic source character set преобразовании таково, что

do_widen(do_narrow(c, 0)) == c

Для любого имени ctype категории с ctype<char> фаской ctc однако, и ctype_­base​::​mask значением M, 

(is(M, c) || !ctc.is(M, do_narrow(c, dfault)) )

есть true (если не do_­narrow возвращается dfault). Кроме того, для любого цифрового символа cвыражение (do_­narrow(c, dfault) - '0') оценивается как цифровое значение символа. Вторая форма преобразует каждый символ *p в диапазоне [low, high), помещая результат (или, dfault если простое преобразование недоступно) в dest[p - low].

14
#

Returns: Первая форма возвращает преобразованное значение; или dfault если нет доступного отображения. Вторая форма возвращается high.

233)

Аргумент char do_­widen предназначен для приема значений, полученных из символьных литералов, для преобразования в кодировку языкового стандарта.

234)

Другими словами, преобразованный символ не является членом какой-либо классификации символов, которая c также не является членом.

25.4.1.2 Class template ctype_­byname [locale.ctype.byname]

namespace std {
  template <class charT>
    class ctype_byname : public ctype<charT> {
    public:
      using mask = typename ctype<charT>::mask;
      explicit ctype_byname(const char*, size_t refs = 0);
      explicit ctype_byname(const string&, size_t refs = 0);
    protected:
      ~ctype_byname();
    };
}

25.4.1.3 ctype specializations [facet.ctype.special]

namespace std {
  template <>
    class ctype<char> : public locale::facet, public ctype_base {
    public:
      using char_type = char;

      explicit ctype(const mask* tab = 0, bool del = false,
                     size_t refs = 0);

      bool is(mask m, char c) const;
      const char* is(const char* low, const char* high, mask* vec) const;
      const char* scan_is (mask m,
                           const char* low, const char* high) const;
      const char* scan_not(mask m,
                           const char* low, const char* high) const;

      char        toupper(char c) const;
      const char* toupper(char* low, const char* high) const;
      char        tolower(char c) const;
      const char* tolower(char* low, const char* high) const;

      char  widen(char c) const;
      const char* widen(const char* low, const char* high, char* to) const;
      char  narrow(char c, char dfault) const;
      const char* narrow(const char* low, const char* high, char dfault,
                         char* to) const;

      static locale::id id;
      static const size_t table_size = implementation-defined;

      const mask* table() const noexcept;
      static const mask* classic_table() noexcept;

    protected:
      ~ctype();
      virtual char        do_toupper(char c) const;
      virtual const char* do_toupper(char* low, const char* high) const;
      virtual char        do_tolower(char c) const;
      virtual const char* do_tolower(char* low, const char* high) const;

      virtual char        do_widen(char c) const;
      virtual const char* do_widen(const char* low,
                                   const char* high,
                                   char* to) const;
      virtual char        do_narrow(char c, char dfault) const;
      virtual const char* do_narrow(const char* low,
                                    const char* high,
                                    char dfault, char* to) const;
    };
}
1
#

Предоставляется специализация, позволяющая реализовать ctype<char> функции-члены по типу . Определяемое реализацией значение member не менее 256.charinline235table_­size

235)

Только char (не unsigned char и signed char) форма предоставляется. Специализация указывается в стандарте и не остается в качестве детали реализации, поскольку она влияет на интерфейс деривации для ctype<char>.

25.4.1.3.1 ctype<char> destructor [facet.ctype.char.dtor]

~ctype();

1
#

Effects: Если первый аргумент конструктора отличался от нуля, а второй аргумент был равен нулю true, имеет значение delete [] table().

25.4.1.3.2 ctype<char> members [facet.ctype.char.members]

1
#

В следующих описаниях членов для unsigned char значений, v где предполагается, что они имеют значение v >= table_­size, table()[v] зависящее от реализации (возможно, различное для каждого такого значения v), без выполнения поиска в массиве.

explicit ctype(const mask* tbl = 0, bool del = false, size_t refs = 0);

2
#

Requires: tbl либо 0, либо массив хотя бы из table_­size элементов.

3
#

Effects: Передает свой refs аргумент конструктору базового класса.

bool is(mask m, char c) const; const char* is(const char* low, const char* high, mask* vec) const;

4
#

Effects: Вторая форма для всех *p в диапазоне [low, high)присваивается vec[p - low] значению table()[(unsigned char)*p].

5
#

Returns: Возвращается первая форма table()[(unsigned char)c] & m; вторая форма возвращается high.

const char* scan_is(mask m, const char* low, const char* high) const;

6
#

Returns: Наименьшее p в диапазоне [low, high) такое, что 

table()[(unsigned char) *p] & m

есть true.

const char* scan_not(mask m, const char* low, const char* high) const;

7
#

Returns: Наименьшее p в диапазоне [low, high) такое, что 

table()[(unsigned char) *p] & m

есть false.

char toupper(char c) const; const char* toupper(char* low, const char* high) const;

8
#

Returns: do_­toupper(c) или do_­toupper(low, high), соответственно.

char tolower(char c) const; const char* tolower(char* low, const char* high) const;

9
#

Returns: do_­tolower(c) или do_­tolower(low, high), соответственно.

char widen(char c) const; const char* widen(const char* low, const char* high, char* to) const;

10
#

Returns: do_­widen(c) или do_­widen(low, high, to), соответственно.

char narrow(char c, char dfault) const; const char* narrow(const char* low, const char* high, char dfault, char* to) const;

11
#

Returns: do_­narrow(c, dfault) или do_­narrow(low, high, dfault, to), соответственно.

const mask* table() const noexcept;

12
#

Returns: Первый аргумент конструктора, если он был ненулевым, в противном случае classic_­table().

25.4.1.3.3 ctype<char> static members [facet.ctype.char.statics]

static const mask* classic_table() noexcept;

1
#

Returns: Указатель на начальный элемент массива размера, table_­size который представляет классификации символов в "C" локали.

25.4.1.3.4 ctype<char> virtual functions [facet.ctype.char.virtuals]

char        do_toupper(char) const;
const char* do_toupper(char* low, const char* high) const;
char        do_tolower(char) const;
const char* do_tolower(char* low, const char* high) const;

virtual char        do_widen(char c) const;
virtual const char* do_widen(const char* low,
                             const char* high,
                             char* to) const;
virtual char        do_narrow(char c, char dfault) const;
virtual const char* do_narrow(const char* low,
                              const char* high,
                              char dfault, char* to) const;

Эти функции описаны так же, как и члены с тем же именем в ctype class template.

25.4.1.4 Class template codecvt [locale.codecvt]

namespace std {
  class codecvt_base {
  public:
    enum result { ok, partial, error, noconv };
  };

  template <class internT, class externT, class stateT>
    class codecvt : public locale::facet, public codecvt_base {
    public:
      using intern_type = internT;
      using extern_type = externT;
      using state_type  = stateT;

      explicit codecvt(size_t refs = 0);

      result out(
          stateT& state,
          const internT* from, const internT* from_end, const internT*& from_next,
                externT*   to,       externT*   to_end,       externT*&   to_next) const;

      result unshift(
          stateT& state,
                externT*    to,      externT*   to_end,       externT*&   to_next) const;

      result in(
          stateT& state,
          const externT* from, const externT* from_end, const externT*& from_next,
                internT*   to,       internT*   to_end,       internT*&   to_next) const;

      int encoding() const noexcept;
      bool always_noconv() const noexcept;
      int length(stateT&, const externT* from, const externT* end, size_t max) const;
      int max_length() const noexcept;

      static locale::id id;

    protected:
      ~codecvt();
      virtual result do_out(
          stateT& state,
          const internT* from, const internT* from_end, const internT*& from_next,
                externT* to,         externT*   to_end,       externT*&   to_next) const;
      virtual result do_in(
          stateT& state,
          const externT* from, const externT* from_end, const externT*& from_next,
                internT* to,         internT*   to_end,       internT*&   to_next) const;
      virtual result do_unshift(
          stateT& state,
                externT* to,         externT*   to_end,       externT*&   to_next) const;

      virtual int do_encoding() const noexcept;
      virtual bool do_always_noconv() const noexcept;
      virtual int do_length(stateT&, const externT* from, const externT* end, size_t max) const;
      virtual int do_max_length() const noexcept;
    };
}
1
#

Класс codecvt<internT, externT, stateT> предназначен для использования при преобразовании из одной кодировки символов в другую, например, из широких символов в многобайтовые символы или между кодировками широких символов, такими как Unicode и EUC.

2
#

В stateT аргументе выбирает пару кодировки символов привязываются между ними.

3
#

Специализации, требуемые в Table 69 ([locale.category]), преобразуют собственный набор символов, определенный реализацией. codecvt<char, char, mbstate_­t> реализует вырожденное преобразование; он вообще не конвертируется. Специализация codecvt<char16_­t, char, mbstate_­t> преобразуется между формами кодирования UTF-16 и UTF-8, а специализация codecvt <char32_­t, char, mbstate_­t> преобразуется между формами кодирования UTF-32 и UTF-8. codecvt<wchar_­t, char, mbstate_­t> преобразует собственные наборы символов для узких и широких символов. Специализации по mbstate_­t выполнению преобразования между кодировками, известные разработчику библиотеки. Другие кодировки можно преобразовать, специализируясь на определяемом пользователем stateT типе. Объекты типа stateT могут содержать любое состояние, которое полезно для связи со специализированнымиdo_­in или do_­out членами или от них .

25.4.1.4.1 codecvt members [locale.codecvt.members]

result out( stateT& state, const internT* from, const internT* from_end, const internT*& from_next, externT* to, externT* to_end, externT*& to_next) const;

1
#

Returns: do_­out(state, from, from_­end, from_­next, to, to_­end, to_­next).

result unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;

2
#

Returns: do_­unshift(state, to, to_­end, to_­next).

result in( stateT& state, const externT* from, const externT* from_end, const externT*& from_next, internT* to, internT* to_end, internT*& to_next) const;

3
#

Returns: do_­in(state, from, from_­end, from_­next, to, to_­end, to_­next).

int encoding() const noexcept;

4
#

Returns: do_­encoding().

bool always_noconv() const noexcept;

5
#

Returns: do_­always_­noconv().

int length(stateT& state, const externT* from, const externT* from_end, size_t max) const;

6
#

Returns: do_­length(state, from, from_­end, max).

int max_length() const noexcept;

7
#

Returns: do_­max_­length().

25.4.1.4.2 codecvt virtual functions [locale.codecvt.virtuals]

result do_out( stateT& state, const internT* from, const internT* from_end, const internT*& from_next, externT* to, externT* to_end, externT*& to_next) const; result do_in( stateT& state, const externT* from, const externT* from_end, const externT*& from_next, internT* to, internT* to_end, internT*& to_next) const;

1
#

Requires: (from <= from_­end && to <= to_­end) четко определенные и true; state инициализируется, если оно находится в начале последовательности, или равно результату преобразования предыдущих символов в последовательности.

2
#

Effects: Переводит символы в исходном диапазоне [from, from_­end), помещая результаты в последовательные позиции, начиная с места назначения to. Преобразует не более (from_­end - from) элементов источника и сохраняет не более (to_­end - to) элементов назначения.

Останавливается, если встречает персонажа, которого не может преобразовать. Он всегда оставляет from_­next и to_­next указатели , указывающие один за последним элементом успешно конвертированы. Если возвращает noconv, internT и externT имеют тот же тип, а преобразованная последовательность идентична входной последовательности [from, from_next). to_­next установлен равным to, значение state не изменяется, и нет никаких изменений в значениях в [to, to_­end).

3
#

codecvt Фаска , который используется basic_­filebuf ([file.streams]) должна обладать свойством , что если 

do_out(state, from, from_end, from_next, to, to_end, to_next)

вернется ok, где from != from_­endтогда 

do_out(state, from, from + 1, from_next, to, to_end, to_next)

также вернется ok, и что если 

do_in(state, from, from_end, from_next, to, to_end, to_next)

вернется ok, где to != to_­endтогда 

do_in(state, from, from_end, from_next, to, to + 1, to_next)

также вернемся ok.236 [  Note: В результате операций с stateон может возвращать ok или partial и устанавливать from_­next == from и to_­next != to. ]  — end note 

4
#

Remarks: Его операции не state указаны. [  Note: Этот аргумент может использоваться, например, для поддержания состояния сдвига, для указания параметров преобразования (например, только счетчик) или для идентификации кэша смещений поиска. ] — end note 

5
#

Returns: Значение перечисления, как показано в Табл 71.

Таблица 71 - do_­in/do_­out значения результатов
ЦенитьИмея в виду
ok завершил преобразование
partial не все исходные символы преобразованы
error обнаружил символ, [from, from_­end) который не может преобразовать
noconv internT и externT одного типа, а входная последовательность идентична преобразованной последовательности

Возвращаемое значение partialif (from_­next == from_­end)указывает, что либо целевая последовательность не поглотила все доступные элементы назначения, либо необходимы дополнительные исходные элементы, прежде чем можно будет создать другой элемент назначения.

result do_unshift(stateT& state, externT* to, externT* to_end, externT*& to_next) const;

6
#

Requires: (to <= to_­end) четко очерченный и true; состояние инициализировано, если оно находится в начале последовательности, или равно результату преобразования предыдущих символов в последовательности.

7
#

Effects: Знаки, начинающиеся с to этого места, должны быть добавлены для завершения последовательности, когда текущее значение stateT задается state.237 Сохраняет не более (to_­end - to) элементов назначения и оставляет to_­next указатель, указывающий на один за последним успешно сохраненным элементом.

8
#

Returns: Значение перечисления, как показано в Табл 72.

Таблица 72 - do_­unshift значения результатов
ЦенитьИмея в виду
ok завершил последовательность
partial пространство для более чем to_­end - to целевых элементов требовалось для завершения последовательности с учетом значения state
error произошла неопределенная ошибка
noconv для этого не требуется прекращения state_­type

int do_encoding() const noexcept;

9
#

Returns: -1 если кодирование externT последовательности зависит от состояния; иначе постоянное количество externT символов, необходимое для создания внутреннего символа; или 0 если это число не является постоянным.238

bool do_always_noconv() const noexcept;

10
#

Returns: true если do_­in() и do_­out() вернуться noconv для всех допустимых значений аргументов. codecvt<char, char, mbstate_­t> возвращается true.

int do_length(stateT& state, const externT* from, const externT* from_end, size_t max) const;

11
#

Requires: (from <= from_­end) четко определенные и true; state инициализируется, если оно находится в начале последовательности, или равно результату преобразования предыдущих символов в последовательности.

12
#

Effects: Влияние на state аргумент «как будто» она называется do_­in(state, from, from_­end, from, to, to+max, to) для to указывая на буфер , по крайней мере max элементов.

13
#

Returns: (from_­next-from) где from_­next - наибольшее значение в диапазоне, [from, from_­end] такое, что последовательность значений в диапазоне [from, from_­next) представляет max или меньше допустимых полных символов типа internT. Специализация codecvt<char, char, mbstate_­t>возвращает меньшее из значений max и (from_­end-from).

int do_max_length() const noexcept;

14
#

Returns: Максимальное значение, которое do_­length(state, from, from_­end, 1) может быть возвращено для любого допустимого диапазона [from, from_­end) и stateT значения state. Специализация codecvt<char, char, mbstate_­t>​::​do_­max_­length() возвращает 1.

236)

Неформально это означает, что basic_­filebuf предполагается, что отображение внутренних символов на внешние - от 1 до N: codecvt фасет, который используется, basic_­filebuf должен иметь возможность переводить символы по одному внутреннему символу за раз.

237)

Обычно это символы, в которые нужно вернуть состояние stateT().

238)

Если encoding() уступает -1, то max_­length() externT при создании одного internT символа может быть использовано больше элементов , а дополнительные externT элементы могут появиться в конце последовательности после тех, которые дают последний internT символ.

25.4.1.5 Class template codecvt_­byname [locale.codecvt.byname]

namespace std {
  template <class internT, class externT, class stateT>
    class codecvt_byname : public codecvt<internT, externT, stateT> {
    public:
      explicit codecvt_byname(const char*, size_t refs = 0);
      explicit codecvt_byname(const string&, size_t refs = 0);
    protected:
      ~codecvt_byname();
    };
}