25 Localization library [localization]

25.4 Standard locale categories [locale.categories]

25.4.1 The ctype category [category.ctype]

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
#

Специализации, требуемые в Table69 ([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 символ.