Класс `codecvt`

Статья
06/16/2023

Шаблон класса, описывающий объект, который может служить аспектом языкового стандарта. Он может управлять преобразованиями между последовательностью значений, используемых для кодирования символов в программе, и последовательностью значений, используемых для кодирования символов за пределами программы.

Синтаксис

template <class CharType, class Byte, class StateType>
class codecvt : public locale::facet, codecvt_base;

Параметры

CharType
Тип, используемый внутри программы для кодирования символов.

Byte
Тип, используемый для кодирования символов вне программы.

StateType
Тип, который можно использовать для представления промежуточных состояний преобразования между внутренними и внешними типами представлений символов.

Замечания

Шаблон класса описывает объект, который может служить аспектом языкового стандарта, для управления преобразованиями между последовательностью значений типа CharType и последовательностью значений типа Byte. Класс StateType характеризует преобразование, а объект класса StateType сохраняет все необходимые сведения о состоянии во время преобразования.

Внутренняя кодировка использует представление с фиксированным числом байтов на один знак, обычно либо тип char, либо тип wchar_t.

Как и в случае любого другого аспекта языкового стандарта, начальное сохраненное значение статического id объекта равно нулю. Первая попытка получить доступ к сохраненному значению сохранит уникальное положительное значение в id.

Версии do_in шаблона и do_out всегда возвращаются codecvt_base::noconv.

Стандартная библиотека C++ определяет несколько явных специализаций:

template<>
codecvt<wchar_t, char, mbstate_t>

выполняет преобразование между последовательностями wchar_t и char.

template<>
codecvt<char16_t, char, mbstate_t>

выполняет преобразование между последовательностями char16_t в кодировке UTF-16 и последовательностями char в кодировке UTF-8.

template<>
codecvt<char32_t, char, mbstate_t>

выполняет преобразование между последовательностями char32_t в кодировке UTF-32 (UCS-4) и последовательностями char в кодировке UTF-8.

Конструкторы

Конструктор	Description
`codecvt`	Конструктор для объектов класса `codecvt`, который служит в качестве аспекта языкового стандарта для обработки преобразований.

Определения типов

Введите имя	Description
`extern_type`	Тип символа, используемый для внешних представлений.
`intern_type`	Тип символа, используемый для внутренних представлений.
`state_type`	Тип символа, который используется для представления промежуточных состояний во время преобразований между внутренними и внешними представлениями.

Функции элементов

Функция-член	Description
`always_noconv`	Проверяет, не требуется ли выполнит преобразования.
`do_always_noconv`	Виртуальная функция, вызываемая проверки того, не требуется ли выполнить преобразования.
`do_encoding`	Виртуальная функция, которая проверяет, зависит ли кодировка `Byte` потока, зависит ли соотношение между `Byte` используемыми значениями и `CharType` значениями, созданными константой, и, если да, определяет значение этого соотношения.
`do_in`	Виртуальная функция, вызываемая для преобразования последовательности внутренних `Byte` значений в последовательность внешних `CharType` значений.
`do_length`	Виртуальная функция, которая определяет, `Byte` сколько значений из заданной последовательности внешних значений создает не более заданного числа внутренних `Byte` `CharType` значений и возвращает это число значений `Byte` .
`do_max_length`	Виртуальная функция, возвращающая максимальное число внешних байтов, необходимых для создания одного внутреннего `CharType`.
`do_out`	Виртуальная функция, вызываемая для преобразования последовательности внутренних `CharType` значений в последовательность внешних байтов.
`do_unshift`	Виртуальная функция, вызываемая для предоставления `Byte` значений, необходимых для преобразования, зависящей от состояния, для завершения последнего символа в последовательности значений `Byte` .
`encoding`	Проверяет, зависит ли кодировка `Byte` потока, зависит ли соотношение между `Byte` используемыми значениями и `CharType` значениями, созданными константой, и, если да, определяет значение этого соотношения.
`in`	Преобразует внешнее представление последовательности `Byte` значений во внутреннее представление последовательности значений `CharType` .
`length`	Определяет, сколько `Byte` значений из заданной последовательности внешних значений создает не более заданного числа внутренних `Byte` `CharType` значений и возвращает это число значений `Byte` .
`max_length`	Возвращает максимальное количество внешних `Byte` значений, необходимых для создания одного внутреннего `CharType`.
`out`	Преобразует последовательность внутренних `CharType` значений в последовательность внешних `Byte` значений.
`unshift`	Предоставляет внешние `Byte` значения, необходимые для преобразования, зависящей от состояния, для завершения последнего символа в последовательности значений `Byte` .

Требования

Заголовок: <locale>

Пространство имен: std

`codecvt::always_noconv`

Проверяет, не нужно ли выполнять преобразования.

bool always_noconv() const throw();

Возвращаемое значение

Логическое значение, которое не true требуется выполнять, если преобразования не требуются, false если необходимо выполнить хотя бы один.

Замечания

Функция-член возвращает значение do_always_noconv.

Пример

// codecvt_always_noconv.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   bool result1 = use_facet<codecvt<char, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result1 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';

   bool result2 = use_facet<codecvt<wchar_t, char, mbstate_t>>
      ( loc ).always_noconv( );

   if ( result2 )
      cout << "No conversion is needed." << '\n';
   else
      cout << "At least one conversion is required." << '\n';
}

No conversion is needed.
At least one conversion is required.

`codecvt::codecvt`

Конструктор для объектов класса codecvt, который служит в качестве аспекта языкового стандарта для обработки преобразований.

explicit codecvt(size_t refs = 0);

Параметры

refs
Целочисленное значение, используемое для указания типа управления памятью для объекта.

Замечания

Возможные значения параметра refs и их важность:

0: время существования объекта управляется языковыми стандартами, которые его содержат.
1: время существования объекта должно управляться вручную.
2. Эти значения не определены.

Конструктор инициализирует базовый locale::facet объект с locale::facet(refs)помощью .

`codecvt::do_always_noconv`

Виртуальная функция, вызываемая для проверки необходимости преобразования.

virtual bool do_always_noconv() const throw();

Возвращаемое значение

Функция защищенного виртуального члена возвращается true только в том случае, если каждый вызов do_in или do_out возврат.noconv

Версия шаблона всегда возвращается true.

Пример

См. пример вызоваalways_noconvdo_always_noconv.

`codecvt::do_encoding`

Виртуальная функция, которая проверяет, зависит ли кодировка Byte потока, зависит ли соотношение между Byte значениями, используемыми и CharType созданными значениями, константой и, если да, определяет значение этого соотношения.

virtual int do_encoding() const throw();

Возвращаемое значение

Защищенная функция-член возвращает:

-1, если кодировка последовательностей типа extern_type зависит от состояния.
0, если кодировка включает последовательности переменной длины;
N, если кодировка включает только последовательности длины N

Пример

См. пример для encoding, в котором вызывается do_encoding.

codecvt::d o_in

Виртуальная функция, вызываемая для преобразования последовательности внешних Byte значений в последовательность внутренних CharType значений.

virtual result do_in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало последовательности для преобразования.

last1
Указатель на конец последовательности для преобразования.

next1
Указатель за пределами преобразованной последовательности для первого непреобразованного символа.

first2
Указатель на начало преобразованной последовательности.

last2
Указатель на конец преобразованной последовательности.

next2
Указатель на CharType то, что происходит после последнего преобразования CharType, на первый неуправляемый символ в конечной последовательности.

Возвращаемое значение

Возвращаемое значение, которое указывает успех, частичный успех или сбой операции. Функция возвращает:

codecvt_base::error Если исходная последовательность не сформирована.
codecvt_base::noconv, если функция не выполняет преобразование;
codecvt_base::ok Значение , если преобразование выполнено успешно.
codecvt_base::partial Значение , если источник недостаточно велик или не достаточно велик, для успешного преобразования.

Замечания

Объект state должен представлять начальное состояние преобразования в начале новой исходной последовательности. Функция изменяет это сохраненное значение так, чтобы отразить текущее состояние успешного преобразования. В противном случае сохраненное значение будет незаданным.

Пример

См. пример вызоваindo_in.

`codecvt::do_length`

Виртуальная функция, которая определяет, Byte сколько значений из заданной последовательности внешних значений создает не более заданного числа внутренних Byte CharType значений и возвращает это число значений Byte .

virtual int do_length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало внешней последовательности.

last1
Указатель на конец внешней последовательности.

len2
Максимальное количество значений Byte , которые могут быть возвращены функцией-членом.

Возвращаемое значение

Целое число, представляющее максимальное число преобразований, не превышающее len2, определенное внешней последовательностью источника по адресу [ first1, last1).

Замечания

Защищенная виртуальная функция-член фактически вызывает do_in( state, first1, last1, next1, buf, buf + len2, next2) состояние (копия состояния), некоторые буферы bufи указатели next1 и next2.

Затем оно возвращает значение next2 - buf. Он подсчитывает максимальное число преобразований, не превышающее len2, определенное исходной последовательностью по адресу [ first1, last1).

Версия шаблона всегда возвращает меньшее last1 - first1 значение и.len2

Пример

См. пример вызоваlengthdo_length.

`codecvt::do_max_length`

Виртуальная функция, возвращающая максимальное количество внешних Byte значений, необходимых для создания одной внутренней CharTypeфункции.

virtual int do_max_length() const throw();

Возвращаемое значение

Максимальное количество значений, необходимых Byte для создания одного CharType.

Замечания

Функция защищенного виртуального члена возвращает наибольшее допустимое значение, которое можно возвращать do_length( first1, last1, 1) для произвольных допустимых значений first1 и last1.

Пример

См. пример вызоваmax_lengthdo_max_length.

`codecvt::do_out`

Виртуальная функция, вызываемая для преобразования последовательности внутренних CharType значений в последовательность внешних Byte значений.

virtual result do_out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало последовательности для преобразования.

last1
Указатель на конец последовательности для преобразования.

next1
Ссылка на указатель на первый неконвертируемый CharTypeпосле последнего CharType преобразования.

first2
Указатель на начало преобразованной последовательности.

last2
Указатель на конец преобразованной последовательности.

next2
Ссылка на указатель на первый неконвертируемый Byteпосле последнего Byte преобразования.

Возвращаемое значение

Функция возвращает:

codecvt_base::error Если исходная последовательность не сформирована.
codecvt_base::noconv, если функция не выполняет преобразование;
codecvt_base::ok Значение , если преобразование выполнено успешно.
codecvt_base::partial Значение , если источник недостаточно велик или не достаточно велик для успешного преобразования.

Замечания

Пример

См. пример для out, в котором вызывается do_out.

`codecvt::do_unshift`

Виртуальная функция, вызываемая для предоставления Byte значений, необходимых для преобразования, зависящей от состояния, для завершения последнего символа в последовательности значений Byte .

virtual result do_unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first2
Указатель первой позиции в целевом диапазоне.

last2
Указатель последней позиции в целевом диапазоне.

next2
Указатель на первый неизмененный элемент в целевой последовательности.

Возвращаемое значение

Функция возвращает:

codecvt_base::error Значение , если состояние представляет недопустимое состояние
codecvt_base::noconv, если функция не выполняет преобразование;
codecvt_base::ok Значение , если преобразование успешно выполнено
codecvt_base::partial Значение , если назначение недостаточно большое для успешного преобразования

Замечания

Защищенная виртуальная функция-член пытается преобразовать исходный элемент CharType(0) в целевую последовательность, которая хранится в [ first2, last2за исключением конечного элемента Byte(0). Она всегда хранит в next2 указатель на первый неизмененный элемент в целевой последовательности.

Объект State должен представлять начальное состояние преобразования в начале новой исходной последовательности. Функция изменяет это сохраненное значение так, чтобы отразить текущее состояние успешного преобразования. Как правило, преобразование исходного элемента CharType(0) оставляет текущее состояние в исходном состоянии преобразования.

Пример

См. пример вызоваunshiftdo_unshift.

`codecvt::encoding`

Проверяет, зависит ли кодировка Byte потока, зависит ли соотношение между Byte используемыми значениями и CharType значениями, созданными константой, и, если да, определяет значение этого соотношения.

int encoding() const throw();

Возвращаемое значение

Если возвращаемое значение является положительным, это значение является константным числом Byte символов, необходимым для создания символа CharType .

Защищенная функция-член возвращает:

-1, если кодировка последовательностей типа extern_type зависит от состояния.
0, если кодировка включает последовательности переменной длины;
N, если кодировка включает только последовательности длины N.

Замечания

Функция-член возвращает do_encoding.

Пример

// codecvt_encoding.cpp
// compile with: /EHsc
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc ( "German_Germany" );
   int result1 = use_facet<codecvt<char, char, mbstate_t>> ( loc ).encoding ( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<wchar_t, char, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
   result1 = use_facet<codecvt<char, wchar_t, mbstate_t>> ( loc ).encoding( );
   cout << result1 << '\n';
}

1
1
1

`codecvt::extern_type`

Тип символа, используемый для внешних представлений.

typedef Byte extern_type;

Замечания

Этот тип является синонимом для параметра шаблона Byte.

codecvt::in

Преобразует внешнее представление последовательности Byte значений во внутреннее представление последовательности значений CharType .

result in(
    StateType& state,
    const Byte* first1,
    const Byte* last1,
    const Byte*& next1,
    CharType* first2,
    CharType* last2,
    CharType*& next2,) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало последовательности для преобразования.

last1
Указатель на конец последовательности для преобразования.

next1
Указатель за пределами преобразованной последовательности для первого непреобразованного символа.

first2
Указатель на начало преобразованной последовательности.

last2
Указатель на конец преобразованной последовательности.

next2
Указатель на CharType то, что происходит после последнего преобразования Chartype в первый неуправляемый символ в конечной последовательности.

Возвращаемое значение

Возвращаемое значение, которое указывает успех, частичный успех или сбой операции. Функция возвращает:

codecvt_base::error Если исходная последовательность не сформирована.
codecvt_base::noconv, если функция не выполняет преобразование;
codecvt_base::ok Значение , если преобразование выполнено успешно.
codecvt_base::partial Значение , если источник недостаточно велик или не достаточно велик для успешного преобразования.

Замечания

Объект state должен представлять начальное состояние преобразования в начале новой исходной последовательности. Функция изменяет это сохраненное значение так, чтобы отразить текущее состояние успешного преобразования. После частичного преобразования state необходимо задать так, чтобы разрешить возобновление преобразования при поступлении новых символов.

Функция-член возвращает значение do_in( state, first1, last1, next1, first2, last2, next2).

Пример

// codecvt_in.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string to be converted!";
   wchar_t pwszInt [LEN+1];
   memset(&pwszInt[0], 0, (sizeof(wchar_t))*(LEN+1));
   const char* pszNext;
   wchar_t* pwszNext;
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C");//English_Britain");//German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).in( state,
          pszExt, &pszExt[strlen(pszExt)], pszNext,
          pwszInt, &pwszInt[strlen(pszExt)], pwszNext );
   pwszInt[strlen(pszExt)] = 0;
   wcout << ( res!=codecvt_base::error ?  L"It worked! " : L"It didn't work! " )
       << L"The converted string is:\n ["
       << &pwszInt[0]
       << L"]" << '\n';
   exit(-1);
}

It worked! The converted string is:
[This is the string to be converted!]

`codecvt::intern_type`

Тип символа, используемый для внутренних представлений.

typedef CharType intern_type;

Замечания

Этот тип является синонимом для параметра шаблона CharType.

codecvt::length

Определяет, сколько Byte значений из заданной последовательности внешних значений создает не более заданного числа внутренних Byte CharType значений и возвращает это число значений Byte .

int length(
    const StateType& state,
    const Byte* first1,
    const Byte* last1,
    size_t len2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало внешней последовательности.

last1
Указатель на конец внешней последовательности.

len2
Максимальное число объектов Byte, которое может возвратить функция-член.

Возвращаемое значение

Целое число, представляющее максимальное число преобразований, не превышающее значение len2, заданное внешней исходной последовательностью в [first1, last1).

Замечания

Функция-член возвращает значение do_length( state, first1, last1, len2).

Пример

// codecvt_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;
#define LEN 90
int main( )
{
   const char* pszExt = "This is the string whose length is to be measured!";
   mbstate_t state = {0}; // zero-initialization represents the initial conversion state for mbstate_t
   locale loc("C"); // English_Britain"); //German_Germany
   int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
     ( loc ).length( state,
          pszExt, &pszExt[strlen(pszExt)], LEN );
   cout << "The length of the string is: ";
   wcout << res;
   cout << "." << '\n';
   exit(-1);
}

The length of the string is: 50.

`codecvt::max_length`

Возвращает максимальное количество внешних Byte значений, необходимых для создания одного внутреннего CharType.

int max_length() const throw();

Возвращаемое значение

Максимальное количество значений, необходимых Byte для создания одного CharType.

Замечания

Функция-член возвращает значение do_max_length.

Пример

// codecvt_max_length.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
using namespace std;

int main( )
{
   locale loc( "C");//English_Britain" );//German_Germany
   int res = use_facet<codecvt<char, char, mbstate_t>>
     ( loc ).max_length( );
   wcout << res << '\n';
}

`codecvt::out`

Преобразует последовательность внутренних CharType значений в последовательность внешних Byte значений.

result out(
    StateType& state,
    const CharType* first1,
    const CharType* last1,
    const CharType*& next1,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first1
Указатель на начало последовательности для преобразования.

last1
Указатель на конец последовательности для преобразования.

next1
Ссылка на указатель на первый неконвертируемый CharType после последнего CharType преобразования.

first2
Указатель на начало преобразованной последовательности.

last2
Указатель на конец преобразованной последовательности.

next2
Ссылка на указатель на первый неконвертируемый Byte после последнего преобразования Byte.

Возвращаемое значение

Функция-член возвращает значение do_out( state, first1, last1, next1, first2, last2, next2).

Замечания

Дополнительные сведения см. в разделе codecvt::do_out.

Пример

// codecvt_out.cpp
// compile with: /EHsc
#define _INTL
#include <locale>
#include <iostream>
#include <wchar.h>
using namespace std;
#define LEN 90
int main( )
{
    char pszExt[LEN + 1];
    const wchar_t* pwszInt = L"This is the wchar_t string to be converted.";
    memset(&pszExt[0], 0, (sizeof(char)) * (LEN + 1));
    char* pszNext;
    const wchar_t* pwszNext;
    mbstate_t state;
    locale loc("C");//English_Britain");//German_Germany
    int res = use_facet<codecvt<wchar_t, char, mbstate_t>>
        (loc).out(state,
            pwszInt, &pwszInt[wcslen(pwszInt)], pwszNext,
            pszExt, &pszExt[wcslen(pwszInt)], pszNext);
    pszExt[wcslen(pwszInt)] = 0;
    cout << (res != codecvt_base::error ? "It worked: " : "It didn't work: ")
        << "The converted string is:\n ["
        << &pszExt[0]
        << "]" << '\n';

}

It worked: The converted string is:
[This is the wchar_t string to be converted.]

`codecvt::state_type`

Тип символа, который используется для представления промежуточных состояний во время преобразований между внутренними и внешними представлениями.

typedef StateType state_type;

Замечания

Этот тип является синонимом для параметра шаблона StateType.

codecvt::unshift

Предоставляет значения, необходимые Byte для преобразования, зависящей от состояния, для завершения последнего символа в последовательности значений Byte .

result unshift(
    StateType& state,
    Byte* first2,
    Byte* last2,
    Byte*& next2) const;

Параметры

state
Состояние преобразования, которое поддерживается между вызовами функции-члена.

first2
Указатель первой позиции в целевом диапазоне.

last2
Указатель последней позиции в целевом диапазоне.

next2
Указатель на первый неизмененный элемент в целевой последовательности.

Возвращаемое значение

Функция возвращает:

codecvt_base::error Значение , если состояние представляет недопустимое состояние.
codecvt_base::noconv, если функция не выполняет преобразование;
codecvt_base::ok Значение , если преобразование выполнено успешно.
codecvt_base::partial Значение , если назначение недостаточно велико для успешного преобразования.

Замечания

Объект state должен представлять начальное состояние преобразования в начале новой исходной последовательности. Функция изменяет это сохраненное значение так, чтобы отразить текущее состояние успешного преобразования. Как правило, преобразование исходного элемента CharType(0) оставляет текущее состояние в исходном состоянии преобразования.

Функция-член возвращает значение do_unshift( state, first2, last2, next2 ).

См. также

<locale>
Кодовые страницы
Сведения о строках имени языкового стандарта, языка, а также страны или региона
Потокобезопасность в стандартной библиотеке C++

Поделиться через

Класс codecvt

Синтаксис

Параметры

Замечания

Конструкторы

Определения типов

Функции элементов

Требования

codecvt::always_noconv

Возвращаемое значение

Замечания

Пример

codecvt::codecvt

Параметры

Замечания

codecvt::do_always_noconv

Возвращаемое значение

Пример

codecvt::do_encoding

Возвращаемое значение

Пример

codecvt::d o_in

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::do_length

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::do_max_length

Возвращаемое значение

Замечания

Пример

codecvt::do_out

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::do_unshift

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::encoding

Возвращаемое значение

Замечания

Пример

codecvt::extern_type

Замечания

codecvt::in

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::intern_type

Замечания

codecvt::length

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::max_length

Возвращаемое значение

Замечания

Пример

codecvt::out

Параметры

Возвращаемое значение

Замечания

Пример

codecvt::state_type

Замечания

codecvt::unshift

Параметры

Возвращаемое значение

Замечания

См. также

Класс `codecvt`

`codecvt::always_noconv`

`codecvt::codecvt`

`codecvt::do_always_noconv`

`codecvt::do_encoding`

`codecvt::do_length`

`codecvt::do_max_length`

`codecvt::do_out`

`codecvt::do_unshift`

`codecvt::encoding`

`codecvt::extern_type`

`codecvt::intern_type`

`codecvt::max_length`

`codecvt::out`

`codecvt::state_type`